`data/state_trees/`

A state tree: the steps of one AI activity, such as a pet’s fetch. States run tasks (move, follow, use an ability, claim an item) and move between each other on transitions; Sequence and Selector are shorthand for common shapes. A full brain’s activities name the tree they run. State names are unique within a tree. Loaded by the server only.


Registry	`manifold-ai:state-tree`
Files	`data/state_trees/.ron`, `.update.ron`, `*.final.ron`
Sides	server: only the server loads it
Reads	`manifold-ai:memory-kind`, `manifold-ai:curve`
Contract	Brains, data stage

Entry

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

Field	Type	Required	Default	Description
`id`	`string`	yes		The tree’s key, `<mod-id>:<name>`.
`root`	`StateNode`	yes		The root state.

Example

From game/flagship-game/data/state_trees/pet.ron:

StateTree(
    id: "flagship-game:pet_cower",
    root: State(name: "cower", complete_when: Some(Task(1)), tasks: [
        Face(target: Memory("manifold:last_hurt_by"), background: true),
        Wait(seconds: (2.0, 3.0)),
    ]),
)

Types

`StateNode`

A state, or shorthand that expands into states when the tree loads.

Variant	Written	Description
`State`	`State(State)`	A state: `State(name: .., tasks: [..], children: [..])`.
`Sequence`	`Sequence(Group)`	Children in order, each moving to the next on success; a failure fails the sequence.
`Selector`	`Selector(Group)`	Children in order, each moving to the next on failure; a success succeeds the selector.

`State`

A state.

A record: State(..) or (..).

Field	Type	Required	Default	Description
`name`	`string`	yes		The state’s name, unique in its tree.
`enter`	`Cond` or `None`	no	always enterable	A condition for entering it.
`select`	`ChildSelect`	no	`Ordered`	How it chooses among its children.
`tasks`	list of `Task`	no	none	Tasks it runs while active.
`complete_when`	`Completion` or `None`	no	`Any` with tasks, else when a child completes	When it completes.
`transitions`	list of `Transition`	no	none	Its transitions.
`timeout`	(`f32`, `Status`) or `None`	no	none	Seconds after which it completes with a status: `(5.0, Failed)`.
`children`	list of `StateNode`	no	none	Its child states.
`hold`	`bool`	no	`false`	Whether it keeps running when the tree is reselected (a fetch is not abandoned midway).
`reenter_default`	`bool`	no	`true`	Whether going to it while it is active restarts it.
`presents`	`string` or `None`	no	none	The presentation activity graphs see while it is active (a `presentation_activities` name).
`utility`	list of `Consideration`	no	none	Considerations, when its parent selects by utility.
`locks`	list of `string`	no	none	Activity tags it locks (`ai.activity.reposition`): while it is active, activities with a matching tag or a descendant are not selected. The running activity is never locked by its own states.

`Cond`

An AI condition, evaluated with the brain in context.

Variant	Written	Description
`Always`	`Always`	Always holds.
`Never`	`Never`	Never holds.
`All`	`All([Cond])`	Every condition holds.
`Any`	`Any([Cond])`	At least one holds.
`Not`	`Not(Cond)`	The condition does not hold.
`MemorySet`	`MemorySet(string)`	The memory (`manifold-ai:memory-kind` key) is set.
`MemoryOlderThan`	`MemoryOlderThan(string, f32)`	The memory was written more than this many seconds ago, or is unset: `MemoryOlderThan("<memory>", 5.0)`.
`Distance`	`Distance(from: .., to: .., min: .., max: ..)`	The distance between two subjects is within bounds.
`StatBelow`	`StatBelow(string, float-or-param)`	The stat’s current fraction of its maximum is below the value: `StatBelow("manifold:health", 0.25)`.
`HasTag`	`HasTag(string)`	The agent has the tag, or a descendant.
`Aware`	`Aware(of: .., at_least: ..)`	The agent’s awareness of a subject is at least a state.
`Perceived`	`Perceived(Subject)`	The agent perceives the subject now.
`Reachable`	`Reachable(Subject)`	Navigation can reach the subject.
`CandidateTagged`	`CandidateTagged(string)`	The activity or behaviour being considered has the tag.
`InState`	`InState(string)`	The agent’s state tree is in the named state.
`OwnerOnline`	`OwnerOnline`	The agent’s owner is online.

Distance fields:

Field	Type	Required	Default	Description
`from`	`Subject`	no	`Self`	From.
`to`	`Subject`	yes		To.
`min`	`float-or-param` or `None`	no	no lower bound	At least this far, in blocks.
`max`	`float-or-param` or `None`	no	no upper bound	At most this far, in blocks.

Aware fields:

Field	Type	Required	Default	Description
`of`	`Subject`	no	`Target`	The subject.
`at_least`	`AwarenessState`	yes		The least state.

`Subject`

A subject an AI condition names.

Variant	Written	Description
`Self`	`Self`	The agent itself.
`Target`	`Target`	The activity’s or behaviour’s target.
`Owner`	`Owner`	The agent’s owner.
`Home`	`Home`	The agent’s home.
`Memory`	`Memory(string)`	A memory’s entity or position (`manifold-ai:memory-kind` key).
`Carried`	`Carried`	The item the agent carries.

`AwarenessState`

An awareness state.

Variant	Written	Description
`Unaware`	`Unaware`	Has not noticed.
`Suspicious`	`Suspicious`	Noticed something.
`Alert`	`Alert`	Looking for it.
`Engaged`	`Engaged`	Acting on it.

`ChildSelect`

How a state chooses among its children.

Variant	Written	Description
`Ordered`	`Ordered`	The first child whose `enter` holds.
`Utility`	`Utility(keep_ratio: ..)`	The child with the best utility score.
`Random`	`Random`	A random child.

Utility fields:

Field	Type	Required	Default	Description
`keep_ratio`	`f32`	no	`0.75`	Keep the current child while its score is at least this fraction of the best.

`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.
`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.

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.
`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.

`Completion`

When a state completes.

Variant	Written	Description
`Any`	`Any`	When any task completes.
`All`	`All`	When every task completes.
`FirstSuccess`	`FirstSuccess`	When a task succeeds.
`Task`	`Task(u8)`	When task `i` (from 0) completes.
`Never`	`Never`	Never: only transitions leave it.

`Transition`

A transition.

A record: Transition(..) or (..).

Field	Type	Required	Default	Description
`on`	`Trigger`	yes		What fires it.
`guard`	`Cond` or `None`	no	none	A condition that must hold.
`to`	`TaskTarget`	yes		Where it leads.
`min_interval`	`u16`	no	`10`	Ticks between `Tick` firings.

`Trigger`

What fires a transition.

Variant	Written	Description
`Succeeded`	`Succeeded`	The state succeeded.
`Failed`	`Failed`	The state failed.
`Completed`	`Completed`	The state completed either way.
`Event`	`Event([Event])`	Any of these events.
`Tick`	`Tick`	Every `min_interval` ticks.

`Event`

A change event transitions and interrupts subscribe to.

Variant	Written	Description
`Memory`	`Memory(string)`	The memory (`manifold-ai:memory-kind` key) changed.
`NewKnowledge`	`NewKnowledge`	The agent perceived something new.
`StateRose`	`StateRose`	An awareness state rose.
`StateFell`	`StateFell`	An awareness state fell.
`TargetLost`	`TargetLost`	The target was lost.
`Damaged`	`Damaged`	The agent took damage.
`CallHeard`	`CallHeard`	The agent heard a call.
`OwnerStateChanged`	`OwnerStateChanged`	The owner’s state changed.
`ActivityEnded`	`ActivityEnded`	The activity ended.
`Signal`	`Signal`	A signal from code.

`TaskTarget`

Where a transition leads.

Variant	Written	Description
`Goto`	`Goto(state: .., reenter: ..)`	To a named state.
`Next`	`Next`	To the next sibling.
`Complete`	`Complete(Status)`	Completes the state with a status.
`ReselectRoot`	`ReselectRoot`	Reselects from the root.
`EndActivity`	`EndActivity(Status)`	Ends the activity with a status.

Goto fields:

Field	Type	Required	Default	Description
`state`	`string`	yes		The state’s name.
`reenter`	`bool` or `None`	no	the state’s `reenter_default`	Whether to restart it when it is already active.

`Status`

A completion status.

Variant	Written	Description
`Succeeded`	`Succeeded`	Success.
`Failed`	`Failed`	Failure.

`Consideration`

A utility consideration: an input, normalised by (v − min) / (max − min) and clamped, through a curve.

A record: Consideration(..) or (..).

Field	Type	Required	Default	Description
`input`	`Input`	yes		What it measures.
`min`	`f32`	no	`0`	The input that scores 0 before the curve.
`max`	`f32`	no	`1`	The input that scores 1 before the curve.
`curve`	`CurveSpec`	no	`Preset("manifold:linear")`	The curve.

`Input`

A consideration’s input. The target’s own stats and tags are read only while it is perceived now or known outright (the owner, a memory’s entity); a remembered target out of sight reads 0.

Variant	Written	Description
`TargetDistance`	`TargetDistance`	Blocks to the target.
`OwnerDistance`	`OwnerDistance`	Blocks to the owner.
`HomeDistance`	`HomeDistance`	Blocks to home.
`Reachable`	`Reachable`	1 when navigation can reach the target, else 0.
`LineOfSight`	`LineOfSight`	1 when the agent perceives the target now, else 0. It reads what the agent already knows and never casts a new sight ray.
`TargetAwareness`	`TargetAwareness`	The awareness state of the target, 0 to 3.
`TargetConfidence`	`TargetConfidence`	The confidence in the target’s position, 0 to 1.
`TargetRelation`	`TargetRelation`	The agent’s relation to the target when last sensed: `Friendly` 0, `Neutral` 0.5, `Hostile` 1.
`GroupKnows`	`GroupKnows`	Not available yet (Talos D6, group knowledge): refused at load.
`SelfStatRatio`	`SelfStatRatio(string)`	The agent’s stat (`manifold:stat` key) as a fraction of its maximum.
`SelfStat`	`SelfStat(string)`	The agent’s stat’s current value.
`SelfHasTag`	`SelfHasTag(string)`	1 when the agent has the tag or a descendant, else 0.
`TargetStatRatio`	`TargetStatRatio(string)`	The target’s stat as a fraction of its maximum.
`TargetHasTag`	`TargetHasTag(string)`	1 when the target has the tag or a descendant, else 0.
`CooldownReady`	`CooldownReady(string)`	1 when the ability (`manifold:ability` key, or `"$param"`) is granted to the agent, idle and off cooldown, else 0.
`MemoryAge`	`MemoryAge(string)`	Seconds since the memory was written (large when unset).
`MemorySet`	`MemorySet(string)`	1 when the memory is set, else 0.
`TimeOfDay`	`TimeOfDay`	The world’s time of day, 0 to 1.
`TimeInActivity`	`TimeInActivity`	Seconds in the current activity.
`BondStrength`	`BondStrength(string)`	Not available yet (Talos D7, relationship memories): refused at load.
`Threat`	`Threat`	Not available yet (Talos D6, threat tables): refused at load.
`TokenAvailable`	`TokenAvailable(string)`	Not available yet (Talos D6, coordination tokens): refused at load.
`AdScore`	`AdScore`	Not available yet (Talos D6, smart objects): refused at load.
`Constant`	`Constant(f32)`	A constant.
`Custom`	`Custom(string)`	Not available yet (Talos D5, a mod’s consideration-input hook): refused at load.

`CurveSpec`

A curve’s shape, over x in 0..1.

Variant	Written	Description
`Linear`	`Linear(m: .., k: .., b: .., c: ..)`	`y = m · (x − c)^k + b`.
`Polynomial`	`Polynomial(m: .., k: .., b: .., c: ..)`	`y = m · (x − c)^k + b`, with a fractional `k` allowed.
`Logistic`	`Logistic(m: .., k: .., b: .., c: ..)`	`y = k / (1 + e^(−m · (x − c))) + b`.
`Logit`	`Logit(m: .., k: .., b: .., c: ..)`	`y = ln(v / (1 − v)) / m + b` with `v = x − c`, rescaled to 0..1.
`Normal`	`Normal(m: .., k: .., b: .., c: ..)`	`y = m · e^(−k · (x − c)²) + b`: a bell.
`Sine`	`Sine(m: .., k: .., b: .., c: ..)`	`y = m · sin(k · π · (x − c)) + b`.
`Step`	`Step(at: ..)`	0 below `at`, 1 at or above it.
`Piecewise`	`Piecewise([(f32, f32)])`	Straight lines between `(x, y)` points, flat outside them; `x` ascending.
`Inverse`	`Inverse(CurveSpec)`	`1 − curve(x)`.
`Preset`	`Preset(string)`	A `manifold-ai:curve` entry by key.

Linear fields:

Field	Type	Required	Description
`m`	`f32`	yes	Slope.
`k`	`f32`	yes	Exponent.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Horizontal shift.

Polynomial fields:

Field	Type	Required	Description
`m`	`f32`	yes	Slope.
`k`	`f32`	yes	Exponent.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Horizontal shift.

Logistic fields:

Field	Type	Required	Description
`m`	`f32`	yes	Steepness.
`k`	`f32`	yes	Height.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Midpoint.

Logit fields:

Field	Type	Required	Description
`m`	`f32`	yes	Steepness.
`k`	`f32`	yes	Unused; write `1.0`.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Horizontal shift.

Normal fields:

Field	Type	Required	Description
`m`	`f32`	yes	Height.
`k`	`f32`	yes	Narrowness.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Centre.

Sine fields:

Field	Type	Required	Description
`m`	`f32`	yes	Amplitude.
`k`	`f32`	yes	Frequency.
`b`	`f32`	yes	Vertical shift.
`c`	`f32`	yes	Phase.

Step fields:

Field	Type	Required	Default	Description
`at`	`f32`	yes		The threshold.

`Group`

A sequence or selector.

A record: Group(..) or (..).

Field	Type	Required	Default	Description
`name`	`string`	yes		The group’s name, unique in its tree.
`enter`	`Cond` or `None`	no	always enterable	A condition for entering it.
`steps`	list of `StateNode`	yes		Its steps, in order.
`tasks`	list of `Task`	no	none	Tasks it runs while active.
`transitions`	list of `Transition`	no	none	Its transitions.
`hold`	`bool`	no	`false`	Whether it keeps running when the tree is reselected.
`presents`	`string` or `None`	no	none	The presentation activity graphs see while it is active.
`utility`	list of `Consideration`	no	none	Considerations, when its parent selects by utility.
`locks`	list of `string`	no	none	Activity tags it locks while it is active, as a state’s `locks`.

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

Keyboard shortcuts