query · world.actor

Actor needs

Returns the six current pressure values for one actor.

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

Stable ID: world.actor.needs
Owner: game.actor-runtime
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

Call this query through world.query with the stable ID world.actor.needs. Each detached record includes hunger, hydration, rest, safety, warmth, and companionship pressure in basis points. 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.
`companionship`	`unsigned-integer`	basis-points	yes	Companionship pressure.
`hunger`	`unsigned-integer`	basis-points	yes	Hunger pressure.
`hydration`	`unsigned-integer`	basis-points	yes	Hydration pressure.
`rest`	`unsigned-integer`	basis-points	yes	Rest pressure.
`safety`	`unsigned-integer`	basis-points	yes	Safety pressure.
`warmth`	`unsigned-integer`	basis-points	yes	Warmth pressure.

Errors

Examples

local result = world.query("world.actor.needs", {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; Phase 16B added hydration pressure to the detached need fields.