world#

world provides world-level queries and is the registration point for mission event handlers, letting scripts react to in-game events such as unit spawns, deaths, and shots fired.

Functions#

world.addEventHandler(handler)#

Registers handler (a table with an onEvent(self, event) function) to receive mission events, such as S_EVENT_BIRTH, S_EVENT_DEAD, and S_EVENT_SHOT.

Parameters:

handler (table) – A table implementing onEvent(self, event).

world.removeEventHandler(handler)#

Unregisters a previously registered event handler.

Parameters:

handler (table) – The handler previously passed to addEventHandler().

world.getPlayer()#

Returns the Unit object controlled by the local player, or nil if not applicable.

Returns:

The local player’s unit, or nil.

Return type:

Unit

world.getAirbases()#

Returns a table of all Airbase objects on the current map.

Returns:

All airbases on the map.

Return type:

table

world.getMarkPanels()#

Returns a table describing all mark panels currently placed on the F10 map.

Returns:

Mark panel descriptor tables.

Return type:

table

world.searchObjects(category, volume, handler)#

Searches for objects of the given category within a volume (e.g. a sphere or box), calling handler for each match.

Parameters:

  • category (number) – Object category to search for.

  • volume (table) – A volume descriptor table (e.g. sphere or box).

  • handler (function) – Called with each matching object.

world.removeJunk(searchVolume)#

Searches searchVolume and removes craters, wreckage, and other debris found within it. Wreckage belonging to scenery objects is not removed.

Parameters:

searchVolume (table) – A volume descriptor table (e.g. sphere or box).

Returns:

The number of objects removed.

Return type:

number

Example:

local sphere = trigger.misc.getZone('trainingAirbase')
sphere.point.y = land.getHeight({x = sphere.point.x, y = sphere.point.z})
local vol = {
    id = world.VolumeType.SPHERE,
    params = {point = sphere.point, radius = sphere.radius},
}
world.removeJunk(vol)

Weather#

world.weather provides queries and mutators for the mission’s current fog settings.

world.weather.getFogThickness()#

Returns the current fog thickness, in meters, at sea level. Returns 0 if no fog is present.

Returns:

Fog thickness, in meters.

Return type:

number

world.weather.setFogThickness(thickness)#

Sets the fog thickness, in meters, at sea level. Any active fog animation (see setFogAnimation()) is discarded.

Parameters:

thickness (number) – Desired fog thickness, in meters. Valid range: 100 to 5000. Passing 0 removes the fog entirely.

world.weather.getFogVisibilityDistance()#

Returns the current maximum fog visibility distance, in meters, at sea level. Returns 0 if no fog is present.

Returns:

Fog visibility distance, in meters.

Return type:

number

world.weather.setFogVisibilityDistance(visibility)#

Sets the maximum fog visibility distance, in meters, at sea level.

Parameters:

visibility (number) – Desired visibility distance, in meters. Valid range: 100 to 100000. Passing 0 removes the fog entirely.

world.weather.setFogAnimation(keys)#

Gradually changes fog visibility and thickness over time, following a list of {time, visibility, thickness} keys, instead of applying values abruptly.

time is in seconds, relative to when the function was called, and must strictly increase between successive keys. A key with time = 0 applies its visibility/thickness immediately; any key with time > 0 interpolates from the current fog values (or the previous key) to that key’s values.

Passing an empty table ({}) or nil discards any active animation, leaving the current thickness and visibility unchanged.

Parameters:

keys (table) – A list of {time, visibility, thickness} key tables, or {}/nil to discard the current animation.

Example:

-- Fade the fog out completely over 1 minute.
world.weather.setFogAnimation({ {60, 0, 0} })

Implementation notes#

addEventHandler() and removeEventHandler() are backed by an internal registry that tracks handlers keyed by the handler table itself, rather than by name. Whenever an event occurs, every registered handler’s onEvent function is invoked in turn.

Note

Because handlers are keyed by table identity rather than name, passing the same handler table to addEventHandler() twice has no additional effect, and removeEventHandler() must be given the exact same table reference used to register it.

world also exposes an additional, undocumented persistence mechanism, allowing a name/handler pair to be registered so that a value can be produced on demand (e.g. for saving state) via a validated name and a corresponding retrieval function.

Warning

This persistence mechanism is not part of any officially documented API and its calling context/lifecycle is unverified. Treat it as unverified/experimental behavior; validate carefully before relying on it in a mission.

Footnotes#

  • Event handlers registered via world.addEventHandler are the primary mechanism for reacting to gameplay events in mission scripts.

  • Event tables passed to onEvent include an id field identifying the event type, along with event-specific fields such as initiator or weapon.

  • There is no world.terrain table in the SSE. Terrain-related queries (elevation, surface type, line-of-sight, etc.) live under the separate land singleton instead.