Cosmetic Configuration

Declare the worn visual flourishes a player can carry, and how each one draws.

A cosmetic changes what other players see around a character and nothing else. It carries no stat and gates nothing. An entry is an id, the name it is listed as, and a kind saying what it draws. Today the only kind is particle: emitters that follow the wearer around.

Declaring a cosmetic says it exists, never that anyone has it. Nothing a mod can write grants one. The server decides who carries which cosmetic and tells every client, so a modified client cannot give itself one that other players will see.

File Location

cosmetic-config.yaml, at the root of a mod, declared in the mod manifest:

# <ModName>.yaml
cosmetic-config:

Both the client and the server load this file. The client needs it to draw a cosmetic, and the server refuses to grant an id that no loaded mod declares.

A few cosmetics are built into the game rather than declared by a mod. A mod cannot replace one: an entry with the same id is refused as a duplicate.

Fields

Each entry under the top-level cosmetics: key is one cosmetic.

Field	Type	Required	Description
`id`	string	yes	Stable identifier, namespaced to the declaring mod. A mod may write its own name in front (`MyMod:sparkle`) but not another mod’s.
`display-name`	string	no	What the player reads. Omitted, the id is title-cased. Translatable — see Localization.
`kind`	string	yes	What the cosmetic draws. Only `particle` is valid.
`particles`	list	when `kind: particle`	Emitter groups, the same shape a tree or interactable declares. See below.

An entry with an unknown key, an unknown kind, a missing particles list, an id in another mod’s namespace, or an id already declared is skipped with an error. The rest of the file still loads.

Particle cosmetics

particles: is a list of groups, and each group holds an emit-random list. Every emit-random entry names a particle from a particle config, and the particle needs a texture before it can spawn.

Field	Type	Default	Description
`name`	string	—	Particle name. Unprefixed names resolve against the declaring mod.
`chance`	float	`0.1`	Probability of emitting each time the cooldown elapses.
`cooldown-ms`	int	`1000`	Time between emit rolls. Clamped to at least 1 ms.
`lifetime-ms`	int	`1`	How long each particle lives.
`has-lifetime`	bool	`true`	Smart particles only. `false` keeps the particle alive.
`x-offset-min` / `x-offset-max`	float	`0.0`	Horizontal spawn range, in blocks.
`y-offset-min` / `y-offset-max`	float	`0.0`	Vertical spawn range, in blocks.

Offsets are measured from the wearer’s feet, centred horizontally, with y pointing up. A player is 2 blocks wide and 3 tall, so x -1.0..1.0 and y 0.0..3.0 covers the body.

Every client draws the cosmetics of the players in the world it is looking at. Particle Amount in the display settings thins cosmetic particles like any other particles. A player can turn off other players’ cosmetics in the particle settings. That setting never hides their own cosmetic or the developer’s.

Example

cosmetics:
  - id: sparkle
    display-name: Sparkle
    kind: particle
    particles:
      - emit-random:
          - name: sparkle
            chance: 0.5
            cooldown-ms: 100
            lifetime-ms: 1500
            x-offset-min: -1.0
            x-offset-max: 1.0
            y-offset-min: 0.0
            y-offset-max: 3.0

Granting a cosmetic

No grant source is open to mods yet. The one grant that exists is built into the engine: a cosmetic bound to a single Steam account. The server makes that grant only from a Steam identity it has verified itself, either through an auth ticket or through the Steam connection. It never takes a player’s own word for who they are. The Almanac’s cosmetic reward family will be the first grant a mod can use, and it will name ids from this file.

Last updated Sep 29, 2026