Artist Guide

Character Overlays

How to create and add hat, sword, axe, and tool overlays to the game. No code changes required — drop the file in the right folder and register the item.

Section 1

Overview

Overlays are sprite images that are composited on top of the base character sprite at runtime. There are two types:

TypeFolderUsed for
Hatoverlays/hats/Headwear worn in any animation
Weapon / Tooloverlays/swords/, overlays/axes/, overlays/tools/Hand-held items shown during idle, walk, and action animations

All overlay files live under:

client/public/assets/characters/humans/overlays/
No code required Drop the PNG in the correct subfolder and the engine picks it up automatically. The only thing you need to do in code is register the item in the admin item editor with the correct overlay key.
Section 2

Hat Overlays

A hat overlay is a small sprite sheet containing the hat drawn from eight different angles — one for each head pose the character uses across all animations. The engine selects the correct cell per animation frame automatically.

Sheet format

PropertyValue
Total size128 × 64 px
Cell size32 × 32 px each
Layout4 columns × 2 rows
Poses8 (numbered 0 – 7, left-to-right, top-to-bottom)
128 × 64 px — 4 cols × 2 rows of 32 × 32 px cells
0front
1tilt R
2side
3back-L
4bob lo
5bob hi
6tilt L
7back-R
Tip — use an existing hat as a template Open overlays/hats/farmers_hat.png in your image editor. It shows the exact layout and pixel alignment. Draw your hat in each cell using that file as a reference layer.

File location & naming

overlays/hats/your-hat-name.png

The filename becomes part of the overlay key. Use lowercase with hyphens; no spaces.

Steps

  1. Create a 128 × 64 px PNG. Fill each of the 8 cells with the hat drawn from the appropriate angle, pixel-perfect at 32 × 32 px.

  2. Save it to client/public/assets/characters/humans/overlays/hats/your-hat-name.png.

  3. In the admin item editor, create or edit an item and set:

    FieldValue
    Equip slothead
    Overlay keyhats/your-hat-name
    Hides hairYes if the hat fully covers the hair; No if hair should still show through
Section 3

Weapon & Tool Overlays

Weapon and tool overlays are single-row animation strips. The strip contains frames that align exactly with the character's attack, axe-swing, or mining animation, plus one dedicated frame used during idle and walk.

All three categories share the same strip format. The category subfolder determines which hand-alignment offsets the engine applies:

SubfolderAnimationExamples
overlays/swords/Attack (ATTACK)swords, daggers, staves
overlays/axes/Axe-swing (AXE)axes, hatchets, cleavers
overlays/tools/Mining (MINING)pickaxes, hammers, shovels

Strip format

PropertyValue
Total size1056 × 64 px
Frame size96 × 64 px each
Frame count11 (frames 0 – 10)
Frames 0 – 9Action animation frames (must align with the character's ATTACK / AXE / MINING strip)
Frame 10Idle / walk pose — the frame shown when the character is standing or walking
1056 × 64 px — 11 frames of 96 × 64 px
0
1
2
3
4
5
6
7
8
9
10idle/walk
Tip — use an existing strip as a template The existing strips in overlays/swords/basic.png, overlays/axes/axe.png, and overlays/tools/basic-pickaxe.png show the expected alignment. The weapon sprite must be positioned so that the grip pixel sits at the character's hand position for each frame. Open the corresponding character animation strip (ATTACK/base_attack_strip10.png etc.) as a reference layer to check alignment.

Idle / walk frame (frame 10)

Frame 10 is used whenever the character is idle or walking. It is a static single frame — no per-frame variation is applied. A good starting point is to copy frame 6 of the action animation (the peak of the swing), which shows the weapon in a natural held position. Adjust from there to match your specific weapon's resting pose.

File location & naming

overlays/swords/your-sword-name.png
overlays/axes/your-axe-name.png
overlays/tools/your-tool-name.png

Steps

  1. Create a 1056 × 64 px PNG. Draw 10 action frames (0 – 9) aligned to the correct character animation strip, then draw the idle/walk pose as frame 10.

  2. Save it to the correct subfolder, e.g. overlays/swords/long-sword.png.

  3. In the admin item editor, create or edit an item and set:

    FieldValue
    Equip slotright_hand
    Overlay keyswords/long-sword  (matches the path without .png)
Rendering rules During idle and walk, the engine draws frame 10 of the overlay strip at a fixed hand-position offset for the category. During attack, axe, or mining animations, the engine draws the matching frame from the overlay strip (frame 0 for the first animation frame, frame 1 for the second, and so on) at position (0, 0) to exactly overlay the character strip. The built-in tools layer is never shown when a weapon overlay is equipped.
Section 4

Registering the Item

Once the PNG is in place, open the admin console and go to the Item Editor. Create a new item (or edit an existing one) and fill in:

FieldHatSword / Axe / Tool
NameDisplay name shown in the inventory
TileIndex of the icon in the items tileset
StackableUsually No for equipment
Equip slotheadright_hand
Overlay keyhats/your-hat-nameswords/name   axes/name   tools/name
Hides hairYes or No depending on the hat designn/a

The overlay key is the path to the PNG file relative to the overlays/ folder, without the .png extension. Save the item and it will be available to equip immediately — no server restart or code change needed.

Section 5

Checklist

Hat overlay
  • PNG is 128 × 64 px
  • 8 cells of 32 × 32 px, 4 columns × 2 rows
  • Saved to overlays/hats/name.png
  • Item created in admin editor with equip slot head and overlay key hats/name
  • Hides hair flag set correctly
Weapon / tool overlay
  • PNG is 1056 × 64 px
  • 11 frames of 96 × 64 px
  • Frames 0 – 9 aligned to the matching character animation strip
  • Frame 10 is the idle / walk pose
  • Saved to the correct category subfolder (swords/, axes/, or tools/)
  • Item created in admin editor with equip slot right_hand and overlay key matching the file path