Entities and Components

All Out games are built around entities (things in the world) and components (behavior/data attached to entities).

If you’ve used Unity before: think “GameObject + Components”. If you’ve used Roblox: think “Instance + Scripts/Components”. The core idea is the same: you compose gameplay by adding components to entities.

Entities

Entities exist in two common ways:

• Placed in the editor: they’re already in the scene at startup.
• Created at runtime: you spawn them from script.

Creating and destroying entities

entity := Scene.create_entity();
entity.set_local_position({10, 20});
entity.set_local_scale({2.5, 2.5});
entity.set_local_rotation(0);

// When you're done:
entity.destroy();

Destroying an entity destroys its components too. Don’t keep references to components after you destroy their entity.

Iterating entities

for e: entity_iterator() {
    // ...
}

Components

Components are the units of behavior. A component “lives on” an entity and can read/modify that entity.

Getting and adding components

sprite := entity.get_component(Sprite_Renderer);

player := entity.get_component(Player);

my_comp := entity.add_component(My_Component);

Iterating components

for enemy: component_iterator(Enemy) {
    enemy.tick_ai();
}

Built-in components you’ll use a lot

Sprite_Renderer

texture := get_asset(Texture_Asset, "ui/button.png");

sprite := entity.get_component(Sprite_Renderer);
sprite.set_texture(texture);
sprite.color = {1, 1, 1, 1}; // RGBA
sprite.depth_offset = 0.5;
sprite.layer = 10;

// Optional: use a custom material. Pass true if the renderer should own it.
// sprite.set_material(material, true);

Prefabs (Prefab_Asset)

Prefabs must be created in the editor. In scripts, you instantiate them.

prefab := get_asset(Prefab_Asset, "MyPrefab.prefab");
spawned := Scene.instantiate(prefab);
spawned.set_local_position({1, 3});

Spine (Spine_Animator)

If you’re using 2D animated characters, you’ll often work with Spine_Animator. See Spine.

Writing a custom component

Make new components in dedicated files (e.g. orbiter.csl) and attach them to entities either:

• Manually in the editor, or
• At runtime with entity.add_component(...)

Components can implement lifecycle callbacks:

• ao_start()
• ao_update(dt)
• ao_late_update(dt) (after all updates)
• ao_end() (when destroyed)

Example:

Orbiter :: class : Component {
    center: v2;
    radius: float;
    speed: float;
    angle: float;

    ao_start :: method() {
        center = entity.local_position;
        radius = 2;
        speed = 1;
        angle = 0;
    }

    ao_update :: method(dt: float) {
        angle += speed * dt;

        offset_x := cos(angle) * radius;
        offset_y := sin(angle) * radius;

        entity.set_local_position({center.x + offset_x, center.y + offset_y});
    }
}

Lifecycle methods for global scripts (ao_start, ao_update, ...) are covered in Game/Frame Lifecycle.

Serialized fields (@ao_serialize)

Use @ao_serialize to expose a field in the Inspector and include it in scene and JSON serialization.

Chest :: class : Component {
    capacity: int @ao_serialize;
}

Triggers and proximity queries

Trigger colliders expose on_trigger_start, on_trigger_stay, and on_trigger_end callbacks. See Navmesh and Collision for setup and callback signatures.

Use proximity queries when you need every component in a radius or only the closest one.

Useful helpers:

Scene.get_all_components_in_range     :: proc(position: v2, range: float, results: ref [..]$T)
Scene.get_closest_component_in_range  :: proc(position: v2, range: float, $T: typeid) -> T, bool

Example:

nearby: [..]Enemy;
Scene.get_all_components_in_range(player.entity.world_position, 5.0, ref nearby);

for e: nearby {
    // ...
}

closest_pickup, found := Scene.get_closest_component_in_range(player.entity.world_position, 2.0, Pickup);
if found {
    // ...
}

Best practices

• Per-player state belongs on Player. Avoid global variables that would break with multiple players.
• Prefer components for gameplay behaviors. You’ll end up with reusable pieces you can attach to different entities.
• Draw player UI from Player.ao_late_update. Wrap it in is_local_or_server().
• Use is_local() only for player-specific visual overrides. Do not change gameplay or UI state inside it.