Spatial Context in the Web SDK
Make NPCs react to where they are: location, time of day, and weather from your game state.
Spatial context is how your game tells an NPC where it is standing. Send a location, optionally a time of day and weather, and the next replies naturally reference them: the rain, the late hour, the noise of the market. One call, no schema to design.
The call
spatial-context.ts
connection.setSpatialContext("Market Square", {
timeOfDay: "midnight",
weather: "heavy rain",
});locationRequired. A semantic place name the NPC can speak about: "Market Square", "The Hollow Lantern", "the north gate".
opts.timeOfDayOptional. Freeform: "dawn", "midday", "midnight". Use whatever vocabulary fits your world.
opts.weatherOptional. Freeform: "clear", "heavy rain", "sandstorm".
When to send it
Send spatial context when the situation changes, not on every chat turn. The natural hooks are zone/area transitions, your day-night cycle rolling over, and weather changes. The values are deliberately short-lived server-side (they expire after several minutes), so a stale update never haunts a conversation — just send a fresh one whenever the world moves on.
Fire-and-forget
setSpatialContext sends over the same WebSocket connection as chat, and there is no acknowledgment frame — success and failure both produce no response. Call it and move on; the next chat turn will reflect it.Let it surface on its own
You do not need to prompt the NPC to mention the environment. With context set, a tavern keeper at midnight in a storm will tell the player to dry off by the fire without being asked. The strongest use is exactly this kind of unprompted color.
Concept deep-dive
For what spatial context is (and is not) at the platform level, see the core concept page: Spatial Context.