> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/configuration/effects.md).

# effects

Effects belong in `effects:` on a node or a supported Journey entry. An effect key must be registered in code; adding a name to `effects/native_catalogue.yml` does not implement it.

The [complete effect catalogue](file:///4985688/reference/effects/README.md) contains every registered exact key, allowed operations, value help, and accepted field. Use its **runtime evidence** label as well as the schema.

## Common effect fields

```yaml
key: pixelmon.capture_power.fire
operation: multiply_final
values: [1.05, 1.10, 1.15]
stacking-group: ember_capture_power
aggregation: sum
cap: 12.0
priority: 0
scope: player
filters: {}
when-missing: disable_effect
```

| Field            | Meaning                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `key`            | Exact registered effect ID                                                                |
| `operation`      | Must be allowed by this effect's schema                                                   |
| `values`         | Total effect value by purchased rank; last value repeats                                  |
| `value`          | Single-value fallback                                                                     |
| `stacking-group` | Retained grouping label; not an enforced de-duplication policy in current core evaluation |
| `aggregation`    | Accepted metadata; current core does not dispatch the advertised aggregation modes        |
| `cap`            | Positive upper cap on the resulting value; 0 means no hard cap from this contribution     |
| `priority`       | Sort priority; affects override ordering                                                  |
| `scope`          | Retained label; does not automatically redirect ownership to a Pokemon/party/server       |
| `filters`        | Both typed action parameters and event conditions; see each schema                        |
| `when-missing`   | Safe default `disable_effect`; see current missing-policy limitations                     |

Keep effect filter values scalar: `filters: {dimension: 'minecraft:overworld', type: 'fire,water'}`. Do not rely on a YAML list being converted correctly in this map.

## Operation math

For ordinary core evaluation, operations execute in this order:

{% stepper %}
{% step %}

### `add_flat`

Add values.
{% endstep %}

{% step %}

### `add_percent_points`

Add values divided by 100.
{% endstep %}

{% step %}

### `multiply_base`

Add `original base × (product of factors - 1)`.
{% endstep %}

{% step %}

### `multiply_final`

Multiply the current result by the product of factors.
{% endstep %}

{% step %}

### `set_min`

Enforce the highest supplied floor.
{% endstep %}

{% step %}

### `set_max`

Enforce the lowest supplied ceiling.
{% endstep %}

{% step %}

### `override`

Use the last active override in priority/node ordering.
{% endstep %}

{% step %}

### `trigger_action`

Contributes its numeric value; the gameplay hook decides the action.
{% endstep %}

{% step %}

### `reroll` / `keep_best`

For values between 0 and 1, compute `1 - (1 - p)^(1 + extra rolls)`.
{% endstep %}

{% step %}

### Apply caps and probability clamping

Apply the smallest positive hard cap, then clamp probability effects to 0–1.
{% endstep %}
{% endstepper %}

Example: a probability base of 0.01 plus `add_percent_points: 1` becomes 0.02 (2%). `multiply_final: 1.10` means 10% more relative to the base, not +10 percentage points. A multiplier of `0.90` reduces a quantity by 10%; use it for supported damage-taken or interval effects, not a positive flat bonus.

Other accepted operation names are `weight_add`, `weight_multiply`, `unlock`, `deny`, `transform`. They are not generic implemented behavior in `EffectEngine.evaluate`; specialized hooks may read them, and an external consumer must support what you intend. A registered allowed operation is not proof that every hook implements it.

Action reward helpers can read individual contributions rather than the ordinary evaluation formula. For item chances, percentage points are converted to fractions; currency rewards sum whole-valued contributions; permission grants use their parameters. Follow the specific schema/recipe, not a universal assumption that every operation affects every helper identically.

## Typed parameters versus conditions

Both live under `filters`, but mean different things:

* **Parameters** tell a helper what to do: `item`, `min_count`, `currency`, `permission`, `status_effect`, `duration_ticks`, `display`, and choice metadata.
* **Conditions** restrict the event: `species`, `type`, `dimension`, `entity`, `block`, `loot_table`, and integration IDs, only when supplied by that hook.

Parameter keys declared by the effect schema do not have to appear in the event context. Undeclared condition keys do. An arbitrary field is not a new behavior merely because YAML accepts a string.

Effect filters use literal keys, comma-separated alternatives, `*` wildcard matching, and a leading `!` exclusion. They do not provide the quest matcher's numeric `min_`/`max_` comparisons or automatic namespace-tail aliases. Use exactly the fields shown by the effect schema and hook context.

## Player-facing benefit text

The server generates readable current/next/max-rank benefits for both custom and fallback menus. Type keys become names such as Dragon Capture Power, not `pixelmon.capture_power.dragon`.

Action schemas provide `display` for a custom explanation and `hidden` to suppress benefit text. For a permission perk, describe the feature the player earns instead of exposing the permission string. Preserve placeholders documented by the field help; a description is not code and does not change the effect value.

## Native permissions

`server.permission` with `provider: native` exposes a permission through StellarSkills' own permission query/API. It does **not** automatically grant that permission to every unrelated mod/plugin.

`provider: commands` runs configured provider grant/revoke commands, with LuckPerms-style defaults. The server must actually have a compatible provider and command. These run with server authority; reserve effect authoring for trusted administrators. Avoid granting a permission the same player already owns independently because a later revoke can remove the provider node. See [permission recipe](file:///4985688/examples/recipes.md).

## First-open container rewards

`minecraft.loot_table_item_chance` runs while a block container generates its loot table for a server player. Vanilla normally clears that table afterward, so reopening does not reroll. It is not a universal listener for every chest opening, manually filled chest, or every mod's custom loot screen. Already-generated chests do not retroactively get a new bonus.

The helper builds a plain registry ItemStack. Icon aliases such as `pixelmon:master_ball` and potion aliases are **not** a general data-component reward syntax. Do not promise a Master Ball or colored potion reward from an alias unless the installed registry actually exposes that exact item or an additional data-aware reward integration exists.

## Missing integrations

`disable_effect` makes the absent integration contribution inactive. `ignore` can retain a contribution but cannot create a missing gameplay hook. The model also accepts `disable_node`, `hide_node`, `refund_node`, `error`; current core does not implement each name as a separate automatic node lifecycle action. Do not rely on automatic refunds simply by choosing `refund_node`.

Optional mod presence is only part of availability. Correct event/bridge consumers are necessary. See [integrations](broken://pages/f5b3203bf0be11a70f3e03231c810672fe73db1e) and [implementation limits](file:///4985688/operations/implementation-limits.md).