u/ScratchJolly3213

Hi AIgamedev,

I'm a school psychologist who taught himself to code and built an open-source platform called AlloFlow (~650K lines). Most of the platform is an AI-powered content creation tool for education, but the part I want to talk about here is the game engine layer, because it uses generative AI in ways I think this community would find interesting.

There are three game systems: an AI-driven interactive fiction engine (Adventure Mode), 80+ Canvas-based simulations (STEM Lab), and a multiplayer quiz system with competitive modes. All open-source.

Adventure Mode: AI as game master

Adventure Mode takes any source text and turns it into an AI-driven interactive narrative where the player makes choices that affect the story. Think of it as an AI dungeon master that's constrained to teach specific content.

The technical challenges:

• Narrative coherence across turns. Each turn is a fresh Gemini API call. The system prompt includes the full narrative history, current game state, and content constraints. I serialize the story state into a compressed format that captures key plot points, active character relationships, and unresolved threads without replaying every line of dialogue.
• State machine with AI-managed variables. The game tracks XP, energy, health, morale, gold, and custom faction relationships across turns. These can run in AI-managed mode (the model decides resource consequences) or manual mode (educator pre-defines rules). I inject a "resource philosophy" into the system prompt that sets bounds without being prescriptive.
• D20 probability engine. Risky actions trigger a dice roll mechanic. The system generates a probability threshold, rolls a D20, and the narrative branches on success or failure. The AI generates content and difficulty assessment, but the outcome is deterministic. This was the key insight: let the AI write the story, but let math decide the fate.
• Multiple input modes: multiple choice (4 AI-generated options per turn), free response (player types anything, AI adapts), and debate mode (player argues a position, AI evaluates argument quality and shifts a momentum meter).
• Democracy Mode (whole-class multiplayer). The adventure is projected on a screen and students vote on which path to take. Real-time vote aggregation via Firebase. The AI must generate options that are all narratively viable, so no option is an obvious "correct" choice.

The Imagen + image-to-image visual pipeline:

This is the part I haven't seen many projects do well, and I think it's relevant to anyone building AI-driven interactive fiction.

Adventure Mode uses a three-stage image generation pipeline:

1. Character portrait generation (Imagen). When a player creates a character, they define a name, role, and appearance description ("tall, silver hair, blue robe"). The system generates an art-style-aware prompt and sends it to Imagen. Portraits render as pixel-art thumbnails in the adventure UI, but can be generated in any of 5+ preset styles:
   • Storybook (soft watercolor, warm palette, whimsical)
   • Pixel art (16-bit retro, clean sprites)
   • Cinematic (dramatic lighting, photorealistic)
   • Anime (clean linework, manga-inspired)
   • Crayon (children's hand-drawn, playful)
   • Custom (user describes any style in free text)
2. Image-to-image editing (Gemini image edit). After generating a portrait, players can iteratively refine it using natural language. Type "Add green glasses" or "Make the robe red" and the system sends the existing image + edit prompt through the image-to-image API. This is genuinely useful for player agency: kids love customizing their characters, and the iteration loop (generate → refine → refine again) teaches them about how AI image models work.
3. Storybook export with AI illustrations. At the end of an adventure, the system can export the entire narrative as an illustrated HTML storybook. For each major story beat, Gemini generates an image prompt from the narrative text, and Imagen renders a scene illustration in the selected art style. The result is a self-contained illustrated story that the player can keep.

The prompt engineering for visual consistency was tricky. Each image generation call includes the art style prefix, a "NO TEXT, NO LABELS, NO LETTERS" instruction (Imagen loves adding text to images), and scene-specific context. For character portraits, I pass the appearance description verbatim. For scene illustrations, I have Gemini write a concise image prompt (max 80 words) from the paragraph text, focusing on setting, characters, and action, before sending that to Imagen. This two-step approach (text model writes the image prompt, image model renders it) produces much better results than sending raw story text directly to Imagen.

Players can also upload their own photos as character portraits and then use AI editing to stylize them, which creates a really compelling blend of real and generated imagery.

Quiz game modes:

• Boss Battle: The class fights an AI boss together. Correct answers deal damage. The AI generates boss personality and attack flavor text.
• Escape Room: Themed puzzle rooms with cipher puzzles and hint tokens (limited supply). AI generates themes, deterministic code handles puzzle mechanics.
• Team Showdown: AI handles adaptive difficulty, adjusting question complexity based on team performance mid-match.

The prompt engineering challenge specific to games:

1. Separate narrative from mechanics. Let the AI write the story, use deterministic code for state transitions and win/loss conditions. Every time I let the AI manage a mechanical outcome directly, it was inconsistent. The D20 system was the breakthrough.
2. Inject game state as structured data, not prose. Early prompts included state as natural language ("The player has 45 XP..."). Switching to a JSON state block ({"xp": 45, "health": 80, "factions": {"north": "allied"}}) dramatically improved consistency.
3. Constrain option quality. For multiple choice, I explicitly prompt for options that are "all narratively plausible and none obviously correct or suicidal." Without this, the model generates one clearly-best option and three joke options.
4. The context window is your enemy. I compress narrative history by extracting only decision points, active plot threads, and character state, discarding descriptive prose.

The numbers:

• ~650,000 lines of code
• 264+ distinct AI generation calls
• 80+ interactive STEM simulations
• 100+ supported languages
• 5+ art style presets with custom style support

Links:

• Canvas link: https://gemini.google.com/share/8325b98d429b
• Promo website (linked to GitHub repo): https://apomera.github.io/AlloFlow/

What I'm looking for:

• Feedback on the visual pipeline. The two-step prompt approach (text model writes image prompt, image model renders) works but feels like a workaround. Is there a more elegant pattern?
• Narrative coherence at scale. Adventures can run 20+ turns. Context compression works but loses nuance. Better patterns welcome.
• Hybrid AI+deterministic patterns. How do others handle the "AI for narrative, code for mechanics" split?
• Research collaboration. I'm hoping to pilot AlloFlow in any context where there is interest in exploring the impact of AI tools to enhance pedagogical practices.

Happy to answer questions about the game architecture, the image pipeline, or the prompt engineering. Code is open-source if you want to dig in.

Hi Buildinpublic,

I'm a school psychologist who taught himself to code and spent the last several months building an open-source platform called AlloFlow that uses the Gemini API to solve a real-world NLP problem: taking any raw text and transforming it into multiple accessible learning formats (leveled text, visual organizers, glossaries, interactive games, narrated audio) in 100+ languages. It is also one of the best ways to create lessons to teach about AI, since the same tech used to run the app is what students are learning about.

The architecture story is the part I think this community will find most interesting, because it started from a constraint that turned out to be a feature.

The monolith constraint (and why it matters):

AlloFlow started as a single-file app inside Gemini Canvas. If you haven't used Canvas for app development, the key constraint is that your entire application has to live in one artifact. One file. All your React components, all your state management, all your AI orchestration, all your CSS. One file.

That sounds insane, and it kind of is. But here's why I did it anyway:

Most schools in the US deploy Google Education accounts to every student and teacher. That means they already have access to Gemini, which means they already have access to Gemini 3 Flash, Gemini TTS, Imagen, and image-to-image models. These are genuinely powerful AI capabilities that are sitting there, included in the account, and almost nobody is using them for orchestrated workflows.

The insight was: if you can build an AI orchestration layer that runs inside Gemini Canvas, you skip the vendor procurement process entirely. There's no new software to approve, no new accounts to provision, no data processing agreements to negotiate. Teachers open Gemini, open the Canvas app, and they're running a full AI-powered content creation platform using infrastructure their school already owns and has already vetted.

So I built everything in one file. And for a while, it worked.

The CDN extraction discovery:

About 1-2 months in, the monolith was getting unwieldy (as monoliths do). I needed to externalize the UI strings for internationalization, so I moved them to a separate JSON file and loaded them from a CDN.

And then I realized: if UI strings can live on a CDN, what else can?

The answer turned out to be: almost everything. Game engines, STEM lab simulations, TTS integrations, export handlers, prompt libraries, teacher dashboard components. Everything except the core AI orchestration layer (the callGemini abstraction and the state management that coordinates generation passes) could be extracted to CDN-hosted modules that load on demand.

The Canvas monolith became the thin orchestration core, and everything else became modular, independently deployable, and cacheable. The app went from one file to a hub-and-spoke architecture where the hub handles AI calls and state, and the spokes handle rendering, interaction, and domain-specific logic.

For anyone building large apps on top of LLM APIs, I think this pattern is underexplored: keep the AI orchestration layer as thin and centralized as possible, and extract everything else. The orchestration layer is the part that changes most often (new prompt strategies, new model versions, new structured output schemas), so isolating it makes iteration faster.

The deployment spectrum:

This architecture enables a three-tier deployment spectrum where schools can choose their comfort level and migrate over time:

1. Gemini Canvas (zero infrastructure). Teacher opens Gemini, opens the Canvas app. Done. All AI calls go through the Google account the school already provides. No hosting, no config. This is the on-ramp.
2. Firebase hosted (middle ground). The full app deployed as a static site on Firebase. Districts bring their own Gemini API key with the Firebase blaze plan. This unlocks the full feature set (CDN modules, live sessions, STEM Lab) while keeping the client-side-only, no-backend architecture. No student data ever touches a server I control, which is critical for FERPA. Teachers can also deploy with a free tier spark plan but this does not include access to certain models (image + image editing)
3. School Box (pure local, in progress). Docker-based deployment on school hardware running open-source models (Ollama, LocalAI). The callGemini abstraction is model-agnostic, so swapping to a local LLM is a function-level change. Complete data sovereignty. This is the exit ramp for schools that want to eliminate cloud dependencies entirely.

Each tier is a superset of the previous one, and migration is non-destructive. No tier is a dead end.

The core AI challenge:

The fundamental problem is multi-stage content transformation. A teacher pastes in raw text, and the system needs to analyze the content for key concepts, generate multiple derivative resources (each with different constraints: reading level, format, interactivity), maintain semantic fidelity across all outputs (the glossary terms should match the leveled text, which should match the quiz questions), and do it in any target language without losing domain-specific accuracy.

Getting Gemini to produce consistent, structured output across 8+ generation passes on the same source material required a lot of prompt engineering iteration.

Prompt engineering patterns that worked:

• Role-constraint prompting. Each generator has a dedicated system prompt that constrains the model's role and output format. Specific personas ("You are a reading specialist creating a glossary for grade 3 ELL students") dramatically improved quality over generic prompts.
• Structured JSON output. Every generator returns validated JSON, not free text. Downstream components (React renderers, game engines, export pipelines) consume AI output programmatically. The tradeoff: you lose some creative flexibility, but you gain reliability.
• On-the-fly UI language pack generation. Instead of maintaining static translation files for 100+ languages, the app generates a complete UI language pack for any language on demand. The user clicks "Generate New Language," types a language name, and Gemini translates the entire UI string library (~5,000+ keys) in about 30 seconds. The pack is cached in localStorage. A teacher who speaks Tigrinya or Marshallese can have the full interface in their language without me maintaining a translation file. One of the most practical uses of generative AI in the project.
• Context windowing for long documents. For PDF remediation, I built a chunking pipeline that splits large documents into overlapping windows, processes each chunk with accessibility fixes, and reassembles them with structural coherence. I landed on ~16KB windows with 2KB overlap.
• Ground-truth verification. The PDF cleanup pipeline compares every output sentence against the original pdf.js extraction using a diff-based approach, distinguishing intentional accessibility additions from AI hallucination artifacts.
• Vision API fallback for copyrighted content. Gemini's text API triggers RECITATION blocks on copyrighted material. The workaround: fall back to the Vision API with a structure-only prompt that processes layout without reproducing protected text verbatim.

Adventure Mode:

This turns any content into an AI-driven interactive narrative with state tracking (XP, resources, factions) across turns, a D20 probability engine, multiple input modes (multiple choice, free response, debate), and a Democracy Mode where the whole class votes on which path to take. Each turn is a fresh Gemini call with the full narrative context, game state, and pedagogical constraints. It could also be a great experiential way to teach students about AI itself, since they're interacting with the same technology they'd be learning about.

The numbers:

• ~650,000 lines of code
• 264+ distinct AI generation calls across the platform
• 80+ interactive STEM simulations
• 100+ supported languages
• Zero student data stored on any server

Links:

• Canvas link: https://gemini.google.com/share/8325b98d429b
• Promo website (linked to GitHub repo): https://apomera.github.io/AlloFlow/

What I'm looking for from this community:

• Architecture feedback. Is the hub-and-spoke CDN extraction pattern something others have explored? Any gotchas I should watch for at scale?
• Prompt engineering tips. I'm self-taught on all of this. If you see patterns in my approach that could be improved, I'm all ears.
• Local deployment experience. If anyone has run Ollama or LocalAI in production (especially in education or other regulated contexts), I'd appreciate advice on model selection and hardware requirements for the School Box tier.
• Research collaboration. I'm hoping to pilot AlloFlow in any context where there is interest in exploring the impact of AI tools to enhance pedagogical practices.

Happy to answer questions about the architecture, the prompt engineering, or the deployment model. Code is open-source if you want to dig in.