Components
A component is any C# class that holds data, not behavior. Components must be reference types (classes, not structs). All built-in components live in managed/core/Components.cs.
Utility Types
Vec3
A 3D vector used for positions, rotations, directions, and sizes throughout the API.
new Vec3() // (0, 0, 0)
new Vec3(1f, 2f, 3f) // (1, 2, 3)
Color
A utility class for representing RGBA colors. Used by Light.LightColor, Collider.DebugColor, and procedural mesh creation.
// From float values (alpha defaults to 1.0)
new Color(1f, 0.5f, 0f)
new Color(1f, 0f, 0f, 0.5f) // with alpha
// From hex string (#RRGGBB or #RRGGBBAA)
new Color("#ff6600")
new Color("#ff660080") // with alpha
// Presets
Color.Green // (0, 1, 0)
Color.Red // (1, 0, 0)
Color.Blue // (0, 0, 1)
Color.Yellow // (1, 1, 0)
Color.Cyan // (0, 1, 1)
Color.White // (1, 1, 1)
Enums
LightType
LightType.Directional // 0 — parallel light (sun)
LightType.Point // 1 — omnidirectional light
LightType.Spot // 2 — cone-shaped light
ShapeType
ShapeType.Box // 0
ShapeType.Sphere // 1
ShapeType.Capsule // 2
ShapeType.Cylinder // 3
ShapeType.Plane // 4
CameraMode
CameraMode.ThirdPerson // 0 — orbit camera (default)
CameraMode.FirstPerson // 1 — eye-level camera
Built-in Components
Position, rotation (degrees), and scale in 3D space.
world.AddComponent(entity, new Transform {
Position = new Vec3(1f, 0f, -2f),
Rotation = new Vec3(0f, 45f, 0f),
Scale = new Vec3(1f, 1f, 1f)
});
Transform.ToMatrix() returns a column-major float[16] matching GLM's memory layout. The rotation order is Rz _ Ry _ Rx, matching a glm::rotate chain of X then Y then Z.
MeshComponent
Links an ECS entity to a loaded mesh and a renderer-side entity. Both fields are engine-internal (prefixed with _) — use world.SpawnMeshEntity() instead of setting them directly.
// Preferred: use SpawnMeshEntity
int entity = world.SpawnMeshEntity(meshId, new Transform());
// Manual (advanced): fields are engine-internal
var mc = new MeshComponent();
// mc._MeshId and mc._RendererEntityId are set by SpawnMeshEntity
You can create multiple entities sharing the same mesh (instancing the same geometry).
Movable
A marker component that flags an entity as controllable by the player controller.
world.AddComponent(entity, new Movable { Speed = 2.0f });
Speed controls horizontal move speed (units/second). The default InputMovementSystem uses camera-relative WASD movement and jump (SPACE) with physics.
Camera
Attaches an orbiting camera to an entity. See the Camera feature page for full details.
world.AddComponent(entity, new Camera {
Offset = new Vec3(0f, 0f, 3f),
Yaw = 0f, Pitch = 0f,
Fov = 45f,
LookSpeed = 90f,
MouseSensitivity = 0.15f
});
Timer
A countdown or interval timer. Ticked automatically by TimerSystem.
world.AddComponent(entity, new Timer {
Duration = 2.0f,
Repeat = true,
Tag = "spawn"
});
Hierarchy
Links a child entity to its parent for transform inheritance and cascade despawn.
world.AddComponent(child, new Hierarchy { Parent = parentEntity });
Stores the computed world-space transform matrix for entities in a hierarchy. Managed automatically by HierarchyTransformSystem.
Light
A dynamic light source. See the Lighting feature page for full details.
world.AddComponent(entity, new Light {
Type = LightType.Directional,
LightColor = Color.White,
Intensity = 1f,
Direction = new Vec3(0f, -1f, 0f),
Radius = 10f,
InnerConeDeg = 12.5f, OuterConeDeg = 17.5f
});
Rigidbody
Defines the dynamics properties of a physics body. See the Physics feature page for full details.
world.AddComponent(entity, new Rigidbody {
MotionType = JPH_MotionType.Dynamic,
Friction = 0.5f,
Restitution = 0.3f,
LinearDamping = 0.05f,
AngularDamping = 0.05f,
GravityFactor = 1.0f
});
Collider
Defines the collision shape. Used together with Rigidbody and Transform.
world.AddComponent(entity, new Collider {
Shape = ShapeType.Box,
BoxHalfExtents = new Vec3(0.5f, 0.5f, 0.5f),
DebugColor = Color.Red
});
Internal Fields (Underscore Convention)
Fields prefixed with _ are engine-managed and should not be set directly by game code:
Writing Custom Components
Define a class — components are plain data holders:
namespace ECS
{
public class Health
{
public float Current = 100f;
public float Max = 100f;
}
public class Velocity
{
public Vec3 Value = new Vec3();
}
public class Enemy
{
public float AggroRange = 5f;
}
}
Then attach them to entities:
int goblin = world.Spawn(
new Transform { Position = new Vec3(5f, 0f, 0f) },
new Health { Current = 50f, Max = 50f },
new Enemy { AggroRange = 3f }
);
world.AddComponent(goblin, new MeshComponent()); // or use SpawnMeshEntity