Struct GameWorld 

pub struct GameWorld { /* private fields */ }

A high-level facade over the internal ECS World and Assets registry.

GameWorld is the primary interface for game developers to create and manage entities, components, and assets. It hides the raw types from khora-data behind a clean, stable API surface.

Examples

fn setup(&mut self, world: &mut GameWorld) {
    // Spawn a camera
    world.spawn_camera(Camera::new_perspective(
        std::f32::consts::FRAC_PI_4, 16.0 / 9.0, 0.1, 1000.0,
    ));

    // Spawn a custom entity
    world.spawn((Transform::identity(), MyComponent { speed: 10.0 }));
}

Implementations

impl GameWorld

pub fn spawn<B: ComponentBundle>(&mut self, bundle: B) -> EntityId

Spawns a new entity with the given component bundle.

Returns the EntityId of the newly created entity.

Examples

let entity = world.spawn((Transform::identity(), Velocity::default()));

pub fn despawn(&mut self, entity: EntityId) -> bool

Removes an entity and all its components from the world.

Returns true if the entity existed and was removed.

pub fn spawn_camera(&mut self, camera: Camera) -> EntityId

Spawns a camera entity with a Camera component and an identity GlobalTransform.

This is the recommended way to add a camera to the scene. The RenderAgent will automatically discover cameras during its extraction phase.

Returns the EntityId of the camera entity.

pub fn add_mesh(&mut self, mesh: Mesh) -> HandleComponent<Mesh>

Adds a mesh to the asset registry and returns a handle component.

The returned HandleComponent<Mesh> can be attached to entities to give them a visible mesh. The RenderAgent will automatically upload the mesh to GPU when the entity is rendered.

Arguments

• mesh - The CPU-side mesh data.

Returns

A HandleComponent<Mesh> that references the stored mesh.

Examples

let plane_mesh = create_plane(10.0, 0.0);
let handle = world.add_mesh(plane_mesh);
let entity = world.spawn((Transform::identity(), handle));

pub fn add_component<C: Component>(&mut self, entity: EntityId, component: C)

Adds a component to an existing entity.

If the entity already has a component of this type, the old value is replaced.

pub fn remove_component<C: Component>(&mut self, entity: EntityId)

Removes a component (and its semantic domain) from an entity.

This is an O(1) operation — the data is orphaned and cleaned up later by the garbage collector agent.

pub fn query<'a, Q: WorldQuery>(&'a self) -> Query<'a, Q>

Creates a read-only query over the world.

Examples

for (pos, vel) in world.query::<(&Transform, &Velocity)>() {
    // iterate matching entities
}

pub fn query_mut<'a, Q: WorldQuery>(&'a mut self) -> QueryMut<'a, Q>

Creates a mutable query over the world.

Examples

for (pos,) in world.query_mut::<(&mut Transform,)>() {
    pos.translate(Vec3::Y * delta);
}

pub fn spawn_entity(&mut self, transform: &Transform) -> EntityId

Spawns an entity with just a transform component.

Returns the EntityId of the newly created entity.

pub fn iter_entities(&self) -> impl Iterator<Item = EntityId> + '_

Returns an iterator over all entity IDs in the world.

pub fn get_transform_mut(&mut self, entity: EntityId) -> Option<&mut Transform>

Gets a mutable reference to a transform component.

Returns None if the entity doesn’t exist or has no transform.

pub fn get_transform(&self, entity: EntityId) -> Option<&Transform>

Gets a reference to a transform component.

Returns None if the entity doesn’t exist or has no transform.

pub fn get_component_mut<C: Component>( &mut self, entity: EntityId, ) -> Option<&mut C>

Gets a mutable reference to any component.

Returns None if the entity doesn’t exist or has no such component.

pub fn get_component<C: Component>(&self, entity: EntityId) -> Option<&C>

Gets a reference to any component.

Returns None if the entity doesn’t exist or has no such component.

pub fn sync_global_transform(&mut self, entity: EntityId)

Synchronizes the GlobalTransform component from the Transform component.

This should be called after modifying a Transform to ensure the changes are visible to the rendering system. This is a convenience method that copies the local transform to the global transform.

Example

// Move entity
if let Some(transform) = world.get_transform_mut(entity) {
    transform.translation += Vec3::Y * delta;
}
// Sync to rendering
world.sync_global_transform(entity);

pub fn update_transform<F>(&mut self, entity: EntityId, f: F)

where F: FnOnce(&mut Transform),

Updates an entity’s transform and immediately syncs it to GlobalTransform.

This is a convenience method that combines getting the transform, applying a modification function, and syncing to GlobalTransform.

Example

world.update_transform(entity, |t| {
    t.translation += Vec3::Y * delta;
});

pub fn add_material<M: Material>(&mut self, material: M) -> MaterialComponent

Adds a material to the asset registry and returns a handle component.

The returned MaterialComponent can be attached to entities to give them a visible material.

Arguments

• material - The CPU-side material data (e.g., StandardMaterial).

Returns

A MaterialComponent that references the stored material.