Crate khora_sdk

Expand description

The public-facing Software Development Kit (SDK) for the Khora Engine.

This is the only crate that should be used by game developers. All internal crates (khora-agents, khora-control, etc.) are implementation details.

§Examples

A minimal game is an EngineApp handed to run_winit. The SDK owns the engine loop; your type owns the game logic. Everything you need for game code is in prelude.

use khora_sdk::prelude::*;
use khora_sdk::prelude::math::Vec3;
use khora_sdk::{
    run_winit, AgentProvider, DccService, EngineApp, GameWorld, PhaseProvider,
    Runtime, Vessel, WindowConfig,
};
use khora_sdk::winit_adapters::WinitWindowProvider;

struct MyGame;

impl EngineApp for MyGame {
    fn window_config() -> WindowConfig {
        WindowConfig { title: "My Game".into(), ..WindowConfig::default() }
    }
    fn new() -> Self {
        MyGame
    }
    fn setup(&mut self, world: &mut GameWorld, _runtime: &Runtime) {
        // Spawn a camera looking down the -Z axis.
        let camera = ecs::Camera::new_perspective(
            std::f32::consts::FRAC_PI_4,
            16.0 / 9.0,
            0.1,
            1000.0,
        );
        Vessel::at(world, Vec3::new(0.0, 2.0, 10.0))
            .with_component(camera)
            .build();
    }
    fn update(&mut self, _world: &mut GameWorld, _inputs: &[InputEvent]) {}
}

// `AgentProvider` / `PhaseProvider` are required super-traits; the default
// (no custom agents, no custom phases) is enough for most games.
impl AgentProvider for MyGame {
    fn register_agents(&self, _dcc: &DccService, _runtime: &mut Runtime) {}
}
impl PhaseProvider for MyGame {}

fn main() -> anyhow::Result<()> {
    run_winit::<WinitWindowProvider, MyGame>(|_window, _runtime, _event_loop| {
        // Wire backends (renderer, physics, audio, …) into `_runtime` here.
    })
}

Re-exports§

pub extern crate inventory;

Re-exports§

pub use winit_adapters::run_winit;
pub use winit_adapters::WinitAppRunner;
pub use winit_adapters::WinitWindowProvider;
pub use khora_io;
pub use khora_data;
pub use khora_core;
pub use khora_agents;
pub use khora_lanes;
pub use winit;

Modules§

editor_ui: Editor UI types re-exported from khora_core.
prelude: Common imports for game development.
renderer: Renderer sub-modules (used by editor gizmo)
tool_ui: UI surface for standalone Khora tools (the hub, future asset cookers, …).
winit_adapters: Winit-specific integration for the Khora Engine.

Structs§

AgentHints: The accumulated hint state for one agent, folded from the EngineHints the DCC has received. A None field means “no developer hint — use the engine default”. Persists across ticks until overwritten by a newer hint.
AgentRegistry: Registry that manages all registered agents with automatic priority ordering.
AgentStatus: A snapshot of an Agent’s current health and performance.
AssetChangeEvent: One filesystem change against an asset under the watched root.
AssetEntry: A lightweight description of an asset for the asset browser panel.
AssetIdRegistry: Maps forward-slash relative asset paths to their frozen AssetUUID.
AssetService: The asset management service.
AssetWatcher: Drains filesystem-change events under a project’s assets/ directory.
Backends: Container of engine backends — concrete impls of abstract traits.
CommandHistory: Fixed-capacity undo/redo stack.
ComponentJson: Snapshot of one component on an inspected entity, captured generically as JSON via the macro-generated to_json on ComponentRegistration.
ComponentRegistration: Registration entry for a serializable component type.
CpalAudioDevice: CPAL-backed AudioDevice factory.
DccConfig: Configuration for the DCC Service.
DccContext: The complete context model used for strategic decision making.
DccService: The Dynamic Context Core service.
DefaultMixBus: Mutex-backed ringbuffer impl of AudioMixBus.
EcsWorld: The central container for the entire ECS, holding all entities, components, and metadata.
EditorCamera: An orbit camera controller for the editor viewport.
EditorCommand: A reversible editor operation.
EditorLogCapture: A log::Log implementation that stores entries in a shared buffer and also writes to stderr.
EditorState: Shared editor state populated by Application::update() each frame.
EngineContext: The complete context model used for strategic decision making.
EngineCore: The core engine state, independent of any windowing backend.
EnvironmentMap: Selects the scene’s environment source for the IBL bake.
ExecutionPhase: A phase in the frame execution pipeline.
ExecutionTiming: Declares when and how an agent should execute within the frame pipeline.
FileLoader: File-based asset loader for editor/development mode.
FileSystemResolver: Resolves resources from the local filesystem relative to a base path.
FontPack: A collection of fonts grouped by family.
GameWorld: A high-level facade over the internal ECS World and Assets registry.
GizmoLineInstance: A single line segment for GPU rendering.
GpuMonitor: GPU performance monitor that works with any RenderSystem implementation.
HandleComponent: A generic ECS component that associates an entity with a shared asset resource. It holds both a handle to the loaded data and the asset’s unique identifier.
IndexBuilder: Recursive scanner that turns a project’s assets/ directory into an AssetMetadata list ready for the VFS.
InspectedEntity: Snapshot of an inspected entity.
Interaction: Result of an UiBuilder::interact_rect call.
LogEntry: A captured log entry for the console panel.
Mat4: A 4x4 column-major matrix, used for 3D affine transformations.
MemoryMonitor: System memory resource monitor.
Mesh: Represents a complete mesh with vertex data and indices.
MeshDispatcher: Default mesh dispatcher: delegates to gltf or obj based on byte sniffing.
MetricsRegistry: Central registry for metrics in the KhoraEngine
MonitorRegistry: A thread-safe registry for resource monitors.
NamedFont: A named font face inside a pack. The name is used by the backend to register the font in its registry and (where applicable) to make it addressable by user code.
PackBuilder: Builds a release pack from a project’s assets/ directory.
PackHeader: Decoded form of the 24-byte header at the start of data.pack.
PackLoader: Pack-based asset loader for release mode.
PackOutput: Output of a successful PackBuilder::build.
RapierPhysicsWorld: Implementation of the PhysicsProvider trait using the Rapier3D physics engine.
Resources: Container of engine resources — long-lived shared state that is principally data (with at most trivial accessors), not a service.
Runtime: Bundle of the three runtime containers.
SceneFile: A logical representation of a full scene file in memory.
SceneNode: A lightweight description of an entity in the scene tree.
SerializationService: The serialization service.
Services: Container of engine services — concrete stateful objects with rich APIs (asset loading, serialization, telemetry, DCC orchestration).
SoundData: Represents a sound asset, decoded and ready for playback.
StandardTextRenderer: A “maison” (home-made) text renderer that is backend-agnostic.
StatusBarData: Status bar data displayed at the bottom of the editor.
StreamInfo: A struct providing information about the audio stream.
SymphoniaDecoder: Decodes multiple audio formats via symphonia.
TaffyLayoutSystem: Layout system implementation using the Taffy layout engine.
TelemetryService: Central service for collecting and managing engine-wide telemetry.
UiTheme: Color palette and sizing tokens for any Khora UI surface.
Vessel: A high-level wrapper around an ECS entity.
ViewportTextureHandle: An opaque handle referencing a texture that the UI backend knows how to display.
WgpuPipelineSystem: The wgpu/naga_oil PipelineSystem backend. Injected via runtime.backends as Arc<dyn PipelineSystem>.
WgpuRenderSystem: The concrete, WGPU-based implementation of the RenderSystem trait.
WindowConfig: Window configuration for applications.
WindowIcon: Raw window icon data for native window creation.

Enums§

AgentId: Unique identifier for engine agents with implicit priority ordering.
AgentImportance: How critical an agent is for frame correctness — and therefore whether GORNA budget arbitration may skip it under pressure.
AssetChangeKind: What kind of change happened to an asset on disk.
AssetSource: Represents the physical source of an asset’s data.
EditorMode: The active editing workspace, switched via the left “spine” mode bar.
EngineHint: A developer/editor hint that biases GORNA arbitration without changing game semantics — the “adapt the HOW, not the WHAT” control surface, on the same axis as [AdaptationMode]. Hints are advisory: a death-spiral safety stop and a Manual pin both still win over them. Sent to the DCC over the hint channel; the DCC folds them per agent (see AgentHints) and feeds the accumulated state into each arbitration round.
EngineMode: The current mode of the engine.
EntityIcon: Icon hint for the scene tree.
FontFamilyHint: Font family hint passed to UiBuilder::paint_text_styled. Backends map each variant to whichever face was registered for that family.
FontHandle: A bundled font, either as a static slice or owned bytes loaded at runtime.
GizmoKind: The kind of gizmo to draw for an entity.
GizmoMode: The active gizmo tool in the viewport toolbar.
Icon: A semantic icon identifier mapped to a Lucide codepoint.
InputEvent: An engine-internal representation of a user input event.
KeyCode: Type-safe physical key codes — a 1-to-1 mirror of winit::keyboard::KeyCode but living in khora-core so app code never has to depend on winit.
LogLevel: Log severity matching log::Level.
MonitoredResourceType: An enumeration of the types of resources that can be monitored.
MouseButton: An engine-internal representation of a mouse button.
PackProgress: One step of a pack build, suitable for driving a UI progress bar.
PanelLocation: Where a panel is placed in the editor dock layout.
PlayMode: The play-mode state of the editor.
PropertyEdit: A property edit to apply back to the ECS world.
SerializationGoal: Defines the developer’s high-level intention for a serialization operation.
StrategyId: Generic strategy identifier for budget allocation.
TelemetryEvent: A high-level telemetry event produced by the Hot Path or hardware sensors.
TextAlign: Horizontal alignment for UiBuilder::paint_text_styled.

Constants§

PACK_FORMAT_VERSION: Current pack format version. Bumped when the on-disk layout changes in a non-additive way; older runtimes refuse newer packs by reading the version from the header.
PACK_HEADER_SIZE: Total size in bytes of the leading PackHeader in data.pack. Asset offsets recorded in index.bin are relative to the start of the asset region, not to byte 0 — PackLoader adds this constant when seeking.
PACK_MAGIC: 8-byte magic prefix that identifies a Khora pack archive on disk.
PRIMARY_VIEWPORT: Well-known viewport handle for the primary 3D viewport.
TEXT_WGSL: Shader for text rendering. Consumed by khora_infra::StandardTextRenderer::new as a raw String.

Traits§

AgentProvider: Allows the application to register custom agents with the DCC.
AssetIo: Trait for asset I/O backends (file system or pack archive).
AssetWriter: Sibling trait to AssetIo for editor-time writing of assets back to storage. Implemented only by crate::asset::FileLoader — release builds (PackLoader) are intentionally read-only, which is why AssetWriter lives separately rather than extending AssetIo.
AudioDevice: Factory for an audio output stream.
AudioMixBus: The contract between audio-producing lanes and the audio backend.
AudioStream: Live audio stream handle. Drop = stop.
EditorPanel: A single editor panel that can render itself into a UiBuilder.
EditorShell: The top-level editor shell — a generic host for docked panels.
EngineApp: The single generic bound for the engine’s application type.
LayoutSystem: A trait defining a system capable of computing UI layouts.
PhaseProvider: Allows the application to add custom execution phases to the scheduler.
PhysicsProvider: Interface contract for any physics engine implementation (e.g., Rapier).
PipelineSystem: Backend that compiles shaders and builds/caches bind-group layouts and render pipelines on demand. See the module docs.
RenderSystem: A high-level trait representing the entire rendering subsystem.
TextRenderer: A service responsible for laying out and rendering text.
UiBuilder: A backend-agnostic, immediate-mode widget builder.
WindowProvider: Provides a platform window for the engine to render into.

Functions§

generate_selection_gizmos: Generates all gizmo lines for a set of selected entities.
instantiate_subtree: Inverse of serialize_subtree. Decodes the recipe bytes and spawns the subtree into world, returning the new root’s EntityId so the caller can position it / reparent it / treat it as the drop target’s child.
run_default: Boots a Khora game with the default runtime app: auto-detects pack vs loose assets, registers every default decoder, and loads the scene named in runtime.json. This is what the pre-built khora-runtime binary calls and what a user project’s src/main.rs should call when it doesn’t need to register custom components/agents/lanes.
serialize_subtree: Encodes the subtree rooted at root (root + all descendants reached via the Children component) as a stand-alone bincode-encoded SceneRecipe. Exists to back the editor’s “Save as Prefab” flow: the resulting bytes round-trip through instantiate_subtree.
spawn_cube_at: Creates a Vessel with a cube mesh at a specific position.
spawn_plane: Creates a Vessel with a plane mesh at the origin.
spawn_sphere: Creates a Vessel with a sphere mesh at the origin.

Crate khora_sdk

Crate khora_sdk Copy item path

§Examples

Re-exports§

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate khora_sdk