Major simplification to migration plan:
- Remove NpcScript model entirely
- Reduce to 2 tables: missions (metadata) + games (state + scenario snapshot)
- Serve ink files directly from filesystem via game endpoints
- Move scenario_data to game instances (enables per-instance randomization)
- Eliminates Issue #2 (NPC schema complexity)
- Reduces P0 fixes from 10 hours to 2-3 hours
- Much simpler seed process (metadata only)
- Identify 5 critical issues requiring fixes before implementation
- Validate architecture decisions (mostly solid)
- Provide corrected database schema for shared NPCs
- Document P0 fixes needed: Ink compilation, file structure, NPC schema
- Recommend 1.5 days of prep work to save 3-5 days of rework
- Total review: 6 documents covering issues, architecture, and solutions
Generated by automated codebase analysis.
Provides detailed breakdown of project structure, systems, and components.
Referenced by updated migration plans.
Updated migration plans to reflect significant codebase evolution:
NEW SYSTEMS DOCUMENTED:
- NPC system (fully implemented with NPCManager, conversation state, events)
- Event system (80+ events across codebase)
- Global game state management (window.gameState.globalVariables)
- Multiple scenarios (24 total, up from 1 originally planned)
KEY UPDATES:
- UPDATED_MIGRATION_STATUS.md: Comprehensive status of what's changed
- What's implemented vs what still needs server-side integration
- Updated timeline: 22 weeks (was 18 weeks)
- New database schema requirements
- Updated risk assessment
- CLIENT_SERVER_SEPARATION_PLAN.md: Added 3 new systems
- System 5: NPC System (hybrid approach confirmed)
- System 6: Event System (selective logging)
- System 7: Global Game State (server as source of truth)
- Updated migration checklist: 9 phases (was 7)
- Updated timeline: 18-22 weeks
- README_UPDATED.md: New master index document
- Quick start guide
- Document index
- What's changed summary
- Timeline breakdown
- Architecture decisions
- Success metrics
MIGRATION APPROACH:
- Hybrid NPC approach: Scripts client-side, validation server-side
- Selective event logging: Critical events only
- State sync: Server as source of truth, client cache for performance
- Incremental rollout with dual-mode support
TIMELINE: 22 weeks (~5.5 months)
- Added 4 weeks for NPC, Event, State integration
- Original: 18 weeks → Updated: 22 weeks (+22%)
All plans are complete, self-contained, actionable, and feature-focused.
Ready for team review and implementation.
Create comprehensive Ink dialogue files for five security tools:
- Kali Linux: Overview and getting started guide
- nmap: Port scanning and network discovery
- Metasploit: Finding and running exploits
- chmod: File permissions and usage
- nikto: Web vulnerability scanning
Each file provides interactive educational content with:
- Multiple topic branches for different aspects
- Practical examples and use cases
- Step-by-step instructions
- Security and ethical usage reminders
- Navigation between related topics
These files can be included in game scenarios to provide
contextual help to players learning security tools.
- Remove ready_for_practice and challenge_tips sections
- Update encoding_encryption.ink header and start section
- Clean exploitation.ink and post_exploitation.ink references
- Ensure all files use consistent game narrative format
- exploitation.ink
- post_exploitation.ink
- phishing_social_engineering.ink
- encoding_encryption.ink
- feeling_blu_ctf.ink
All files now use consistent Haxolottle character and conversational tone
- Add nmap_basics.ink, metasploit_basics.ink, netcat_basics.ink as reusable tools
- Completely rewrite intro_linux.ink:
- Remove all unnecessary tracking variables
- Change from 'Tech Instructor' to 'Haxolottle'
- Remove lab/training/exercise language
- Convert to helpful NPC offering to explain concepts
- Keep all technical content but make conversational
- Link to reusable tool files where appropriate
- Use proper ink patterns (hub structure, #exit_conversation)
- Copy all lab sheets to game_scenarios/ for narrative conversion
- Add dead_drop_system.ink explaining ENTROPY's flag-based communication
- Prepare for converting educational labs into game challenges
Converts introducing_attacks/1_intro_linux.md into interactive dialogue:
- Tech Instructor NPC guides through Linux basics
- Hub structure for major topics: command-line, vi, piping, redirection, networking, SSH, Hydra
- Each topic has short explanations with deep-dive options
- Commands reference section
- Challenge tips for practical exercises
- Progress tracking and instructor rapport system
Game-based learning replacement for traditional lab sheets.
- Remove inconsistent 5-cell (ALPHA/BETA/GAMMA/DELTA/EPSILON) structure
- Update all organizational LORE to reference 11 established cells:
* Digital Vanguard, Critical Mass, Quantum Cabal
* Zero Day Syndicate, Social Fabric, Ghost Protocol
* Ransomware Incorporated, Supply Chain Saboteurs
* Insider Threat Initiative, AI Singularity, Crypto Anarchists
Changes:
- STRAT_001: Add postscript explaining evolution from 5 to 11 cells
- TECH_TOOL_001: Update to reference Critical Mass (not DELTA)
- ENTROPY_PERSONNEL_001: Update Cascade to match Critical Mass member Dr. Sarah Winters
- ENTROPY_OPS_001: Update to reference Digital Vanguard and Insider Threat Initiative
- ENTROPY_HISTORY_001: Note early cell evolution to specialized structure
- PROTO_CELL_001: Remove specific cell designation examples
- TRAIN_RECRUIT_001/TRAIN_OPSEC_001: Remove cell-specific references
- README_ORGANIZATIONAL_LORE: Remove OPCOM_001, update all references
Deletions:
- OPCOM_001: Removed Phase 3 coordination doc (inconsistent with universe bible)
This brings all organizational LORE into consistency with established universe bible.
Created interconnected LORE fragment collection revealing ENTROPY's
world through discoverable artifacts. Organized by content type and
artifact format for progressive player discovery.
**Structure:**
- 4 content categories: ENTROPY Intelligence, The Architect,
Character Backgrounds, Location History
- 7 artifact types: encrypted comms, intelligence reports, text notes,
emails, voice messages, corporate docs, personal items
- Progressive revelation: early game intro → mid game connections →
late game master plan
**10 Seed Fragments Created:**
ENTROPY Intelligence (5):
- Operation Glass House completion report (cell communication)
- Dead drop server list (compromised infrastructure)
- Thermite.py tool analysis (The Architect's signature)
- Operative "Cascade" profile (true believer)
- Complete organizational history (2015-2025, Phase 3 timeline)
The Architect (2):
- Philosophical manifesto on inevitability (ideology revealed)
- Phase 3 activation directive (July 15, complete master plan)
Character Backgrounds (3):
- Sarah Martinez confession email (insider threat desperation)
- Marcus Chen final voice message (civilian courage, survived!)
- Agent 0x99 axolotl philosophy (regeneration vs entropy)
Location History (1):
- Vanguard Financial complete history (25 years, breach, recovery)
**Key Features:**
- Interconnected narrative web (fragments reference each other)
- Educational value (CyBOK-aligned security lessons)
- Moral complexity (sympathetic characters on both sides)
- Emotional impact (personal stories, real consequences)
- Progressive mystery (builds understanding over time)
- Master catalog tracking all connections and discovery timing
**Thematic Elements:**
- ENTROPY: "For entropy and inevitability" - thermodynamic philosophy
- SAFETYNET: "For regeneration and resilience" - axolotl metaphor
- Phase 3: July 15, 2025 - infrastructure-wide coordinated attack
- Moral gray areas: desperate people, true believers, ethical constraints
Fragments demonstrate sophisticated threat actor (ENTROPY) with
decade-long planning, ideological commitment, and custom tooling,
opposed by dedicated defenders (SAFETYNET) who regenerate after
every setback.
See story_design/lore_fragments/MASTER_CATALOG.md for complete
interconnection map and expansion guidelines.
Create design document explaining how CTF flags integrate into
Break Escape's narrative through ENTROPY's dead drop system.
Key concepts:
- Flags as ENTROPY coordination messages
- Drop-site terminals hidden in plain sight
- Why physical presence is required for infiltration
- Flag reward categories (equipment, intel, access, story)
- Complete gameplay loop from briefing to debrief
- Sample Ink dialogue for character interactions
This system allows SecGen CTF scenarios to be embedded
narratively while providing tangible gameplay progression.
Updated both INK_BEST_PRACTICES.md and NPC_HUB_ARCHITECTURE.md to
accurately document the conversation flow pattern we're using.
Key Corrections:
1. Personal Conversations:
- Return to mission_hub WITHOUT #end_conversation tag
- This allows seamless return to hub menu
- Player can choose more topics without closing UI
2. Exit Options:
- Located in mission_hub knot
- Use pattern: #end_conversation -> mission_hub
- Tag closes UI while preserving state at mission_hub
- NOT -> DONE (which doesn't preserve hub state)
3. Flow Documentation:
- Added clear step-by-step flow examples
- Updated "How It Works" sections
- Fixed all code examples to show correct pattern
- Updated checklists and quick reference sections
4. Common Mistakes:
- Added examples of WRONG patterns (tag in personal endings)
- Added examples of CORRECT patterns (tag only in exit options)
- Clarified why each approach matters
5. Tag Name Updates:
- Changed references from old #exit_conversation to #end_conversation
- Updated all game engine integration notes
This ensures documentation matches the actual implementation in
chen_hub.ink, netherton_hub.ink, and haxolottle_hub.ink.
Applied the same conversation flow fix from chen_hub.ink to the other
two NPCs. Exit options now properly preserve state at mission_hub while
closing the conversation.
Pattern Applied:
#end_conversation
-> mission_hub
Instead of:
#end_conversation
-> DONE
This ensures:
1. Exit options close the conversation minigame (#end_conversation tag)
2. Story state is preserved AT mission_hub (not DONE)
3. Next conversation resumes from mission_hub with all options available
4. Player can have multiple conversation topics before choosing to exit
Files Updated:
- netherton_hub.ink (2 exit options)
- haxolottle_hub.ink (2 exit options)
Recompiled all hub JSON files.
All three NPCs now have consistent conversation flow behavior.
Fixed issue where personal conversations were closing the entire interaction
instead of returning to mission_hub menu.
The Problem:
- Personal conversation endings had #end_conversation tag before -> mission_hub
- This caused the entire conversation to close when personal chat ended
- Player couldn't access mission_hub menu options after personal conversations
The Fix:
- Removed #end_conversation tags from conversation_end knots in ongoing_conversations
- Personal conversations now return to mission_hub WITHOUT closing
- Player sees mission_hub menu again with all available options
- #end_conversation tag remains ONLY in mission_hub exit options
Correct Flow Now:
1. Player chooses personal conversation topic at mission_hub
2. Has personal conversation
3. Personal conversation ends -> mission_hub (no tag)
4. Player sees mission_hub menu again
5. Player can continue with other options OR choose exit
6. Exit option has #end_conversation -> DONE (closes conversation)
Files modified:
- dr_chen_ongoing_conversations.ink
- netherton_ongoing_conversations.ink
- haxolottle_ongoing_conversations.ink
Recompiled all hub JSON files.
Consolidated all ink source files into scenarios/ink directory for better
organization. All ink source files and documentation are now in the same
location as their compiled JSON output.
Changes:
1. Moved all .ink source files from story_design/ink/ to scenarios/ink/
- chen_hub.ink and supporting files
- netherton_hub.ink and supporting files
- haxolottle_hub.ink and supporting files
- All other ink source files
2. Moved documentation files to scenarios/ink/
- INK_BEST_PRACTICES.md
- NPC_HUB_ARCHITECTURE.md
- ONGOING_CONVERSATIONS_README.md
- README.md
3. Added scripts/compile-ink.sh
- Automatically compiles all .ink files in scenarios/ink/
- Outputs JSON to the same directory
- Shows colored output with success/failure status
- Provides compilation summary
Usage:
./scripts/compile-ink.sh
This consolidates the ink development workflow into a single directory
and provides an easy way to recompile all ink files after making changes.
Implemented proper handling for the #end_conversation tag to automatically
close the conversation UI without requiring manual ESC key press.
Changes:
1. Added event listener for 'npc-conversation-ended' event in setupEventListeners()
- Saves NPC state when event is received
- Automatically ends minigame and returns to game
- Verifies event is for current NPC
2. Updated showCurrentDialogue() to detect graceful conversation endings
- Checks for #end_conversation tag when story reaches hasEnded
- If tag present, waits for event handler instead of showing manual exit message
- Preserves manual exit message for unexpected/error END states
Flow:
- Ink script: #end_conversation -> DONE
- PhoneChatConversation processes tag and dispatches npc-conversation-ended event
- PersonChatMinigame receives event and automatically closes
- Player sees smooth transition back to game
This eliminates the "(End of conversation - press ESC to exit)" message
for normal conversation endings while preserving it as a safety fallback.
Fixes issue where choosing conversation exit options would show
"reached end of story" console message. All mission_hub exit points
now use:
#end_conversation
-> DONE
Instead of:
#end_conversation
-> END
This preserves conversation state at mission_hub while cleanly
ending the interaction without triggering ink's end-of-story behavior.
Updated hub files:
- chen_hub.ink
- netherton_hub.ink
- haxolottle_hub.ink
Recompiled all hub JSON files to reflect changes.
BREAKING CHANGE: Unified relationship variable naming
Old System (Per-NPC Variables):
- Dr. Chen: npc_chen_rapport with #rapport_gained/lost tags
- Director Netherton: npc_netherton_respect with #respect_gained/lost tags
- Haxolottle: npc_haxolottle_friendship_level with #friendship_gained/lost tags
New System (Unified Influence):
- Dr. Chen: npc_chen_influence with #influence_gained/lost tags
- Director Netherton: npc_netherton_influence with #influence_gained/lost tags
- Haxolottle: npc_haxolottle_influence with #influence_gained/lost tags
Benefits:
- Consistent scoring system across all NPCs
- Simpler to understand and balance
- Unified tag system (#influence_gained/lost)
- Messages still customized per NPC based on their personality
Files Changed:
- dr_chen_ongoing_conversations.ink: rapport → influence
- chen_hub.ink: rapport → influence
- netherton_ongoing_conversations.ink: respect → influence
- netherton_hub.ink: respect → influence
- haxolottle_ongoing_conversations.ink: friendship_level → influence
- haxolottle_hub.ink: friendship_level → influence
- PersonChatConversation.js: Updated getInfluenceMessage() for unified system
- Now detects NPC ID and provides appropriate messages
- Supports legacy tag names for backward compatibility
- INK_BEST_PRACTICES.md: Updated all examples and documentation
- Variable naming conventions
- Tag system documentation
- All code examples
- NPC-specific sections
- NPC_HUB_ARCHITECTURE.md: Updated influence system documentation
- Recompiled all hub JSON files
Messages by NPC:
- Dr. Chen: "Dr. Chen appreciates that" / "Dr. Chen is disappointed"
- Netherton: "Director Netherton approves" / "Director Netherton is displeased"
- Haxolottle: "Haxolottle likes that" / "Haxolottle seems disappointed"
All files compile successfully with unified influence system.
