Player Configuration

Set the player's default hitbox, movement, health, oxygen, and divine Channel resource, plus a per-tick Lua hook that runs for every connected player.

Player configuration defines the base entity every player is built from — its hitbox, movement feel, starting health and oxygen — and an optional per-tick Lua hook that runs for the player entity itself (as opposed to a specific mob or interactable). The hitbox, health, and oxygen blocks reuse the exact same schemas as Mob Configuration, so if you have configured a mob you already know most of this file.

Unlike catalog files, this one is a single object — there’s no wrapping list, and only one mod’s player-config.yaml needs to declare each block (the last mod to load with a given block set wins).

:::note[Player config lives in two files] This file sets the player’s mechanics. The player’s identity — player-id, display-name, and the chosen skin (player-texture-path) — lives separately in the instance’s game_config/config.yaml, because the skin is a per-user choice rather than a mod definition. :::

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

player-config: player-config.yaml

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

mods/<YourMod>/player-config.yaml

It is a single object at the document root — no - name: list entries:

health:
  max: 20

Minimal Example

health:
  max: 20
  regen-per-second: 0.0
oxygen:
  max: 30
  takes-damage: true

Fields

Every block is independently optional — omitting one leaves the engine’s own default (or, if another loaded mod already set it, that mod’s value) in place.

Movement

The movement block controls how the player’s own key presses translate into motion. These are direct input-driven velocities, which is a different model from a mob’s walk-speed — a mob’s is a pathfinder target, whereas the player’s is the velocity applied the instant a key is held. Copying a mob’s small walk-speed (e.g. 5.0) into the player config will feel like a crawl.

The remaining fields tune the capability-gated verbs. They are inert until the player actually holds the matching capability (see Capabilities) — setting air-dash-velocity does not by itself give anyone an air dash.

dodge-iframe-ms, dodge-cooldown-ms, block-fraction, parry-window-ms, parry-stagger-velocity, and block-cooldown-ms are the movement fields the server reads. Everything else here is client-simulated locomotion; a dodge’s invulnerability and the block/parry mitigation are resolved server-side, so they cannot be left to the client. (block-cooldown-ms is read by both sides — the client mirrors it to gate its own input, exactly as it does dodge-cooldown-ms.)

Capabilities

Capabilities are named strings a player either holds or doesn’t. They gate the movement verbs below, and they are the same strings required-capability barrier blocks check — so a verb granted by armor doubles as a key that opens a gated wall.

A player’s effective set is the union of three sources:

1. capabilities: baseline: in this file — verbs everyone has inherently.
2. Gear grants — grants-capabilities on a worn armor piece or a met set-bonus tier. Withdrawn the moment the gear comes off.
3. Persistent grants — player:grant_capability(name) from a Lua script (a boss first-kill, a consumed key). Saved with the player.

Four names are recognized by the engine as verbs; everything else is free-form and only meaningful to whatever gates you write.

Both defensive verbs only intercept attacker-sourced hits (the mitigable class armor reduces — melee, projectiles, scripted damage, AoE zones). Neither touches environmental damage — a roll or a block cannot cancel a fall, a drowning tick, the void, or suffocation.

The shipped configuration sets baseline: [dodge, block]: the defensive verbs are inherent, while double_jump and air_dash are earned so they can double as keys for required-capability barriers. Putting a verb in baseline makes it universal instead — useful for a total conversion where mobility is assumed rather than unlocked:

capabilities:
  baseline:
    - dodge
    - block
    - double_jump

Combat Verbs

The combat-verbs block defines granted active offensive abilities. The shipped game uses it for the two universal force-strikes — the Wither (a decay strike) and the Kindling (a creation strike that also heals its caster). Like the dodge, a combat verb is a keypress that sends an intent the server re-checks; unlike the dodge, it resolves a typed area strike in front of the player, in the direction they are visually facing.

Combat verbs are gated on a capability — so a verb doubles as a key for required-capability barriers — and are meant to be granted through progression (player:grant_capability, a boss reward or a crafted catalyst), not put in baseline.

combat-verbs is a map keyed by verb id. The verb id is also the default capability name. The shipped game wires two verbs — wither and kindling, triggered by the WITHER / KINDLING control actions — and this block is where you tune them (damage, cooldown, reach, and so on). Adding a wholly new verb id needs engine support for its input action and cannot be done from config alone today.

combat-verbs:
  wither:
    cooldown-ms: 4000
    damage: 40.0
    damage-type: decay
    range: 3.0
    width: 3.0
  kindling:
    cooldown-ms: 4000
    damage: 30.0
    damage-type: radiant
    range: 3.0
    width: 3.0
    heal: 15.0

Because the verbs are granted, a fresh player cannot use one until a script grants its capability; for testing, an operator can run /capability grant wither.

Damage Types

A damage-type — here, and on weapons, contact/impact blocks, and AoE zones — is one of the following (case-insensitive; an unknown name is a config error). Each has its own armor-resistance slot, so a mod can make a mob resist decay without changing its physical armor:

Channel

The Channel pool is the divine caster’s resource — the mana-analogue a divine focus spends to cast (never called “mana”). It is a single per-player pool that regenerates passively over time; it refills fully on respawn. The HUD meter for it stays hidden until the player has held a focus, so it adds no clutter for non-casters.

channel:
  max: 100.0             # optional, default 100.0. The pool's ceiling.
  regen-per-second: 8.0   # optional, default 8.0. Passive regeneration rate.

Both keys are optional; omit the whole block to take the engine defaults. The values are provisional tuning.

Complete Example

Based on the real shipped player configuration. The hitbox and movement values match the engine’s built-in defaults, but the oxygen/health values below are the shipped Creation tuning, not the engine defaults — omit a block to fall back to the defaults documented in health-config.md (max 100) and oxygen-config.md (max 10):

scripts:
  server-update: /player/server_update.lua

hitbox:
  width: 2.0
  height: 3.0

movement:
  walk-speed: 20.0
  jump-velocity: 20.0
  jump-acceleration: 150.0
  fall-through-velocity: 10.0
  air-jump-count: 1
  air-dash-velocity: 45.0
  air-dash-duration-ms: 150
  air-dash-count: 1
  dodge-velocity: 40.0
  dodge-duration-ms: 200
  dodge-cooldown-ms: 900
  dodge-iframe-ms: 300
  block-fraction: 0.5
  parry-window-ms: 200
  parry-stagger-velocity: 30.0
  block-cooldown-ms: 500
  max-velocity:
    x: 50.0
    y: 50.0

capabilities:
  # dodge and block are inherent; double_jump and air_dash are earned from armor.
  baseline: [dodge, block]

combat-verbs:
  # Granted force-strikes (gated on the wither / kindling capabilities, not baseline).
  wither:
    cooldown-ms: 4000
    damage: 40.0
    damage-type: decay
    range: 3.0
    width: 3.0
  kindling:
    cooldown-ms: 4000
    damage: 30.0
    damage-type: radiant
    range: 3.0
    width: 3.0
    heal: 15.0

oxygen:
  max: 30
  consumption-rate-per-second: 20.0
  regen-per-second: 1.0
  takes-damage: true

health:
  max: 10
  regen-per-second: 0.0
  takes-damage: true

Last updated Aug 25, 2026