Getting Started

AI NPC Brain - Getting Started

A Unity package that gives your NPCs an LLM-powered brain. NPCs hold conversations, remember facts about the player, track relationship scores, suggest game events (open shop, offer quests, play animations), and validate everything through a configurable whitelist before anything fires.

Unity version: 6000.x (Unity 6)
Render pipeline: URP
Key dependencies: TextMesh Pro, Input System, Newtonsoft JSON (via Unity package)

1. Import the Package

1. Open your Unity project (Unity 6 / URP recommended).
2. Copy or import the Assets/Runtime, Assets/Editor, Assets/Scripts, Assets/Samples, and Assets/Prefabs folders into your project's Assets directory.
3. Make sure the following packages are installed via Window > Package Manager:
4. TextMesh Pro (included with Unity)
5. Input System (com.unity.inputsystem)
6. Newtonsoft JSON (com.unity.nuget.newtonsoft-json)

If you are using the demo scene, also import Assets/Scenes, Assets/Mixamo Character, and Assets/Settings.

2. Create Your NPC's ScriptableObject Assets

You need four ScriptableObject assets per NPC. Create them via Right-click in Project > Create > AI NPC Brain > ...

2a. Persona Definition

Create > AI NPC Brain > Persona Definition

Example persona JSON:

{
  "role": "Alchemist shopkeeper in a fantasy village",
  "traits": ["witty", "cautious", "curious"],
  "goals": ["sell potions", "find rare ingredients"],
  "speech_style": "Speaks in short, precise sentences with dry humor"
}

2b. Brain Config

Create > AI NPC Brain > Brain Config

This controls which LLM provider to use, API keys, generation parameters, and safety limits. Key fields:

2c. Event Catalog

Create > AI NPC Brain > Event Catalog

The catalog is a whitelist of every game event the NPC is allowed to suggest. Each event has: - An eventId (e.g. shop.open, anim.trigger) - A description (shown to the LLM in the prompt) - A list of typed arguments with optional allowed values

Common events to add:

2d. NPC Animation Map (optional)

Create > AI NPC Brain > NPC Animation Map

Maps semantic animation IDs (like nod, wave) to actual Animator trigger parameter names (like Nod, Wave). This lets the LLM pick contextually appropriate animations.

Tip: Use the editor tool Tools > AI NPC Brain > NPC Animation Setup to auto-fill this from your Animator Controller. See Editor Tools.

3. Set Up the Scene

3a. Add the AiNpcBrain Component

1. Create or select the NPC's root GameObject.
2. Add the AiNpcBrain component.
3. Assign your ScriptableObject assets:
4. Persona → your Persona Definition asset
5. Config → your Brain Config asset
6. Event Catalog → your Event Catalog asset
7. Animation Map → (optional) your NPC Animation Map asset

3b. Add a Chat UI

Two sample UIs are provided:

Simple (for prototyping): Add SimpleChatUi to a GameObject and wire up: - brain → the AiNpcBrain component - input → a TMP_InputField - chatLog → a TMP_Text

Full-featured: Add NpcChatUiController to a GameObject and wire up: - brain → the AiNpcBrain component - inputField → a TMP_InputField - sendButton → a UI Button - scrollRect → a ScrollRect - contentRoot → the Content transform inside the ScrollView - messagePrefab → the ChatText prefab from Prefabs/UI/

3c. Wire Up Event Receivers

The AiNpcBrain component exposes an OnAnyNpcEventPayload UnityEvent that fires validated JSON payloads. Connect your receiver(s) in the Inspector:

• For animations: Add NpcAnimationReceiver → assign its OnEventPayload method to OnAnyNpcEventPayload.
• For UI panels: Add AureliaDemoReceiver (or your own receiver) → assign its OnEventFired method to OnAnyNpcEventPayload.

3d. Optional: UI Panel Routing

If you want events like shop.open to actually open panels:

1. Create > AI NPC Brain > NPC UI Bindings — set the NPC ID and it auto-generates window IDs.
2. Add WindowRegistryRuntime to a GameObject in the scene.
3. Add WindowPanelId components to each panel root (shop panel, quest panel, etc.).
4. Use the editor button Auto-Populate From Scene on the WindowRegistryRuntime inspector to discover all panels.

4. Configure Your LLM Provider

Option A: OpenAI (cloud)

1. Get an API key from platform.openai.com.
2. In your Brain Config asset, set:
3. providerMode = OpenAI_Default or OpenAI_Only
4. openAiApiKey = your key
5. openAiModel = gpt-4o-mini (fast and cheap) or gpt-4o (smarter)

Security: For production, set the API key at runtime via script instead of baking it into the asset: csharp brain.config.openAiApiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");

Option B: Ollama (local, free)

1. Install Ollama on your machine.
2. Pull a model: ollama pull llama3.1:8b
3. In your Brain Config asset, set:
4. providerMode = Ollama_Only
5. ollamaBaseUrl = http://localhost:11434
6. ollamaModel = llama3.1:8b

Option C: Mock (offline testing)

Set providerMode to any mode without providing an API key. The system will fall back to MockProvider, which returns canned responses based on keyword matching (useful for testing UI flow without burning API credits).

5. Press Play

1. Enter Play Mode.
2. Type a message in the chat input and press Enter or click Send.
3. The NPC will respond in-character, and may trigger animations or open UI panels.

Check the Console for [AiNpcBrain] log messages if something isn't working.

6. Running the Demo Scene

1. Open Assets/Scenes/AI Brain Demo.unity.
2. The scene comes pre-configured with:
3. Aurelia — a Mixamo character with an Animator Controller
4. Pre-built ScriptableObject assets in Assets/Samples/
5. A chat UI with ScrollView
6. AureliaDemoReceiver for panel routing
7. NpcAnimationReceiver for animation playback
8. DemoCursorUnlock to keep the mouse visible
9. Set your API key in the Aurelia Brain config asset (or run Ollama locally).
10. Press Play and start chatting.

7. Troubleshooting

Next Steps

• Architecture Overview — understand how all the pieces fit together
• Configuration Guide — deep dive into every setting
• Event System — how events are suggested, validated, and dispatched
• API Reference — detailed documentation for every script
• Editor Tools — automate animation setup and catalog sync