World

A table that references a world and allows interacting with it.

---

GetActiveCamera

Get the active camera. A world can only have one active camera at a time.

Sig: camera = World:GetActiveCamera() - Ret: Camera3D camera Active camera

---

GetAudioReceiver

Get the active audio receiver. A world can only have one active audio receiver at a time. If no audio receiver is assigned, the active camera will be used as the audio receiver.

Sig: receiver = World:GetAudioReceiver() - Ret: Node3D receiver Audio receiver

---

SetActiveCamera

Set the active camera. A world can only have one active camera at a time.

Sig: World:SetActiveCamera(camera) - Arg: Camera3D camera Active camera

---

SetAudioReceiver

Set the active audio receiver. A world can only have one active audio receiver at a time. If no audio receiver is assigned, the active camera will be used as the audio receiver.

Sig: World:SetAudioReceiver(receiver) - Arg: Node3D receiver Audio receiver

---

SpawnNode

Spawn a node from a given class. The spawned node will be attached to the world's root node. If there is no root node, this newly spawned node will become the world's root node.

Sig: node = World:SpawnNode(className, position=Vec(0,0,0)) - Arg: string className Name of the class to spawn - Arg: Vector position World position to place new node - Ret: Node node Newly created node

---

SpawnScene

Spawn a scene. The spawned node will be attached to the world's root node. If there is no root node, this newly spawned node will become the world's root node.

Sig: node = World:SpawnScene(scene, position=Vec(0,0,0)) - Arg: Scene scene Scene asset to spawn - Arg: Vector position World position to place new node - Ret: Node node Newly spawned node (root of spawned scene)

---

DespawnScene

Despawn a previously spawned scene by destroying its root node and all of its children. Uses deferred destruction so it is safe to call mid-frame.

Sig: World:DespawnScene(sceneRoot) - Arg: Node sceneRoot Root node returned by SpawnScene

---

GetRootNode

Get the world's root node.

Sig: root = World:GetRootNode() - Ret: Node root Root node

---

SetRootNode

Set the world's root node.

Sig: World:SetRootNode(root) - Arg: Node root Root node

---

DestroyRootNode

Destroy the world's root node.

Sig: World:DestroyRootNode()

---

FindNode

Find a node by its name.

Sig: node = World:FindNode(name) - Arg: string name Node name - Ret: Node node Found node (or nil if it couldn't be found)

---

FindNodesWithTag

Find all nodes with a given tag.

Sig: nodes = World:FindNodesWithTag(tag) - Arg: string tag Tag to search for - Ret: table nodes Array of Node elements

---

FindNodesWithName

Find all nodes with a given name.

Sig: nodes = World:FindNodesWithName(name) - Arg: string name Name to search for - Ret: table nodes Array of Node elements

---

IsSeenByCamera

Check whether a node is currently visible to the camera: inside the frustum and not hidden by baked occlusion (see Development/OcclusionCulling.md). Baked occludees use their static visibility bit, everything else (moved props, animated meshes, plain Node3Ds) uses the dynamic table. Evaluated immediately, so there is no one-frame lag. Hidden nodes and the camera itself are never seen.

Sig: seen = World:IsSeenByCamera(node, camera=nil) - Arg: Node3D node Node to test - Arg: Camera3D camera (optional) Camera to test against. Defaults to the active camera. - Ret: boolean seen True if the camera can see the node

---

GetSeenByCamera

Gather every Node3D the camera can currently see, optionally filtered to nodes carrying one of the given tags. Walks the whole scene, so call it on events rather than every frame on consoles.

Sig: nodes = World:GetSeenByCamera(tags=nil, camera=nil) - Arg: string|table tags (optional) A single tag or an array of tags. Nodes with any of them are returned; nil returns all seen nodes. - Arg: Camera3D camera (optional) Camera to test against. Defaults to the active camera. - Ret: table nodes Array of Node3D elements

Example:

if world:IsSeenByCamera(self) then self:Alert() end
local threats = world:GetSeenByCamera({ "Enemy", "Turret" })
for _, node in ipairs(threats) do node:Taunt() end

---

FindNavPath

Find a navigation path between two world positions.

Sig: res = World:FindNavPath(start, goal) - Arg: Vector start Start world position - Arg: Vector goal Goal world position - Ret: table res - boolean success True if a path was found - table points Array of Vector waypoints

---

FindRandomNavPoint

Find a random point on the current navmesh.

Sig: point = World:FindRandomNavPoint() - Ret: Vector point Random nav point (or nil if unavailable)

---

FindClosestNavPoint

Project a position to the closest point on the current navmesh.

Sig: point = World:FindClosestNavPoint(pos) - Arg: Vector pos Input world position - Ret: Vector point Closest nav point (or nil if unavailable)

---

BuildNavData

Build navigation data for the world in its current state. This function must be called before any navigation-related functions will work properly.

Sig: World:BuildNavData()

---

EnableAutoNavRebuild

Enable automatic generation of navigation data. This feature is disable dy default. When disabled, BuildNavData() must be called before any navigation-related functions will work properly.

Sig: World:EnableAutoNavRebuild(enable) - Arg: boolean enable Whether to enable auto rebuild

---

SetAmbientLightColor

Set the world's ambient light color.

Sig: World:SetAmbientLightColor(ambient) - Arg: Vector ambient Ambient light color

---

GetAmbientLightColor

Get the world's ambient light color.

Sig: ambient = World:GetAmbientLightColor() - Ret: Vector ambient Ambient light color

---

SetShadowColor

Set the world's shadow color. Shadow color is used by both projected shadows and simple shadows (ShadowMesh3D).

Sig: World:SetShadowColor(color) - Arg: Vector color Shadow color

---

GetShadowColor

Get the world's shadow color. Shadow color is used by both projected shadows and simple shadows (ShadowMesh3D).

Sig: color = World:GetShadowColor() - Ret: Vector color Shadow color

---

SetFog

Set the world's fog settings.

Sig: World:SetFog(fogData) - Arg: table fogData Table of fog attributes to change - boolean enable Enable fog - Vector color Fog color - boolean exponential Exponential fog falloff (vs linear) - number near Distance at which fog starts to accumulate - number far Distance at which fog is 100% dense

---

GetFog

Get the world's fog settings.

Sig: fogData = World:GetFog() - Ret: table fogData Fog data table - boolean enable Enable fog - Vector color Fog color - boolean exponential Exponential fog falloff (vs linear) - number near Distance at which fog starts to accumulate - number far Distance at which fog is 100% dense

---

SetGravity

Set the world's gravity. Only used by Primitive3D nodes with physics enabled.

Sig: World:SetGravity(gravity) - Arg: Vector gravity Gravity vector

---

GetGravity

Get the world's gravity. Only used by Primitive3D nodes with physics enabled.

Sig: gravity = World:GetGravity() - Ret: Vector gravity Gravity vector

---

RayTest

Find the first primitive node that intersects a ray.

Sig: res = World:RayTest(start, end, colMask, ignoreObjects=nil, ignorePureOverlaps=true) - Arg: Vector start Start position - Arg: Vector end End position - Arg: integer colMask Collision mask (use 0xff for all collision groups) - Arg: table ignoreObjects Array of Primitive3D nodes to ignore in test - Arg: bool ignorePureOverlap Ignore primitives that have Overlaps enabled and Collision disabled - Ret: table res Ray test result - Vector start - Vector end - Primitive3D hitNode - Vector hitNormal - Vector hitPosition - number hitFraction

---

RayTestMulti

Find all primitive nodes that intersect a ray.

Sig: res = World:RayTestMulti(start, end, colMask, ignoreObjects=nil, ignorePureOverlaps=true) - Arg: Vector start Start position - Arg: Vector end End position - Arg: integer colMask Collision mask (use 0xff for all collision groups) - Arg: bool ignorePureOverlap Ignore primitives that have Overlaps enabled and Collision disabled - Ret: table results Array of results - table res Element of the array - Primitive3D node - Vector normal - Vector position - number fraction

---

SweepTest

Perform a shape sweep test using a Primitive3D node's collision shape. This test will return the first primitive node hit.

TODO: Add ignore list. (This function will ignore the swept primitive though)

Sig: res = World:SweepTest(prim, start, end, colMask) - Arg: Primitive3D prim Primitive node whose collision shape will be used for the test - Arg: Vector start Start position - Arg: Vector end End position - Arg: integer colMask Collision mask (Use 0xff for all collision groups) - Ret: table res Test result - Vector start - Vector end - Primitive3D hitNode - Vector hitNormal - Vector hitPosition - number hitFraction

---

LoadScene

Clear the world and instantiate a new scene as the root node.

Sig: World:LoadScene(sceneName, instant=false) - Arg: string sceneName Name of Scene asset to load - Arg: boolean instant Whether to instantly load the scene, or wait until the start of the next frame. Note: Using instant loading may cause problems and probably shouldn't be used. Setting instant to false is generally safer.

---

GetLoadedSceneName

Get the name of the scene most recently loaded via World:LoadScene(). Only reflects the top-level scene load (or queued scene load, once it takes effect at the start of the next frame) -- it isn't updated if the root node is changed some other way (e.g. World:SetRootNode()).

Sig: name = World:GetLoadedSceneName() - Ret: string name Name of the currently loaded scene (empty string if none)

---

GetLoadedSceneNames

Get the names of every currently instantiated scene in the world, including nested/child scenes (scenes spawned via World:SpawnScene(), or scene references nested inside another scene's hierarchy). Names are de-duplicated, so a scene instanced multiple times only appears once.

Sig: names = World:GetLoadedSceneNames() - Ret: table names Array of scene name strings

---

QueueRootNode

Queue a new node to be set as the world's root node at the start of the next frame. This is used internally by World:LoadScene().

Sig: World:QueueRootNode(newRoot) - Arg: Node newRoot New root node

---

EnableInternalEdgeSmoothing

Enable internal edge smoothing. May provide smoother collisions along collision mesh boundaries.

Sig: World:EnableInternalEdgeSmoothing(enable) - Arg: boolean enable Enable internal edge smoothing

---

IsInternalEdgeSmoothingEnabled

Check if internal edge smoothing is enabled. May provide smoother collisions along collision mesh boundaries.

Sig: enable = World:IsInternalEdgeSmoothingEnabled() - Ret: boolean enable Internal edge smoothing enabled

---

SpawnParticle

Spawn a particle system at a specific location and set it to automatically destroy itself after it finishes. An optional velocity can be provided to give all spawned particles an additional base velocity.

Sig: particle = World:SpawnParticle(system, position, velocity=nil) - Arg: ParticleSystem system Particle system asset to instantiate - Arg: Vector position World position to place particle - Arg: Vector velocity (optional) Base velocity added to all spawned particles - Ret: Particle3D particle The newly created particle

---