Affix Configuration

Define weapon affixes — the tag-gated "intrinsic playstyle" half of the gear-enhancement pools.

An affix is an enhancement that shapes a weapon’s intrinsic playstyle — a verb like a lunge, a cleave, a guard window, or a damage-over-time bleed — chosen at a reforge station and re-tunable there (its sibling is the infusion, the swappable typing/utility half). Which affixes a given weapon can take is decided by tags: the affix lists tags, the weapon lists tags, and the affix is available only where they overlap.

This page defines the catalog of affixes that exist. Which affix a specific item instance currently carries is per-instance state set at a reforge station, not authored here. An affix’s behavior is declared by its effect — a small set of engine-native verbs (widen the swing, dash on use, apply a status effect on hit) plus a Lua escape hatch for anything else.

File Location

affix-config:

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/affix-config.yaml

The file is a single list of affix entries:

affixes:
  - name: lunge
    tags: light
  - name: cleave
    tags: [heavy, melee]

Fields

Field	Required	Description
`name`	yes	The affix’s name. Mod-qualified automatically (`lunge` → `YourMod:lunge`) unless you write an explicit `Mod:name`. This is the id stored on an item that carries the affix.
`tags`	no	A tag or list of tags gating which weapons can take this affix. A weapon can take the affix only if the weapon’s own `tags:` (see item-config) share at least one tag. Matched case-insensitively. Omitted or empty → the affix is available on no weapon (fail-closed).
`effect`	no	The affix’s behavior — a `{ kind: … }` block (see Effects). Omitted → the affix is a catalog entry with no behavior yet.

Tags gate availability, and a typo fails closed

Tags are the same open, un-namespaced registry used everywhere else (tool-types, #tag item references): any word is a valid tag, matched case-insensitively. An affix tagged light is offered on every weapon whose tags: include light. A tag no weapon carries — including a typo like lite — simply makes the affix available on nothing, rather than erroring or applying everywhere. The server logs a load-time warning naming any enhancement tag no weapon declares, so a typo is visible rather than silent.

Effects

An affix’s effect block is a kind plus that kind’s fields. An unknown kind, or a kind missing a required field, warns at load and the affix is skipped (fail-closed). All affix effects apply to weapons and are server-authoritative.

Kind	Fields	Fires	Behavior
`hitbox-scale`	`magnitude` (number)	swing build	Widens the swing hit-area by the factor (a `cleave`-style wider arc).
`lunge`	`magnitude` (number)	swing start	Dashes the wielder toward the cursor as an impulse of this speed.
`on-hit-effect`	`target` (`victim`\|`wielder`), `status-effect` (id)	on a landed hit	Applies a status effect to the struck entity (a bleed/rot DoT) or the wielder (a ward). The id scopes to the declaring mod unless written `Mod:id`.
`lua`	`server-on-hit` and/or `server-on-primary-use` (script paths)	on-hit / swing start	Runs a server Lua hook — the escape hatch for behavior the native kinds don’t cover.

affixes:
  - name: cleave
    tags: melee
    effect: { kind: hitbox-scale, magnitude: 1.5 }

  - name: lunge
    tags: light
    effect: { kind: lunge, magnitude: 8.0 }

  - name: rot                                    # decay DoT on whatever it hits
    tags: melee
    effect: { kind: on-hit-effect, target: victim, status-effect: poison }

  - name: ward                                   # restorative tick on the wielder
    tags: light
    effect: { kind: on-hit-effect, target: wielder, status-effect: regeneration }

Lua hooks

For behavior beyond the native kinds, an affix may name server Lua hook files. Each file returns a function (the standard hook contract):

  - name: my_affix
    tags: melee
    effect:
      kind: lua
      server-on-hit: /affixes/my_affix_on_hit.lua               # (wielder, victim)
      server-on-primary-use: /affixes/my_affix_on_primary.lua   # (wielder, x, y)

-- my_affix_on_hit.lua
return function(wielder, victim)
    victim:apply_effect("MyMod:some_effect")
end

The hooks receive the wielder and (for on-hit) the victim as entity handles exposing apply_effect, apply_impulse, and the rest of the entity API. Note: server-on-primary-use fires only for a player wielder; a mob wielding a Lua-server-on-primary-use affix is a known gap (mob native affixes and mob server-on-hit hooks work normally).

Example

affixes:
  - name: cleave
    tags: [heavy, melee]
    effect: { kind: hitbox-scale, magnitude: 1.5 }

For a weapon to take cleave, give it a matching tag in item-config:

items:
  - name: my_greatsword
    type: weapon
    tags: [heavy, melee]     # can now take the `cleave` affix
    weapon-info:
      type: melee
      damage: 30.0

Last updated Aug 25, 2026