Environment

Environment controls world visual atmosphere: skybox, fog, weather, sun, and time-of-day.

Error Handling Pattern

• Success: err == nil
• Failure: err is an error code string

Scope Model

• Server is authoritative for shared world environment state.
• Client can read state and request server changes through shared methods.
• Client-only photo/debug overrides are exposed as explicit local-override methods.
• Environment is visual state, not deterministic physics state.

Node Relationship

• Environment controls global world atmosphere and is separate from node-domain CRUD.
• It complements NodeSharedVisual and NodeClientVisual:
• Environment for global sky/fog/weather/time.
• node domains for discrete visual objects/effects.
• Environment changes must not directly mutate NodeSim deterministic gameplay state.
• The world baseline includes an always-present ocean node managed by runtime (Systems/World/Always/OceanRoot/Ocean); treat it as global world visual infrastructure, not per-resource content.

Resource Arbitration

• Only one effective shared environment state is active at a time.
• When multiple resources request changes, server policy decides precedence.
• Recommended precedence:
• explicit operator/system command
• active map resource
• other resources by priority/order
• Include reason and actor metadata for auditability in change events.
• Use options.priority (negative/positive offset) to tune precedence between competing resources.

Function List

Function	Description	Scope
Environment.GetState	Get effective environment state.	S
Environment.SetState	Replace full shared environment state.	S
Environment.PatchState	Update selected environment fields only.	S
Environment.SetWeatherPreset	Apply a named weather preset.	S
Environment.SetTimeOfDay	Set in-game clock/time-of-day.	S
Environment.GetPresets	List available built-in presets.	S
Environment.SetLocalOverride	Apply local client-only environment override.	C
Environment.ClearLocalOverride	Remove local client-only override.	C

Event List

Event	Description	Scope
world:environment_changed	Fired after shared environment state changes.	S
world:weather_changed	Fired after weather preset/weather fields change.	S
world:time_changed	Fired after time-of-day changes.	S
world:local_override_changed	Fired when local override is applied/cleared.	C

Environment State Shape

Environment.GetState() and change events use this shape:

Field	Type	Description
preset	string or nil	Active preset name, if applied.
sky	table	Sky settings.
fog	table	Fog settings.
sun	table	Sun/light settings.
weather	table	Rain/snow/cloud/wind settings.
time	table	Time-of-day settings.

Common nested fields:

• sky.mode: procedural | physical | panorama
• sky.rotation: number (degrees)
• sky.panorama: string (resource path/id)
• fog.enabled: boolean
• fog.density: number
• fog.color: #RRGGBB
• sun.direction: { x, y, z }
• sun.energy: number
• weather.kind: clear | cloudy | rain | storm | snow
• weather.intensity: number (0..1)
• weather.wind: number (0..1)
• time.hour: number (0..23)
• time.minute: number (0..59)

Functions

Environment.GetState

S Shared (Client & Server)

local state, err = Environment.GetState()

Returns:

• state (table | nil)
• err (nil | string)

Environment.SetState

S Shared (Client Request + Server Authority)

local err = Environment.SetState(state, options)

Parameters:

• state (table): full environment state.
• options (table, optional):
• transitionSeconds (number)
• reason (string)
• priority (number, optional): arbitration offset (-100..100)
• force (boolean, optional, server/system only): bypass precedence checks

Behavior:

• Client call: request routed to server.
• Server call: applies directly.

Environment.PatchState

S Shared (Client Request + Server Authority)

local err = Environment.PatchState(patch, options)

Parameters:

• patch (table): partial state update.
• options (table, optional):
• transitionSeconds (number)
• reason (string)
• priority (number, optional): arbitration offset (-100..100)
• force (boolean, optional, server/system only): bypass precedence checks

Environment.SetWeatherPreset

S Shared (Client Request + Server Authority)

local err = Environment.SetWeatherPreset(name, options)

Parameters:

• name (string): preset id (clear_day, rain_evening, storm_night, ...).
• options (table, optional):
• transitionSeconds (number)
• priority (number, optional): arbitration offset (-100..100)
• force (boolean, optional, server/system only): bypass precedence checks

Environment.SetTimeOfDay

S Shared (Client Request + Server Authority)

local err = Environment.SetTimeOfDay(hour, minute, options)

Parameters:

• hour (number, 0..23)
• minute (number, 0..59, optional, default 0)
• options (table, optional):
• transitionSeconds (number)
• priority (number, optional): arbitration offset (-100..100)
• force (boolean, optional, server/system only): bypass precedence checks

Environment.GetPresets

S Shared (Client & Server)

local presets, err = Environment.GetPresets()

Returns:

• presets (table | nil): array of preset descriptors.
• err (nil | string)

Environment.SetLocalOverride

C Client Only

local err = Environment.SetLocalOverride(patch, options)

Parameters:

• patch (table): partial environment override for local view only.
• options (table, optional):
• transitionSeconds (number)

Notes:

• Local override never changes server state.
• Use for photo mode, accessibility, debugging.

Environment.ClearLocalOverride

C Client Only

local err = Environment.ClearLocalOverride(options)

Parameters:

• options (table, optional):
• transitionSeconds (number)

Events

All events use the standard event envelope:

• event.name
• event.payload
• event.source
• event.target
• event.timestamp
• event.correlationId
• event.version

world:environment_changed (Event Bus)

S Shared (Client & Server)

Payload:

• state (table)
• reason (string or nil)
• changedBy (server | resource:<name> | player:<playerId>)
• resource (string or nil): resource context that initiated the change, when available.
• changedByClientId (string or nil)
• changedByAccountId (string or nil)
• arbitrationPolicy (string): current policy id (priority_v1)
• arbitrationOwner (string): effective writer owner key (server / resource:<name> / player:<id>)
• arbitrationSource (string): source class (system, resource_map, resource, player_admin, player)
• arbitrationPriority (number): effective precedence score for this change
• arbitrationSequence (number): monotonic arbitration write sequence
• arbitrationReplacedOwner (string or nil): previous owner if ownership changed

Identity note:

• playerId in changedBy is a session id; correlate with clientId/accountId via Connection when needed.

world:weather_changed (Event Bus)

S Shared (Client & Server)

Payload:

• preset (string or nil)
• weather (table)

world:time_changed (Event Bus)

S Shared (Client & Server)

Payload:

• hour (number)
• minute (number)

world:local_override_changed (Event Bus)

C Client Only

Payload:

• active (boolean)

Godot Mapping Notes

This API maps to Godot scene/runtime systems:

• WorldEnvironment + Environment for background/sky/fog/tonemap.
• Sky + sky materials (ProceduralSkyMaterial, PhysicalSkyMaterial, PanoramaSkyMaterial) for skybox.
• DirectionalLight3D for sun direction/energy/color.
• GPUParticles3D/FogVolume for weather volume effects.

Error Codes

• ERR_INVALID
• ERR_INVALID_PRESET
• ERR_INVALID_TIME
• ERR_PERMISSION_DENIED
• ERR_PRECEDENCE_DENIED
• ERR_NOT_FOUND
• ERR_NOT_SUPPORTED
• ERR_BUSY

Quick Examples

Set rain on server:

local err = Environment.SetWeatherPreset("rain_evening", {
    transitionSeconds = 2.0
})

Patch only fog density:

local err = Environment.PatchState({
    fog = {
        enabled = true,
        density = 0.035
    }
})

Client photo mode override:

local err = Environment.SetLocalOverride({
    fog = { enabled = false },
    sky = { rotation = 180.0 }
}, { transitionSeconds = 0.5 })