Struct Scene 

pub struct Scene { /* private fields */ }

A scene graph managing nodes with parent-child hierarchy and layers.

Implementations

impl Scene

pub fn new() -> Self

Create an empty scene with a default layer.

pub fn version(&self) -> u64

Monotonically increasing generation counter.

Incremented by wrapping_add(1) on every mutation. Compare against a cached value to detect scene changes without hashing instance data.

pub fn add( &mut self, mesh_id: Option<MeshId>, transform: Mat4, material: Material, ) -> NodeId

Add a node with a mesh, transform, and material. Returns the new node’s ID.

pub fn add_named( &mut self, name: &str, mesh_id: Option<MeshId>, transform: Mat4, material: Material, ) -> NodeId

Add a named node. Returns the new node’s ID.

pub fn remove(&mut self, id: NodeId) -> Vec<NodeId>

Remove a node and all its descendants. Returns all removed IDs (caller can use these to release mesh references).

pub fn set_parent(&mut self, child_id: NodeId, new_parent: Option<NodeId>)

Reparent a node. None makes it a root node.

pub fn children(&self, id: NodeId) -> &[NodeId]

Children of a node.

pub fn parent(&self, id: NodeId) -> Option<NodeId>

Parent of a node.

pub fn roots(&self) -> &[NodeId]

Root nodes.

pub fn set_local_transform(&mut self, id: NodeId, transform: Mat4)

Set the local transform of a node, marking it and its descendants dirty.

pub fn set_visible(&mut self, id: NodeId, visible: bool)

Set node visibility.

pub fn set_material(&mut self, id: NodeId, material: Material)

Set node material.

pub fn set_appearance(&mut self, id: NodeId, appearance: ItemSettings)

Set node appearance overrides.

pub fn set_mesh(&mut self, id: NodeId, mesh_id: Option<MeshId>)

Set node mesh.

pub fn set_name(&mut self, id: NodeId, name: &str)

Set node name.

pub fn set_skin_instance(&mut self, id: NodeId, instance: Option<u32>)

Set the GPU skinning instance ID for a node.

Some(instance_id) routes the node through the skinned pipeline using the joint palette uploaded via crate::ViewportGpuResources::set_skin_palette. None treats the node as static even if its mesh has skin data attached.

pub fn set_receives_decals(&mut self, id: NodeId, v: bool)

Set whether projected decals land on this node’s surface.

pub fn set_show_normals(&mut self, id: NodeId, show: bool)

Set whether to show normals.

pub fn set_layer(&mut self, id: NodeId, layer: LayerId)

Set the layer of a node.

pub fn node(&self, id: NodeId) -> Option<&SceneNode>

Get a reference to a node.

pub fn node_count(&self) -> usize

Number of nodes in the scene.

pub fn nodes(&self) -> impl Iterator<Item = &SceneNode>

Iterate over all nodes.

pub fn add_layer(&mut self, name: &str) -> LayerId

Add a new layer, returning its ID.

pub fn remove_layer(&mut self, id: LayerId)

Remove a layer, moving all its nodes to the default layer. Cannot remove the default layer (LayerId(0)).

pub fn set_layer_visible(&mut self, id: LayerId, visible: bool)

Set layer visibility.

pub fn set_layer_locked(&mut self, id: LayerId, locked: bool)

Set layer locked state. Locked layers render but nodes cannot appear selected.

pub fn set_layer_colour(&mut self, id: LayerId, colour: [f32; 4])

Set layer display colour.

pub fn set_layer_order(&mut self, id: LayerId, order: u32)

Set layer sort order.

pub fn is_layer_locked(&self, id: LayerId) -> bool

Whether a layer is currently locked.

pub fn layers(&self) -> Vec<&Layer>

All layers, sorted by their order field (ascending).

pub fn create_group(&mut self, name: &str) -> GroupId

Create a new named group, returning its ID.

pub fn remove_group(&mut self, id: GroupId)

Remove a group by ID. Does not affect its member nodes.

pub fn add_to_group(&mut self, node: NodeId, group: GroupId)

Add a node to a group.

pub fn remove_from_group(&mut self, node: NodeId, group: GroupId)

Remove a node from a group.

pub fn get_group(&self, id: GroupId) -> Option<&Group>

Get a group by ID.

pub fn groups(&self) -> &[Group]

All groups in the scene.

pub fn node_groups(&self, node: NodeId) -> Vec<GroupId>

Which groups contain the given node.

pub fn update_transforms(&mut self)

Recompute world transforms for all dirty nodes (BFS from roots).

pub fn rebuild_spatial_index( &mut self, mesh_aabb_fn: impl Fn(MeshId) -> Option<Aabb>, )

Rebuild the spatial index from scratch.

Call this after bulk scene construction (level load, import) to avoid accumulating many incremental dirty updates. The index is maintained automatically from this point on.

pub fn scene_stats(&self) -> SceneStats

Diagnostic statistics from the most recent collect_render_items_culled call.

pub fn collect_render_items( &mut self, selection: &Selection, ) -> Vec<SceneRenderItem>

Update transforms and collect render items for all visible nodes.

Skips nodes that are invisible, on an invisible layer, or have no mesh. Marks selected nodes based on the provided Selection.

pub fn collect_render_items_culled( &mut self, selection: &Selection, frustum: &Frustum, mesh_aabb_fn: impl Fn(MeshId) -> Option<Aabb>, ) -> (Vec<SceneRenderItem>, CullStats)

Update transforms and collect render items, culling objects outside the frustum.

Like collect_render_items, but skips objects whose world-space AABB is entirely outside the given frustum. mesh_aabb_fn should return the local-space AABB for a given MeshId (typically read from GpuMesh::aabb).

When the scene has at least 500 nodes, a loose octree spatial index is used to prune subtrees that are entirely outside the frustum. Below that threshold the existing flat walk is used.

pub fn add_light(&mut self, light: LightSource) -> NodeId

Add a light source to the scene graph. Returns the new node’s ID.

The node has no mesh. Set its transform with Scene::set_local_transform to position and orient the light. For directional lights, rotation drives the shading direction; for point and spot lights, translation drives position.

Pass the result of Scene::collect_lights into SceneFrame::lights each frame so the renderer unions these lights with EffectsFrame::lighting.lights.

pub fn collect_lights(&mut self) -> Vec<LightSource>

Collect world-space light sources from all visible nodes on visible layers.

Position and direction values are resolved from each node’s world transform: directional lights rotate their direction, point lights take their position from the world translation, and spot lights take both.

Push the returned vec into SceneFrame::lights each frame. The renderer unions it with EffectsFrame::lighting.lights before building the GPU light uniform.

pub fn set_light(&mut self, id: NodeId, light: Option<LightSource>)

Replace the light source on a node. Pass None to remove the light.

pub fn mesh_ref_count(&self, mesh_id: MeshId) -> usize

Count how many scene nodes reference the given mesh.

O(n) over all nodes. Useful for deciding when to free a GPU mesh.

pub fn walk_depth_first(&self) -> Vec<(NodeId, usize)>

Depth-first traversal of the scene tree. Returns (NodeId, depth) pairs.

impl Scene

pub fn add_decal(&mut self, item: DecalItem) -> DecalHandle

Add a permanent decal to the scene. Returns a handle for later removal.

pub fn add_decal_with_lifetime( &mut self, item: DecalItem, lifetime: f32, fade_duration: f32, )

Add a decal that fades and is automatically removed after lifetime seconds.

fade_duration controls how many seconds the alpha ramps to zero before expiry. Pass 0.0 to use the default (20% of lifetime).

pub fn add_decal_animated( &mut self, item: DecalItem, animation: DecalAnimation, lifetime: Option<f32>, ) -> DecalHandle

Add a decal with an optional animation and optional lifetime.

pub fn remove_decal(&mut self, handle: DecalHandle)

Remove a decal by handle. No-op if the handle is no longer valid.

pub fn update_decals(&mut self, dt: f32)

Advance all live decals by dt seconds and drop expired ones.

Call once per frame before Scene::collect_decal_items.

pub fn collect_decal_items(&self) -> Vec<DecalItem>

Build the [DecalItem] list for this frame’s fd.scene.decals.

Applies lifetime fading (alpha ramps to 0 in the last 20% of life) and computes UV offset/scale for animated decals.

Trait Implementations

impl Default for Scene

fn default() -> Self

Returns the “default value” for a type.