kangengine¶
This page documents application-wide entry points and helpers exported directly
by the kangengine package. With the conventional
import kangengine as ke alias, these are accessed as ke.App,
ke.DebugGeometry, and similar top-level names.
Specialized APIs are grouped by responsibility under domain modules such as
ke.scene, ke.physics, ke.material, and ke.sim. Use the documented
public paths regardless of whether an object is implemented in C++ or Python.
Use the API Reference navigation to jump to a specific area.
Application¶
Application lifecycle, camera access, and viewport interaction.
- class kangengine.App[native]¶
Bases:
AppBase class for Python KangEngine apps.
This mirrors the C++ App lifecycle:
setup() runs once before the loop starts.
pre_update() handles per-frame input before simulation updates.
fixed_update(dt) runs zero or more fixed updates per rendered frame.
pre_render() runs before scene rendering each frame.
render() runs while the ImGui frame is active.
post_render() runs after UI rendering and buffer swap setup.
The C++ implementation still handles the default camera controls: WASD/mouse navigation, H to hide UI, Escape to close, framebuffer updates, and the built-in scene/performance panels.
Fixed-step simulations may opt into Enter play/pause and Space pause/single-step controls with set_simulation_hotkeys_enabled(True).
- add_ground(path: str = '/ground', scale: float = 20.0, material=None)¶
- add_mesh(path: str, mesh_data, material=None, color=None, *, uri=None)¶
- add_obj(path: str, obj_path, **kwargs)¶
- add_playback_target(target)¶
- add_render_hook(phase, callback, *, pipeline=None)¶
Register a custom draw callback and optionally track its pipeline.
- add_skinned_mesh(prim, material, skinned_mesh_data, transform_source=None)¶
Register a skinned mesh prim and return a RenderablePrimView.
The bind mesh is registered as the shared resource identity. Runtime skinning and deformable vertex updates remain per-renderable state.
- as_vec3(value)¶
- cleanup()¶
- configure_run(config)¶
Apply the rendering policy used by App-owned services.
- configure_timing(config)¶
Apply a SimulationTimingConfig to this application loop.
- create_pbr_material(
- preset=None,
- *,
- base_color=None,
- metallic=None,
- roughness=None,
- emissive_color=None,
- emissive_strength=None,
- base_color_texture=None,
- normal_texture=None,
- metallic_roughness_texture=None,
- metallic_texture=None,
- roughness_texture=None,
- ao_texture=None,
- orm_texture=None,
- emissive_texture=None,
Create and retain a PBR material instance.
Material identity is intentionally per instance: sharing one material shares its parameters, while separate materials can use the same shader with different factors/textures.
- Return type:
- create_phong_material(
- preset=None,
- *,
- ambient=None,
- diffuse=None,
- specular=None,
- shininess=None,
- diffuse_map=None,
- specular_map=None,
- alpha_map=None,
- normal_map=None,
Create and retain a Phong material instance.
Each call returns a distinct material, so two meshes can share the same shader while carrying different colors/textures and batching keys.
- Return type:
- create_scene_hook_pipeline(desc, *, shader_uris=None, shader_languages=None)¶
Create a custom scene pipeline and mirror its authored definition.
The returned backend pipeline remains caller-owned. Shader sources and the pipeline definition are copied into
/.Resourcesfor editor inspection; compiled backend objects are not scene resources.
- create_standard_materials(*, force: bool = False)¶
Create or return the cached standard material bundle.
The bundle contains shared defaults for common scene and visualization work. Use create_phong_material() or create_pbr_material() when an object needs independently mutable surface parameters.
- create_standard_shaders(*, force: bool = False)¶
Compatibility alias for the built-in material bundle.
Standard render paths no longer expose backend Shader objects. New code should call
create_standard_materials()directly.
- create_vertex_color_material(
- *,
- style=<VertexColorStyle.UNTEXTURED: 0>,
Create and retain a built-in vertex/display-color material.
- Return type:
- fixed_update(self: App, fixed_dt: float) None¶
User override called zero or more times at a fixed timestep.
- get_native_scene()¶
Return the native SceneBackend escape hatch.
Public Python code should prefer self.scene for authored scene workflows. Use this only when a C++ or pybind API explicitly requires SceneBackend.
- get_renderer()¶
Return the native renderer exposed through
ke.render.
- get_scene()¶
Return the Python-friendly SceneContext facade.
This mirrors the
app.sceneproperty. Use get_native_scene() or scene.native only when a C++ or pybind API explicitly requires the native SceneBackend.
- get_video_recording_path()¶
- initialize(
- self: App,
- width: int,
- height: int,
- hide_ui: bool = False,
- up_axis: kangengine.UpAxis = <UpAxis.Y: 1>,
- graphics_backend_type: kangengine.BackendType = <BackendType.OPENGL: 0>,
- scene_backend_type: kangengine.scene.BackendType = <BackendType.NATIVE: 0>,
- headless: bool = False,
Initialize the window, renderer, input, and scene backend.
- is_key_down(key)¶
- is_video_recording() bool¶
- Return type:
bool
- load_texture(path, *, flip: bool = True) Texture¶
Load and retain a GPU texture, cached by normalized path.
- Return type:
- package_asset_path(*parts: str) str¶
- Return type:
str
- remove_render_hook(handle)¶
Remove a custom scene draw callback.
- set_camera_view(position, target)¶
- set_render_hz(hz: float)¶
Set the target render/update frequency in Hz.
- set_video_recording_dir(output_dir)¶
- set_video_recording_fps(fps: float)¶
- set_video_recording_resolution(width: int | None, height: int | None = None)¶
Set the recording resolution cap, or pass None for native size.
- should_close_shortcut_pressed()¶
- start_video_recording(output_path=None, fps: float | None = None)¶
Start framebuffer recording using the configured run mode.
- stop_video_recording()¶
Stop framebuffer recording and finalize the output file.
- toggle_video_recording()¶
Toggle framebuffer recording, matching the Shift+T shortcut.
- was_key_pressed(key)¶
- was_key_released(key)¶
- class kangengine.SimulationTimingConfig(
- render_hz: float = 60.0,
- physics_hz: float = 120.0,
- fixed_update_hz: float = 60.0,
- max_catch_up_steps: int = 8,
- max_frame_delta: float = 0.25,
Rates and safety limits for an App-driven simulation loop.
Rates are the writable source of truth. Time intervals are derived to avoid contradictory
hzanddtsettings.- render_hz¶
- physics_hz¶
- fixed_update_hz¶
- max_catch_up_steps¶
- max_frame_delta¶
- property decimation¶
Physics substeps represented by one fixed update.
- property fixed_dt¶
Duration in seconds of one App fixed update.
- classmethod from_dt(
- *,
- physics_dt: float,
- fixed_dt: float,
- render_hz: float = 60.0,
- max_catch_up_steps: int = 8,
- max_frame_delta: float = 0.25,
Create a config at a boundary that already expresses time in dt.
- Return type:
- property physics_dt¶
Duration in seconds of one physics substep.
- property sim_dt¶
Compatibility alias for
physics_dt.
- class kangengine.SceneContext(app: App)[python]¶
Scene-facing facade connected to the owning App renderer.
Use this for common add/remove workflows. It keeps renderer handles inside the app-facing layer while preserving access to the underlying scene backend for lower-level operations.
- add_ground(path: str = '/ground', scale: float = 20.0, material=None)¶
Add a checkerboard ground plane.
- add_mesh(
- path: str,
- mesh_data,
- material,
- color=None,
- transform_source=None,
- uri=None,
- add_obj(path: str, obj_path, *, transform_source=None, double_sided=False)¶
Load an OBJ/MTL file and add material-subset mesh prims.
Multi-material OBJ files become one Xform root with one renderable child per material subset. Single-material OBJ files still use the same code path, which keeps resource registration and material creation consistent.
- add_renderable(prim, material, transform_source=None)¶
Register a scene prim as renderable through RenderComponent.
This is the preferred public path for authored scene objects. It returns a RenderablePrimView facade instead of exposing the native renderer handle. Pass a Material describing the render surface.
- define_prim(path: str, prim_type)¶
- get_prim_at_path(path: str)¶
- get_root_prim()¶
- log_arrows(
- path: str,
- material,
- starts,
- ends,
- colors=None,
- radius: float = 0.02,
- segments: int = 12,
- log_lines(
- path: str,
- material,
- starts,
- ends,
- colors=None,
- radius: float = 0.005,
- segments: int = 8,
- property native¶
Return the native SceneBackend escape hatch.
Prefer SceneContext helpers such as add_mesh(), add_ground(), and define_prim() for authored scene objects. Use native only when a C++ or pybind API explicitly requires SceneBackend.
- remove_prim(path_or_prim)¶
- class kangengine.DebugGeometry(scene_context: SceneContext)[python]¶
Mesh-based debug geometry owned by the SceneGraph.
- add_arrows(
- path: str,
- starts,
- ends,
- colors=None,
- *,
- material=None,
- radius: float = 0.02,
- segments: int = 12,
Add instanced arrow meshes and return a DebugPrimitiveView.
- add_axes(
- path: str,
- origin,
- rotation=None,
- *,
- length: float = 1.0,
- material=None,
- radius: float = 0.005,
- segments: int = 8,
Add RGB axis meshes and return a DebugPrimitiveView.
- add_lines(
- path: str,
- starts,
- ends,
- colors=None,
- *,
- material=None,
- radius: float = 0.005,
- segments: int = 8,
Add instanced line meshes and return a DebugPrimitiveView.
- add_spheres(
- path: str,
- centers,
- radii=0.5,
- colors=None,
- *,
- material=None,
- segments: int = 16,
- rings: int = 12,
Add instanced solid spheres and return a DebugPrimitiveView.
- class kangengine.DebugOverlay(app: App)[python]¶
OpenGL debug overlay that does not create SceneGraph prims.
- axes(
- path: str,
- origin,
- rotation=None,
- *,
- length: float = 1.0,
- width: float = 1.0,
- hidden: bool = False,
- clear(path: str)¶
Clear both line/axis and point overlay batches at a path.
- clear_lines(path: str)¶
- clear_points(path: str)¶
- lines(
- path: str,
- starts,
- ends,
- colors=None,
- *,
- width: float = 1.0,
- hidden: bool = False,
- points(
- path: str,
- points,
- colors=None,
- *,
- size: float = 6.0,
- hidden: bool = False,
- overlay: bool = False,
- class kangengine.WorldText(app: App)[python]¶
Persistent screen-aligned text anchored at world-space positions.
- clear()¶
- remove(path: str)¶
- set(
- path: str,
- text: str,
- position,
- *,
- color=None,
- pixel_size: float = 18.0,
- alignment=None,
- depth_test: bool = True,
- hidden: bool = False,
- set_position(path: str, position)¶
- set_text(path: str, text: str)¶
- class kangengine.ScreenText(app: App)[python]¶
Persistent text positioned in viewport pixel(screen) coordinates.
- clear()¶
- remove(path: str)¶
- set(
- path: str,
- text: str,
- position,
- *,
- color=None,
- pixel_size: float = 18.0,
- alignment=None,
- anchor=None,
- hidden: bool = False,
- set_position(path: str, position)¶
- set_text(path: str, text: str)¶
- class kangengine.RenderablePrimView(app: App, prim, component)[python]¶
User-facing view for one scene prim and its renderer resources.
- compute_local_matrix()¶
Compute the effective parent-relative transform matrix.
- compute_world_matrix()¶
Compute the effective world-space transform matrix.
- get_base_color()¶
Return the per-instance base-color multiplier.
- get_local_rotation()¶
Return the effective parent-relative quaternion rotation.
- get_local_translation()¶
Return the effective parent-relative translation.
- get_world_rotation()¶
Return the effective world-space quaternion rotation.
- get_world_translation()¶
Return the effective world-space translation.
- property path¶
- remove()¶
- set_alpha_mode(mode, cutoff: float = 0.5)¶
Choose opaque, cutout-mask, or blended alpha rendering.
- set_base_color(color)¶
Set the per-instance base-color multiplier for this renderable.
- set_casts_shadow(enabled: bool = True)¶
- set_double_sided(enabled: bool = True)¶
- set_local_matrix(matrix)¶
Set the parent-relative transform matrix.
- set_local_rotation(rotation)¶
Set the parent-relative quaternion rotation.
- set_local_rotation_axis_angle(axis, angle_radians: float)¶
Set parent-relative rotation from an axis and angle in radians.
- set_local_scale(scale)¶
Set the parent-relative scale.
- set_local_translation(translation)¶
Set the parent-relative translation.
- set_material(material)¶
Replace this renderable’s material and move it to the right batch.
- set_texture(texture, role_or_slot=<TextureRole.BASE_COLOR: 0>)¶
- set_transform_buffer(
- transforms,
- *,
- sim_device=None,
- sync_policy=None,
- version=None,
Set an ExternalBuffer renderable’s
[N, 4, 4]transform buffer.versionlets a versioned producer mark reused storage as changed without allocating a new NumPy array or Torch tensor.
- set_visible(visible: bool)¶
- set_world_matrix(matrix)¶
Set the transform matrix in world space.
- set_world_rotation(rotation)¶
Set quaternion rotation in world space.
- set_world_rotation_axis_angle(axis, angle_radians: float)¶
Set world rotation from an axis and angle in radians.
- set_world_translation(translation)¶
Set translation in world space.
- update_geometry(positions, normals=None)¶
Update dynamic vertex positions and optional normals.
- update_skinning(bone_matrices)¶
Update skinned bone matrices for this renderable.
- class kangengine.RayPickResult[native]¶
- property distance¶
- property handle¶
- property hit¶
- property instance_index¶
- property position¶
- property prim¶
- property transform_source¶
ke.imgui¶
Small Dear ImGui binding for application panels and controls. Access these
functions through ke.imgui.
Small Dear ImGui wrapper for Python apps
Window flags¶
Name |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
- kangengine.imgui.begin(name: str, flags: int = 0) bool[native]¶
- kangengine.imgui.begin_child(
- id: str,
- width: float = 0.0,
- height: float = 0.0,
- border: bool = False,
- kangengine.imgui.button(arg0: str) bool[native]¶
- kangengine.imgui.checkbox(label: str, value: bool) tuple[native]¶
- kangengine.imgui.cursor_screen_pos() tuple[native]¶
- kangengine.imgui.draw_circle_filled(
- x: float,
- y: float,
- radius: float,
- color: glm::vec<4,
- float,
- (glm: :qualifier)0>,
- kangengine.imgui.draw_convex_polygon_filled(
- points: collections.abc.Sequence,
- color: glm::vec<4,
- float,
- (glm: :qualifier)0>,
- kangengine.imgui.draw_line(
- x1: float,
- y1: float,
- x2: float,
- y2: float,
- color: glm::vec<4,
- float,
- (glm: :qualifier)0>,
- thickness: float = 1.0,
- kangengine.imgui.draw_rect_filled(
- x1: float,
- y1: float,
- x2: float,
- y2: float,
- color: glm::vec<4,
- float,
- (glm: :qualifier)0>,
- kangengine.imgui.end() None[native]¶
- kangengine.imgui.end_child() None[native]¶
- kangengine.imgui.image(
- texture: kangengine.Texture,
- width: float,
- height: float,
- opacity: float = 1.0,
- kangengine.imgui.main_viewport_work_rect() tuple[native]¶
- kangengine.imgui.motion_sequencer(
- label: str,
- current_frame: int,
- frame_min: int,
- frame_max: int,
- first_frame: int = 0,
- expanded: bool = True,
- selected_entry: int = -1,
- item_label: str = 'Motion',
- fit_to_content: bool = False,
- kangengine.imgui.motion_sequencer_resizable(
- label: str,
- current_frame: int,
- frame_min: int,
- frame_max: int,
- first_frame: int = 0,
- expanded: bool = True,
- selected_entry: int = -1,
- item_label: str = 'Motion',
- fit_to_content: bool = False,
- legend_width: float = 200.0,
- kangengine.imgui.progress_bar(
- fraction: float,
- width: float = -1.0,
- height: float = 0.0,
- overlay: str = '',
- kangengine.imgui.same_line() None[native]¶
- kangengine.imgui.separator() None[native]¶
- kangengine.imgui.set_next_window_pos(x: float, y: float) None[native]¶
- kangengine.imgui.set_next_window_size(width: float, height: float) None[native]¶
- kangengine.imgui.slider_float(label: str, value: float, min: float, max: float) tuple[native]¶
- kangengine.imgui.text(arg0: str) None[native]¶
- kangengine.imgui.text_disabled(arg0: str) None[native]¶
ke.keys¶
Keyboard constants accepted by the App input helpers. Access them through
ke.keys, for example ke.keys.ESCAPE, ke.keys.SPACE, or ke.keys.A.
GLFW keyboard key constants
Key constants¶
Name |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|