Reactor Logic: Foam Run

Reactor Logic: Foam Run is a React, TypeScript, and Three.js browser game about programming a fictional disaster-response robot through a damaged coastal research reactor. The player assembles command blocks, previews the resulting Python-like pseudocode, then runs or steps through the program to seal stabilizing-foam hotspots, unlock historical records, and reach extraction before the reactor gauge runs out.

The project is intentionally arcade-puzzle focused. The Kuroshio facility, stabilizing foam, reactor systems, and final radioactive Godzilla encounter are fictional gameplay devices inspired by remote-robot disaster response scenarios.

Screenshots

Briefing and robot selection

Robot POV and command editor

Mission tray

Python-like code preview

Sensor hints

AI Copilot panel

Gameplay

Each mission starts with a maze, a robot, one or more unsealed radiation hotspots, a limited foam supply, and a countdown-style reactor gauge. A successful program must move the robot onto every hotspot, deploy foam to seal it, then route the robot to the extraction platform.

Sealing hotspots unlocks historical records in the mission tray archive. Once the player has collected 25 records, the game opens a final overhead arcade battle against radioactive Godzilla. The final battle uses the arrow keys to move, Space to rapid-fire foam shots, and must be cleared before the game is fully won.

The first three levels are fixed training missions:

• Level 1 introduces straight-line sequencing and step mode.
• Level 2 introduces repeat loops and sensor-guarded if blocks.
• Level 3 introduces procedures, procedure calls, if blocks, and while loops.

After level 3, the game stores training completion in localStorage and starts future runs at level 4. Generated levels use seeded randomness, BFS reachability checks, hotspot placement, route estimates, and scaling timers so each mission remains solvable. Level 4+ mazes also receive seeded wall-hole and room-carving passes so generated layouts are less like tight one-cell corridors, with larger clearings around radiation hotspots and the extraction point. Players can also enable Disable training levels (1-3) from the Tools tab to start new runs on generated levels immediately.

Player Tools

• Command List: Click a control module to append it, drag blocks to reorder them, or select a drop slot before adding new blocks.
• CLI mode: Switch from the visual list to a terminal-style command interface for direct command entry. Semicolon-separated batches execute step by step instead of rushing through the full batch instantly.
• Run / Step / Pause: Execute the full program, debug one instruction at a time, or pause a running routine.
• Robot camera / Overhead: Toggle between the first-person robot view and an overhead maze view.
• Pinned map: Keep the minimap visible while programming.
• Mission tray: Open briefing notes, historical archive progress, Sora sensor hints, pseudocode, seed controls, reset tools, and training skip options. Teacher mode (?mode=teacher) also exposes a final-boss playtest button in Tools.
• AI Copilot: In Cloudflare Pages preview/deploy, ask for hints, reviews, next steps, route explanations, or solutions based on the current maze snapshot.

Control Modules

The block palette is intentionally small enough for beginners but expressive enough for nested logic:

• Movement: Move Forward, Turn Left, Turn Right, Deploy Foam
• Conditions: If Then, If Then Else
• Loops: Repeat N, While
• Procedures: Define Procedure, Call Procedure
• Variables: Set Counter, Increase Counter, If Counter
• Memory: Mark Tile

Available condition reads include wall_ahead(), bumped_wall(), on_hotspot(), hotspot_ahead(), at_extraction(), not_at_extraction(), foam_remaining > 0, hotspots_left > 0, radiation_level > value, counter comparisons, current-tile memory checks, and ahead-tile memory checks.

Mark Tile gives players a simple counted memory system for maze-solving logic. The robot can mark its current tile up to two times, then branch on whether the current tile or the open tile ahead is unmarked, marked once, or marked twice. The generated training-solution examples use these memory commands so players can practice exploration strategies rather than only following fixed routes.

Robots

• Kumo Scout: Fastest and most efficient route runner. Starts with extra meltdown time but has no bonus foam.
• Tancho Carrier: Heavier unit with more foam capacity and stronger radiation reduction per seal. Movement costs more time.
• Sora Mapper: Training-focused robot with enhanced sensor hints for step-by-step debugging. It has a lower score multiplier.

Scoring

Scores reward mission completion, radiation reduced, time remaining, action efficiency, compact block use, foam discipline, and the selected robot multiplier. Successful missions earn 1-5 stars based on action efficiency, block efficiency, and remaining reactor time.

The final radioactive Godzilla battle is an end-state challenge rather than a normal maze score event. Winning it stores final-boss completion locally and marks the overall game as cleared.

Local Development

Install dependencies and start the webpack dev server:

npm install
npm start

Open http://localhost:3000/.

Useful checks:

npm run typecheck
npm run build

Cloudflare Pages and AI Copilot

This project is configured to build as a Cloudflare Pages app with a Pages Function at /api/copilot. The copilot sends a compact maze/program snapshot, available blocks, available conditions, and a deterministic shortest-route plan to Workers AI using the AI binding and @cf/google/gemma-4-26b-a4b-it.

Cloudflare Pages Git settings:

• Framework preset: None / custom
• Install command: npm ci
• Build command: npm run build
• Build output directory: dist

Local Pages preview:

npm run pages:preview

The deployed Cloudflare Pages project must have a Workers AI binding named AI. The plain webpack dev server does not serve Pages Functions, so the AI Copilot endpoint is available through Cloudflare Pages preview or a deployed Pages project. The pages:preview script exposes the binding with --ai AI.

Direct upload deploy with Wrangler:

npm run cf:whoami
npm run pages:deploy

The local wrangler.jsonc, .wrangler/, .dev.vars*, and other Cloudflare/account-specific files are ignored so secrets and deployment-specific settings do not get committed. Keep production values in the Cloudflare Pages project settings.

Project Structure

• src/App.tsx: game state orchestration, level flow, training persistence, historical archive unlocks, final-boss trigger, HUD controls, mission tray, AI Copilot drawer, and execution controls.
• src/components/FinalBossMiniGame.tsx: overhead radioactive Godzilla arcade encounter unlocked after 25 historical records.
• src/components/GameScene.tsx: React Three Fiber maze rendering, robot and hotspot visuals, camera modes, lighting, materials, and post-processing.
• src/components/ProgramEditor.tsx: visual command editor, drag-and-drop program ordering, list/CLI tabs, and block editing controls.
• src/components/BlockPalette.tsx: control module rail and training-solution loader.
• src/components/HUD.tsx: mission status, reactor gauge, resource counters, and top-level action buttons.
• src/components/MiniMap.tsx: compact maze overview for pinned and tray views.
• src/components/AiCopilot.tsx: draggable/pinnable Copilot UI and response rendering.
• src/game/mazeGenerator.ts: fixed training levels, seeded generation, wall-hole carving, hotspot/extraction room carving, BFS reachability, route estimates, and training solutions.
• src/game/historicalFacts.ts: ordered historical archive records unlocked by sealing hotspots.
• src/game/routePlanner.ts: shortest-path planning through unsealed hotspots to extraction for Copilot context.
• src/game/interpreter.ts: block execution, nested control flow, sensor reads, safety caps, wall-hit handling, and success/failure checks.
• src/game/blocks.ts: block registry, default block factories, condition metadata, and pseudocode rendering.
• src/game/robots.ts: robot stat definitions and tradeoffs.
• src/game/scoring.ts: score and star calculation.
• functions/api/copilot.ts: Cloudflare Pages Function that validates Copilot requests and calls Workers AI.

Extending the Game

Add a block

Add an entry in src/game/blocks.ts with:

• type, label, category, and description
• createDefaultBlock
• optional childSlots
• interpreter metadata
• toPseudoCode

Then add execution behavior in src/game/interpreter.ts if the block is not a simple primitive or existing control shape. Add the block type to paletteBlockTypes to show it in the palette.

Add a robot

Add a RobotConfig entry in src/game/robots.ts. The game state applies movement costs, foam capacity, foam strength, wall-hit tolerance, sensor hints, and score multiplier from that config.

Tune levels

Adjust the predefined training definitions or generateMaze in src/game/mazeGenerator.ts for maze size, hotspot count, radiation values, foam budget, wall-hole density, room carving, and reactor-gauge scaling. Levels 1-3 are fixed training maps; later levels use seeded randomness plus BFS validation so generated hotspots and extraction remain reachable.

License

Licensed under the GNU Affero General Public License v3.0 only. Modified versions and network-deployed derivatives must provide corresponding source under the same license. Commercial use is allowed when those copyleft obligations are met; closed-source commercial forks are not permitted by this license.