Player Configuration

Set the player's default hitbox, movement, health, and oxygen, 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

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.

Field	Default	Description
`hitbox`	`2.0` × `3.0`	The player’s collision box, in blocks — the shared `hitbox` block.
`movement`	(see below)	The player’s locomotion values. See Movement.
`health`	(engine default)	The player’s starting health — same shape as Health Configuration.
`oxygen`	(engine default)	The player’s starting oxygen — same shape as Oxygen Configuration.
`scripts.server-update`	(none)	A per-tick Lua hook that runs for the player entity, declared the same way as items’ `server-on-primary-use` (a bare path to a `.lua` file that `return`s its handler).

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.

Field	Default	Description
`walk-speed`	`20.0`	Horizontal velocity applied while a move key is held (before block drag).
`jump-velocity`	`20.0`	Initial upward velocity of a jump started from the ground (before drag).
`jump-acceleration`	`150.0`	Sustained upward acceleration while the jump key is held mid-air (before drag).
`fall-through-velocity`	`10.0`	Downward velocity applied when dropping through a one-way platform.
`max-velocity`	`{ x: 50.0, y: 50.0 }`	The physics speed cap, same `{ x, y }` shape mobs use. Distinct from `walk-speed`: it clamps the result of all forces, not the walk input. Either axis may be omitted and defaults independently to `50.0` (the same convention as mobs and mounts).

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
  max-velocity:
    x: 50.0
    y: 50.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