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

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{Camera, GlobalTransform, Name, Transform};
use khora_sdk::prelude::math::Vec3;

let mut world = GameWorld::new();

// Spawn a camera.
world.spawn_camera(Camera::new_perspective(
    std::f32::consts::FRAC_PI_4, 16.0 / 9.0, 0.1, 1000.0,
));

// Spawn an entity from a component bundle.
let entity = world.spawn((
    Transform::from_translation(Vec3::new(0.0, 1.0, 0.0)),
    GlobalTransform::default(),
    Name::new("hero"),
));
assert!(world.get_transform(entity).is_some());

Implementations

impl GameWorld

pub fn new() -> Self

Creates a new GameWorld with an empty world and asset registry.

pub fn from_world(world: World) -> Self

Creates a GameWorld from an existing ECS World. Used for restoring a snapshot in play mode.

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

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{GlobalTransform, Transform};

let mut world = GameWorld::new();
let entity = world.spawn((Transform::identity(), GlobalTransform::default()));
assert!(world.get_transform(entity).is_some());

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

// `mesh` is CPU-side geometry you have built or loaded.
let handle = world.add_mesh(mesh);
let entity = world.spawn((Transform::identity(), handle));

For the common case of built-in shapes, prefer the procedural helpers spawn_plane, spawn_cube_at, and spawn_sphere, which attach the mesh for you.

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 single component C from entity. Other components on the same entity (in any domain) are preserved — this is a surgical removal, not a domain wipe. Backed by World::remove_component.

No-op (silently logged) if the entity is dead or doesn’t carry C.

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

Creates a read-only query over the world.

Examples

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{GlobalTransform, Name, Transform};

let mut world = GameWorld::new();
world.spawn((Transform::identity(), GlobalTransform::default(), Name::new("a")));

// Iterate every entity that has both a Transform and a Name.
for (transform, name) in world.query::<(&Transform, &Name)>() {
    let _ = (transform.translation, &name.0);
}

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

Creates a mutable query over the world.

Examples

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{GlobalTransform, Transform};
use khora_sdk::prelude::math::Vec3;

let mut world = GameWorld::new();
world.spawn((Transform::identity(), GlobalTransform::default()));

// Nudge every transform up by one unit.
for (transform,) in world.query_mut::<(&mut Transform,)>() {
    transform.translation = transform.translation + Vec3::Y;
}

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

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{GlobalTransform, Transform};
use khora_sdk::prelude::math::Vec3;

let mut world = GameWorld::new();
let entity = world.spawn((Transform::identity(), GlobalTransform::default()));

// Move the entity, then sync so the renderer sees the new pose.
if let Some(transform) = world.get_transform_mut(entity) {
    transform.translation = transform.translation + Vec3::Y;
}
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

use khora_sdk::GameWorld;
use khora_sdk::prelude::ecs::{GlobalTransform, Transform};
use khora_sdk::prelude::math::Vec3;

let mut world = GameWorld::new();
let entity = world.spawn((Transform::identity(), GlobalTransform::default()));

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

pub fn set_parent(&mut self, child: EntityId, new_parent: Option<EntityId>)

Reparents child under new_parent, or detaches it (root) when new_parent is None.

Maintains both the Parent component on child and the Children list on the involved parents. Refuses cycles silently (a no-op).

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

Builds an authored, inline material reference to attach to entities.

The returned MaterialRef::Inline embeds the material value directly in the scene. The resolver turns it into a runtime material handle, which the GPU projection uploads. To reference a .kmat asset instead, attach MaterialRef::Asset(uuid).

Arguments

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

Returns

A MaterialRef::Inline referencing the given material.

pub fn inner_world(&self) -> &World

Returns a shared reference to the underlying ECS World.

Useful for serialization and other low-level operations that need direct access to the world outside the GameWorld API surface.

pub fn inner_world_mut(&mut self) -> &mut World

Returns an exclusive reference to the underlying ECS World.

Useful for serialization and other low-level operations that need direct access to the world outside the GameWorld API surface.

Trait Implementations

impl Default for GameWorld

fn default() -> Self

Returns the “default value” for a type.