From f8ad0776ce566baa078b3d7eabc3c71c0332fb53 Mon Sep 17 00:00:00 2001 From: "Z. Cliffe Schreuders" Date: Wed, 14 Jan 2026 09:46:32 +0000 Subject: [PATCH] Add Quick Start Guide for Stage 9 implementation (condensed 8-step checklist) --- .../stages/stage_9_prep/QUICK_START_GUIDE.md | 364 ++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 planning_notes/overall_story_plan/mission_initializations/m03_ghost_in_the_machine/stages/stage_9_prep/QUICK_START_GUIDE.md diff --git a/planning_notes/overall_story_plan/mission_initializations/m03_ghost_in_the_machine/stages/stage_9_prep/QUICK_START_GUIDE.md b/planning_notes/overall_story_plan/mission_initializations/m03_ghost_in_the_machine/stages/stage_9_prep/QUICK_START_GUIDE.md new file mode 100644 index 0000000..3879443 --- /dev/null +++ b/planning_notes/overall_story_plan/mission_initializations/m03_ghost_in_the_machine/stages/stage_9_prep/QUICK_START_GUIDE.md @@ -0,0 +1,364 @@ +# Stage 9 Quick Start Guide + +**Mission:** Mission 3 - Ghost in the Machine +**Purpose:** Condensed implementation checklist for rapid startup +**For:** Developers beginning Stage 9 assembly +**Date:** 2025-12-27 + +--- + +## Prerequisites Checklist + +**Before Starting:** +- [ ] Read `/stages/stage_8/validation_report.md` (approval confirmation) +- [ ] Read `/stages/stage_9_prep/IMPLEMENTATION_ROADMAP.md` (full guide) +- [ ] Install Inky editor (https://github.com/inkle/inky) +- [ ] Install Docker Engine 20.10+ and Docker Compose 1.29+ +- [ ] Configure game engine with Ink runtime integration + +--- + +## Critical Path (Minimum Viable Implementation) + +### Step 1: Compile Ink Scripts (4-6 hours) + +**Priority:** ⚠️ CRITICAL BLOCKER + +```bash +# Open each .ink file in Inky editor: +cd planning_notes/.../m03_ghost_in_the_machine/stages/stage_7/ + +# Files to compile (in order): +1. m03_opening_briefing.ink +2. m03_npc_victoria.ink +3. m03_npc_receptionist.ink +4. m03_npc_guard.ink +5. m03_james_choice.ink +6. m03_terminal_vm.ink +7. m03_terminal_cyberchef.ink +8. m03_terminal_dropsite.ink +9. m03_phone_agent0x99.ink +10. m03_closing_debrief.ink +``` + +**Validation:** +- [ ] All 9 files compile without errors +- [ ] .json output files generated +- [ ] Test load in game's Ink runtime + +--- + +### Step 2: Setup VM Network (6-8 hours) + +**Priority:** HIGH (Required for technical challenges) + +```bash +# Create project structure +mkdir -p m03_ghost_vm_network/{distcc,ftp-data,http-data/pricing} +cd m03_ghost_vm_network + +# Copy configurations from /stages/stage_9_prep/vm_infrastructure_setup.md: +# - docker-compose.yml (lines 46-100) +# - proftpd.conf (lines 110-139) +# - distcc/Dockerfile (lines 166-200) +# - distcc/operational_logs.txt (lines 202-236) +# - http-data/pricing/data.txt (lines 256-276) + +# Build and start +docker-compose up -d + +# Verify services +docker ps # Should show 3 running containers +docker exec -it m03_ftp_server nc localhost 21 # Should show ProFTPD banner +``` + +**Validation:** +- [ ] FTP server responds on 192.168.100.10:21 +- [ ] distcc responds on 192.168.100.20:3632 +- [ ] HTTP serves pricing data on 192.168.100.30:80 +- [ ] Player VM can reach all services + +--- + +### Step 3: Create 7 Room JSONs (10-12 hours) + +**Priority:** HIGH (Core gameplay environment) + +**Reference:** `/stages/stage_5/room_design.md` + +**Implementation Order:** +1. Reception Lobby (lines 40-99) - Entry point +2. Main Hallway (lines 154-195) - Hub corridor +3. Conference Room (lines 102-151) - RFID cloning location +4. Server Room (lines 198-309) - Investigation hub ⭐ +5. Executive Wing Hallway (lines 312-341) - Connector +6. Executive Office (lines 344-422) - Victoria's workspace +7. James's Office (lines 426-487) - Moral choice trigger + +**Each Room Needs:** +- Background image (or placeholder colored rectangle) +- Dimensions (GU measurements in room_design.md) +- Interactive props (computers, safes, filing cabinets) +- Exits (directional connections to other rooms) +- Lighting state (daytime/nighttime where applicable) + +**Use Placeholders Initially:** +- Colored backgrounds with room names +- Text labels for interactive objects +- Simple shapes for props + +--- + +### Step 4: Integrate NPCs (6-8 hours) + +**Priority:** HIGH (Core narrative) + +**Critical NPCs:** + +1. **Victoria Sterling** - `m03_npc_victoria.ink` + - Location: Conference Room (daytime), Executive Office (nighttime optional) + - Portraits needed: 5 expressions (neutral, persuasive, defensive, vulnerable, defiant) + - Key variables: `victoria_influence`, `victoria_suspicious`, `victoria_trusts_player` + +2. **Agent 0x99** - `m03_phone_agent0x99.ink` + - Trigger: After `flag{distcc_legacy_compromised}` submitted + - Portrait: `agent_0x99_concerned.png` + - **Critical:** M2 revelation scene + +3. **James Park** - `m03_james_choice.ink` + - Trigger: Examining diary in James's Office + - Portraits: 3 expressions (neutral, guilty, desperate) + +4. **Guard** - `m03_npc_guard.ink` + - Location: Main Hallway patrol (nighttime) + - Detection system required + +5. **Receptionist** - `m03_npc_receptionist.ink` + - Location: Reception Lobby (daytime) + - Simple dialogue tree + +--- + +### Step 5: Implement 4 Core Challenges (8-10 hours) + +**Priority:** HIGH (Gameplay mechanics) + +**Challenge 1: RFID Cloning** (Scenario Initialization) +- Trigger: Player near Victoria in Conference Room +- Mechanic: Stay within 2m for 10 seconds +- UI: Progress bar +- Success: Unlock Executive access + +**Challenge 2: VM Terminal** (Technical Hub) +- nmap scan → `flag{network_scan_complete}` +- netcat FTP banner → `flag{ftp_intel_gathered}` +- curl HTTP + decode → `flag{pricing_intel_decoded}` +- distcc exploit → `flag{distcc_legacy_compromised}` ⭐ M2 trigger + +**Challenge 3: CyberChef Workstation** (Decoding) +- ROT13 decoder (whiteboard message) +- Base64 decoder (HTTP pricing data) +- Hex decoder (client roster) +- Cascading: Base64→ROT13 (LORE Fragment 3) + +**Challenge 4: Safe PIN Entry** +- Location: Server Room safe +- PIN: 2010 (from Reception founding plaque) +- Contains: LORE Fragment 2 (Exploit Catalog) + +--- + +### Step 6: Objectives System (4-6 hours) + +**Priority:** HIGH (Player guidance) + +**Reference:** `/stages/stage_4/objectives.json` + +**Structure:** +- 3 Aims: `establish_cover`, `network_recon`, `gather_evidence` +- 11 Primary tasks +- 4 Optional objectives + +**Progressive Unlocking:** +- `network_recon` unlocks when `clone_rfid_card` completes +- `gather_evidence` unlocks when `clone_rfid_card` completes +- `moral_choices` unlocks when `distcc_exploit` completes (M2 revelation) + +**Task Completion Triggers:** +- Ink tag: `#complete_task:` +- Flag submission: Auto-complete corresponding task +- Object interaction: Examining LORE fragment + +--- + +### Step 7: M2 Revelation Event (2-4 hours) + +**Priority:** ⭐ CRITICAL (Emotional turning point) + +**Trigger Sequence:** +1. Player exploits distcc service +2. Submits `flag{distcc_legacy_compromised}` at drop-site terminal +3. Operational logs display: "$12,500 hospital exploit sale to GHOST" +4. **Phone call initiates:** Agent 0x99 reveals St. Catherine's Hospital attack + +**Requirements:** +- Phone call overlay UI +- `m03_phone_agent0x99.ink` dialogue integration +- Portrait change: `agent_0x99_concerned.png` +- Music cue: M2 revelation sting +- Unlocks: `moral_choices` optional objective + +**Emotional Impact:** This is the mission's emotional climax. Test multiple times to ensure timing and delivery are effective. + +--- + +### Step 8: Basic Testing (4-6 hours) + +**Priority:** HIGH (Quality assurance) + +**Critical Path Playthrough:** +1. Opening briefing plays correctly +2. Victoria conversation works (RFID cloning triggers) +3. Nighttime transition occurs +4. All 7 rooms accessible with correct exits +5. VM terminal challenges solvable +6. All 4 VM flags validate correctly +7. M2 revelation triggers after distcc flag +8. James choice presents correctly +9. Victoria confrontation offers all options +10. Closing debrief reflects player choices + +**Target Time:** 45-60 minutes for complete playthrough + +**Test Variations:** +- Victoria recruitment ending +- Victoria arrest ending +- James protected vs. exposed +- Perfect stealth achievement + +--- + +## Asset Placeholder Strategy + +**Character Portraits:** +``` +victoria_neutral.png → Colored square with "V" text +james_guilty.png → Colored square with "J" text +agent_0x99_concerned.png → Colored square with "A" text +``` + +**Room Backgrounds:** +``` +reception_bg.png → Solid color (#3A6B8C) with "RECEPTION" text +server_room_bg.png → Solid color (#2C3E50) with "SERVER ROOM" text +``` + +**Interactive Objects:** +``` +computer_sprite.png → Simple rectangle with "COMPUTER" label +safe_sprite.png → Rectangle with "SAFE" label +``` + +**Benefits:** +- Implementation can proceed immediately +- Art team works in parallel +- Swap placeholders for final assets later + +--- + +## Time Estimate (Minimum Viable) + +**Critical Path Only:** +- Step 1 (Ink): 4-6 hours +- Step 2 (VM): 6-8 hours +- Step 3 (Rooms): 10-12 hours +- Step 4 (NPCs): 6-8 hours +- Step 5 (Challenges): 8-10 hours +- Step 6 (Objectives): 4-6 hours +- Step 7 (M2 Event): 2-4 hours +- Step 8 (Testing): 4-6 hours + +**Total:** 44-60 hours (6-8 working days) + +**With Polish:** 68-102 hours (9-13 working days) + +--- + +## Common Pitfalls + +**Ink Integration:** +- ❌ Forgetting to handle `#speaker:` tags +- ❌ Missing `#complete_task:` tags +- ❌ Variable persistence across conversation knots +- ✅ Test each Ink script individually before full integration + +**VM Network:** +- ❌ Containers not on same Docker network +- ❌ Game VM can't reach 192.168.100.x subnet +- ❌ Services not starting (check logs: `docker-compose logs`) +- ✅ Follow VM infrastructure guide exactly (line-by-line) + +**M2 Revelation:** +- ❌ Phone call triggers too early/late +- ❌ Music cue doesn't play +- ❌ Portrait doesn't change +- ✅ Test distcc flag → phone call sequence repeatedly + +**Objectives System:** +- ❌ Tasks don't unlock progressively +- ❌ Flag submission doesn't complete tasks +- ❌ Optional objectives not tracked +- ✅ Verify objectives.json structure matches game's system + +--- + +## Success Checklist + +**Minimum Viable Mission:** +- [ ] All 9 Ink scripts compiled and integrated +- [ ] VM network functional (all 4 flags validate) +- [ ] All 7 rooms accessible with correct exits +- [ ] Victoria conversation (RFID cloning works) +- [ ] M2 revelation triggers correctly +- [ ] James choice presents +- [ ] Victoria confrontation offers 3 options +- [ ] Closing debrief plays +- [ ] Player can complete mission start-to-finish (45-60 min) + +**When Above Complete:** Mission 3 is playable and testable. + +--- + +## Next Steps After MVP + +**Polish Phase:** +1. Replace placeholder assets with final art +2. Add sound effects (flag submission, RFID clone, lockpicking) +3. Add music tracks (4-5 tracks) +4. Implement stealth system (guard patrol) +5. Add LORE fragments (3 documents) +6. Implement accessibility features +7. Playtesting and iteration + +**Future Enhancements:** +1. Post-mission knowledge check +2. Additional LORE fragments (5-6 total) +3. New Game Plus mode +4. Advanced moral choice branches + +--- + +## Support Documents + +**Full Implementation Guide:** `/stages/stage_9_prep/IMPLEMENTATION_ROADMAP.md` (437 lines) +**Asset Requirements:** `/stages/stage_9_prep/asset_manifest.md` (421 lines) +**VM Setup:** `/stages/stage_9_prep/vm_infrastructure_setup.md` (549 lines) +**Validation Report:** `/stages/stage_8/validation_report.md` (1,909 lines) + +--- + +**Quick Start Version:** 1.0 +**Last Updated:** 2025-12-27 +**Status:** Ready for immediate use + +Begin with Step 1 (Ink Compilation) and work sequentially through Steps 1-8 for fastest path to playable mission.