1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
|
---
name: add-flecs-system
description: Use when adding or editing a Flecs ECS component or system in game Ruby code. Covers declaring components as runtime meta structs, registering systems with the right phase, the raw-id/writeback semantics, what survives a hot-reload, and (once Part B R3 lands) the hot-reloadable system registry and live-mount verification.
---
# Add a Flecs component / system
Read `.agents/knowledge/flecs-binding.md` first. Components are **real C structs
declared at runtime** via the meta addon; values cross as Ruby Hashes.
## Steps
1. **Declare components** as meta structs:
`pos = world.struct("Position", "{float x; float y;}")`.
- Adding a **new** component is additive and **hot-reload safe**.
- Changing an **existing** component's struct **layout** needs a **reboot**
(existing entities hold the old layout) — see the hot-reload table (R3).
2. **Register a system:**
```ruby
world.system("Move", with: [pos, vel], phase: Flecs::ON_UPDATE) do |id, p, v|
p[:x] += v[:x]; p[:y] += v[:y] # mutations to p/v are written back
end
```
- The yielded entity is a **raw Integer id** (no per-entity wrapper alloc); use
`world.entity_for(id)` when you need entity methods. A `tag` term yields `nil`.
3. **Pick a phase** (run order per `progress`):
`ON_LOAD → PRE_UPDATE → ON_UPDATE` (default) `→ ON_START`.
4. **Queries** for ad-hoc iteration: `world.query(pos).each { |id, p| … }` (cached,
`Enumerable`, same writeback semantics). Build once, reuse across frames.
5. **(Part B / R3 — planned)** Define systems through the **hot-reload registry**
(`define_system(name, with:, phase:, &blk)`) so re-running the file **swaps the
proc** in place — same system id, same matched tables, entity/component state
preserved. Organize reloadable units as `game/components.rb`,
`game/systems/*.rb` re-runnable top-to-bottom.
6. **Verify:** `./zig-out/bin/game game/<scene>.rb`; confirm the same script under
`node build/web/game.js /game/<scene>.rb` (flecs logic is identical across
targets — validate desktop first, it's faster). (Part B) inspect entity/component
state via the live mount.
## Cross-refs
- Knowledge: `.agents/knowledge/flecs-binding.md` · Spec: `docs/API_SPEC_FLECS.md`
- Glossary: World/Entity/Component/tag/System/phase/query
- Roadmap R3 (hot-reload) for the registry mechanism.
|
