values Module

Public Luau surface over the __values Internal FFI namespace: the named values an entity holds. Auto-injected as _G.values via the prelude; every entity proxy carries the same calls as entity(id).values. The topics/values guide covers the whole system.

A named value is a number, a vector or a boolean an entity carries under a name. Scripts and engine systems write and read it through one store, with nothing queued between a write and the next read, so the readers that follow values (material properties, Audio voices, UI props, replication) see a write on their next read with no script copying it to them.

Exports

• values.set(entity, name, value): write a value; nil removes it. A name keeps the kind of its first value.
• values.get(entity, name) -> value?: read a value.
• values.declare(entity, name, { type?, default?, replicate? }): state a name's kind, the value it starts at and the rate in Hz it replicates at; a value with no rate stays on this engine.
• values.remove(entity, name) -> boolean, values.clear(entity) -> number.
• values.list(entity) -> { [name]: value }.
• values.describe(entity) -> { row }: each value with its type, last writer (script, engine, remote), revision, replication rate and whether it is declared.
• values.entities() -> { id }: every entity holding a value.
• values.stats() -> { entities, values, revision, replication }.
• values.subscribe(entity, name?, fn) -> connection: fn(value, name, entityId) once per frame the value changed; nil name follows every value of the entity.
• values.onAnyChange(fn) -> connection: every change of every value.
• values.bind(entity, name, { format?, scale?, offset?, fallback? }): a UI prop that follows a value.

Usage

local car = entity.find("car")
car.values.declare("throttle", { type = "number", replicate = 10 })
car.values.set("throttle", 0.8)
car.values.set("brake", true)
print(values.get(car, "throttle"))            --> 0.8
for _, row in values.describe(car) do print(row.name, row.type, row.value, row.writer) end