storyteller-godot/docs/vibecoding/ProjectPlan.md

Storyteller - Project Plan

Phase 1: Foundation (The Grid & State)

Goal: A walkable 4x4 grid with state persistence, without AI or fancy graphics.

• Setup: Initialize Git, Godot Project (Done).
• Data Structures: Create RoomData, ItemData, GameState resources.
• Map Creation: Create 16 RoomData assets representing the 4x4 grid. Link them via exits.
• Game Manager: Implement GameManager to handle move(direction) logic.
• Debug UI: Simple text label showing "Current Room: [Name]" and buttons for N/S/E/W.
• State Management: Implement Save/Load functionality for GameState.

Testing:

• Verify player can navigate all 16 rooms correctly.
• Verify walls (invalid exits) block movement.
• Verify state persists after restarting the game.

Phase 2: The Brain (AI Integration)

Goal: Replace hardcoded text with LLM-generated narrative and parsing.

• LLM Service: Implement LLMService.gd with HTTPRequest node.
• API Integration: Connect to OpenRouter (test with curl first, then Godot).
• Prompt Engineering: Design the System Prompt to enforce JSON output.
• Input Parsing: Connect User Input Field -> GameManager -> LLMService.
• Action Handling: Parse returned JSON to trigger move_player or get_item.

Testing:

• Verify LLM returns valid JSON.
• Verify "Go North" results in {"type": "MOVE", "target": "north"}.
• Verify narrative text is displayed in the UI.

Phase 3: The Body (Visuals & UI)

Goal: Implement the "Myst-style" visuals and proper UI layout.

• Layout: Create the Main Scene with TextureRect (Background), RichTextLabel (Log), LineEdit (Input), and GridContainer (Minimap).
• Minimap: Implement a dynamic 4x4 grid that highlights the current room.
• Asset Import: Import placeholder images for rooms.
• Dynamic Backgrounds: Update TextureRect when changing rooms based on RoomData.image_path.

Testing:

• Verify background changes on room entry.
• Verify minimap updates correctly.
• Verify text log scrolls properly.

Phase 4: The Conflict (Combat & Items)

Goal: Add gameplay depth with Inventory and Combat.

• Inventory System: Implement pickup_item and use_item. Update UI to show inventory.
• Combat UI: Create a separate Control node for Combat (Enemy Sprite, HP Bars, Action Buttons).
• Combat Logic: Implement turn-based logic (Player Attack -> Calc Dmg -> Enemy Attack -> Calc Dmg).
• LLM Combat: Update System Prompt to handle combat narration ("You strike the goblin!").

Testing:

• Verify items can be picked up and removed from the room.
• Verify combat loop ends correctly (Win/Loss).
• Verify HP updates correctly.

Phase 5: Polish & Juice

Goal: Audio, effects, and refinement.

• Audio Manager: Add background music and SFX (footsteps, hits).
• Feedback: Add screen shake on damage, text typing effect.
• Bug Fixing: Edge case handling (LLM hallucinations, invalid JSON).

MVP Checklist

• 4x4 Navigable Grid
• LLM Narrative Generation
• JSON Action Parsing
• Basic Inventory (Pickup/Use)
• Turn-based Combat (1 Enemy Type)
• Save/Load System