Runtime Context

Make NPCs aware of their surroundings and situation.

What Is Context?

Context is information about the current moment that helps NPCs respond appropriately:

Where is the conversation happening?
When is it (time of day, season)?
What’s the atmosphere (peaceful, tense)?
What does the NPC observe about the player?
What just happened in the game world?

Without context, NPCs respond generically. With context, they feel present in your world.

Example: Context in Action

Without context:


Player: Is it safe to travel?
NPC: Travel can be dangerous. Be careful out there.

With context:


{
  "location": "Mountain Pass Guard Post",
  "timeOfDay": "night",
  "weather": "stormy",
  "recentEvents": ["Bandit attacks reported on the eastern road"]
}


Player: Is it safe to travel?
NPC: At this hour? In this storm? The eastern road has bandits, and you
     can barely see your hand in front of your face. Wait until morning.

The NPC now responds with awareness of time, weather, location, and current events.

Context Fields

All fields are optional strings (or string arrays) inside the request’s context object:

Field	Type / Values	What it does
`location`	string — “Blacksmith Shop”	NPC knows their current location
`locationDetails`	string — “Hot, smell of coal and metal”	Adds atmosphere to the location
`timeOfDay`	dawn, morning, midday, afternoon, dusk, evening, night, midnight	Greetings and time references
`weather`	clear, cloudy, rainy, stormy, foggy, snowing	NPCs comment on weather, adjust advice
`atmosphere`	peaceful, tense, festive, eerie, somber, busy, quiet	NPC matches the scene’s mood
`situation`	shopping, combat, exploring, trading	Frames the type of interaction
`npcMood`	string — “cheerful”, “suspicious”, “nervous”	NPC’s current emotional state
`npcActivity`	string — “tending bar”, “patrolling”	What the NPC is doing right now
`playerAppearance`	string — “Battle-worn, bloodied armor”	NPC reacts to what they see
`playerReputation`	string — “Trusted ally”, “Known troublemaker”	How the NPC views the player
`playerVisibleItems`	string[] — [“Royal insignia”]	Notable items the player carries
`nearbyCharacters`	string[] — [“Guard Captain”, “Hooded stranger”]	Other characters present
`nearbyObjects`	string[] — [“Ancient statue”, “Wanted poster”]	Notable objects present
`recentEvents`	string[] — [“Dragon spotted near the village”]	World events the NPC would know about
`custom`	string — “active_quest: … \| faction: …”	Game-specific context that fits nowhere else

Limits: string fields max 200 characters (500 for custom); arrays max 10 items, 100 characters per item; the whole context block max 2,000 characters. The schema is strict — unknown fields are rejected with a 400 error.

Field Examples

Location


location: "Town Square"
locationDetails: "Festival decorations, crowds, music playing"

NPC: "Quite the celebration today! Can barely hear myself think!"

Time


timeOfDay: "midnight"

NPC: "What brings you to my door at this hour? This better be important."

Weather


weather: "stormy"

Player: "Should I head to the mountain?"
NPC: "In this weather? You'd be struck by lightning before you reached the pass."

Atmosphere


atmosphere: "tense"

NPC speaks cautiously, glances around, lowers voice

NPC State


npcMood: "tired"
npcActivity: "closing up the shop"

NPC: "*yawns* Sorry, long day. What can I help you with? We're about to close."

Player Observation


playerAppearance: "covered in blood, carrying a broken sword"

NPC: "Gods, what happened to you? Sit down, let me fetch the healer!"

Nearby Entities


nearbyCharacters: ["Guard Captain Elena"]

Player: "Can you help me with... a sensitive matter?"
NPC: *glances at guard* "Perhaps we should discuss this somewhere more private."

Recent Events


recentEvents: ["Merchant caravan attacked on the northern road"]

Player: "I'm heading north."
NPC: "Be careful. Heard there were attacks on the road just yesterday."

Custom Context

Game-specific context that doesn’t fit other fields goes in the custom string:


{
  "context": {
    "custom": "active_quest: Find the missing merchant | faction_standing: Allied with Silver Hawks | player_class: Warrior"
  }
}

Game engine SDKs provide key-value helpers (e.g. SetCustomContext("faction", "Allied")) that are folded into this single custom string for you.

Sending Context

Via API

Include context in your POST /npc/interact request body:


{
  "text": "What's happening around here?",
  "entityMindId": "em_innkeeper",
  "playerId": "player_001",
  "context": {
    "location": "The Rusty Anvil Tavern",
    "locationDetails": "Crowded evening, music and laughter",
    "timeOfDay": "evening",
    "weather": "rainy",
    "atmosphere": "festive",
    "npcMood": "cheerful",
    "npcActivity": "serving drinks",
    "playerAppearance": "Soaking wet, just came in from the rain",
    "nearbyCharacters": ["Mysterious traveler in the corner", "Local drunk"],
    "recentEvents": ["Festival starts tomorrow", "Strange lights seen in the forest"]
  }
}

Via Game Engine SDK

SDKs provide convenient ways to set context. Example (C#):


// Direct property access
npc.Context.location = "Blacksmith Shop";
npc.Context.timeOfDay = "afternoon";
 
// Helper method for location
npc.SetLocation("Blacksmith Shop", "Hot, smoky, sound of hammering");
 
// Custom context
npc.SetCustomContext("faction_standing", "Allied");

See your SDK’s context documentation for details (e.g., Unity SDK Context System).

Best Practices

Only Send Relevant Context

Don’t send everything. Send what matters for the current conversation.

Too much:


{
  "playerInventory": ["sword", "shield", "50 gold", "healing potion", "bread", "rope", "torch", ...],
  "allNearbyObjects": ["chair", "table", "mug", "barrel", "torch", "window", ...],
  "fullQuestLog": [...]
}

Just right:


{
  "location": "Blacksmith Shop",
  "playerAppearance": "Carrying a broken sword",
  "npcActivity": "Examining weapon on counter"
}

Use Natural Language

Context values should be natural descriptions, not codes.

Avoid:


{
  "playerState": "HEALTH_LOW",
  "relationshipLevel": 75
}

Better:


{
  "playerAppearance": "wounded, moving slowly",
  "playerReputation": "trusted friend"
}

Update Context Just Before Conversations

Don’t update every frame. Update when:

Player initiates conversation
Something significant changes mid-conversation

Keep recentEvents Fresh

Only include events NPCs would plausibly know about:

Recent (last few days)
Local (in their area) or major (kingdom-wide news)
Not secret events they couldn’t know

Test in Playground First

Before implementing in code, test context combinations in the Playground to see how NPCs respond.

Common Patterns

Greeting Based on Relationship


{
  "playerReputation": "returning customer, bought weapons last week"
}

Result: “Ah, welcome back! How’s that blade treating you?”

Reaction to Player State


{
  "playerAppearance": "exhausted, covered in road dust, large pack"
}

Result: “Long journey? You look like you could use a room and a hot meal.”

Environmental Awareness


{
  "timeOfDay": "night",
  "weather": "stormy",
  "atmosphere": "eerie"
}

Result: NPC is nervous, suggests staying indoors, speaks of superstitions about storms.

Quest Awareness


{
  "custom": "active_quest: Find the missing merchant | quest_stage: just started"
}

Result: NPC provides hints appropriate to early quest stage, doesn’t spoil later reveals.

Troubleshooting

Context Seems Ignored

Check field names match exactly (case-sensitive) - unknown fields are rejected with a 400 error
Verify context is included in the request
Keep values within the field limits above
Use Playground to test with verbose logging

Responses Are Too Generic

Add more specific context
Make sure location details are descriptive
Include atmospheric details

NPC Mentions Things They Shouldn’t Know

Review what context you’re sending
Check if recentEvents includes private information
Use restrictions in Entity Mind for sensitive topics

Next Steps

Unity SDK Context System - Context integration for Unity
Entity Minds - Configure how NPCs use context
API Reference - Full context field documentation