Spatial Context in Godot
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.gd
connection.set_spatial_context("Market Square", "midnight", "heavy rain")locationRequired. A semantic place name the NPC can speak about: "Market Square", "The Hollow Lantern", "the north gate".
time_of_dayOptional. Freeform: "dawn", "midday", "midnight". Use whatever vocabulary fits your world.
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 area-trigger signals, 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
set_spatial_context sends over the same WebSocket connection as chat, and there is no acknowledgment signal — 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.