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():**

```javascript
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():**

```javascript
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:**

```javascript
// 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:**

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

### **Use Sense Pulse (F key binding):**

```javascript
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:**

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

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

---

## 📖 **QUEST SYSTEM USAGE**

### **Start a Quest:**

```javascript
this.questSystemExpanded.startQuest('quest_1_1_wake_up');
```

### **Complete an Objective:**

```javascript
//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:**

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

### **Check Quest Status:**

```javascript
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:**
```javascript
this.questTrackerUI.update(this.questSystemExpanded.getMainQuest());
```

---

## 🏃 **QUICK START EXAMPLE**

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

```javascript
// 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:**

```javascript
// 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:**
```javascript
// 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:

```javascript
// 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*