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

Location

Where the conversation is happening.

Field	Description	Example
`location`	Place name	”Blacksmith Shop”
`locationDetails`	Additional description	”Hot, smell of coal and metal, sound of hammering”

Effect: NPCs reference their surroundings naturally.


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

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

Time

When the conversation is happening.

Field	Values	Example Effect
`timeOfDay`	dawn, morning, midday, afternoon, dusk, evening, night, midnight	”Good morning!” vs “Working late tonight?”

Effect: NPCs adjust greetings and reference time naturally.


timeOfDay: "midnight"

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

Weather

Current weather conditions.

Field	Values	Example Effect
`weather`	clear, cloudy, rainy, stormy, foggy, snowing	”Lovely day!” vs “Nasty weather out there.”

Effect: NPCs comment on weather, adjust advice accordingly.


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

The mood of the scene.

Field	Values	Example Effect
`atmosphere`	peaceful, tense, festive, eerie, somber, busy, quiet	Affects NPC’s tone and mood

Effect: NPCs match the mood of the environment.


atmosphere: "tense"

NPC speaks cautiously, glances around, lowers voice

NPC State

What the NPC is doing and feeling.

Field	Description	Example
`npcMood`	Current emotional state	”cheerful”, “suspicious”, “nervous”
`npcActivity`	What they’re doing	”tending bar”, “hammering at the forge”, “patrolling”

Effect: NPCs respond consistently with their current 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

What the NPC sees when they look at the player.

Field	Description	Example
`playerAppearance`	Visual description	”Battle-worn, bloodied armor, limping”
`playerReputation`	How NPC views player	”Trusted ally”, “Suspicious stranger”, “Known troublemaker”
`playerVisibleItems`	Notable carried items	”Royal insignia”, “Enchanted sword”

Effect: NPCs react to what they observe.


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

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

Nearby Entities

Other characters and objects in the scene.

Field	Description	Example
`nearbyCharacters`	Array of visible characters	[“Guard Captain”, “Hooded stranger”]
`nearbyObjects`	Array of notable objects	[“Ancient statue”, “Wanted poster”]

Effect: NPCs reference and react to surroundings.


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

Things that happened in the game world that NPCs would know about.

Field	Description	Example
`recentEvents`	Array of event strings	[“Dragon spotted near the village”, “King’s birthday tomorrow”]

Effect: NPCs bring up current events naturally.


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.


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

Effect: Enables game-specific awareness.

Sending Context

Via API

Include context in your API requests:


POST /npc/interact
{
  "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


{
  "customEntries": {
    "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)
Verify context is included in the request
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