`data/abilities/`

An ability: something an entity does, such as a sword swing, a rifle shot or a boar’s charge. Its root is a chain of nodes (in order, in parallel, by condition, repeated) over engine elements: waits, animation plays, telegraphs, area hits, sweeps, traces, dashes, projectiles, effects and cues. An ability is granted by an archetype, an item kind or an effect; a player activates it with a bound input action, and an AI behaviour or task requests it. Activation checks tags, cooldowns, charges, costs and the target. Cooldowns and costs are effects.


Registry	`manifold:ability`
Files	`data/abilities/.ron`, `.update.ron`, `*.final.ron`
Sides	both: the server and every client load it, and the handshake’s data hash covers it
Reads	`manifold:predicate`, `manifold:stat`, `manifold:gameplay-config`, `manifold:presentation-field`, `manifold:effect`
Contract	Gameplay framework, data stage

Entry

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

Field	Type	Required	Default	Description
`id`	`string`	yes		The ability’s key, `<mod-id>:<name>`.
`tags`	list of `string`	no	none	Tags describing the ability, which other abilities’ `cancels` and removal triggers test.
`required`	`TagQuery` or `None`	no	no requirement	The activator’s tags must match.
`blocked`	`TagQuery` or `None`	no	never blocked	Activation fails while the activator’s tags match.
`cancels`	`TagQuery` or `None`	no	none	Starting it cancels the activator’s running abilities whose tags match.
`blocks_while_active`	`TagQuery` or `None`	no	none	While it runs, the activator cannot start abilities whose tags match.
`owned_tags`	list of `string`	no	none	Tags the activator holds while it runs (`manifold:state.casting`).
`costs`	list of `string`	no	none	Instant effects that only change resources, paid at `Commit` (on activation without one); activation fails when they cannot be afforded.
`cooldown`	`string` or `None`	no	none	The cooldown effect, applied at `Commit` (on activation without one); activation fails while it is active.
`charges`	`u16` or `None`	no	`1`	Uses before the cooldown blocks: the cooldown (an `Aggregate` effect with `expire: One`) blocks once it holds this many stacks. Needs a cooldown when above 1.
`targeting`	`Targeting`	no	`None`	What it aims at.
`interrupt`	`Interrupt`	no	nothing	What interrupts it.
`predict`	`PredictPolicy` or `None`	no	`None`	What the activating client predicts.
`input`	`string` or `None`	no	none	For players: the input action whose press activates it (declared by the game’s input declarations). An action no declaration names fails the data stage (`DATA010`).
`passive`	list of `GrantedModifier`	no	none	Constant stat modifiers the holder has while the ability is granted.
`root`	`AbilityNode`	yes		The chain it runs (at most 256 nodes, 8 deep).
`ui`	`AbilityUi` or `None`	no	none	Player-facing text.

Example

From game/flagship-game/data/abilities/m14.ron:

Ability(
    id: "flagship-game:m14_reload",
    tags: ["flagship-game:ability.reload"],
    input: Some("flagship-game:reload"),
    owned_tags: ["flagship-game:state.reloading"],
    blocked: (any: ["flagship-game:state.reloading"]),
    predict: Presentation,
    root: OneShot(play: "rifle_reload", stop_on_end: true),
    ui: Some((name: Some("flagship-game.ability.m14_reload.name"))),
)

Types

`TagQuery`

A tag query: which tag sets match. Every part written must hold; () matches everything.

A record: TagQuery(..) or (..).

Field	Type	Required	Default	Description
`all`	list of `tag-match`	no	none	Every one of these tags.
`any`	list of `tag-match`	no	none	At least one of these tags.
`none`	list of `tag-match`	no	none	None of these tags.
`or`	list of `TagQuery`	no	none	At least one of these queries.
`not`	`TagQuery`	no	none	This query must not match.

`Targeting`

What an ability aims at.

Variant	Written	Description
`None`	`None`	Nothing.
`Aim`	`Aim`	The activator’s view.
`Target`	`Target(range: .., relation: .., requires_sight: ..)`	An entity, checked at activation.
`Point`	`Point`	A point the activating input supplies.

Target fields:

Field	Type	Required	Default	Description
`range`	`f32`	yes		The farthest target, in metres (players get half a metre more).
`relation`	`relation-mask`	no	any	The relations a target may have to the activator.
`requires_sight`	`bool`	no	`false`	Whether the target must be in line of sight.

`Interrupt`

What interrupts a running ability.

A record: Interrupt(..) or (..).

Field	Type	Required	Default	Description
`on_tags`	`TagQuery` or `None`	no	never	Interrupted when the activator’s tags match.
`on_damage_fraction`	`f32` or `None`	no	never	Interrupted once the activator has taken damage of at least this fraction of its maximum health since the ability started.
`before_commit_only`	`bool`	no	`false`	Whether interrupts apply only before `Commit`.

`PredictPolicy`

What the activating client predicts.

Variant	Written	Description
`None`	`None`	Nothing: the client waits for the server.
`Presentation`	`Presentation`	One-shot plays and presentation counters.
`Local`	`Local`	Tags, cooldowns, costs and dashes too. The cooldown’s duration must be constant and each cost must change a predicted stat by a constant.

`GrantedModifier`

A stat modifier granted while its source lasts: an item while equipped, or an ability while granted.

A record: GrantedModifier(..) or (..).

Field	Type	Required	Default	Description
`stat`	`string`	yes		The stat (`manifold:stat` key). Not a resource: modify its maximum.
`op`	`ModOp`	yes		How it combines.
`value`	`number`	yes		The amount: a constant. A value that scales with its holder is a derived stat.
`scope`	`condition` or `None`	no	always counts	A condition in the `damage` context: the modifier counts only when the stat is read while a hit is resolved and the condition holds (“+100 against undead”).

`ModOp`

How a stat modifier combines with the stat’s other modifiers. A stat’s value is (base + Σ Flat) × (1 + Σ Increased) × Π (1 + More) + Σ Final, then the last Override, then the stat’s clamp and rounding.

Variant	Written	Description
`Flat`	`Flat`	Added to the base.
`Increased`	`Increased`	Summed with the other `Increased` modifiers, then multiplies.
`More`	`More`	Multiplies on its own (`0.5` is +50%, `-0.5` is half).
`Final`	`Final`	Added after the multipliers.
`Override`	`Override`	Replaces the value; the last applied wins.

`AbilityNode`

A node of an ability’s chain: a structure node, or an element. An element with one required value may be written positionally (Wait("0.2s"), EmitCue("x:cue.snort"), Noise(48.0), WaitWindow("swing")). A node succeeds or fails; a failure ends the chain unless a structure node handles it.

Variant	Written	Description
`Serial`	`Serial([AbilityNode])`	Runs the nodes in order; fails when one fails.
`Parallel`	`Parallel(until: .., children: ..)`	Runs up to four nodes at once.
`Select`	`Select([(condition, AbilityNode)])`	Runs the first branch whose condition holds: `[(condition, node), ..]`, conditions in the `ability` context (which can test the outcome bits, `AbilityOutcome(HIT_ANY)`).
`Repeat`	`Repeat(count: .., until: .., body: ..)`	Runs `body` repeatedly. A repeat without a count must wait.
`Next`	`Next(string)`	Ends the chain and starts the named ability with the same target, point and input in the same tick. It must be last.
`Commit`	`Commit`	Pays the costs and starts the cooldown; interrupts with `before_commit_only` stop applying.
`Wait`	`Wait(ticks: ..)`	Waits.
`OneShot`	`OneShot(play: .., section: .., rate: .., stop_on_end: ..)`	Plays an animation once.
`BumpCounter`	`BumpCounter(string)`	Bumps a counter presentation field (`manifold:presentation-field` key of kind `Counter`).
`SetPresentation`	`SetPresentation(field: .., value: ..)`	Sets a presentation field until the ability ends.
`Face`	`Face(to: .., turn_rate_deg_per_s: ..)`	Turns the caster.
`Telegraph`	`Telegraph(shape: .., anchor: .., lock: .., ticks: .., cue: ..)`	Shows a shape on the ground that a later `AreaHit` resolves against.
`AreaHit`	`AreaHit(shape: .., hit: ..)`	Hits everything in an area once.
`SweepVolume`	`SweepVolume(shape: .., ticks: .., timeout: .., hit: ..)`	Hits what a volume sweeps through over some ticks, each target once.
`Trace`	`Trace(origin: .., range: .., shape: .., hit: ..)`	A lag-compensated trace along the view: the nearest hit.
`Dash`	`Dash(speed: .., ticks: .., direction: .., stop: ..)`	Moves the caster at a speed for some ticks.
`ApplyEffect`	`ApplyEffect(to: .., effect: .., level: ..)`	Applies an effect to the caster or its target.
`EmitCue`	`EmitCue(cue: .., anchor: ..)`	Plays a cue.
`Noise`	`Noise(loudness: ..)`	Makes a noise AI hearing perceives.
`SetOutcome`	`SetOutcome(OutcomeBit)`	Sets an outcome bit `Select` branches test.
`Leap`	`Leap(speed: .., vertical: .., ticks: .., direction: .., stop: ..)`	Jumps the caster: a dash with a vertical push at its start.
`WaitTags`	`WaitTags(query: .., timeout: ..)`	Waits until the caster’s tags match.
`WaitWindow`	`WaitWindow(window: .., timeout: ..)`	Waits for the caster’s named animation window to open.
`SpawnProjectile`	`SpawnProjectile(archetype: .., speed: .., gravity: .., lifetime: .., radius: .., hit: ..)`	Fires a projectile from the caster’s eye along its view (or toward its target, for an AI).

Parallel fields:

Field	Type	Required	Default	Description
`until`	`Until`	no	`All`	When it ends.
`children`	list of `AbilityNode`	yes		The nodes.

Repeat fields:

Field	Type	Required	Default	Description
`count`	`number`	no	until `until`	How many times.
`until`	`Until` or `None`	no	none	Stops when its input action is released (`Released`, a held channel), or on the body’s result (`All`, `Any`).
`body`	`AbilityNode`	yes		The repeated node.

Wait fields:

Field	Type	Required	Default	Description
`ticks`	`duration`	yes		How long.

OneShot fields:

Field	Type	Required	Default	Description
`play`	`string`	yes		The play’s name in the caster’s animation graph.
`section`	`string` or `None`	no	the whole play	A section of the play.
`rate`	`f32`	no	`1`	The playback rate.
`stop_on_end`	`bool`	no	`false`	Whether the node waits for the play to end, and stops it if the ability ends first.

SetPresentation fields:

Field	Type	Required	Default	Description
`field`	`string`	yes		The field (a `manifold:presentation-field` key, not a counter).
`value`	`f32`	yes		The value.

Face fields:

Field	Type	Required	Default	Description
`to`	`FaceTo`	no	`Target`	What it faces.
`turn_rate_deg_per_s`	`f32`	no	`0`	A turn rate in degrees per second, carried on the turn request. The caster turns at its locomotion profile’s rate, which this cannot raise.

Telegraph fields:

Field	Type	Required	Default	Description
`shape`	`Shape`	yes		The shape.
`anchor`	`TelegraphAnchor`	no	`CasterFacing`	Where it is placed.
`lock`	`Lock`	no	`OnStart`	Whether it stays where it started or follows its anchor.
`ticks`	`duration`	yes		How long it shows before it resolves.
`cue`	`string` or `None`	no	none	A persistent cue while it shows.

AreaHit fields:

Field	Type	Required	Default	Description
`shape`	`HitArea`	yes		The area: a shape, or `Telegraph(i)` for the ability’s `i`-th telegraph.
`hit`	`Hit`	yes		What a hit does.

SweepVolume fields:

Field	Type	Required	Default	Description
`shape`	`Shape`	no	the blade (windowed sweeps only)	The volume. A windowed sweep without one sweeps the held item’s blade.
`ticks`	`sweep-ticks`	yes		How long it sweeps, or `Window("<name>")` while that animation window is open.
`timeout`	`duration`	no	2 seconds	How long a windowed sweep waits for its window.
`hit`	`Hit`	yes		What a hit does.

Trace fields:

Field	Type	Required	Default	Description
`origin`	`TraceOrigin`	no	`Eyes`	Where it starts.
`range`	`f32`	yes		Its length, in metres.
`shape`	`TraceShape`	no	`Ray`	A ray or a sphere.
`hit`	`Hit`	yes		What a hit does.

Dash fields:

Field	Type	Required	Default	Description
`speed`	`f32`	yes		The speed, m/s.
`ticks`	`duration`	yes		How long.
`direction`	`DashDirection`	no	`Locked`	Which way.
`stop`	list of `DashStop`	no	nothing	What ends it early.

ApplyEffect fields:

Field	Type	Required	Default	Description
`to`	`subject`	no	`This`	`This` or `Target`.
`effect`	`string`	yes		The effect (`manifold:effect` key).
`level`	`number`	no	the ability’s	The effect’s level, a number in the `ability` context.

EmitCue fields:

Field	Type	Required	Default	Description
`cue`	`string`	yes		The cue (`manifold:cue` key).
`anchor`	`CueAt`	no	`Caster`	Where it plays.

Noise fields:

Field	Type	Required	Default	Description
`loudness`	`f32`	yes		How loud: the distance in blocks at which it is just audible (a rifle shot is about 48).

Leap fields:

Field	Type	Required	Default	Description
`speed`	`f32`	yes		The horizontal speed, m/s.
`vertical`	`f32`	yes		The vertical speed, m/s.
`ticks`	`duration`	yes		How long.
`direction`	`DashDirection`	no	`Locked`	Which way.
`stop`	list of `DashStop`	no	nothing	What ends it early.

WaitTags fields:

Field	Type	Required	Default	Description
`query`	`TagQuery`	yes		The tags (not empty).
`timeout`	`duration` or `None`	no	no limit	The longest wait; the node fails after it.

WaitWindow fields:

Field	Type	Required	Default	Description
`window`	`string`	yes		The window’s name.
`timeout`	`duration`	no	2 seconds	The longest wait; the node fails after it.

SpawnProjectile fields:

Field	Type	Required	Default	Description
`archetype`	`string`	yes		The projectile’s archetype (`manifold:archetype` key); it should not be saved.
`speed`	`f32`	yes		The launch speed, m/s.
`gravity`	`f32`	no	`0`	Gravity, m/s².
`lifetime`	`duration`	yes		How long it flies before it despawns.
`radius`	`f32`	no	`0`	Its radius, in metres.
`hit`	`Hit`	yes		What a hit does; it stops at its first hit unless the hit names `max_targets`.

`Until`

When a Parallel ends, or a Repeat stops.

Variant	Written	Description
`All`	`All`	Every child succeeded (fails as soon as one fails).
`Any`	`Any`	One child succeeded (fails when all failed).
`First`	`First(u8)`	Child `i` finished; its result is the node’s (`Parallel` only).
`Released`	`Released`	The ability’s input action was released: a held channel.

`FaceTo`

What Face turns to.

Variant	Written	Description
`Target`	`Target`	The ability’s target.
`Point`	`Point`	The ability’s point.

`Shape`

A hit area’s shape, on the ground in front of the caster.

Variant	Written	Description
`Circle`	`Circle(radius: ..)`	A circle.
`Rect`	`Rect(width: .., length: ..)`	A rectangle ahead.
`Box`	`Box(half: ..)`	A box.
`Cone`	`Cone(radius: .., angle_deg: ..)`	A cone ahead.

Circle fields:

Field	Type	Required	Default	Description
`radius`	`f32`	yes		Its radius, in metres.

Rect fields:

Field	Type	Required	Default	Description
`width`	`f32`	yes		Its width, in metres.
`length`	`f32`	yes		Its length ahead, in metres.

Box fields:

Field	Type	Required	Default	Description
`half`	(`f32`, `f32`, `f32`)	yes		Its half extents, `(x, y, z)` in metres.

Cone fields:

Field	Type	Required	Default	Description
`radius`	`f32`	yes		Its length, in metres.
`angle_deg`	`f32`	yes		Its full angle, in degrees.

`TelegraphAnchor`

Where a telegraph is placed.

Variant	Written	Description
`CasterFacing`	`CasterFacing`	At the caster, facing its way.
`Caster`	`Caster`	Centred on the caster.
`Target`	`Target`	Centred on the target.

`Lock`

Whether a telegraph moves.

Variant	Written	Description
`OnStart`	`OnStart`	Placed once, when it starts.
`Follow`	`Follow`	Follows its anchor.

`HitArea`

An AreaHit’s area.

Variant	Written	Description
`Circle`	`Circle(radius: ..)`	A circle.
`Rect`	`Rect(width: .., length: ..)`	A rectangle ahead.
`Box`	`Box(half: ..)`	A box.
`Cone`	`Cone(radius: .., angle_deg: ..)`	A cone ahead.
`Telegraph`	`Telegraph(u8)`	Exactly the shape and pose of the ability’s `i`-th telegraph (from 0), at its resolve tick.

Circle fields:

Field	Type	Required	Default	Description
`radius`	`f32`	yes		Its radius, in metres.

Rect fields:

Field	Type	Required	Default	Description
`width`	`f32`	yes		Its width, in metres.
`length`	`f32`	yes		Its length ahead, in metres.

Box fields:

Field	Type	Required	Default	Description
`half`	(`f32`, `f32`, `f32`)	yes		Its half extents, `(x, y, z)` in metres.

Cone fields:

Field	Type	Required	Default	Description
`radius`	`f32`	yes		Its length, in metres.
`angle_deg`	`f32`	yes		Its full angle, in degrees.

`Hit`

What a hit does.

A record: Hit(..) or (..).

Field	Type	Required	Default	Description
`damage`	`DamageSpec` or `None`	no	none	Damage dealt to each target.
`effects`	list of `string`	no	none	Effects applied to each target (`manifold:effect` keys).
`filter`	`relation-mask`	no	`Any`	The relations a target may have to the caster, or `Any`.
`tags`	`TagQuery` or `None`	no	any target	A target’s tags must match.
`max_targets`	`u8`	no	no limit (one for traces and projectiles)	The most targets, at least 1. A trace hits one.
`cue`	`string` or `None`	no	none	A cue played at each hit.

`DamageSpec`

Damage to deal: an effect’s damage, or an ability hit’s.

A record: DamageSpec(..) or (..).

Field	Type	Required	Default	Description
`damage_type`	`string`	yes		The damage type (`manifold:damage-type` key).
`base`	`number`	yes		The base amount, before the formula, a number in the use site’s context.
`element`	`string`	no	the damage type’s element	The element (`manifold:element` key).
`context_tags`	list of `string`	no	none	Tags the hit carries for hooks and conditions (`ContextTags(..)`).
`can_crit`	`bool`	no	`true`	Whether the formula may roll a critical hit.

`TraceOrigin`

Where a trace starts.

Variant	Written	Description
`Eyes`	`Eyes`	The caster’s eyes.
`Camera`	`Camera`	The player’s camera.

`TraceShape`

A trace’s shape.

Variant	Written	Description
`Ray`	`Ray`	A thin ray.
`Sphere`	`Sphere(radius: ..)`	A sphere swept along the trace.

Sphere fields:

Field	Type	Required	Default	Description
`radius`	`f32`	yes		Its radius, in metres.

`DashDirection`

Which way a dash or leap goes.

Variant	Written	Description
`Locked`	`Locked`	The way the caster faced when it started.
`Target`	`Target`	Toward the target.

`DashStop`

What ends a dash or leap early.

Variant	Written	Description
`Collision`	`Collision`	Running into a wall (sets `HIT_WALL`).
`HitTarget`	`HitTarget`	Hitting a target.
`TagMatch`	`TagMatch`	A tag match.

`CueAt`

Where EmitCue plays.

Variant	Written	Description
`Caster`	`Caster`	At the caster.
`Target`	`Target`	At the target.

`OutcomeBit`

An ability outcome bit.

Variant	Written	Description
`HIT_ANY`	`HIT_ANY`	Something was hit.
`HIT_WALL`	`HIT_WALL`	A wall was hit.
`HIT_NONE`	`HIT_NONE`	Nothing was hit.
`INTERRUPTED`	`INTERRUPTED`	The ability was interrupted.

`AbilityUi`

An ability’s player-facing text, as message keys.

A record: AbilityUi(..) or (..).

Field	Type	Required	Default	Description
`name`	`string` or `None`	no	none	The name’s message key.
`description`	`string` or `None`	no	none	The description’s message key.
`icon`	`string` or `None`	no	none	An icon asset.

Value forms used here: condition, duration, number, relation-mask, subject, sweep-ticks, tag-match.

Keyboard shortcuts