BreakEscape/docs/NPC_ITEM_GIVING_EXAMPLES.md

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:

{
  "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:

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:

=== 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:

=== 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:

=== 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:

// 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:

=== 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:

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