ke.scene

Scene graph, prim hierarchy, components, resource mirrors, and debug drawing.

API overview

Prim

USD-like scene graph node with hierarchy, transform, and mesh data.

Camera

View camera used by KangEngine applications.

DirectionalLight

Infinite-distance light used as the scene's main sun light.

PointLight

Finite local scene light.

SpotLight

Finite cone-shaped scene light.

SceneBackend

Abstract scene backend interface for native and USD scenes.

SceneResourceManager

Scene resource manager mirrored into metadata-only /.Resources prims.

MeshData

Static mesh payload with vertex attributes and triangle indices.

SkinnedMeshData

Mesh payload with skinning attributes for skeletal animation.

DebugDraw

Helpers for creating debug lines, arrows, and coordinate axes.
class kangengine.scene.Token[native]

Interned-style attribute key used by scene prims.

id(self: Token) → int

Return the token’s stable numeric id.

str(self: Token) → str

Return the token string.

class kangengine.scene.Prim[native]

USD-like scene graph node with hierarchy, transform, and mesh data.

add_articulation_binding_component(
self: Prim,
) → ArticulationBindingComponent

Attach and return this prim’s articulation binding component.

add_articulation_component(
self: Prim,
) → ArticulationComponent

Attach and return this prim’s articulation root component.

add_camera_component(
self: Prim,
) → kangengine.scene.CameraComponent

Attach and return this Camera prim’s camera component.

add_child(
self: Prim,
name: str,
type: kangengine.scene.PrimType,
) → Prim

Create and return a child prim.

add_collision_shape_component(
self: Prim,
) → CollisionShapeComponent

Attach and return this prim’s collision shape metadata component.

add_light_component(self: Prim) → kangengine.scene.LightComponent

Attach and return this Light prim’s light component.

add_material_binding_component(
self: Prim,
) → MaterialBindingComponent

Attach and return this prim’s material binding component.

add_mesh_component(self: Prim) → MeshComponent

Attach and return this Mesh/MeshInstance prim’s mesh component.

add_render_component(
self: Prim,
) → RenderComponent

Attach and return this prim’s render component.

add_resource_component(
self: Prim,
) → ResourceComponent

Attach and return this Resource prim’s resource component.

add_rotate_quaternion_op(
self: Prim,
rotation: glm::qua<float,
(glm: :qualifier)0>,
) → None

Compatibility alias for local quaternion rotation.

add_scale_op(
self: Prim,
scale: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Compatibility alias for local scale.

add_translate_op(
self: Prim,
translation: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Compatibility alias for local translation.

compute_local_matrix(
self: Prim,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Compute this prim’s local transform matrix.

compute_model_matrix(
self: Prim,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Compute this prim’s model matrix.

compute_world_matrix(
self: Prim,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Compute this prim’s world transform matrix.

static create_capsule_data(
radius: float,
height: float,
up_axis: kangengine.UpAxis = <UpAxis.Y: 1>,
segments: int = 32,
) → KE::Scene::MeshData

Create capsule mesh data.

static create_cylinder_data(
radius: float,
length: float,
up_axis: kangengine.UpAxis = <UpAxis.Y: 1>,
segments: int = 32,
) → KE::Scene::MeshData

Create cylinder mesh data.

static create_plane_data(
scale: float,
up_axis: kangengine.UpAxis = <UpAxis.Y: 1>,
) → KE::Scene::MeshData

Create plane mesh data.

static create_rectangle_data(
x_scale: float,
y_scale: float,
z_scale: float,
) → KE::Scene::MeshData

Create box/rectangle mesh data.

static create_sphere_data(
radius: float,
num_longitudes: int,
num_latitudes: int,
) → KE::Scene::MeshData

Create sphere mesh data.

static create_square_data(scale: float = 1.0) → KE::Scene::MeshData

Create square mesh data.

static define_manipulation_group(
scene: KE::Scene::SceneBackend,
path: str,
) → Prim

Create an Xform prim that manipulates as a group.

get_articulation_binding_component(
self: Prim,
) → ArticulationBindingComponent

Return this prim’s articulation binding component, or None.

get_articulation_component(
self: Prim,
) → ArticulationComponent

Return this prim’s articulation root component, or None.

get_attribute_float(self: Prim, name: str) → float

Get a float attribute.

get_attribute_int(self: Prim, name: str) → int

Get an integer attribute.

get_attribute_quat(
self: Prim,
name: str,
) → glm::qua<float, (glm::qualifier)0>

Get a quaternion attribute.

get_attribute_string(self: Prim, name: str) → str

Get a string attribute.

get_attribute_vec3(
self: Prim,
name: str,
) → glm::vec<3, float, (glm::qualifier)0>

Get a vec3 attribute.

get_attribute_vec4(
self: Prim,
name: str,
) → glm::vec<4, float, (glm::qualifier)0>

Get a vec4 attribute.

get_camera_component(
self: Prim,
) → kangengine.scene.CameraComponent

Return this prim’s camera component, or None.

get_child(self: Prim, name: str) → Prim

Return a direct child by name.

get_children(self: Prim) → list[Prim]

Return direct child prims.

get_collision_shape_component(
self: Prim,
) → CollisionShapeComponent

Return this prim’s collision shape component, or None.

get_directional_light(
self: Prim,
) → DirectionalLight

Return directional light data from this Light prim.

get_display_color(
self: Prim,
) → glm::vec<3, float, (glm::qualifier)0> | None

Return RGB display color metadata if present.

get_display_color_alpha(
self: Prim,
) → glm::vec<4, float, (glm::qualifier)0> | None

Return RGBA display color metadata if present.

get_light_component(self: Prim) → kangengine.scene.LightComponent

Return this prim’s light component, or None.

get_light_type(
self: Prim,
default_type: kangengine.scene.LightType = <LightType.POINT: 1>,
) → kangengine.scene.LightType

Return the light subtype for a Light prim.

get_local_rotation(
self: Prim,
) → glm::qua<float, (glm::qualifier)0>

Return the effective parent-relative quaternion rotation.

get_local_translation(
self: Prim,
) → glm::vec<3, float, (glm::qualifier)0>

Return the effective parent-relative translation.

get_manipulation_policy(
self: Prim,
) → kangengine.scene.ManipulationPolicy

Return this prim’s manipulation policy.

get_material(self: Prim) → kangengine.Material

Return the bound material, or None.

get_material_binding_component(
self: Prim,
) → MaterialBindingComponent

Return this prim’s material binding component, or None.

get_mesh_component(self: Prim) → MeshComponent

Return this prim’s mesh component, or None.

get_mesh_data(self: Prim) → KE::Scene::MeshData

Return mesh data attached directly to this prim.

get_mesh_source_path(self: Prim) → str

Return the mesh source path for mesh instances.

get_name(self: Prim) → str

Return this prim’s local name.

get_parent(self: Prim) → Prim

Return this prim’s parent, or None for the root.

get_path(self: Prim) → str

Return this prim’s absolute scene path.

get_point_light(self: Prim) → PointLight

Return point light data from this Light prim.

get_prim_at_path(self: Prim, path: str) → Prim

Find a descendant prim by absolute path.

get_render_component(
self: Prim,
) → RenderComponent

Return this prim’s render component, or None.

get_resource_component(
self: Prim,
) → ResourceComponent

Return this prim’s resource component, or None.

get_spot_light(self: Prim) → SpotLight

Return spot light data from this Light prim.

get_transform_component(
self: Prim,
) → TransformComponent

Return this prim’s mandatory transform component.

get_type(self: Prim) → kangengine.scene.PrimType

Return this prim’s type.

get_world_rotation(
self: Prim,
) → glm::qua<float, (glm::qualifier)0>

Return the effective world-space quaternion rotation.

get_world_translation(
self: Prim,
) → glm::vec<3, float, (glm::qualifier)0>

Return the effective world-space translation.

has_articulation_binding_component(self: Prim) → bool

Return whether this prim has an articulation binding component.

has_articulation_component(self: Prim) → bool

Return whether this prim has an articulation root component.

has_attribute(self: Prim, name: str) → bool

Return true when an attribute exists.

has_camera_component(self: Prim) → bool

Return whether this prim has a camera component.

has_collision_shape_component(self: Prim) → bool

Return whether this prim has a collision shape component.

has_light_component(self: Prim) → bool

Return whether this prim has a light component.

has_material_binding_component(self: Prim) → bool

Return whether this prim has a material binding component.

has_mesh_component(self: Prim) → bool

Return whether this prim has a mesh component.

has_render_component(self: Prim) → bool

Return whether this prim has a render component.

has_resource_component(self: Prim) → bool

Return whether this prim has a resource component.

has_transform_component(self: Prim) → bool

Return whether this prim has a transform component.

is_active(self: Prim) → bool

Return local active state.

is_active_in_hierarchy(self: Prim) → bool

Return active state after parent hierarchy is considered.

is_visible(self: Prim) → bool

Return local visibility state.

is_visible_in_hierarchy(self: Prim) → bool

Return visibility after parent hierarchy is considered.

remove_articulation_binding_component(self: Prim) → bool

Detach this prim’s articulation binding component.

remove_articulation_component(self: Prim) → bool

Detach this prim’s articulation root component.

remove_camera_component(self: Prim) → bool

Detach this prim’s camera component.

remove_collision_shape_component(self: Prim) → bool

Detach this prim’s collision shape component.

remove_light_component(self: Prim) → bool

Detach this prim’s light component.

remove_material_binding_component(self: Prim) → bool

Detach this prim’s material binding component.

remove_mesh_component(self: Prim) → bool

Detach this prim’s mesh component.

remove_render_component(self: Prim) → bool

Detach this prim’s render component.

remove_resource_component(self: Prim) → bool

Detach this prim’s resource component.

resolve_manipulation_target(self: Prim) → Prim

Resolve which prim should be manipulated from this prim.

resolve_mesh_data(self: Prim) → KE::Scene::MeshData

Return direct mesh data or resolved source mesh data.

set_active(self: Prim, active: bool) → None

Set local active state.

set_attribute_float(self: Prim, name: str, value: float) → None

Set a float attribute.

set_attribute_int(self: Prim, name: str, value: int) → None

Set an integer attribute.

set_attribute_quat(
self: Prim,
name: str,
value: glm::qua<float,
(glm: :qualifier)0>,
) → None

Set a quaternion attribute.

set_attribute_string(self: Prim, name: str, value: str) → None

Set a string attribute.

set_attribute_vec3(
self: Prim,
name: str,
value: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set a vec3 attribute.

set_attribute_vec4(
self: Prim,
name: str,
value: glm::vec<4,
float,
(glm: :qualifier)0>,
) → None

Set a vec4 attribute.

set_directional_light(
self: Prim,
light: DirectionalLight,
) → None

Attach directional light data to this Light prim.

set_display_color(
self: Prim,
color: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set RGB display color metadata.

set_display_color_alpha(
self: Prim,
color: glm::vec<4,
float,
(glm: :qualifier)0>,
) → None

Set RGBA display color metadata.

set_local_matrix(
self: Prim,
matrix: glm::mat<4,
4,
float,
(glm: :qualifier)0>,
) → None

Set local transform matrix.

set_local_rotation(
self: Prim,
rotation: glm::qua<float,
(glm: :qualifier)0>,
) → None

Set local quaternion rotation.

set_local_rotation_axis_angle(
self: Prim,
axis: glm::vec<3,
float,
(glm: :qualifier)0>,
angle_radians: float,
) → None

Set local rotation from an axis and an angle in radians.

set_local_scale(
self: Prim,
scale: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set local scale.

set_local_translation(
self: Prim,
translation: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set local translation.

set_manipulation_policy(
self: Prim,
policy: kangengine.scene.ManipulationPolicy,
) → None

Set this prim’s manipulation policy.

set_material(self: Prim, material: kangengine.Material) → None

Bind a non-owned material to this prim at the scene level.

set_mesh_data(self: Prim, mesh_data: KE::Scene::MeshData) → None

Attach mesh data to this prim.

set_mesh_source_path(self: Prim, path: str) → None

Set a source path for mesh instancing.

set_point_light(
self: Prim,
light: PointLight,
) → None

Attach point light data to this Light prim.

set_spot_light(
self: Prim,
light: SpotLight,
) → None

Attach spot light data to this Light prim.

set_visible(self: Prim, visible: bool) → None

Set local visibility state.

set_world_matrix(
self: Prim,
matrix: glm::mat<4,
4,
float,
(glm: :qualifier)0>,
) → None

Set world transform matrix.

set_world_rotation(
self: Prim,
rotation: glm::qua<float,
(glm: :qualifier)0>,
) → None

Set world quaternion rotation.

set_world_rotation_axis_angle(
self: Prim,
axis: glm::vec<3,
float,
(glm: :qualifier)0>,
angle_radians: float,
) → None

Set world rotation from an axis and an angle in radians.

set_world_translation(
self: Prim,
translation: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set world translation.

traverse(
self: Prim,
callback: std::function<void (KE::Scene::Prim*)>,
) → None

Traverse this prim subtree and call callback for each prim.

class kangengine.scene.Camera[native]

View camera used by KangEngine applications.

get_camera_look_dir(
self: Camera,
) → glm::vec<3, float, (glm::qualifier)0>

Return the normalized forward/look direction.

get_camera_pos(
self: Camera,
) → glm::vec<3, float, (glm::qualifier)0>

Return the camera position.

get_camera_right_dir(
self: Camera,
) → glm::vec<3, float, (glm::qualifier)0>

Return the normalized right direction.

get_camera_up_dir(
self: Camera,
) → glm::vec<3, float, (glm::qualifier)0>

Return the normalized up direction.

get_far_plane(self: Camera) → float

Return the far clipping distance.

get_fov(self: Camera) → float

Return the vertical field of view in degrees.

get_near_plane(self: Camera) → float

Return the near clipping distance.

get_target_pos(
self: Camera,
) → glm::vec<3, float, (glm::qualifier)0>

Return the current camera target point.

set_camera_pos(
self: Camera,
position: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set the camera position.

set_far_plane(self: Camera, distance: float) → None

Set the far clipping distance.

set_fov(self: Camera, fov: float) → None

Set the vertical field of view in degrees.

set_near_plane(self: Camera, distance: float) → None

Set the near clipping distance.

set_target_pos(
self: Camera,
target: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set the camera target point.

class kangengine.scene.DirectionalLight[native]

Infinite-distance light used as the scene’s main sun light.

property ambient
property color
property direction
property intensity
class kangengine.scene.PointLight[native]

Finite local scene light.

property color
property intensity
property position
property range
class kangengine.scene.SpotLight[native]

Finite cone-shaped scene light.

property color
property direction
property inner_cone_angle
property intensity
property outer_cone_angle
property position
property range
class kangengine.scene.TransformComponent[native]

Local/world transform state attached to every scene prim.

property attached

Return whether this component is attached.

compute_local_matrix(
self: TransformComponent,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Return the cached/computed local matrix.

compute_model_matrix(
self: TransformComponent,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Return the model matrix, currently equal to world matrix.

compute_world_matrix(
self: TransformComponent,
) → glm::mat<4, 4, float, (glm::qualifier)0>

Return the cached/computed world matrix.

get_local_rotation(
self: TransformComponent,
) → glm::qua<float, (glm::qualifier)0>

Return the effective parent-relative quaternion rotation.

get_local_translation(
self: TransformComponent,
) → glm::vec<3, float, (glm::qualifier)0>

Return the effective parent-relative translation.

get_world_rotation(
self: TransformComponent,
) → glm::qua<float, (glm::qualifier)0>

Return the effective world-space quaternion rotation.

get_world_translation(
self: TransformComponent,
) → glm::vec<3, float, (glm::qualifier)0>

Return the effective world-space translation.

property owner

Return the owning prim, or None after detach.

set_local_matrix(
self: TransformComponent,
matrix: glm::mat<4,
4,
float,
(glm: :qualifier)0>,
) → None

Set the local transform matrix.

set_local_rotation(
self: TransformComponent,
rotation: glm::qua<float,
(glm: :qualifier)0>,
) → None

Set local rotation.

set_local_rotation_axis_angle(
self: TransformComponent,
axis: glm::vec<3,
float,
(glm: :qualifier)0>,
angle_radians: float,
) → None

Set local rotation from an axis and an angle in radians.

set_local_scale(
self: TransformComponent,
scale: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set local scale.

set_local_translation(
self: TransformComponent,
translation: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set local translation.

set_world_matrix(
self: TransformComponent,
matrix: glm::mat<4,
4,
float,
(glm: :qualifier)0>,
) → None

Set the world transform matrix.

set_world_rotation(
self: TransformComponent,
rotation: glm::qua<float,
(glm: :qualifier)0>,
) → None

Set world rotation.

set_world_rotation_axis_angle(
self: TransformComponent,
axis: glm::vec<3,
float,
(glm: :qualifier)0>,
angle_radians: float,
) → None

Set world rotation from an axis and an angle in radians.

set_world_translation(
self: TransformComponent,
translation: glm::vec<3,
float,
(glm: :qualifier)0>,
) → None

Set world translation.

property version

Return the transform state version.

class kangengine.scene.MeshComponent[native]

Geometry payload/reference attached to a renderable mesh prim.

property attached

Return whether this component is attached.

property mesh_data

Get or set directly attached mesh data.

property mesh_source_path

Get or set the source path for MeshInstance prims.

property owner

Return the owning prim, or None after detach.

resolve_mesh_data(
self: MeshComponent,
) → KE::Scene::MeshData

Return direct mesh data or resolved source mesh data.

property resource_handle

Get or set the optional SceneResourceManager handle.

property version

Return the mesh component version.

class kangengine.scene.RenderComponent[native]

Renderer-independent visual state attached to one scene prim. Renderer handles are owned by SceneRenderSystem, not by this object.

property alpha_cutoff

Return the alpha-mask cutoff.

property alpha_mode

Return the alpha rendering mode.

property attached

Return whether this component is attached.

property casts_shadow

Get or set shadow casting. Registered components sync this change to the renderer.

property double_sided

Get or set double-sided rendering. Registered components sync this change to the renderer.

property mesh_data

Resolve mesh data from the owning prim.

property owner

Return the owning prim, or None after detach.

property transform_source

Get or set the transform data source.

property version

Return the visual state version.

property visible

Get or set local render visibility. Registered components sync this change to the renderer.

class kangengine.scene.MaterialBindingComponent[native]

Scene-level non-owning binding from one prim to a renderer material.

property attached

Return whether this component is attached.

clear_material(
self: MaterialBindingComponent,
) → None

Clear the material binding.

property material

Get or set the bound material. The component does not own it.

property owner

Return the owning prim, or None after detach.

property version

Return the material binding version.

class kangengine.scene.ArticulationComponent[native]

Root-level metadata for an articulated object subtree.

property asset_path

Imported articulation asset path or URI.

property attached

Return whether this component is attached.

property body_count

Number of body frame prims.

property mesh_asset_base_path

Shared mesh resource base path, if any.

property owner

Return the owning prim, or None after detach.

property render_prim_count

Number of renderable visual prims.

property root_path

Scene root prim path for this articulation.

set_articulation_metadata(
self: ArticulationComponent,
root_path: str,
asset_path: str,
mesh_asset_base_path: str,
body_count: int,
render_prim_count: int,
split_visual_geoms: bool,
) → None

Set all root articulation metadata fields at once.

property split_visual_geoms

Whether visual geoms were instantiated as split child prims.

property version

Return the articulation metadata version.

class kangengine.scene.ArticulationBindingComponent[native]

Metadata binding a Prim to an articulated body/frame.

property articulation_root_path

Root prim path of the owning articulation.

property attached

Return whether this component is attached.

property body_index

Articulation body index this prim belongs to.

property body_name

Articulation body name this prim belongs to.

property owner

Return the owning prim, or None after detach.

property role

Role of this prim inside the articulation.

set_binding(
self: ArticulationBindingComponent,
role: kangengine.scene.ArticulationPrimRole,
body_index: int,
body_name: str,
articulation_root_path: str,
) → None

Set all binding fields at once.

property version

Return the articulation binding version.

class kangengine.scene.CollisionShapeComponent[native]

Scene-side metadata for a collision shape debug prim.

property attached

Return whether this component is attached.

property condim

Imported MuJoCo contact dimensionality, if any.

property dynamic_friction

Reference PhysX dynamic friction.

property from_position

Body-local from endpoint when has_from_to is true.

property has_from_to

Whether this shape was authored by from/to.

property local_position

Body-local collision shape position.

property local_rotation

Body-local collision shape rotation.

property margin

Imported MuJoCo margin mapped to contactOffset, if any.

property owner

Return the owning prim, or None after detach.

property restitution

Reference PhysX restitution.

property shape_type

Primitive collision shape type.

property size

Shape size descriptor. Interpretation depends on shape type.

property source_geom_index

Index of the source collision geom inside the body descriptor.

property static_friction

Reference PhysX static friction.

property to_position

Body-local to endpoint when has_from_to is true.

property version

Return the collision shape metadata version.

class kangengine.scene.ResourceComponent[native]

Lightweight resource metadata attached to a Resource prim.

property attached

Return whether this component is attached.

property display_name

Get or set a user-facing resource name.

property handle

Get or set the SceneResourceManager handle.

property owner

Return the owning prim, or None after detach.

property type

Get or set the resource type.

property uri

Get or set the resource URI/path.

property version

Return the resource metadata version.

class kangengine.scene.SceneResourceManager[native]

Scene resource manager mirrored into metadata-only /.Resources prims.

add_external_usage(
self: SceneResourceManager,
handle: int,
path: str,
) → None

Track a non-scene consumer of a resource.

bind_scene(
self: SceneResourceManager,
scene: KE::Scene::SceneBackend,
) → None

Bind the scene used for Resource prim mirrors.

clear(self: SceneResourceManager) → None

Clear all registered resource records and their metadata mirror prims.

invalidate_usage_cache(
self: SceneResourceManager,
) → None

Mark cached resource usage counts dirty after direct scene or material mutation.

is_used(
self: SceneResourceManager,
handle: int,
) → bool

Return whether at least one scene prim binding references this resource.

material(
self: SceneResourceManager,
handle: int,
) → kangengine.Material

Return material for a handle, or None.

mesh(
self: SceneResourceManager,
handle: int,
) → KE::Scene::MeshData

Return mesh data for a handle, or None.

pipeline(
self: SceneResourceManager,
handle: int,
) → kangengine.scene.PipelineResource

Return authored pipeline metadata, or None.

register_material(
self: SceneResourceManager,
name: str,
material: kangengine.Material,
uri: str = '',
) → int

Register a non-owned material and return a resource handle.

register_mesh(
self: SceneResourceManager,
name: str,
mesh: KE::Scene::MeshData,
uri: str = '',
) → int

Register mesh data and return a resource handle.

register_pipeline(
self: SceneResourceManager,
name: str,
pipeline: kangengine.scene.PipelineResource,
uri: str = '',
) → int

Register an authored graphics or compute pipeline definition.

register_shader_source(
self: SceneResourceManager,
name: str,
shader_source: kangengine.scene.ShaderSourceResource,
uri: str = '',
) → int

Register authored shader source metadata and return a resource handle.

register_texture(
self: SceneResourceManager,
name: str,
texture: kangengine.Texture,
uri: str = '',
) → int

Register a non-owned texture and return a resource handle.

remove_external_usage(
self: SceneResourceManager,
handle: int,
path: str,
) → None

Stop tracking a non-scene consumer of a resource.

resource_prim(
self: SceneResourceManager,
handle: int,
) → KE::Scene::Prim

Return mirrored Resource prim for a handle, or None.

shader_source(
self: SceneResourceManager,
handle: int,
) → kangengine.scene.ShaderSourceResource

Return authored shader source metadata, or None.

texture(
self: SceneResourceManager,
handle: int,
) → kangengine.Texture

Return texture for a handle, or None.

usage_count(
self: SceneResourceManager,
handle: int,
) → int

Return how many scene prim bindings currently reference this resource.

usage_paths(
self: SceneResourceManager,
handle: int,
) → list[str]

Return scene prim paths that currently reference this resource.

class kangengine.scene.MeshData[native]

Static mesh payload with vertex attributes and triangle indices.

property indices

Triangle index buffer.

property normals

Vertex normals.

property uvs

Vertex texture coordinates.

property vertices

Vertex positions.

class kangengine.scene.SkinnedMeshData[native]

Mesh payload with skinning attributes for skeletal animation.

property bone_node_indices

Skeleton node index for each bound bone.

has_valid_vertex_skinning(
self: SkinnedMeshData,
) → bool

Return true when vertex bone data matches the mesh vertex count.

property mesh

Base static mesh data.

class kangengine.scene.SceneBackend[native]

Abstract scene backend interface for native and USD scenes.

define_prim(
self: SceneBackend,
path: str,
type: kangengine.scene.PrimType,
) → Prim

Define and return a prim at a scene path.

get_backend_type(
self: SceneBackend,
) → kangengine.scene.BackendType

Return the backend implementation type.

get_prim_at_path(
self: SceneBackend,
path: str,
) → Prim

Return a prim at a scene path, or None if it does not exist.

get_root_prim(self: SceneBackend) → Prim

Return the scene root prim.

list_meshes(self: SceneBackend) → list[str]

Return mesh prim paths known by this scene.

load_mesh(
self: SceneBackend,
prim_path: str,
) → MeshData

Load mesh data for a prim path.

load_scene(self: SceneBackend, path: str) → bool

Load a scene from a file.

remove_prim(self: SceneBackend, path: str) → bool

Remove a prim subtree. Components registered by an App detach their renderer resources during destruction.

save_scene(self: SceneBackend, path: str) → bool

Save a scene to a file.

Return and ownership rules

API

Return and lifetime contract

register_mesh/material/texture()

A runtime ResourceHandle; it is not a persistent asset identifier.

register_shader_source/pipeline()

A handle for copied authored metadata; compiled backend objects are not stored here.

mesh()

A shared mesh payload, or None for an unknown handle.

material(), texture()

Borrowed engine objects, or None; the manager does not own these payloads.

shader_source(), pipeline()

Authored metadata retained by the manager, or None.

resource_prim()

A scene-owned mirror prim, valid until removal, clear(), or scene teardown.

usage_paths()

A Python list converted from the current usage cache.

clear() removes manager records and their /.Resources mirror prims. Keep a separate owned reference when a non-owned material or texture must outlive its resource registration.

Debug geometry

Use app.scene.debug_geometry for mesh-based debug lines, arrows, and axes. These objects are ordinary SceneGraph renderables and return DebugPrimitiveView instances.

ke.scene.DebugDraw is the low-level native implementation used by that facade:

class kangengine.scene.DebugDraw[native]

Helpers for creating debug lines, arrows, and coordinate axes.

static log_component_arrows(
app: KE::App,
material: kangengine.Material,
path: str,
starts: npt.ArrayLike | torch.Tensor,
ends: npt.ArrayLike | torch.Tensor,
colors: object = None,
radius: float = 0.019999999552965164,
segments: int = 12,
) → RenderComponent

Create instanced debug arrow geometry and return its RenderComponent.

static log_component_lines(
app: KE::App,
material: kangengine.Material,
path: str,
starts: npt.ArrayLike | torch.Tensor,
ends: npt.ArrayLike | torch.Tensor,
colors: object = None,
radius: float = 0.004999999888241291,
segments: int = 8,
) → RenderComponent

Create instanced debug line geometry and return its RenderComponent.

static log_coordinate_axes(
app: KE::App,
material: kangengine.Material,
path: str,
origin: glm::vec<3,
float,
(glm: :qualifier)0>,
orientation: glm::qua<float,
(glm: :qualifier)0>,
length: float = 1.0,
radius: float = 0.004999999888241291,
segments: int = 8,
) → int

Create instanced XYZ coordinate axes.

static log_scene_arrows(*args, **kwargs)

Overloaded function.

  1. log_scene_arrows(scene: KE::Scene::SceneBackend, path: str, starts: npt.ArrayLike | torch.Tensor, ends: npt.ArrayLike | torch.Tensor, colors: npt.ArrayLike | torch.Tensor, radius: float = 0.019999999552965164, segments: int = 12) -> list[kangengine.scene.Prim]

Create scene-backed arrow prims from numpy arrays.

  1. log_scene_arrows(scene: KE::Scene::SceneBackend, path: str, starts: collections.abc.Sequence[glm::vec<3, float, (glm::qualifier)0>], ends: collections.abc.Sequence[glm::vec<3, float, (glm::qualifier)0>], colors: collections.abc.Sequence[glm::vec<4, float, (glm::qualifier)0>], radius: float = 0.019999999552965164, segments: int = 12) -> list[kangengine.scene.Prim]

Create scene-backed arrow prims.

static log_scene_coordinate_axes(
scene: KE::Scene::SceneBackend,
path: str,
origin: glm::vec<3,
float,
(glm: :qualifier)0>,
orientation: glm::qua<float,
(glm: :qualifier)0>,
length: float = 1.0,
radius: float = 0.004999999888241291,
segments: int = 8,
) → list[Prim]

Create scene-backed XYZ coordinate axes.

static log_scene_lines(*args, **kwargs)

Overloaded function.

  1. log_scene_lines(scene: KE::Scene::SceneBackend, path: str, starts: npt.ArrayLike | torch.Tensor, ends: npt.ArrayLike | torch.Tensor, colors: npt.ArrayLike | torch.Tensor, radius: float = 0.004999999888241291, segments: int = 8) -> list[kangengine.scene.Prim]

Create scene-backed line prims from numpy arrays.

  1. log_scene_lines(scene: KE::Scene::SceneBackend, path: str, starts: collections.abc.Sequence[glm::vec<3, float, (glm::qualifier)0>], ends: collections.abc.Sequence[glm::vec<3, float, (glm::qualifier)0>], colors: collections.abc.Sequence[glm::vec<4, float, (glm::qualifier)0>], radius: float = 0.004999999888241291, segments: int = 8) -> list[kangengine.scene.Prim]

Create scene-backed line prims.

static make_arrow_transform(
start: glm::vec<3,
float,
(glm: :qualifier)0>,
end: glm::vec<3,
float,
(glm: :qualifier)0>,
) → object

Return the arrow transform, or None for a zero-length arrow.

static make_line_transform(
start: glm::vec<3,
float,
(glm: :qualifier)0>,
end: glm::vec<3,
float,
(glm: :qualifier)0>,
) → object

Return the centered line transform, or None for a zero-length line.

static update_component_arrows(
app: KE::App,
component: RenderComponent,
starts: npt.ArrayLike | torch.Tensor,
ends: npt.ArrayLike | torch.Tensor,
colors: object = None,
) → None

Update component-backed debug arrow geometry.

static update_component_lines(
app: KE::App,
component: RenderComponent,
starts: npt.ArrayLike | torch.Tensor,
ends: npt.ArrayLike | torch.Tensor,
colors: object = None,
) → None

Update component-backed debug line geometry.

Resource Prim lifecycle

SceneResourceManager is the source of truth for scene-local shared resources. Registering a mesh/material/texture or authored shader-source/pipeline assigns a runtime ResourceHandle and creates a metadata-only mirror prim under /.Resources/....

Resource prims are not renderable world objects:

  • they are created, updated, and removed by SceneResourceManager;

  • they carry ResourceComponent metadata: type, handle, display name, and URI;

  • they do not own a TransformComponent;

  • they do not own mesh/GPU payloads;

  • they are not manipulation targets;

  • renderable prims draw through their own MeshComponent.mesh_data cache and keep MeshComponent.resource_handle only as resource identity.

ResourceHandle is a runtime identifier. Use URI/path metadata for persistent asset identity when saving or rebuilding a scene.

Resource usage counts are editor diagnostics. SceneResourceManager exposes usage_count(handle) / is_used(handle) to report current scene bindings, and keeps the result in a lazy cache. Normal engine paths invalidate the cache when resources or renderable bindings change; direct material/component mutation can call invalidate_usage_cache() explicitly.

Articulation collision metadata

Articulation scene prims use components for metadata rather than a dedicated PrimType::Articulation.

  • ArticulationComponent belongs on the articulation root prim and stores source/root/mesh-asset metadata.

  • ArticulationBindingComponent records whether a generated prim is a body frame, visual geom, or collision geom and which body it belongs to.

  • CollisionShapeComponent is attached only to optional collision debug prims created by PhysicsBridge.add_collision_visuals(...).

CollisionShapeComponent mirrors reference collision data for inspection. It does not own PhysX shapes/materials. When collision debug prims are not created, physics collision still runs normally but there is no scene component to inspect.