Components
A component is a named bag of fields attached to an entity. You declare yours with engine.ecs.component, at load
time, in the same way on the server and on every client.
engine.ecs.component("game.Ship", {
fields = { position = "vec2", player = "u32" },
defaults = { player = 0 },
replication = "everyChange",
})
engine.ecs.component("game.MisfireTimer", { fields = { remaining = "f32" }, presence = "serverOnly" })
The declaration
| Option | Meaning |
|---|---|
fields |
Required. A table of field name to type name. An empty table makes a tag. |
defaults |
The starting value of some fields; a field not listed starts at zero. It can only name declared fields. |
replication |
"none" (default), "everyChange" (sent whenever it changes) or "spawnOnly" (sent once, when the entity appears). A replicated component needs at least one field: a tag cannot be sent, and the server stops at start naming it. |
presence |
"both" (default), "serverOnly" or "clientOnly": which side the component exists on. |
Any other option is an error. Names are conventionally game.Name; the rtype. and net. prefixes belong to the
engine.
Field types
| Type | In a script |
|---|---|
bool |
true / false |
i8, i16, i32, i64, u8, u16, u32, u64 |
a number |
f32, f64 |
a number |
vec2, vec3, vec4 |
a table { x = ..., y = ... } (z, w for the larger ones) |
entity |
an entity |
assetId |
the id of an asset; a path is accepted where a value is written |
string |
a string (limited to 255 bytes) |
The layout of a component is the same on every machine. When a client connects, the server checks that both sides declared the same components, and refuses a client that differs, naming the component.
Engine components
The engine's own components are declared by its plugins and used by name, with the same views as yours:
rtype.Name (value, a text: what the editor shows an entity as, given by a capsule to each entity it
spawns), rtype.Transform, rtype.Camera, rtype.SpriteRenderer, rtype.TextRenderer, rtype.ShapeRenderer,
rtype.AudioListener, rtype.Collider, rtype.RigidBody, rtype.Velocity, and the network ones net.Owner and
net.PlayerInput. Fields are written the same way (size = { x = 48, y = 48 }). Enum-like fields are numbers; for
example the physics shape is 0 box, 1 circle, 2 capsule. What exists depends on the plugins the program and
project.luau add: a server has no sprites.
Reading and writing
A system receives a view of a component for each entity it matches (see Systems). Fields read and write
like table fields: ship.position, ship.player = 1, transform.position = { x = 4, y = 5 }. A view is valid only
during the call to run: do not keep it. Writing a read-only view is an error. An entity is a value you can keep
(entity.bits identifies it, for example as a table key), and it stays valid across frames.
Where components live
The server is authoritative. A component with replication other than "none" is sent from the server to the
clients, and a system running on the client may not write it (nor a serverOnly one); this is checked when the
system is declared and when a command is recorded. Put client-only presentation data in presence = "clientOnly"
components. See Networking.