`data/smart_objects/`

A smart object definition: an entity that advertises activities and owns slots agents claim, so a mod adds a forge, a bench or a shrine without touching any brain. A brain’s activity finds objects with targets: SmartObjects(..), claims a slot with ClaimSlot and runs the slot’s behaviour with UseSlot. An entity becomes one through the manifold-ai:smart-object component, (def: "<key>"). Loaded by the server only.


Registry	`manifold-ai:smart-object`
Files	`data/smart_objects/.ron`, `.update.ron`, `*.final.ron`
Sides	server: only the server loads it
Reads	`manifold-ai:state-tree`
Contract	Population, data stage

Entry

A record, written SmartObject(..); the name before the parentheses is optional.

Field	Type	Required	Default	Description
`id`	`string`	yes		The definition’s key, `<mod-id>:<name>`.
`tags`	list of `string`	no	none	The object’s tags, dotted; a query’s tag matches itself and its descendants.
`slots`	list of `Slot`	no	none	Its slots, at most 16 with the engagement ring’s.
`engagement`	`Engagement` or `None`	no	none	A ring of engagement slots around the object (a large enemy), so melee attackers spread around it.
`advertisements`	list of `Advertisement`	no	none	The activities it offers, at most 8.
`player_usable`	`bytes`	no	none	Slot ids players may occupy.
`query_radius`	`u16`	no	`48`	The distance, in blocks, at which an advertisement’s score halves.

Example

No bundled file declares one yet. From the reference’s test fixture, crates/manifold-server-state/tests/data-reference-fixture/data/smart_objects/workshop.ron, which the data stage loads in its tests:

SmartObjectDef(id: "dataref-fixture:so/marker")

Types

`Slot`

A claimable slot.

A record: Slot(..) or (..).

Field	Type	Required	Default	Description
`id`	`u8`	yes		The slot’s id, unique within the object.
`offset`	(`f32`, `f32`, `f32`)	no	`(0.0, 0.0, 0.0)`	Where the occupant stands, from the object’s position, turned by the object’s yaw.
`yaw`	`f32`	no	`0.0`	The way the occupant faces, in degrees, added to the object’s yaw.
`tags`	list of `string`	no	none	The slot’s tags, which advertisements and jobs name.
`accepts`	`condition` or `None`	no	anyone	A condition in the `smart_object` context (`This` the agent, `Target` the object) an occupant must meet.
`behaviour`	`SlotBehaviour`	yes		What the occupant does there.
`timeout`	`duration`	no	`"60s"`	How long a claim lasts unless renewed.

`SlotBehaviour`

What a slot’s occupant does.

Variant	Written	Description
`StateTree`	`StateTree(string)`	A state tree by key (`manifold-ai:state-tree`), which must be declared.
`Tasks`	`Tasks([Task])`	Tasks run in order, at least one: `Tasks([Face(target: Slot), PlayAnimation(play: "sit"), Wait(seconds: 8.0)])`.

`Task`

A task a state runs.

Variant	Written	Description
`MoveTo`	`MoveTo(target: .., stop_within: .., speed: .., fail_on: ..)`	Walks to a target.
`Follow`	`Follow(target: .., band: .., speed: .., teleport_beyond: .., fail_on: .., background: ..)`	Keeps within a distance band of a target.
`Face`	`Face(target: .., background: ..)`	Turns to face a target.
`Wait`	`Wait(seconds: ..)`	Waits.
`Wander`	`Wander(radius: .., around: ..)`	Wanders.
`UseAbility`	`UseAbility(ability: .., target: .., max_range: ..)`	Requests an ability.
`Claim`	`Claim(target: ..)`	Claims a target, so no other agent takes it (released when the state’s scope ends).
`Release`	`Release(target: ..)`	Releases a claim.
`AcquireToken`	`AcquireToken(pool: .., wait: ..)`	Asks for a token from a pool for the activity’s target, each tick until it is granted; held until the state’s scope ends, like a claim.
`RequestRole`	`RequestRole(role: .., score: ..)`	Asks the agent’s squad for a role; succeeds at once. The squad grants roles within its style’s limits.
`ClaimSlot`	`ClaimSlot(object: ..)`	Claims a slot of a smart object for the running activity: the first free slot its advertisement names whose `accepts` holds. Scoped like `Claim`.
`UseSlot`	`UseSlot`	Runs the held slot’s behaviour as a nested tree; ends with it. Not allowed inside a slot’s own behaviour.
`PullJob`	`PullJob(wait: ..)`	Asks the chore board for a job: at the activity’s target station when it has one, else the best job the worker may take. The job and its slot belong to the state’s scope, like a claim.
`Work`	`Work(cycles: ..)`	Works the held job at its station; the station completes cycles from its `work` numbers.
`PickUp`	`PickUp(item: ..)`	Picks up a dropped item.
`PutDown`	`PutDown`	Puts the carried item down at the agent’s feet.
`PlayAnimation`	`PlayAnimation(play: ..)`	Plays an animation by its play name.
`Emit`	`Emit(Emit)`	Emits a cue, an ally call or a noise.
`SetMemory`	`SetMemory(kind: .., value: .., ttl: ..)`	Writes a memory.
`ClearMemory`	`ClearMemory(kind: ..)`	Clears a memory.

MoveTo fields:

Field	Type	Required	Default	Description
`target`	`Bind`	yes		Where.
`stop_within`	`f32`	no	`1.0`	Succeeds within this many blocks.
`speed`	`f32`	no	`1.0`	A fraction of walking speed; above 1 sprints.
`fail_on`	list of `FailOn`	no	none	Conditions that fail it.

Follow fields:

Field	Type	Required	Default	Description
`target`	`Bind`	yes		Whom.
`band`	(`f32`, `f32`)	yes		The band, `(near, far)` in blocks.
`speed`	`f32`	no	`1.0`	A fraction of walking speed.
`teleport_beyond`	`f32` or `None`	no	never	Teleports to the target beyond this many blocks.
`fail_on`	list of `FailOn`	no	none	Conditions that fail it.
`background`	`bool`	no	`false`	Whether it runs alongside the state’s other tasks without deciding its completion.

Face fields:

Field	Type	Required	Default	Description
`target`	`Bind`	yes		What.
`background`	`bool`	no	`false`	Whether it runs in the background.

Wait fields:

Field	Type	Required	Default	Description
`seconds`	`seconds`	yes		How long.

Wander fields:

Field	Type	Required	Default	Description
`radius`	`float-or-param`	no	`8.0`	How far, in blocks.
`around`	`Around`	no	`Home`	Around what.

UseAbility fields:

Field	Type	Required	Default	Description
`ability`	`string`	yes		The ability (`manifold:ability` key), or `"$param"`. An unknown key fails the data stage (`DATA010`).
`target`	`Bind`	no	`Target`	At whom.
`max_range`	`f32`	no	`16.0`	Fails beyond this many blocks.

Claim fields:

Field	Type	Required	Default	Description
`target`	`Bind`	yes		What.

Release fields:

Field	Type	Required	Default	Description
`target`	`Bind`	yes		What.

AcquireToken fields:

Field	Type	Required	Default	Description
`pool`	`string`	yes		The pool (`manifold-ai:token-pool` key).
`wait`	`f32`	no	`2.0`	Fails `Denied` after this many seconds without a grant.

RequestRole fields:

Field	Type	Required	Default	Description
`role`	`string`	yes		The role (`manifold-ai:role` key).
`score`	`i32`	no	`0`	The request’s score; higher requests win the role.

ClaimSlot fields:

Field	Type	Required	Default	Description
`object`	`Bind`	no	`Target`	The smart object.

PullJob fields:

Field	Type	Required	Default	Description
`wait`	`f32`	no	`2.0`	Fails `Denied` after this many seconds without a job.

Work fields:

Field	Type	Required	Default	Description
`cycles`	`u32` or `None`	no	runs until the job ends	Succeeds after this many cycles.

PickUp fields:

Field	Type	Required	Default	Description
`item`	`Bind`	yes		Which.

PlayAnimation fields:

Field	Type	Required	Default	Description
`play`	`string`	yes		The play.

SetMemory fields:

Field	Type	Required	Default	Description
`kind`	`string`	yes		The memory (`manifold-ai:memory-kind` key).
`value`	`Bind`	yes		The value.
`ttl`	`f32` or `None`	no	the memory kind’s	Seconds until it expires.

ClearMemory fields:

Field	Type	Required	Default	Description
`kind`	`string`	yes		The memory.

`Bind`

Who or what a task acts on.

Variant	Written	Description
`Target`	`Target`	The activity’s target.
`Owner`	`Owner`	The agent’s owner.
`Self`	`Self`	The agent itself.
`Home`	`Home`	The agent’s home.
`Memory`	`Memory(string)`	A memory’s entity or position.
`Claimed`	`Claimed`	What the current scope claimed.
`Carried`	`Carried`	The item the agent carries.
`Slot`	`Slot`	The slot the agent holds on the smart object it claimed: the slot’s position; `Face(Slot)` turns to the slot’s facing.
`Point`	`Point(f32, f32, f32)`	A fixed point: `Point(x, y, z)`.

`FailOn`

A condition that fails a task.

Variant	Written	Description
`TargetGone`	`TargetGone`	The target is gone.
`TargetLost`	`TargetLost`	The target is lost.
`ReservationLost`	`ReservationLost`	The claim was lost.
`OwnerGone`	`OwnerGone`	The owner is gone.
`OwnerFarther`	`OwnerFarther(f32)`	The owner is farther than this many blocks.
`Timeout`	`Timeout(f32)`	The task ran longer than this many seconds.

`Around`

Where wandering centres.

Variant	Written	Description
`Home`	`Home`	The agent’s home, else where it first stood.
`Self`	`Self`	Where the agent is.
`Owner`	`Owner`	The agent’s owner.

`Emit`

An emission.

Variant	Written	Description
`Cue`	`Cue(string)`	A gameplay cue by key.
`Call`	`Call(tag: .., radius: ..)`	An ally call about the activity’s target: its last-known position and confidence, heard by allies whose `Hearing` sensor listens for the tag.
`Noise`	`Noise(tag: .., loudness: ..)`	A noise other agents hear.

Call fields:

Field	Type	Required	Default	Description
`tag`	`string`	yes		The call’s tag (`call.help`).
`radius`	`f32`	yes		Allies within this many blocks hear it, 1 to 255.

Noise fields:

Field	Type	Required	Default	Description
`tag`	`string`	yes		The noise’s tag (`noise.growl`).
`loudness`	`f32`	yes		Heard within this many blocks (times the listener’s sensitivity), 1 to 255.

`Engagement`

An engagement ring: count slots evenly on a circle around the object, the first in front of it, each facing its centre, with ids after the object’s own.

A record: Engagement(..) or (..).

Field	Type	Required	Default	Description
`count`	`u8`	yes		The slots, 1 to 16.
`radius`	`f32`	yes		The circle’s radius, in blocks, above 0 and at most 16.
`tags`	list of `string`	no	`["slot.engage"]`	The slots’ tags.
`offset`	(`f32`, `f32`, `f32`)	no	`(0.0, 0.0, 0.0)`	Only the height, the middle value, is used: the ring’s height above the object.
`accepts`	`condition` or `None`	no	anyone	A condition an occupant must meet, as a slot’s.
`behaviour`	`SlotBehaviour`	yes		What an occupant does there.
`timeout`	`duration`	no	`"60s"`	How long a claim lasts unless renewed.

`Advertisement`

An activity the object offers in slots with matching tags.

A record: Advertisement(..) or (..).

Field	Type	Required	Default	Description
`activity`	`string`	yes		The activity’s id in the agents’ brains.
`slot_tags`	list of `string`	no	none (any slot)	The tags a slot needs; some slot must have them.
`score`	`number`	yes		The score, a number in the `smart_object` context, lowered by distance (`score × r / (r + d)` with `r` the `query_radius`).
`requires`	`condition` or `None`	no	always	A condition in the same context that must hold.

Value forms used here: condition, duration, float-or-param, number, seconds.

Keyboard shortcuts