Terra Tales

Young learners earn carbon credits for real acts; an AI DM converts credits into narrative challenges and targeted lessons to build climate literacy.

Comment

Terra Tales: A Postmortem on Weaving Narrative, AI, and Climate Action

As developers, we often look for projects that are not only technically challenging but also meaningful. With Terra Tales (internally known as Echoes of Gaia), we found an opportunity to tackle both. This project aimed to transform climate education from a series of stark warnings into an immersive, empowering fantasy adventure. Here’s a look at how we did it.

Inspiration

The core inspiration was simple: make climate literacy engaging. We observed that for young learners, the topic can feel overwhelming and abstract. How do you connect a global issue to individual action in a way that feels tangible and hopeful?

We drew inspiration from the rich, player-driven narratives of tabletop RPGs like Dungeons & Dragons. What if we could create a world where magic was intrinsically tied to ecological balance? Where a player's choices could heal a blighted forest or clear a polluted river? This led to the concept of a "hard magic system" based on environmental science, creating a perfect vehicle for storytelling that teaches. The final piece was connecting it back to the real world, rewarding players for their actual eco-friendly habits.

What it does

Terra Tales is a dynamic, narrative-driven RPG powered entirely by generative AI. When players start, they aren't just creating a character; they're reflecting on their own day. The intro screen prompts them to log real-world, eco-friendly actions—from using a reusable bottle to describing a unique effort, like starting a compost bin. Our AI evaluates these actions and awards the player their starting in-game currency, Carbon Credits.

From there, the core gameplay loop begins:

  • AI Storyteller & Illustrator: The player is dropped into the world of Veridia. The game's narrative, generated in real-time by the Google Gemini API, unfolds text by text. Crucially, each narrative block is accompanied by a unique, AI-generated image in a "fantasy journal sketch" style, visually grounding the player in the scene.

  • Unprecedented Player Agency: Instead of a simple choice A or B, players are presented with two suggested actions and a text box. They can follow the suggested paths or type in any action they can imagine. The AI Dungeon Master then incorporates that custom action into the evolving story.

  • Integrated Learning: As the story touches on topics like water pollution or biodiversity, the game seamlessly unlocks "Scrolls of Wisdom"—short, digestible learning materials. Later, it might present a "Knowledge Check" quiz to reinforce these concepts, rewarding correct answers with more credits.

  • RPG Staples: The experience is wrapped in familiar RPG mechanics, including an inventory for magical, eco-friendly items and a shop to spend earned Carbon Credits, all presented within a cohesive, nature-themed journal UI.

How we built it

The magic of Terra Tales is in its simplicity and its powerful use of AI.

  • Frontend & Styling: We built the application with React and TypeScript, keeping the architecture lean and focused. Styling was achieved with a combination of TailwindCSS for rapid, responsive layouts and custom CSS to implement the intricate "journal" theme, from the parchment background and rustic wooden buttons to the floral corner motifs. The Cutive Mono Google Font was chosen to complete the thematic, typewriter-esque feel.

  • The AI Core (Google Gemini): The entire dynamic experience is orchestrated by a few key calls to the Gemini API.

    • Narrative Engine: We use gemini-2.5-flash for its impressive balance of speed and narrative quality. The real breakthrough was leveraging its JSON Mode with a strict responseSchema. This allows us to ask the model for the story, choices, and optional learning materials or quizzes, and receive a perfectly structured, ready-to-use JSON object every time. This completely bypasses the need for fragile text parsing and makes the integration robust.
    • Dynamic Imagery: The beautiful sketches that accompany the story are generated by gemini-2.5-flash-image-preview. We meticulously crafted a prompt that instructs the model to produce images in the style of "an intricate, fantasy journal sketch with floral and nature motifs," which gives the game its signature visual identity.
    • Carbon Credit Calculation: The custom task evaluation on the intro screen is also handled by gemini-2.5-flash. We provide a prompt that sets the context of the game and ask for an integer value between 1 and 15, again using a JSON schema to ensure we get a clean, numerical output.

Challenges we ran into

  • Maintaining Narrative Focus: Giving the player a custom text input is powerful, but it's also a fast way to derail the story. Our primary challenge was prompt engineering. We refined the "Dungeon Master" prompt to continuously provide the "story so far" and clear instructions to gently guide the narrative back to the core environmental themes, regardless of the player's input.

  • Performance of On-the-Fly Image Generation: Generating an image takes a few seconds. To ensure a fluid user experience, we architected the GameScreen to load the narrative text first, allowing the player to begin reading immediately. The image loads in parallel, accompanied by a thematic loading message ("An artist spirit is sketching the scene..."), replacing the placeholder once it's ready.

  • Balancing Education and Fun: We had to iterate on the AI's instructions to prevent it from delivering a "learning material" on every single turn. The key was to prompt it to identify only the most relevant moments for a lesson and to make quizzes a rare, rewarding event rather than a constant test.

Accomplishments that we're proud of

  • The Immersive UI/UX: The journal aesthetic is more than just a theme; it's a core part of the experience. Every element, from the font to the button styles, works to suspend disbelief and draw the player into the world. It feels less like an app and more like a magical object.

  • The Custom Action System: Allowing players to type their own actions and see the world react is a huge step beyond traditional multiple-choice narrative games. It's a testament to how far LLMs have come in understanding and continuing a conversational context.

  • The Real-World to In-Game Bridge: The system for logging real-world actions is our proudest accomplishment. It fulfills the project's primary mission by creating a positive feedback loop where pro-environmental behavior is directly and immediately rewarded within a context the player enjoys.

What we learned

  • Prompt Engineering is a Design Discipline: Crafting the prompts for our AI was as much a UI/UX design task as it was a technical one. The words you choose directly shape the user's experience.

  • Structured Output is a Game-Changer: Gemini's ability to reliably return structured JSON is what elevates this from a cool tech demo to a workable application architecture. It's the key to building stateful, predictable applications on top of generative models.

  • Anticipate, Don't Just Wait: When dealing with asynchronous AI responses (especially images), designing thoughtful loading states is critical. A simple spinner is functional, but a thematic, in-world message maintains immersion and manages user expectations beautifully.

What's next for Terra Tales

The world of Veridia has only just begun to grow. We have a long list of features we're excited to explore:

  • Persistent World State: Implementing longer story arcs where player choices have a lasting, visible impact on the game world—for example, seeing a river run clean or a village's crops flourish after a quest.

  • Character Progression: Adding a simple skill system tied to climate action, allowing players to become better at Restoration, Community Organizing, or Innovation.

  • A Visual Economy: Generating unique images for inventory and shop items to make the world feel even richer.

  • Community Goals: Introducing server-wide challenges where all players contribute towards healing a part of Veridia, fostering a sense of collective action.

"Terra Tales" has been a rewarding journey, demonstrating that with the right design and the power of modern AI, we can create experiences that are not only fun but also genuinely inspiring.

Built With

Share this project:

Updates