query · world.actor

Actor information

Returns detached identity, affiliation, actor revision, control authority, and condition facts for one actor.

world.actor.info(filters?, cursor?, page_size?) -> query-page

Stable ID: world.actor.info
Owner: game.actor-runtime and game.control-authority
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.0.0

Usage

Read stable Actor identity, role, life, plan, and versioned appearance-generation facts. The record also reports current work, carried work-tool and hunting-spear custody, injury and illness severity, and local weather used by detached presentation. These are source-owner facts; they do not expose sprite or mutation authority. Consume records during the current callback and use the returned cursor for bounded continuation.

Parameters

filters: optional table of query-specific stable IDs and bounded selectors.
cursor: optional opaque continuation cursor returned by the same query.
page_size: optional positive record limit capped by the host.

Returns

A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.

Cost

Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.

Fields

ID	Type	Units	Required	Description
`actor_id`	`stable-id`	none	yes	Actor identity.
`affiliation_id`	`stable-id`	none	yes	Affiliation identity.
`appearance_generation_key`	`unsigned-integer`	none	yes	Stable Actor-owned appearance generation key.
`appearance_policy_id`	`string`	none	yes	Authored appearance generator policy.
`authority_revision`	`unsigned-integer`	none	yes	Control-authority owner revision.
`body_shape`	`unsigned-integer`	none	yes	Inherited body-shape trait index.
`carries_hunting_spear`	`boolean`	none	yes	Whether Resource custody currently supplies a hunting spear.
`carries_work_tool`	`boolean`	none	yes	Whether Resource custody currently supplies a carried work tool.
`control_mode`	`enumeration`	none	yes	Current actor control mode.
`current_cell_x`	`signed-integer`	grid-cells	yes	Current World-grid X coordinate.
`current_cell_y`	`signed-integer`	grid-cells	yes	Current World-grid Y coordinate.
`current_x_meters`	`number`	meters	yes	Current embodied World X coordinate.
`current_y_meters`	`number`	meters	yes	Current embodied World Y coordinate.
`face_shape`	`unsigned-integer`	none	yes	Inherited face-shape trait index.
`hair_color`	`unsigned-integer`	none	yes	Inherited hair-color trait index.
`hair_texture`	`unsigned-integer`	none	yes	Inherited hair-texture trait index.
`illness_severity`	`unsigned-integer`	basis-points	yes	Current Actor-owned illness severity.
`injury_severity`	`unsigned-integer`	basis-points	yes	Current Actor-owned injury severity.
`life_stage`	`enumeration`	none	yes	Age-derived life stage.
`living`	`boolean`	none	yes	Whether the actor is alive.
`local_weather`	`enumeration`	none	yes	Current World-owned weather at the embodied Actor site.
`revision`	`unsigned-integer`	none	yes	Owner revision.
`skin_tone`	`unsigned-integer`	none	yes	Inherited skin-tone trait index.
`working`	`boolean`	none	yes	Whether Actor currently supplies a work layer.

Errors

Examples

local result = world.query("world.actor.info", {page_size = 16})
if result.status == "completed" then
    for _, record in ipairs(result.records) do
        -- Render or inspect detached record fields here.
    end
end

API history

1.0.0: Runtime contract published from the complete Phase 14 registry.
1.19.2: Actor-owned inherited appearance facts added for Village Life O1.
1.19.3: Current work, carried equipment, health severity, and local weather facts added for Village Life O3 presentation control.