BreakEscape/TESTING_GUIDE.md

Global Ink Variables - Testing Guide

Quick Start Test

Prerequisites

• Open the game with the npc-sprite-test2.json scenario
• Browser console open (F12)

Test 1: Basic Functionality

1. Verify Initial State

   console.log(window.gameState.globalVariables);
   // Should show: { player_joined_organization: false }
   

2. Start conversation with test_npc_back

   • Click on the back NPC in test_room
   • Follow the conversation through to "player_closing"

3. Make the Join Choice

   • Select "I'd love to join your organization!"
   • Observe NPC response

4. Check Global State

   console.log(window.gameState.globalVariables.player_joined_organization);
   // Should now be: true
   

Test 2: Cross-NPC Syncing

1. Start conversation with container_test_npc (Equipment Officer)

   • Click on the equipment officer NPC
   • Start conversation

2. Observe Menu Options

   • If you joined in Test 1, you should see:
     • "Tell me about your equipment"
     • "Show me what you have available" ← This should appear!
     • "Show me your specialist items"
   • If you didn't join, only the specialist items option appears

3. Verify Variable Synced

   console.log(window.gameState.globalVariables.player_joined_organization);
   // Still true from previous conversation!
   

Test 3: Direct Phaser Access

1. Open Console

2. Directly Set Variable

   window.gameState.globalVariables.player_joined_organization = false;
   

3. Start new conversation with Equipment Officer

   • Full inventory option should now be GONE
   • Only specialist items option appears

4. Set Back to True

   window.gameState.globalVariables.player_joined_organization = true;
   

5. Start conversation again

   • Full inventory option should reappear

Test 4: State Persistence

1. Join organization (if not already done)

   • Complete the test_npc_back conversation
   • Choose to join

2. Talk to Equipment Officer

   • Verify full inventory option is available

3. End conversation

   • Close the minigame

4. Reload the page (F5)

   • Wait for game to fully load

5. Check Global State

   console.log(window.gameState.globalVariables.player_joined_organization);
   // Should still be true!
   

6. Talk to Equipment Officer again

   • Full inventory option should still appear

Debugging Checks

Verify Scenario Loaded

console.log(window.gameScenario.globalVariables);
// Should show: { player_joined_organization: false }

Check All Global Variables

console.log('Global Variables:', window.gameState.globalVariables);
console.log('NPC Cache:', Array.from(window.npcManager.inkEngineCache.keys()));
console.log('Saved States:', window.npcConversationStateManager.getSavedNPCs());

Check Variable Change Events

Add this before starting a conversation:

// Temporarily enable verbose logging
window.npcConversationStateManager._log = (level, msg, data) => {
    console.log(`[${level}]`, msg, data);
};

Then start a conversation and watch the console for variable sync messages.

Verify Ink Variable Names

// Check what variables are in test2.ink story
const test2Engine = window.npcManager.inkEngineCache.get('test_npc_back');
if (test2Engine?.story?.variablesState?._defaultGlobalVariables) {
    console.log('test2.ink variables:', 
        Array.from(test2Engine.story.variablesState._defaultGlobalVariables.keys()));
}

// Check equipment officer
const eqEngine = window.npcManager.inkEngineCache.get('container_test_npc');
if (eqEngine?.story?.variablesState?._defaultGlobalVariables) {
    console.log('equipment-officer.ink variables:', 
        Array.from(eqEngine.story.variablesState._defaultGlobalVariables.keys()));
}

Expected Console Output

When everything is working correctly, you should see messages like:

🌐 Initialized global variables: {player_joined_organization: false}
✅ Synced player_joined_organization = false to story
🔍 Auto-discovered global variable: player_joined_organization = false
🌐 Global variable changed: player_joined_organization = true (from test_npc_back)
📡 Broadcasted player_joined_organization = true to container_test_npc
✅ Restored global variables: {player_joined_organization: true}

Common Issues & Solutions

Issue: Full inventory option never appears

Check:

1. Did you actually choose "Join organization"?

   console.log(window.gameState.globalVariables.player_joined_organization);
   

2. Did the Equipment Officer conversation load?

   console.log(window.npcManager.inkEngineCache.has('container_test_npc'));
   

3. Are the stories properly synced?

   const eqStory = window.npcManager.inkEngineCache.get('container_test_npc').story;
   console.log('Eq Officer has variable:', eqStory.variablesState.GlobalVariableExistsWithName('player_joined_organization'));
   console.log('Value:', eqStory.variablesState['player_joined_organization']);
   

Issue: Variable resets on page reload

Check:

1. Was state actually saved?

   console.log(window.npcConversationStateManager.getNPCState('test_npc_back'));
   

2. Does saved state have global snapshot?

   const state = window.npcConversationStateManager.getNPCState('test_npc_back');
   console.log('Global snapshot:', state?.globalVariablesSnapshot);
   

Issue: Changes not syncing to other NPCs

Check:

1. Are multiple stories loaded?

   console.log('Loaded stories:', Array.from(window.npcManager.inkEngineCache.keys()));
   

2. Does the variable exist in both stories?

   // Check each story's variables
   window.npcManager.inkEngineCache.forEach((engine, id) => {
       const exists = engine.story.variablesState.GlobalVariableExistsWithName('player_joined_organization');
       console.log(`${id}: has player_joined_organization =`, exists);
   });
   

Advanced Testing

Test Auto-Discovery of global_* Variables

1. Create a new Ink file with:

   VAR global_test_flag = false
   

2. Add it to an NPC in scenario

3. Load that NPC's conversation

4. Check console:

   console.log(window.gameState.globalVariables);
   // Should auto-discover: { player_joined_organization: false, global_test_flag: false }
   

Test Modifying from Phaser Code

1. Get reference to game code:

   // In Phaser scene, emit an event
   window.dispatchEvent(new CustomEvent('player-achievement', { 
       detail: { achievement: 'joined_org' } 
   }));
   
   // In listener code:
   window.addEventListener('player-achievement', (e) => {
       window.gameState.globalVariables.player_joined_organization = true;
   });
   

2. Start new NPC conversation

3. Verify variable is synced

Test Multiple Global Variables

1. Update npc-sprite-test2.json:

   "globalVariables": {
     "player_joined_organization": false,
     "reputation": 0,
     "quest_stage": 0
   }
   

2. Add to Ink files:

   VAR player_joined_organization = false
   VAR reputation = 0
   VAR quest_stage = 0
   

3. Use in conditionals:

   {reputation >= 5:
     You're well known around here
   }
   

4. Test syncing multiple variables at once

Success Criteria

✅ Initial state loads with correct defaults ✅ Variable changes persist in window.gameState ✅ Changes sync to other loaded stories in real-time ✅ Menu options conditionally appear based on variables ✅ State persists across page reloads ✅ Console shows appropriate sync messages ✅ No errors in browser console ✅ Multiple variables can be managed simultaneously

Performance Notes

The system is optimized for:

• Few global variables (< 50 per scenario) ✅
• Multiple NPCs (handles all loaded stories) ✅
• Event-driven syncing (only syncs on change) ✅
• No circular loops (prevents infinite propagation) ✅

If testing with > 100 global variables, monitor console for any performance impact.