Player sprites in Reldens use a spritesheet - a single PNG image containing all animation frames arranged in a grid. This guide explains the required format, how to configure frame dimensions, and how to assign different sprites per class path.

Adding spritesheets via admin

The sprite of each class path is linked by its key, and the frames and the frame size are config rows edited in the administration panel.

1. Draw the spritesheet following the Spritesheet Format and the Default Frame Dimensions described below.
2. Log in to the administration panel at /reldens-admin (the path can be changed with the RELDENS_ADMIN_ROUTE_PATH environment variable).
3. Open Classes & Levels > Class Paths (/reldens-admin/skills-class-path) and find the Key of the class path, or click Create New to add a new class path with its own key.
4. Name the file after that key, for example sorcerer.png for the key sorcerer, and copy it into the assets/custom/sprites folder of your theme. The administration panel has no upload field for the player sprites.
5. Open Control Panel and run Copy Assets to Dist so the new file is published with the game assets.
6. Open Settings > Config (/reldens-admin/config), type players/animations in the search box and click Filter. Edit the defaultFrames rows when your layout differs from the default one, or add the frames of that class path only with Create New (see Per Class Path Sprites below).
7. If the frame size is not 52 x 71 pixels, search players/size and edit the width and height rows.
8. Restart the server and reload the game: the config is loaded when the server starts.

Spritesheet and configuration reference

Spritesheet Format

The default layout is 4 rows x 3 columns = 12 frames, one row per movement direction:

• Row 1 (frames 0-2): Walking down (toward the camera)
• Row 2 (frames 3-5): Walking left
• Row 3 (frames 6-8): Walking right
• Row 4 (frames 9-11): Walking up (away from the camera)

Each row must contain exactly 3 frames: idle (center), step-left, step-right. The middle frame of each row is typically used as the standing/idle pose.

You are not limited to this layout - frame start/end indices are fully configurable per class path (see below).

Default Frame Dimensions

The default frame size is 52 x 71 pixels. Your spritesheet must be exactly:

• Width: frameWidth x number of columns (e.g. 52 x 3 = 156 px)
• Height: frameHeight x number of rows (e.g. 71 x 4 = 284 px)

The frame size is stored in two config rows that are already created by the installation:

• Scope: client - Path: players/size/width - Value: frame width in pixels - Type: 2 (number)
• Scope: client - Path: players/size/height - Value: frame height in pixels - Type: 2 (number)

To change them, go to the admin panel under Settings > Config and edit those entries (or create them with the form below if your database does not have them).

Alternatively, update the entries directly via SQL:

UPDATE `config` SET `value` = '52' WHERE `scope` = 'client' AND `path` = 'players/size/width';
UPDATE `config` SET `value` = '71' WHERE `scope` = 'client' AND `path` = 'players/size/height';

The size is global: it is used to load the fallback sprite and every class path sprite, and to size the avatar preview on the character selection screen. A different frame size per class path is not supported yet, so all your player spritesheets must use the same frame size.

File Location

Place your spritesheet in:

theme/[your-theme]/assets/custom/sprites/

The fallback sprite is the file loaded for all players who do not have a class-path-specific sprite. It is configured by the players/animations/fallbackImage entry (installed with the value player-base.png). Change it in the admin panel under Settings > Config:

• Scope: client - Path: players/animations/fallbackImage - Value: your filename (e.g. player-base.png) - Type: 1 (string)

Alternatively via SQL:

UPDATE `config` SET `value` = 'player-base.png' WHERE `scope` = 'client' AND `path` = 'players/animations/fallbackImage';

Configuring Frame Ranges

Default frame ranges define which frame indices map to each movement direction. They are stored as one number row (type 2) per value under players/animations/defaultFrames, and the config manager rebuilds them into this object:

{
    "down":  { "start": 0, "end": 2 },
    "left":  { "start": 3, "end": 5 },
    "right": { "start": 6, "end": 8 },
    "up":    { "start": 9, "end": 11 }
}

The installation creates the eight rows, from players/animations/defaultFrames/down/start to players/animations/defaultFrames/up/end (scope client). Edit them in the admin panel under Settings > Config, or via SQL:

UPDATE `config` SET `value` = '0' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/down/start';
UPDATE `config` SET `value` = '2' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/down/end';
UPDATE `config` SET `value` = '3' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/left/start';
UPDATE `config` SET `value` = '5' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/left/end';
UPDATE `config` SET `value` = '6' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/right/start';
UPDATE `config` SET `value` = '8' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/right/end';
UPDATE `config` SET `value` = '9' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/up/start';
UPDATE `config` SET `value` = '11' WHERE `scope` = 'client' AND `path` = 'players/animations/defaultFrames/up/end';

Since the defaults are stored as individual rows, edit those rows instead of adding a single JSON row with the same players/animations/defaultFrames path.

These defaults apply to every sprite unless overridden per class path.

Per Class Path Sprites

Each class path can use a different spritesheet. The sprite file must be named after the class path key (the key field of the skills_class_path record):

theme/[your-theme]/assets/custom/sprites/[classPathKey].png

For example, a class path with key mage loads /assets/custom/sprites/mage.png. If that file is not found in the loaded assets, the player uses the fallback sprite.

You can also override the frame ranges for a specific class path with the path players/animations/[classPathKey]Frames (e.g. players/animations/mageFrames), same shape as the defaults: one number row (type 2) per value, scope client. Add them in the admin panel under Settings > Config, or via SQL (replace mage with your class path key):

INSERT INTO `config` (`scope`, `path`, `value`, `type`) VALUES
('client', 'players/animations/mageFrames/down/start', '0', 2),
('client', 'players/animations/mageFrames/down/end', '2', 2),
('client', 'players/animations/mageFrames/left/start', '9', 2),
('client', 'players/animations/mageFrames/left/end', '11', 2),
('client', 'players/animations/mageFrames/right/start', '3', 2),
('client', 'players/animations/mageFrames/right/end', '5', 2),
('client', 'players/animations/mageFrames/up/start', '6', 2),
('client', 'players/animations/mageFrames/up/end', '8', 2);

A single JSON row (type 4) at players/animations/mageFrames with the whole object as value is parsed into the same structure, just do not mix both formats for the same key.

Notes:

• If no override is set, the defaultFrames config is used as fallback.
• An override replaces the defaults completely, so it must define the four directions (down, left, right and up), each one with start and end.
• A value of 0 is treated as not set and replaced by the default layout value of that direction (for example left start 3), so keep frame 0 in the down row, where the default start is also 0.

The class path key is sent to the client as the player avatarKey, see Player Animations Configuration for the full technical flow.

Animation Playback

Reldens automatically creates four looping animations per avatar key:

• {avatarKey}_down
• {avatarKey}_left
• {avatarKey}_right
• {avatarKey}_up

For example, a class path with key mage gets mage_down, mage_left, mage_right and mage_up.

These are played automatically based on the player movement direction. The animation stops (holding the last frame) when the player is stationary.

The default frame rate is 10 fps. To change it, go to Settings > Config in the admin panel and edit:

• Scope: client - Path: general/animations/frameRate - Value: frames per second - Type: 2 (number)

Alternatively via SQL:

UPDATE `config` SET `value` = '10' WHERE `scope` = 'client' AND `path` = 'general/animations/frameRate';

Additional Configuration

All these entries use the scope client and are edited in the admin panel under Settings > Config:

• basedOnPress - path players/animations/basedOnPress: if 1, the animation plays while a direction key is held; if 0, it plays based on the actual position change.
• diagonalHorizontal - path players/animations/diagonalHorizontal: if 1, the horizontal (left / right) animation plays during diagonal movement.
• collideWorldBounds - path players/animations/collideWorldBounds: whether the player physics body collides with the world bounds.
• fadeDuration - path players/animations/fadeDuration: duration in milliseconds of the camera fade played when the player scene is created (default 1000).
• topOffset / leftOffset - paths players/size/topOffset and players/size/leftOffset: pixel offsets for the sprite anchor point relative to the physics body.

Recommended Tools

• Aseprite - pixel art editor with spritesheet export
• GIMP - free image editor
• LibreSprite - free Aseprite fork

When exporting, ensure the spritesheet is exported as a flat PNG with no padding or margins between frames (unless you adjust the Phaser loader parameters accordingly).

Related Documentation

• Player Animations Configuration - Technical reference for the player size and animation config keys.
• Player Sprites and Assets - Player asset overview.
• Class Path Entity - The key field used to name the class path sprites.
• Configuration - General config system.