novafarma/docs/ACT1_INTEGRATION_GUIDE.md

🔧 ACT 1 SYSTEMS - INTEGRATION GUIDE

Quick Reference: How to Use New Systems

---

📋 Systems Created:

1. DialogueSystem - NPC conversations
2. TwinBondSystem - Kai ↔ Ana connection
3. QuestSystemExpanded - Main quest tracking
4. QuestTrackerUI - Visual quest display
5. Act1QuestData - 8 quest definitions
6. GrokDialogues - Grok NPC dialogue trees

---

🚀 INTEGRATION STEPS

1. Initialize Systems in GameScene.create():

create() {
    // ... existing code ...
    
    // Initialize new systems
    this.dialogueSystem = new DialogueSystem(this);
    this.twinBondSystem = new TwinBondSystem(this);
    this.questSystemExpanded = new QuestSystemExpanded(this);
    this.questTrackerUI = new QuestTrackerUI(this);
    
    // Load Grok dialogues
    if (typeof GrokDialogues !== 'undefined') {
        Object.keys(GrokDialogues).forEach(key => {
            this.dialogueSystem.registerDialogue(key, GrokDialogues[key]);
        });
    }
    
    // Start first quest after prologue
    this.time.delayedCall(1000, () => {
        this.questSystemExpanded.startQuest('quest_1_1_wake_up');
    });
}

2. Update Systems in GameScene.update():

update(time, delta) {
    // ... existing update code ...
    
    // Update new systems
    if (this.twinBondSystem) {
        this.twinBondSystem.update(delta);
    }
    
    if (this.questSystemExpanded) {
        this.questSystemExpanded.update(delta);
    }
}

---

💬 DIALOGUE USAGE

Start a Conversation:

// When player talks to Grok
const grokNPC = {
    name: 'Grok',
    id: 'grok'
};

this.dialogueSystem.startDialogue(
    'grok_first_meeting',
    grokNPC,
    () => {
        console.log('Conversation ended!');
        // Complete quest objective
        this.questSystemExpanded.completeObjective(
            'quest_1_2_meet_grok',
            'talk_to_grok'
        );
    }
);

---

💞 TWIN BOND USAGE

Show Ana's Message:

// Ana sends telepathic message
this.twinBondSystem.showTelepathicMessage(
    "Kai... I can feel you getting closer!",
    'hope'
);

Use Sense Pulse (F key binding):

this.input.keyboard.on('keydown-F', () => {
    const result = this.twinBondSystem.useSensePulse();
    if (result) {
        console.log(`Ana is ${result.distanceCategory}`);
        // Show direction arrow
    }
});

Change Bond Strength:

// Strengthen bond (positive action)
this.twinBondSystem.changeBondStrength(+10);

// Weaken bond (negative action)  
this.twinBondSystem.changeBondStrength(-5);

---

📖 QUEST SYSTEM USAGE

Start a Quest:

this.questSystemExpanded.startQuest('quest_1_1_wake_up');

Complete an Objective:

//Complete location objective (auto-checks in update)
// Just walk to the location!

// Complete action objective
this.input.keyboard.on('keydown-I', () => {
    this.questSystemExpanded.completeObjective(
        'quest_1_1_wake_up',
        'check_inventory'
    );
});

Update Progress:

// For item collection objectives
this.questSystemExpanded.updateObjectiveProgress(
    'quest_1_5_ana_grave',
    'gather_stone',
    1  // collected 1 stone
);

Check Quest Status:

if (this.questSystemExpanded.isQuestActive('quest_1_2_meet_grok')) {
    console.log('Grok quest is active!');
}

const progress = this.questSystemExpanded.getQuestProgress('quest_1_1_wake_up');
console.log(`Progress: ${progress.percentage}%`);

---

🎮 QUEST TRACKER UI

Auto-Updates:

The QuestTrackerUI automatically updates when quests change.

Toggle:

Press J key to show/hide tracker

Manual Update:

this.questTrackerUI.update(this.questSystemExpanded.getMainQuest());

---

🏃 QUICK START EXAMPLE

Here's a complete example for Quest 1.1 (Wake Up):

// In create()
this.questSystemExpanded.startQuest('quest_1_1_wake_up');

// Location objective auto-completes when player reaches (500, 500)
// Just need to handle inventory check:

this.input.keyboard.on('keydown-I', () => {
    // Player pressed I to open inventory
    this.questSystemExpanded.completeObjective(
        'quest_1_1_wake_up',
        'check_inventory'
    );
});

// Quest will auto-complete when all objectives done
// Then auto-start Quest 1.2 (Meet Grok)

---

🧘 GROK NPC INTEGRATION

1. Spawn Grok:

// Create Grok sprite
const grok = this.add.sprite(1000, 800, 'grok_sprite');
grok.setInteractive();

// On click
grok.on('pointerdown', () => {
    const grokData = { name: 'Grok', id: 'grok' };
    
    // Check which dialogue to show
    if (this.questSystemExpanded.isQuestActive('quest_1_2_meet_grok')) {
        this.dialogueSystem.startDialogue('grok_first_meeting', grokData);
    } else if (this.questSystemExpanded.isQuestActive('quest_1_8_decipher_clues')) {
        this.dialogueSystem.startDialogue('grok_symbol_knowledge', grokData);
    } else {
        this.dialogueSystem.startDialogue('grok_casual', grokData);
    }
});

---

🎯 TESTING CHECKLIST

Test Prologue:

1. ✅ Run game
2. ✅ Click "NEW GAME"
3. ✅ Watch prologue (19 scenes)
4. ✅ Should transition to GameScene

Test Quest System:

1. ✅ Quest 1.1 should auto-start
2. ✅ Walk to (500, 500) → objective completes
3. ✅ Press I → objective completes
4. ✅ Quest 1.2 should auto-start

Test Dialogue:

1. ✅ Spawn Grok NPC
2. ✅ Click Grok
3. ✅ Dialogue appears with choices
4. ✅ Clicking choice advances dialogue

Test Twin Bond:

1. ✅ Wait 60 seconds
2. ✅ Ana should send telepathic message
3. ✅ Press F → Sense Pulse activates
4. ✅ Console shows direction/distance

Test Quest Tracker:

1. ✅ Quest appears in top-right
2. ✅ Objectives show with checkboxes
3. ✅ Press J → tracker toggles
4. ✅ Completing objectives updates UI

---

🐛 DEBUGGING

Check Console:

// Quest status
console.log(this.questSystemExpanded.getActiveQuests());

// Dialogue status
console.log(this.dialogueSystem.isActive());

// Twin Bond status
console.log(this.twinBondSystem.getBondStrength());

Common Issues:

Quest not starting:

• Check if Act1QuestData is loaded
• Verify questId matches exactly
• Check console for errors

Dialogue not showing:

• Confirm GrokDialogues is loaded
• Check dialogue is registered
• Verify speaker data format

Twin Bond not working:

• Wait 60 seconds for first message
• Check if TwinBondSystem initialized
• Use F key to test Sense Pulse

Quest Tracker not visible:

• Press J to toggle
• Check if quest is active
• Verify QuestTrackerUI created

---

📂 FILE LOCATIONS

src/
├── systems/
│   ├── DialogueSystem.js          ← Conversations
│   ├── TwinBondSystem.js           ← Kai ↔ Ana bond
│   ├── QuestSystemExpanded.js      ← Quest tracking
│   └── ZombieSystem.js             ← Already exists!
│
├── ui/
│   ├── QuestTrackerUI.js           ← Visual quest display
│   └── CraftingUI.js               ← Already exists!
│
├── data/
│   ├── Act1QuestData.js            ← 8 quests
│   └── GrokDialogues.js            ← Grok conversations
│
└── scenes/
    ├── PrologueScene.js            ← Story intro
    ├── GameScene.js                ← Main game (integrate here!)
    └── StoryScene.js               ← Main menu

---

🚀 NEXT STEPS

1. Add to GameScene.js:

   • Initialize all 4 systems in create()
   • Add update() calls
   • Start Quest 1.1

2. Spawn Grok NPC:

   • Create sprite at (1000, 800)
   • Add click handler
   • Connect to dialogue system

3. Test Full Flow:

   • Prologue → Quest 1.1 → Meet Grok → Quest chain

4. Add Assets (Optional):

   • Grok character sprite
   • Quest icons
   • Ana portrait for Twin Bond

---

💡 PRO TIPS

Auto-Chain Quests:

Quests automatically start next quest when completed (defined in nextQuest field)

Bond Events:

Twin Bond messages happen automatically every 1-3 minutes. No setup needed!

Location Objectives:

Are checked automatically in update(). Just define the target coordinates!

Dialogue Choices:

Can trigger quest actions, give items, change relationships. Very powerful!

---

✅ QUICK VALIDATION

Run this in browser console after game starts:

// Check all systems loaded
console.log('Dialogue:', !!window.DialogueSystem);
console.log('TwinBond:', !!window.TwinBondSystem);
console.log('QuestExp:', !!window.QuestSystemExpanded);
console.log('Act1Data:', !!window.Act1QuestData);
console.log('Grok:', !!window.GrokDialogues);

// Should all be true!

---

🎉 ALL SYSTEMS READY! INTEGRATE AND TEST! 🎉

---

Last Updated: 2025-12-23
Integration Guide for Act 1
Total Systems: 4 | Total Quests: 8 | Total Dialogues: 4