Veins-of-Eridun

Veins of Eridûn: A dynamic text-based adventure game where your story is imagined in real-time by AI. Powered by the Google Gemini API (Gemini 2.5 Flash, Imagen 3, TTS), React, and Zustand.

Comment

Veins of Eridûn

A Living Narrative Engine

"Eridûn. A continent balanced on a knife's edge. Ancient kingdoms and powerful guilds vie for control in a shadow war of secrets and coin. But a new age is dawning—one that will be defined not by crowns or contracts, but by power itself."

A Missive for the Scribe

Greetings, Scribe. You have discovered the source codex for a living world. Veins of Eridûn is not merely a game; it is a dynamic narrative engine powered by the Google Gemini API. It is a portal to a grim-hopeful world of political intrigue, where a player's story is not pre-written but woven in real-time by a master storyteller AI.

This compendium serves as your guide to the architecture of this world—from the core metaphysical concepts that give it life, to the arcane schematics that bind its digital form.

On the Nature of Flow

Magic in this world is a raw, living force known as the Flow. It is not an internal energy source, but the rare ability to resonate with the fundamental energies of the world itself. An Awakened is an individual whose body has become a living tuning fork for these powers, manifesting as glowing veins on their skin.

This resonance is both powerful and perilous, governed by a system of deep, consistent rules:

  • Reagents as Catalysts: True power and control require Reagents—rare minerals, flora, and other substances that amplify and stabilize the Flow. This makes control of reagent supply lines a primary driver of war and politics.
  • The Cost of Power: Channeling this energy inflicts Vein-Strain, a degenerative condition that can lead to memory loss, madness, and a horrific petrified state. Every powerful act also leaves a detectable Echo, a magical footprint that can be tracked by enemies and attract dangerous aetheric creatures.

The player is a newly Awakened, a spark in the growing Flow Schism—an ideological war that will determine the future of magic. This application is the engine that brings their story to life.

  • Dynamic, Not Scripted: Every description, every choice, and every consequence is generated by the AI based on a deep "World Bible" and the player's evolving character profile. No two playthroughs are the same.
  • Player as Fulcrum: The player is the central point upon which the world turns. Their choices directly influence their reputation, their relationships, and the very state of the world around them.

The Engine's Arts: Key Features

This narrative engine is built upon several pillars, each a distinct art designed for maximum immersion and player agency.

📜 The Loom of Fate (Gemini 2.5 Flash)

The heart of the engine. A sophisticated system instruction and a detailed world bible guide the Gemini model, allowing it to act as a master storyteller. It crafts a continuous, coherent narrative, complete with complex NPCs, political intrigue, and meaningful choices. The model uses a streaming response to deliver text with a natural, "typed-out" feel, as if transcribing thoughts from the aether.

🌍 The World's Memory

The world remembers and reacts. The player's journey is tracked through a series of evolving data points which are fed back to the Oracle with every action:

  • The Chronicle (Journal): Automatically updated from the character's perspective, creating a personal log of their quests and discoveries.
  • The Great Game (Reputation): Actions have consequences. Your standing with the world's major factions is tracked, opening and closing narrative paths.
  • The Court of Memory (Dramatis Personae): The AI logs key NPCs the player meets, remembering their relationships and a description from the player's point of view.
  • The Satchel (Inventory): Players acquire tangible items—keys, documents, and crucial Reagents—that the AI can offer as unique choices in future scenarios.

🖼️ Visions in the Aether (Imagen 3)

Every scene is accompanied by a unique, AI-generated image. The story model generates a detailed descriptive prompt for Imagen 3, ensuring the visuals perfectly match the narrative moment, including the player character's appearance and the lingering Echo of their magic.

🔊 Echoes of Eridûn (Immersive Audio)

The soundscape is as dynamic as the story:

  • The Oracle's Voice (Gemini TTS): A high-quality, AI-generated voice narrates the story, providing a richer experience than standard browser speech synthesis.
  • Whispers on the Wind (Ambient Audio): The AI can change the background music to match the mood of a scene—from a tense dungeon drone to the bustling sounds of a city.
  • Resonant Clashes (Sound Effects): Key moments are punctuated with one-shot sound effects, also triggered by the AI.

✨ The Spark of Self (Player Agency)

The player's identity is paramount.

  • The Awakening (Character Creation): Players define their character through a series of evocative, narrative choices about their origin, personality, and the physical manifestation of their power.
  • The Shifting Soul (Evolving Personality): Choices are tied to personality leans (Empathy, Cunning, Resolve, Lore). Making these choices increases the character's score, which in turn influences how NPCs react to them.
  • Forging a Path (Custom Actions): An open input field allows players to defy the offered choices, with the AI capable of interpreting and reacting to their custom actions.

The Architect's Schematics: A Look Under the Hood

To channel the chaotic energies of creation into a stable form requires a precise and powerful architecture. This engine is built with a careful selection of arcane arts and potent frameworks.

  • The Runic Framework (React): The foundational structure of our world's interface is built upon a system of interlocking components, or "runes," allowing for a modular and powerful display.
  • The Scribe's Tongue (TypeScript): We enforce order and prevent catastrophic misinterpretations of the world's laws with a strict, type-safe language.
  • The Oracle's Conduit (@google/genai): All communion with the master intelligence of the Gemini API is handled through this dedicated SDK, our channel to the aether.
  • The Aetheric Resonator (Zustand): The flow of the game's state—the very memory and consciousness of the world—is managed by this lightweight but potent resonator, ensuring information is available where and when it is needed.
  • The Artisan's Toolkit (TailwindCSS): The visual form of Eridûn is crafted with a system of utility-first principles, allowing for rapid and consistent design across all components.

Performance Glyphs

  • API Caching: The vast "World Bible" is cached on the Oracle's servers to reduce token incantations and hasten response times.
  • Ephemeral Visions (Blob URLs): Generated images are transmuted from base64 into ephemeral blob URLs, easing the memory strain on the user's system.
  • Runic Efficiency (Memoization): Components are enchanted to prevent unnecessary re-casting, ensuring a smooth and performant experience.

Scribing Your Own Saga: Local Invocation

To run this engine on your local machine, you must possess an active Google Gemini API key—a key to the Oracle's chambers.

Prerequisites

  • Node.js (v18 or higher recommended)
  • A modern web browser (Chrome, Firefox, etc.)

Invocation Steps

  1. Acquire the Codex

    git clone https://github.com/your-repo/veins-of-eridun.git
cd veins-of-eridun

  2. Present Your Key The engine is configured to find the Gemini API key within process.env.API_KEY. You must ensure this environment variable is available during invocation.

  3. Kindle the Engine This project is designed to be run with a simple static server. The index.html codex uses ES modules, so you can serve the project root. For example, using http-server:

    # If you do not possess http-server, install it globally
npm install -g http-server

# Begin the ritual from the project root
http-server .

    Open your browser and navigate to the provided local URL (e.g., http://127.0.0.1:8080). If the ritual is successful, the world of Eridûn will awaken before you.

The Scribe's Archives: Project Structure

The codebase is organized to separate concerns, making it easier to navigate and extend.

/
├── public/                # Relics and static assets
├── src/
│   ├── components/        # The Alchemist's workshop of UI components
│   ├── constants/         # Unchanging laws and constants of the world
│   ├── features/          # Core engine mechanics (API services, character logic)
│   ├── lore/              # The heart of the world: system instructions & the World Bible
│   ├── store/             # The central Aetheric Resonator (Zustand store)
│   ├── types/             # The Scribe's dictionary of defined types
│   └── utils/             # Helper scrolls and utility functions
├── .gitignore
├── index.html             # The primary summoning circle (HTML entry point)
├── index.tsx              # Main invocation script (React entry point)
├── metadata.json          # The world's charter
└── README.md              # This compendium

"Your very existence is a spark in a growing conflict. You will be feared, hunted, and coveted for the power that surges within you. Your story begins now..."

Share this project:

Updates