> ## Documentation Index
> Fetch the complete documentation index at: https://docs.npcbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & Items

> Detailed guide on how to create and configure events and items globally and in character, including their purpose and usage.

<Info>
  NPC Builder's **Events & Items system** is a cornerstone of in-game interactions. These entities allow you to script dynamic NPC behaviors and customize gameplay responses. Events serve as triggers to drive actions, while items represent objects or tokens used in these actions. Whether reused across your game or set uniquely for specific characters, both events and items are essential to building an immersive narrative and interactive environment.
</Info>

## Create & Configure: Quick workflow

<Steps>
  <Step title="Decide scope: Global vs Character">
    Choose whether the event/item should be reused across many characters (Global) or tailored to a single NPC (Character-level).
    Global → reuse, version centrally, link from repo.\
    Character → bespoke behavior, local overrides.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-items-scope.png" alt="scope-placeholder" />
  </Step>

  <Step title="Global creation (recommended for reuse)">
    Open Settings → Collections → Events or Items → New.
    Fill Name/UID, Description, Type, and Save to collection.
    Use descriptive UIDs to make linking easier (e.g. <code>quest-token-gold</code>).

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-global-create.png" alt="global-create" />
  </Step>

  <Step title="Character-level creation">
    Open a Character → Properties → Events & Items panel → Click “New Event” or “New Item”.
    Fill required fields for the character-specific behavior. Use this when the event/item is unique to that NPC.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-character-create.png" alt="character-create" />
  </Step>

  <Step title="Link global elements to a character">
    In the character’s Events & Items panel choose “Link from Repo”, then select the global event or item.
    Linked items remain managed in Settings; edits there propagate to characters that reference them.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-link-repo.png" alt="link-repo" />
  </Step>
</Steps>

***

## What is an Event? (entity & purpose)

<Info>
  An Event is an entity that represents a triggerable interaction or behavior in the game world. Use events to encode what should happen and when—either as standalone behaviors or as item-driven actions.
</Info>

<Steps>
  <Step title="When to use Events">
    Use events to:

    * Trigger NPC behaviors (dialogue, follow, flee, give item).
    * React to player actions (pick up, talk, trade).
    * Drive quest steps and gameflow.
  </Step>

  <Step title="Benefits of modelling Events explicitly">
    * Reusability: define once and link across characters.
    * Clarity: central place to document intent and outcomes.
    * Composition: combine events with items and quests to build complex interactions.
  </Step>
</Steps>

### Event Types

<Steps>
  <Step title="Action Event">
    Action Events are item‑agnostic behaviors (e.g., "NPC follows player", "NPC starts conversation", "NPC flees"). They describe a direct behavioral change and usually contain the action name, triggering conditions, and optional parameters (duration, range).

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-action.png" alt="action-event" />
  </Step>

  <Step title="Item Event">
    Item Events are associated with a specific item (e.g., "Give token to player", "Consume key to open door"). They define the relationship between an action and an item, including how the item is granted, removed, or checked.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/events-item.png" alt="item-event" />
  </Step>
</Steps>

### Event Definition (fields to fill)

<Steps>
  <Step title="Name / UID">
    Unique identifier used for linking and API calls. Use short, descriptive slugs (e.g. <code>give-quest-token</code>).
  </Step>

  <Step title="Description">
    Human-friendly explanation: purpose, when it runs, and expected outcome.
  </Step>

  <Step title="Type & Parameters">
    Select Action or Item. Provide any parameters (conditions, item UID, quantity, timing).
  </Step>
</Steps>

<Callout type="tip">
  For events that alter game state (give/remove items, complete quests), prefer global definitions to ensure consistent behavior across NPCs.
</Callout>

***

## What is an Item? (entity & purpose)

<Info>
  An Item is a definable object used in gameplay and events: currency, quest tokens, keys, tools, or any tangible entity the game tracks. Items can be used for trade, progression, or story beats.
</Info>

<Steps>
  <Step title="When to create Items">
    * Use Trade items for shops, barter, or economy systems.\\
    * Use Action items for quest tools, keys, or story-specific objects.
  </Step>

  <Step title="Why model Items explicitly">
    * Trackable state: inventory, ownership, counts.
    * Interoperability: referenced by events, quests, and UI.
    * Clear semantics: description and type ensure consistent usage.
  </Step>
</Steps>

### Item Types

<Steps>
  <Step title="Trade">
    Items intended for buying/selling or barter (e.g., "gold coin", "merchant voucher"). Include value, unit, and any trade rules.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/items-trade.png" alt="trade-item" />
  </Step>

  <Step title="Action">
    Items with a gameplay role (e.g., "skeleton key", "ancient map", "quest token"). Typically consumed or checked by Item Events.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/npcbuilder/media/items-action.png" alt="action-item" />
  </Step>
</Steps>

### Item Definition (fields to fill)

<Steps>
  <Step title="Name / UID">
    Unique identifier used by events and inventory systems.
  </Step>

  <Step title="Description">
    Explain role, appearance, and any rules (can be stacked, consumable, tradable).
  </Step>

  <Step title="Type & Metadata">
    Choose Trade or Action; add metadata such as unit, value, or tags used by game systems.
  </Step>
</Steps>

<Callout type="tip">
  Keep item UIDs stable and descriptive. If you expect many variants, use tags or metadata instead of creating many near-duplicate items.
</Callout>

***

<Tip>
  For request schemas, example payloads, and enum lists, open the <a href="/api-reference/introduction">OpenAPI explorer</a>.
</Tip>