Module ecs 

Implements Khora’s custom Chunked Relational Page ECS (CRPECS).

This module contains the complete implementation of the engine’s Entity-Component-System, which is the heart of the [D]ata layer in the CLAD architecture.

The CRPECS is designed from the ground up to enable the Adaptive Game Data Flows (AGDF) concept from the SAA philosophy. Its key architectural feature is the dissociation of an entity’s identity from the physical storage of its component data, which allows for extremely fast structural changes (adding/removing components).

The primary entry point for interacting with the ECS is the World struct.

Re-exports

pub use component::Component;

pub use maintenance::EcsMaintenance;

pub use soa::FieldSoaColumn;

pub use soa::SoaLayout;

pub use system::DataSystemRegistration;

pub use system::TickPhase;

Modules

component

Component

layout

Adaptive-layout learner — the decision core of online memory-layout adaptation.

maintenance

ECS maintenance subsystem — page compaction (orphan-row reclamation).

soa

Field-split (Structure-of-Arrays) component storage — the physical layout the AGDF compute kernels want.

system

DataSystem — invariant systems of the Data layer.

systems

Invariant systems of the Data layer (Substrate Pass).

Structs

AccessCounters

Online access-pattern counters for one component type.

ActiveEvents

Indicates that an entity should receive collision events. By default, the physics engine does not report collisions for every entity to save on performance. Adding this component enables reporting for this entity.

AudioListener

An ECS component that defines the point of audition in the scene.

AudioSource

An ECS component that makes an entity an emitter of sound.

Camera

A component that defines a camera’s projection parameters.

Children

A component that lists the direct children of an entity.

Collider

Component representing a collider attached to an entity.

CollisionEvents

A component that stores collision events for the current frame. Typically attached to a singleton entity or used as a resource.

ComponentDomainRegistration

Inventory entry submitted by #[derive(Component)] when the type carries a #[component(domain = ...)] attribute.

ComponentPage

A page of memory that stores the component data for multiple entities in a Structure of Arrays (SoA) layout.

ComponentRegistry

A registry that maps component types to their semantic domains.

DomainBitset

A simple bitset wrapped around a Vec<u64>.

DomainStats

Simple statistics for a semantic domain.

EntityMetadata

Represents the central record for an entity, acting as a “table of contents” that points to the physical location of its component data across various ComponentPages.

GlobalTransform

A component that stores the final, calculated, world-space transformation of an entity.

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.

KinematicCharacterController

Component for kinematic character movement. It provides high-level movement resolution (slopes, steps, etc.) that is more suitable for player characters than raw rigid-body physics.

Light

A component that adds a light source to an entity.

MaterialRegistration

Registration entry for a serializable material type.

Name

A component providing a human-readable name for an entity.

PageIndex

A logical address pointing to an entity’s component data within a specific ComponentPage.

Parent

A component that establishes a parent-child relationship.

PhysicsDebugData

Component that holds debug rendering data for the physics simulation.

PhysicsMaterial

Defines the physical properties of a collider surface.

PlaybackState

The internal playback state of an active sound. This will be managed by the AudioMixingLane.

Prefab

Marks an entity as having been instantiated from a .kprefab asset in the project’s VFS. The source field stores the forward-slash relative path under <project>/assets/ so the editor can offer “open prefab”, “revert overrides” and “spawn another” actions.

Query

An iterator that yields the results of a WorldQuery.

QueryMut

An iterator that yields the results of a mutable WorldQuery.

QueryPlan

A pre-calculated execution strategy for a specific set of component types.

RigidBody

Component representing a rigid body in the physics simulation.

SerializableMaterialData

A serializable wrapper for a material that stores the type name and binary data.

Soa

A query that reads a field-SoA component by value.

Tag

Free-form string tags attached to an entity for grouping and querying.

Transform

A component that describes an entity’s position, rotation, and scale relative to its Parent. If the entity has no Parent, this is relative to the world origin.

TypeRegistry

A registry that provides reflection data, like type names.

Without

A WorldQuery filter that matches entities that do NOT have component T.

World

The central container for the entire ECS, holding all entities, components, and metadata.

Enums

AddComponentError

Errors that can occur when adding a component to an entity.

ComponentProvenance

Who is allowed to write a component — the axis orthogonal to SemanticDomain.

DeserializeArchetypeError

Errors that can occur while reconstructing a World from a raw archetype memory snapshot in World::deserialize_archetype.

LayoutPolicy

How a component column is physically laid out in memory.

MaterialRef

Authored reference to a material — the only serialized material form.

MeshRef

Authored reference to a mesh — the only serialized mesh form.

ProceduralMeshKind

Identifies a known procedural mesh primitive.

ProjectionType

Defines the type of camera projection.

QueryMode

Defines whether a query can be executed “natively” or requires a transversal join.

RemoveComponentError

Errors that can occur when removing a single component from an entity.

SemanticDomain

Defines the semantic domains a component can belong to.

SetFromBytesError

Error returned when raw column bytes fail validation in AnyVec::set_from_bytes.

Constants

MAX_COLUMN_PAYLOAD_BYTES

Upper bound on the byte payload accepted by AnyVec::set_from_bytes for a single component column.

Traits

AnyVec

An internal helper trait to perform vector operations on a type-erased Box<dyn Any>.

ComponentBundle

A trait for any collection of components that can be spawned together as a single unit.

WorldQuery

A trait implemented by types that can be used to query data from the World.

Functions

create_cube

Builds an axis-aligned cube primitive of the given size, centered at origin.

create_plane

Builds a flat XZ plane primitive of the given size at height y.

create_sphere

Builds a UV sphere primitive of the given radius, segments and rings.

deserialize_material_component

Deserializes a (handle, uuid) material pair from binary data.

entities_with_all_tags

Returns every entity that carries all the given tags (logical AND). An empty tags slice matches every entity that has any Tag component at all (vacuous truth).

entities_with_any_tag

Returns every entity that carries any of the given tags (logical OR). An empty tags slice yields an empty result.

entities_with_tag

Returns every entity that carries the given tag.

material_from_json

Reconstructs a (handle, uuid) pair from a JSON object produced by material_to_json. The type_name selects the matching registration; the material sub-value is decoded by that registration’s deserialize_json.

material_to_json

Serializes a material into an editable serde-JSON object of the form { "type_name": <name>, "material": <concrete material> }, matching the (type_name, data) split that serialize_material_component uses for bincode. Returns None if no registration claims the material.

reconstruct_procedural_mesh

Reconstructs a procedural [Mesh] from its kind and parameters.

serialize_material_component

Serializes a dyn Material by finding the matching MaterialRegistration and encoding the material data with its type name.

Type Aliases

MaterialDeserializeFn

Function pointer that decodes binary data into a boxed dyn Material.

MaterialHandle

Runtime-only resolved material: a shared handle to the type-erased material data plus its identifying AssetUUID. Produced by the resolver, consumed by the GPU material projection. A readable alias for call sites.