mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-22 19:58:05 +00:00
ad942112cf
Implemented a comprehensive system for carrying variable state between game
scenarios, enabling:
- NPC trust levels to persist across different missions
- Discussion topics tracking to prevent repetitive conversations
- Narrative decisions with consequences in later scenarios
- Flexible scenario ordering (play missions in any order)
## Core Implementation
### New Module: PersistentStateManager
- Created js/systems/persistent-state-manager.js
- Handles loading, merging, and exporting of carry-over variables
- Supports both simple and metadata format for variable definitions
- Deep clones values to prevent reference issues
- Type validation when loading persistent state
- Structured error codes for debugging (PSM_001-005)
### Scenario Integration
- Modified js/core/game.js to load persistent state via URL parameter
- Persistent state loaded from ?persistentState=filename parameter
- Automatic merging with scenario defaults during initialization
- Visual error notification if persistent state file fails to load
- Detailed console logging for debugging merge operations
### Console Commands (js/main.js)
- window.exportPersistentState() - Export current state as JSON
- window.downloadPersistentState(filename) - Download state as file
- window.viewPersistentState() - View formatted persistent state
### Export Triggers
- Added #export_persistent_state Ink tag handler
- Implemented in chat-helpers.js (shared by person-chat and phone-chat)
- Auto-exports state when triggered from Ink conversations
- Delayed export to ensure all variable syncs complete
### Example Files
- Created persistent-states/ directory with README
- Added example-continued-game.json showing state format
- Comprehensive documentation on usage and file format
### Scenario Updates
- Updated scenarios/ceo_exfil.json with carry-over variables
- Added scenario_id field for tracking
- Defined 6 carry-over variables (trust, topics, narrative flags)
- Included 1 session-only variable for comparison
## Variable Format
Metadata format (carry-over):
{
"npc_trust_helper": {
"default": 50,
"carryOver": true,
"type": "number",
"description": "Trust level with helpful contact"
}
}
Simple format (session-only):
{
"temp_variable": "value"
}
## Persistent State File Format
{
"version": 1,
"timestamp": "ISO-8601-timestamp",
"lastScenario": "scenario_id",
"variables": { /* carry-over variables only */ },
"metadata": { "exportedCount": N, "sessionOnlyCount": M }
}
## Usage
Load with persistent state:
index.html?scenario=ceo_exfil&persistentState=my-progress
Export from console:
window.downloadPersistentState('my-progress.json')
Trigger from Ink:
#export_persistent_state
## Testing
Tested loading, merging, exporting, and error handling.
Verified backward compatibility with existing scenarios.
## Future Enhancements
- Server-side persistence (postToServer method ready)
- State versioning and migrations
- Advanced validation (min/max ranges)
- Debug UI panel for editing state
Addresses requirements from planning_notes/state_save/implementation_plan.md
and incorporates improvements from planning_notes/state_save/review1.md