Object Sprites and Assets

Objects in Reldens (NPCs, enemies, interactable items) use sprites and spritesheets configured through the admin panel. This guide explains the supported asset types, file placement, and how animations are defined per object.

Uploading object assets

The administration panel has no upload field for object sprites: the image files are part of your theme. You copy the file into the theme, publish the theme assets from the Control Panel and then register the file as an asset of the object, with its animations.

  1. Prepare the spritesheet PNG with all the frames in a grid of equal size (PNG is recommended for transparency).
  2. Copy the file into the theme/[your-theme]/assets/custom/sprites/ folder of your project.
  3. Log in to the administration panel at /reldens-admin.
  4. Open Control Panel, choose your theme in Theme Selector and click Copy Assets to Dist in Client Dist Commands, so the file is copied into dist/assets where the game client loads it from. From a terminal the same command is npx reldens copyAssetsToDist [your-theme].
  5. Open Game Objects > Assets (/reldens-admin/objects-assets) and click Create New (/reldens-admin/objects-assets/edit).
  6. Select the Object ID, set Asset Type to spritesheet, type a unique Asset Key (for example enemy_forest_1), the file name in Asset File (for example monster-treant.png, without folders) and the frame size in Extra Params: {"frameWidth":47,"frameHeight":50}. Click Save.
  7. Open Game Objects > Animations (/reldens-admin/objects-animations) and click Create New. Select the Object ID, type the AnimationKey and the AnimationData JSON with the frames, then click Save. For an enemy that walks around add one row per direction, for example merge-respawn-area-monsters_6_down with {"start":0,"end":2} and the same for left, right and up.
  8. Restart the server and reload the game: the objects, their assets and their animations are loaded when the room starts.
Admin Panel - Game Objects Assets list Admin Panel - Create Assets form with Object ID, Asset Type, Asset Key, Asset File and Extra Params Admin Panel - Game Objects Animations list with one animation key per direction Admin Panel - Create new object animation form

To create many objects with their assets and animations at once use the Objects Importer.

Configuration reference

File Location

Place sprite files inside your theme's assets folder:

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

Any image format supported by Phaser works (PNG is recommended for transparency support).

Assets form

  • Object ID (required) - the object that owns the asset.
  • Asset Type (required) - see Asset Types below; use spritesheet.
  • Asset Key (required) - texture key of the asset. A respawn enemy uses the first asset of its object as sprite; any other object uses the asset whose key is equal to the object Client Key, or the asset_key set in the object Client Params.
  • Asset File (required) - file name inside assets/custom/sprites (for example monster-treant.png); the client loads it from /assets/custom/sprites/[Asset File].
  • Extra Params - JSON spritesheet options: frameWidth and frameHeight are required for spritesheets, spacing and margin are optional. Example: {"frameWidth":47,"frameHeight":50,"spacing":2}

Asset Types

Each object can have one or more assets. The Asset Type field controls how Phaser loads the file:

  • spritesheet - A grid of animation frames. Requires frameWidth and frameHeight in Extra Params.
  • image - A static single image with no animation frames.
  • atlas - A texture atlas with a JSON descriptor file.

The server sends the assets of every type to the client, but the default client only preloads the spritesheet assets; image and atlas need custom client code. For a static image use a spritesheet with a single frame.

Animations form

  • Object ID (required) - the object that owns the animation.
  • AnimationKey (required, unique per object) - the Phaser animation key. When an object moves the client plays the first existing key of: [clientKey]_[direction], [layer]_[objectId]_[direction], [clientKey], where direction is up, down, left or right. Respawn enemies must use the [layer]_[objectId]_[direction] form (the layer is the object layer name), because every spawned instance gets its own generated client key.
  • AnimationData (required) - JSON animation configuration: start and end frames, frameRate, repeat (-1 loops forever), hideOnComplete, and an optional asset_key to take the frames from another asset of the object (by default the object asset is used).

Example AnimationData for a looping walk cycle:

{
  "start": 0,
  "end": 3,
  "frameRate": 8,
  "repeat": -1
}

Spritesheet Layout

Object spritesheets follow the same directional convention as player sprites, but you have full control over which frames map to which animation. There is no enforced layout - any frame range can be assigned to any animation key.

A typical enemy spritesheet might use:

  • Frames 0-3: Walk down
  • Frames 4-7: Walk left
  • Frames 8-11: Walk right
  • Frames 12-15: Walk up
  • Frames 16-19: Attack
  • Frames 20-21: Death

Multiple Assets Per Object

An object can have multiple assets. This is useful when an object uses different spritesheets for different states (e.g. a separate death animation sheet): every spritesheet asset of the room objects is preloaded, and an animation can point to any of them with asset_key. A respawn enemy always takes its main sprite from its first asset.

Code integration (advanced)

  • ObjectsManager.prepareAssetsPreload() (lib/objects/server/manager.js) collects the objects_assets rows of the room objects into roomData.preloadAssets, and enrichWithMultipleAnimationsData() maps the objects_animations rows by animationKey.
  • For respawn objects, RoomRespawn (lib/respawn/server/room-respawn.js) sets the client asset_key to the first asset key and passes the animations to the client.
  • ScenePreloader.preloadValidAssets() (lib/game/client/scene-preloader.js) loads every spritesheet asset from /assets/custom/sprites/[asset_file] with the parsed extra_params.
  • AnimationEngine.createObjectAnimations() (lib/objects/client/animation-engine.js) creates the Phaser animations, and ObjectAnimationFactory.fetchAvailableAnimationKey() (lib/objects/client/object-animation-factory.js) picks the animation by direction.

Related Documentation

Go Up