mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
Add NPC item giving examples and enhance container UI functionality
- Created a new documentation file detailing usage examples for the NPC item giving system, including immediate and container-based item transfers. - Updated the ContainerMinigame to support additional NPC context, enhancing the user experience when interacting with NPC inventories. - Implemented new NPC configurations in the scenario JSON to demonstrate item giving mechanics and container UI features. - Added an Ink script for the Equipment Officer NPC, showcasing how to present items through the container UI and manage player interactions.
This commit is contained in:
Z. Cliffe Schreuders
271
docs/NPC_ITEM_GIVING_EXAMPLES.md
Normal file
271
docs/NPC_ITEM_GIVING_EXAMPLES.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# NPC Item Giving System - Usage Examples
|
||||
|
||||
This document demonstrates how to use the NPC item giving system with both immediate and container-based approaches.
|
||||
|
||||
## Setup
|
||||
|
||||
NPCs must declare `itemsHeld` array in the scenario JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "equipment_officer",
|
||||
"displayName": "Equipment Officer",
|
||||
"itemsHeld": [
|
||||
{
|
||||
"type": "lockpick",
|
||||
"name": "Lock Pick Kit",
|
||||
"takeable": true,
|
||||
"observations": "Professional lock picking set"
|
||||
},
|
||||
{
|
||||
"type": "workstation",
|
||||
"name": "Analysis Workstation",
|
||||
"takeable": true,
|
||||
"observations": "Portable workstation"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Ink Variables
|
||||
|
||||
Items are automatically synced to Ink variables:
|
||||
|
||||
```ink
|
||||
VAR has_lockpick = false
|
||||
VAR has_workstation = false
|
||||
VAR has_phone = false
|
||||
VAR has_keycard = false
|
||||
```
|
||||
|
||||
Declare only the `has_*` variables you need for your NPC.
|
||||
|
||||
## Usage Pattern 1: Immediate Single Item Transfer
|
||||
|
||||
**Tag:** `#give_item:type`
|
||||
|
||||
**Use Case:** Give one specific item immediately without opening UI
|
||||
|
||||
**Ink Example:**
|
||||
```ink
|
||||
=== give_basic_item ===
|
||||
Here's a lockpick set!
|
||||
#give_item:lockpick
|
||||
Good luck!
|
||||
-> hub
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. Player reads dialogue
|
||||
2. Tag is processed
|
||||
3. First `lockpick` from NPC's `itemsHeld` is added to inventory
|
||||
4. Item is removed from NPC's inventory
|
||||
5. Conversation continues
|
||||
|
||||
**Notes:**
|
||||
- Only gives the first matching item type
|
||||
- No UI overlay
|
||||
- Fast and clean for single items
|
||||
|
||||
---
|
||||
|
||||
## Usage Pattern 2: Container UI - All Items
|
||||
|
||||
**Tag:** `#give_npc_inventory_items`
|
||||
|
||||
**Use Case:** Show all items the NPC is holding for player to choose from
|
||||
|
||||
**Ink Example:**
|
||||
```ink
|
||||
=== give_all_items ===
|
||||
# speaker:npc
|
||||
Here are all the tools I have available. Take what you need!
|
||||
#give_npc_inventory_items
|
||||
What else can I help with?
|
||||
-> hub
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. Tag is processed
|
||||
2. Container minigame opens in "NPC mode"
|
||||
3. Shows NPC's portrait and all items in `itemsHeld`
|
||||
4. Player can take items from container
|
||||
5. Each taken item is removed from NPC's inventory
|
||||
6. Variables updated automatically
|
||||
7. Conversation continues
|
||||
|
||||
**Container UI Features:**
|
||||
- NPC portrait/avatar displayed
|
||||
- "Equipment Officer offers you items" header
|
||||
- Grid of available items
|
||||
- Player can examine each item before taking
|
||||
|
||||
---
|
||||
|
||||
## Usage Pattern 3: Container UI - Filtered Items
|
||||
|
||||
**Tag:** `#give_npc_inventory_items:type1,type2`
|
||||
|
||||
**Use Case:** Show only specific item types from NPC's inventory
|
||||
|
||||
**Ink Example:**
|
||||
```ink
|
||||
=== give_tools_only ===
|
||||
# speaker:npc
|
||||
Here are the specialized tools we have. Choose what you need for the job.
|
||||
#give_npc_inventory_items:lockpick,workstation
|
||||
Let me know if you need anything else!
|
||||
-> hub
|
||||
```
|
||||
|
||||
**Comma-separated types:**
|
||||
```ink
|
||||
// Show lockpicks and keycards only
|
||||
#give_npc_inventory_items:lockpick,keycard
|
||||
|
||||
// Show workstations only
|
||||
#give_npc_inventory_items:workstation
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. Tag parsed for filter types
|
||||
2. Container UI opens showing only matching items
|
||||
3. If NPC has 2 lockpicks, 1 workstation, 1 keycard:
|
||||
- With filter `lockpick,keycard`: shows 2 lockpicks + 1 keycard (not workstation)
|
||||
4. Player can take from filtered list
|
||||
5. Variables updated
|
||||
|
||||
---
|
||||
|
||||
## Advanced Example: Conditional Item Giving
|
||||
|
||||
**Ink Example:**
|
||||
```ink
|
||||
=== equipment_hub ===
|
||||
What tools do you need?
|
||||
|
||||
{has_lockpick and has_workstation and has_keycard:
|
||||
+ [I have all the tools I need]
|
||||
-> thanks_npc
|
||||
}
|
||||
|
||||
{has_lockpick or has_workstation or has_keycard:
|
||||
+ [Show me everything else you have]
|
||||
#give_npc_inventory_items
|
||||
-> equipment_hub
|
||||
}
|
||||
|
||||
+ [I need specialized tools]
|
||||
-> show_tools
|
||||
|
||||
+ [I need security access]
|
||||
-> show_keycards
|
||||
|
||||
+ [I'm good for now]
|
||||
-> goodbye
|
||||
|
||||
=== show_tools ===
|
||||
Here are our specialized tools:
|
||||
#give_npc_inventory_items:lockpick,workstation
|
||||
-> equipment_hub
|
||||
|
||||
=== show_keycards ===
|
||||
Here are the access devices:
|
||||
#give_npc_inventory_items:keycard
|
||||
-> equipment_hub
|
||||
|
||||
=== thanks_npc ===
|
||||
Perfect! Anything else?
|
||||
-> equipment_hub
|
||||
|
||||
=== goodbye ===
|
||||
Come back if you need anything!
|
||||
-> END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Scenario Example
|
||||
|
||||
From `npc-sprite-test2.json`:
|
||||
|
||||
### Helper NPC (Immediate Item Transfer)
|
||||
- Position: (5, 3)
|
||||
- Story: `helper-npc.ink`
|
||||
- Items: phone, workstation, lockpick
|
||||
- Pattern: Uses `#give_item:type` for single items
|
||||
- Demonstrates: Conditional dialogue that adapts to available items
|
||||
|
||||
### Equipment Officer (Container-Based UI)
|
||||
- Position: (8, 5)
|
||||
- Story: `equipment-officer.ink`
|
||||
- Items: 2 lockpicks (Basic & Advanced), 1 workstation, 1 keycard
|
||||
- Pattern: Uses `#give_npc_inventory_items` to show container minigame
|
||||
- Demonstrates:
|
||||
- Container UI with NPC portrait
|
||||
- Multiple items of same type
|
||||
- All items displayed in interactive grid
|
||||
- Items removed from NPC inventory as player takes them
|
||||
- Conversation continues after item selection
|
||||
|
||||
## Container Minigame UI Features (NPC Mode)
|
||||
|
||||
When `#give_npc_inventory_items` is used, the container minigame opens with:
|
||||
|
||||
1. **NPC Portrait/Avatar** - Displayed at top if available
|
||||
2. **Custom Header** - "Equipment Officer offers you items"
|
||||
3. **Item Grid** - Interactive grid showing all held items (or filtered items)
|
||||
4. **Item Details** - Click items to see observations/descriptions
|
||||
5. **Take Items** - Player can take any/all items shown
|
||||
6. **Automatic Updates** - NPC inventory decreases as items taken
|
||||
7. **Variable Sync** - `has_*` variables update in real-time
|
||||
|
||||
Example dialogue flow:
|
||||
```
|
||||
Player: "Show me what you have available"
|
||||
→ Container minigame opens with NPC's items
|
||||
→ Player takes "Advanced Lock Pick Kit"
|
||||
→ NPC inventory now has 1 lockpick instead of 2
|
||||
→ has_lockpick variable remains true (still has items)
|
||||
→ Conversation continues with "What else can I help with?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Event System
|
||||
|
||||
When items are given, the `npc_items_changed` event is emitted:
|
||||
|
||||
```javascript
|
||||
window.eventDispatcher.emit('npc_items_changed', { npcId });
|
||||
```
|
||||
|
||||
This automatically triggers:
|
||||
1. Variables re-sync in Ink
|
||||
2. Conditions re-evaluated
|
||||
3. Conversation state updated
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Declare all `has_*` variables** you'll check in Ink at the top of your story
|
||||
2. **Use immediate giving** (`#give_item`) for story-critical single items
|
||||
3. **Use container UI** when offering multiple items or choices
|
||||
4. **Use filtered container UI** for specialized equipment categories
|
||||
5. **Check variables** in conditions to adapt dialogue based on what's available
|
||||
6. **Remove items as they're taken** - they're automatically removed from NPC inventory
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
To test the NPC item giving system:
|
||||
|
||||
1. Load `npc-sprite-test2.json` scenario
|
||||
2. Talk to "Helper NPC" (5, 3) - demonstrates immediate giving
|
||||
3. Talk to "Equipment Officer" (8, 5) - demonstrates container UI
|
||||
4. Try different dialogue paths to see variable updates
|
||||
5. Verify items appear in player inventory
|
||||
6. Check that NPC inventory decreases as items are taken
|
||||
|
||||
Reference in New Issue
Block a user