query · world.actor

Actor relationships

Returns one Actor's retained social relationships in stable owner order.

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

Stable ID: world.actor.relationships
Owner: game.relationship and authored settlement
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.10.0

Usage

Query one actor_id to inspect the villager's retained social connections, current relationship stage, affinity, trust, strain, and latest change reason without changing either Actor.

Parameters

filters.actor_id: required stable Actor identity.
cursor: optional continuation cursor.
page_size: bounded relationship-row limit.

Returns

Detached relationship rows in stable owner order with the other villager's authored display name.

Cost

One Actor validation, one indexed Relationship lookup, and one bounded authored-name lookup per returned row.

Fields

ID	Type	Units	Required	Description
`actor_id`	`stable-id`	none	yes	Requested Actor identity.
`affinity`	`signed-integer`	basis-points	yes	Retained affinity.
`last_reason`	`enumeration`	none	yes	Reason for the latest relationship change.
`peer_actor_id`	`stable-id`	none	yes	Other Actor in the relationship.
`peer_display_name`	`string`	none	yes	Authored peer name or stable fallback label.
`relationship_id`	`stable-id`	none	yes	Relationship identity.
`stage`	`enumeration`	none	yes	Current evaluated relationship stage.
`strain`	`signed-integer`	basis-points	yes	Retained relationship strain.
`trust`	`signed-integer`	basis-points	yes	Retained trust.
`updated_at_tick`	`unsigned-integer`	ticks	yes	Latest relationship update.

Errors

Examples

local relationships = world.query("world.actor.relationships", {page_size = 4, filters = {actor_id = selected_id}})

API history

1.10.0: Retained villager relationships exposed for Village Life addendum D.