AI NPCs

An AI NPC is a character powered by a large language model: it talks in character, reacts to what happens in your world, and can do things in it (open doors, change lights, hand out items). You build one by adding an SSAINpc component to a GameObject and configuring it — the brain runs on the server.

The pieces

Piece	What it is
SSAINpc component	The NPC itself — personality, capabilities, links to its actions and voice.
Provider	Which LLM powers it, and the API key — see Providers & keys.
Action manifest	What the NPC can do (actions) and react to (world events), edited in the Action Designer.
NexusScripts	Your code behind custom actions and world events — see Custom Actions and World Events.

Everything travels inside your world when you upload it — there's no server config for you to touch.

Giving it a personality

On the SSAINpc component:

Field	Purpose
npcName	The character's name.
systemPrompt	The core instructions — who they are, how they behave, what they know. This is the personality.
personalitySummary	A short tag (e.g. "gruff blacksmith") used in brief contexts.
additionalContext / knowledgeTags	Extra background the NPC should know.

systemPrompt:
You are Bracken, a gruff but kind blacksmith. You speak in short sentences,
know everything about weapons and armor, and never break character.

Capabilities

Toggle	Effect
enableTextChat	Players can type to the NPC.
enableVoice	The NPC speaks out loud (TTS) and can hear players (STT) — see Voice.
enableImageGeneration	The NPC can generate images (where supported).

Tuning: temperature, maxTokens, maxHistoryLength, enableStreaming, reasoning, and per‑NPC providerOverride / modelOverride.

reasoning (thinking effort) — Default, Off, Low, Medium, High. How much the model "thinks" before replying. Set it per NPC.

• Off is best for most NPCs: fast, direct dialogue. If you run a reasoning model (Gemma, Qwen, o‑series) and leave thinking on, the NPC can waste its whole token budget on hidden reasoning and reply with nothing — Off fixes that.
• Use Low/Medium/High for NPCs that should deliberate (riddle‑masters, strategists, planners).
• Default leaves the model/server's own setting untouched.

This dial sets how much; the wire format is chosen once per provider in the Provider Manager → Reasoning dropdown (or on an AI Provider Profile entry): pick Thinking flag for Gemma/Qwen/local, Reasoning effort for OpenAI o‑series, None for plain models, or Auto to guess from the model name. Picking it explicitly avoids the guesswork.

How players reach it

interactionMode (Proximity / …) with interactionRange controls when a player can talk to it; greetingCooldown and maxConcurrentConversations keep it sane in a crowd. For voice, hearingRange sets how far its speech carries.

What it can do and react to

• Actions — tools the NPC can choose to call: built‑ins (move, emote, look at, play audio, set a light) or your own Custom Actions.
• World Events — facts your scripts hand it ("a player walked up", "the round ended") via NPC.Notify, so it reacts in character.

Both are wired in the Action Designer.

Set one up

1. Add an empty GameObject; add the SSAINpc component.
2. Write its personality (npcName, systemPrompt).
3. Point it at a provider (Providers & keys).
4. (Optional) Open the Action Designer to add actions and world events.
5. (Optional) Turn on Voice.
6. Build and upload your world — the NPC config travels with it.

Test before uploading

Use the in‑editor NPC tester to chat with your NPC and watch its tool calls without a full upload. Turn on debugToolCalls to see exactly what actions it invokes and what they returned.