`data/effects/`

An effect: a bag of parts applied to an entity. An instant effect changes bases and leaves nothing behind; a duration or infinite effect lives as an instance that adds stat modifiers and tags until it ends, and a periodic one runs its instant parts each period. Effects deal damage, heal, chain other effects, grant immunity, cleanse, and run damage hooks while they last. Cooldowns and costs are effects too. Abilities, hooks and items apply them, and stacking decides what a second application does.


Registry	`manifold:effect`
Files	`data/effects/.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`
Contract	Gameplay framework, data stage

Entry

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

Field	Type	Required	Default	Description
`id`	`string`	yes		The effect’s key, `<mod-id>:<name>`.
`asset_tags`	list of `string`	no	none	Tags describing the effect itself (`x:effect.poison`), which `immunity` and `cleanse` queries test. Tagging it `manifold:effect.applies_to_dead` lets it apply to dead entities.
`duration`	`effect-duration`	no	`Instant`	How long it lasts.
`period`	`Period` or `None`	no	not periodic	Runs the instant parts every period instead of once. Not for an instant effect.
`modifiers`	list of `Modifier`	no	none	Stat modifiers: an instant or periodic effect changes the stats’ bases; a duration effect adds modifiers while it is live.
`grant_tags`	list of `string`	no	none	Tags the holder has while the instance is live.
`damage`	`DamageSpec` or `None`	no	none	Damage dealt to the holder when applied, or each period.
`heal`	`number` or `None`	no	none	An amount healed when applied, or each period, through `manifold:incoming_healing`.
`apply_effects`	list of `effect-ref`	no	none	Effects applied with it (at most four deep).
`requirements`	`condition` or `None`	no	always applies	A condition in the `effect_apply` context that must hold for the effect to apply.
`ongoing`	`TagQuery` or `None`	no	never inhibited	While the holder’s tags do not match, the instance is inhibited: it keeps its timer, and its modifiers and tags are revoked.
`immunity`	`TagQuery` or `None`	no	none	While live, blocks applications of effects whose asset tags match.
`cleanse`	`TagQuery` or `None`	no	none	When applied, removes the holder’s effects whose asset tags match.
`damage_hooks`	list of `DamageHook`	no	none	Damage hooks active while the instance is live. Not for an instant effect.
`stacking`	`Stacking` or `None`	no	`Independent(max_instances: 8)`	What a second application does. Not for an instant effect.
`stacking_group`	`string` or `None`	no	the effect’s own key	Effects of one group stack with each other.
`removal`	list of `RemovalTrigger`	no	none	Events that end the instance. Not for an instant effect.
`cue`	`string` or `None`	no	none	A cue played when applied and each period (`manifold:cue` key).
`ui`	`EffectUi` or `None`	no	`<mod>.effect.<id>.name`, shown, timer hidden	Player-facing presentation.
`persist`	`bool`	no	`false`	Whether the instance is saved with its holder.
`persist_through_death`	`bool`	no	`false`	Whether the instance survives its holder’s death.
`set_by_caller`	list of `string`	no	none	Names the applier sets per application, read as `v.<name>` in the effect’s numbers.
`parts`	list of `Part`	no	none	Registered native parts, run after the built-in parts in list order.
`execution`	`reserved` or `None`	no	none	Reserved for guest executions (Talos B6).

Example

From tools/test-mods/guide-creature/data/effects/lunge.ron:

Effect(
    id: "guide-creature:cooldown.lunge",
    duration: For("3s"),
    grant_tags: ["guide-creature:cooldown.lunge"],
    stacking: Replace,
)

Types

`Period`

An effect’s period. Write every or secs.

A record: Period(..) or (..).

Field	Type	Required	Default	Description
`every`	`number`	no	use `secs`	The period: ticks as an integer, seconds as `"1s"`, or a number of ticks. At least one tick.
`secs`	`number`	no	use `every`	The period in seconds, as a number.
`on_apply`	`bool`	no	`false`	Whether the instant parts also run once on application.

`Modifier`

A stat modifier an effect adds.

A record: Modifier(..) or (..).

Field	Type	Required	Default	Description
`stat`	`string`	yes		The stat (`manifold:stat` key). A duration effect may not modify a resource: modify its maximum.
`op`	`ModOp`	yes		How it combines.
`value`	`number`	yes		The amount, a number in the `effect_apply` context.
`per_stack`	`bool`	no	`false`	Whether the amount is multiplied by the instance’s stack count.
`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 it holds. Only on a duration effect.

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

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

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

`DamageHook`

A data hook on the damage pipeline, evaluated in the damage context (This is the victim; v.damage_amount is the stage’s amount). Within a stage, hooks run by priority, then side, then source, then list order.

A record: DamageHook(..) or (..).

Field	Type	Required	Default	Description
`stage`	`DamageStage`	yes		The pipeline stage it runs at, which limits its actions.
`side`	`HookSide`	yes		Which participant carries it: an `Attacker` hook on a sword’s effect runs when its holder attacks, a `Victim` hook on a shield’s when its holder is hit.
`priority`	`i16`	no	`0`	Higher runs first, -32768 to 32767.
`when`	`condition` or `None`	no	always	A condition that must hold.
`action`	`DamageAction`	yes		What it does.

`DamageStage`

A stage of the damage pipeline.

Variant	Written	Description
`Admit`	`Admit`	Before anything: `Cancel`.
`Gather`	`Gather`	The attacker’s part: `Add`, `Multiply`, `Set`, `AddContextTag`.
`Convert`	`Convert`	Between elements: `Convert`.
`Mitigate`	`Mitigate`	The victim’s part: `Add`, `Multiply`, `Set`.
`PreApply`	`PreApply`	Last changes (blocks, parries, shields): all of the above and `Cancel`.
`PreDeath`	`PreDeath`	A killing hit only: `Cancel` (the victim survives), `ApplyEffect`.
`PostHit`	`PostHit`	After the hit: `ApplyEffect`, `Reflect`, `Leech`, `Knockback`, `Cue`.
`PostKill`	`PostKill`	After a kill: as `PostHit`.

`HookSide`

The participant a hook belongs to.

Variant	Written	Description
`Attacker`	`Attacker`	The attacker.
`Direct`	`Direct`	The direct source (an arrow).
`Owner`	`Owner`	The attacker’s owner.
`Victim`	`Victim`	The victim.

`DamageAction`

What a hook does. Actions may also be written positionally, in field order (Cancel("x:cancel.blocked")); Add, Multiply and Set take (<value>) or (<element>, <value>).

Variant	Written	Description
`Add`	`Add(value: .., element: ..)`	Adds to an element’s amount.
`Multiply`	`Multiply(value: .., element: ..)`	Multiplies by `1 + value`, on one element or all of them.
`Set`	`Set(value: .., element: ..)`	Sets one element’s amount, or the total (rescaling the elements).
`Convert`	`Convert(from: .., to: .., fraction: ..)`	Moves a fraction of one element’s amount into another.
`Cancel`	`Cancel(reason: ..)`	Stops the hit, with a reason tag (`manifold:cancel.*` or the game’s).
`AddContextTag`	`AddContextTag(tag: ..)`	Adds a tag to the hit’s context tags.
`ApplyEffect`	`ApplyEffect(to: .., effect: .., level: ..)`	Applies an effect to a participant, with the hook’s holder as source.
`Reflect`	`Reflect(fraction: .., damage_type: ..)`	Thorns: deals a fraction of the applied amount back to the attacker as a new hit (never more than two levels deep).
`Leech`	`Leech(fraction: .., resource: ..)`	Lifesteal: heals the attacker by a fraction of the applied amount.
`Knockback`	`Knockback(add: ..)`	Adds to the hit’s horizontal knockback, m/s.
`Cue`	`Cue(cue: ..)`	Plays a cue at the hit.

Add fields:

Field	Type	Required	Default	Description
`value`	`number`	yes		The amount, a number.
`element`	`string` or `None`	no	the hit’s primary element	The element (`manifold:element` key).

Multiply fields:

Field	Type	Required	Default	Description
`value`	`number`	yes		The change (`-0.5` halves).
`element`	`string` or `None`	no	every element	The element.

Set fields:

Field	Type	Required	Default	Description
`value`	`number`	yes		The amount.
`element`	`string` or `None`	no	the total	The element.

Convert fields:

Field	Type	Required	Description
`from`	`string`	yes	The element taken from.
`to`	`string`	yes	The element given to.
`fraction`	`number`	yes	The fraction, clamped to 0..=1.

Cancel fields:

Field	Type	Required	Default	Description
`reason`	`string`	yes		The reason tag.

AddContextTag fields:

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

ApplyEffect fields:

Field	Type	Required	Default	Description
`to`	`subject`	yes		The participant.
`effect`	`string`	yes		The effect (`manifold:effect` key).
`level`	`number`	no	the holding effect’s	The effect’s level.

Reflect fields:

Field	Type	Required	Default	Description
`fraction`	`number`	yes		The fraction.
`damage_type`	`string`	yes		The reflected hit’s damage type.

Leech fields:

Field	Type	Required	Default	Description
`fraction`	`number`	yes		The fraction.
`resource`	`string`	no	`manifold:health`	The resource healed (`manifold:stat` key).

Knockback fields:

Field	Type	Required	Default	Description
`add`	`number`	yes		The speed added.

Cue fields:

Field	Type	Required	Default	Description
`cue`	`string`	yes		The cue (`manifold:cue` key).

`Stacking`

What a second application of an effect does.

Variant	Written	Description
`Independent`	`Independent(max_instances: ..)`	Each application is a new instance; past the cap the oldest goes.
`Replace`	`Replace`	The new instance replaces the old one (whose removal triggers do not fire).
`PerSource`	`PerSource(reapply: ..)`	One instance per source.
`Aggregate`	`Aggregate(by: .., max_stacks: .., reapply: .., expire: ..)`	One instance whose stack count grows.
`StrongestWins`	`StrongestWins(hide_weaker: ..)`	The strongest instance of the group is active.

Independent fields:

Field	Type	Required	Default	Description
`max_instances`	`u8`	yes		The most instances.

PerSource fields:

Field	Type	Required	Default	Description
`reapply`	`Reapply`	yes		What a reapplication by the same source does to the duration.

Aggregate fields:

Field	Type	Required	Description
`by`	`AggregateBy`	yes	What the stacks are counted per.
`max_stacks`	`u16`	yes	The most stacks.
`reapply`	`Reapply`	yes	What a reapplication does to the duration.
`expire`	`StackExpire`	yes	How stacks expire.

StrongestWins fields:

Field	Type	Required	Default	Description
`hide_weaker`	`bool`	yes		Whether weaker instances stay hidden (at most two per group) rather than going.

`Reapply`

What reapplying does to an instance’s duration.

Variant	Written	Description
`Refresh`	`Refresh`	Resets the expiry (not the period’s phase).
`Extend`	`Extend(max_ticks: ..)`	Adds the new duration, up to a cap.
`Keep`	`Keep`	Keeps the current expiry.

Extend fields:

Field	Type	Required	Default	Description
`max_ticks`	`u32`	yes		The most ticks remaining after extending.

`AggregateBy`

What Aggregate counts stacks per.

Variant	Written	Description
`Target`	`Target`	One instance per target, whatever the source.
`Source`	`Source`	One instance per source.

`StackExpire`

How aggregated stacks expire.

Variant	Written	Description
`All`	`All`	All at once.
`One`	`One`	One at a time: at expiry one stack falls off and the next runs for one stack’s duration (charges that recover in turn).

`RemovalTrigger`

An event that ends an effect instance. Distances are checked four times a second. A trigger may also be written positionally (TagAdded((any: [..]))).

Variant	Written	Description
`TagAdded`	`TagAdded(query: ..)`	A matching tag is added to the holder from another source.
`DamageTaken`	`DamageTaken(min: ..)`	The holder took at least `min` damage in one hit.
`DealtDamage`	`DealtDamage`	The holder dealt damage.
`AbilityActivated`	`AbilityActivated(query: ..)`	The holder activated an ability whose tags match.
`SourceDied`	`SourceDied`	The source died.
`SourceGone`	`SourceGone`	The source despawned or unloaded.
`SourceBeyond`	`SourceBeyond(metres: ..)`	The source is farther away than `metres`.
`Moved`	`Moved(metres: ..)`	The holder moved `metres` from where the effect applied.
`Charges`	`Charges(count: .., spent_on: ..)`	Each event spends a charge; the last ends the instance. At most one per effect.

TagAdded fields:

Field	Type	Required	Default	Description
`query`	`TagQuery`	yes		The tags.

DamageTaken fields:

Field	Type	Required	Default	Description
`min`	`f32`	no	`0`	The smallest hit that counts.

AbilityActivated fields:

Field	Type	Required	Default	Description
`query`	`TagQuery`	no	any ability	The ability’s tags.

SourceBeyond fields:

Field	Type	Required	Default	Description
`metres`	`f32`	yes		The distance.

Moved fields:

Field	Type	Required	Default	Description
`metres`	`f32`	yes		The distance.

Charges fields:

Field	Type	Required	Default	Description
`count`	`u16`	yes		The charges, 1 to 65535.
`spent_on`	`ChargeEvent`	yes		The event that spends one.

`ChargeEvent`

The event that spends a Charges trigger’s charge.

Variant	Written	Description
`DamageTaken`	`DamageTaken`	The holder took damage.
`DealtDamage`	`DealtDamage`	The holder dealt damage.
`AbilityActivated`	`AbilityActivated`	The holder activated an ability.

`EffectUi`

An effect’s player-facing presentation, as message keys.

A record: EffectUi(..) or (..).

Field	Type	Required	Default	Description
`name`	`string` or `None`	no	`<mod>.effect.<id>.name`	The name’s message key.
`icon`	`string` or `None`	no	none	An icon asset.
`category`	`string` or `None`	no	none	A category the HUD groups effects by.
`show`	`bool`	no	`true`	Whether the HUD shows it.
`timer`	`TimerVisibility`	no	`Hidden`	Who sees its timer.

`TimerVisibility`

Who sees an effect’s timer.

Variant	Written	Description
`Hidden`	`Hidden`	No one.
`Owner`	`Owner`	The holder’s owner.
`SourceOwner`	`SourceOwner`	The owner of the effect’s source (the caster sees their debuff’s timer).
`Public`	`Public`	Every client with the holder in scope.

`Part`

A registered native effect part, which another crate provides (the AI’s taunt, manifold:taunt).

A record: Part(..) or (..).

Field	Type	Required	Default	Description
`id`	`string`	yes		The part’s id.
`args`	`part-args`	no	none, for a part without arguments	Its arguments, as the part declares them.

Value forms used here: condition, effect-duration, effect-ref, number, part-args, reserved, subject, tag-match.

Keyboard shortcuts