Objects Importer

The objects importer bulk-creates game objects (NPCs, enemies, interactables) from a JSON payload. For each object, one database record is created per target room, with all related assets, animations, stats, respawn configuration, and experience rewards inserted in a single operation.

Run the importer in the admin panel

  1. Log in to the administration panel at /reldens-admin.
  2. Open Wizards > Objects Import (/reldens-admin/objects-import).
  3. Click Set Sample Data in "Generator Data" to fill the Generator data textarea with a complete working example: two forest enemies (enemy_forest_1 and enemy_forest_2) with their spritesheet asset, stats and respawn settings. Click Check sample to read the same sample formatted in a read-only window.
  4. Edit the JSON for your game. The sample places the enemies in the rooms bots-001 to bots-050: objects are only created in rooms that exist, so change roomsNames to your room names. The stats keys must exist in Users > Stats.
  5. Instead of pasting the JSON you can select files in JSON Files. The uploaded files are saved in the generate-data/generated folder of your project and, when Generator data is empty, the first selected file is imported. When Generator data is not empty it is used instead of the files.
  6. To use the generators output, select the generated files in JSON Files (they are stored in generate-data/generated), paste the objects JSON in Generator data and point attributesPerLevelFile and experiencePerLevelFile to generated/[file-name].json. Files uploaded before stay in that folder, so they do not need to be uploaded again.
  7. The assetFile images must exist in your theme assets/custom/sprites folder and be copied to the dist folder (Control Panel > Copy Assets to Dist), see Object Sprites and Assets. The sample uses monster-treant.png and monster-golem2.png from the default theme.
  8. Click Import and confirm. The page shows the result: an error message when the JSON files are missing, the data is invalid or the import fails.
  9. Check the created records in Game Objects > Objects, Game Objects > Assets, Respawn and Rewards, then restart the server so the rooms load the new objects.
Admin Panel - Objects Import wizard with the sample buttons, JSON Files and Generator data Admin Panel - Objects Import with the sample data set in Generator data

Configuration reference

Objects Import form

  • Set Sample Data in "Generator Data" - Fills the textarea with the sample JSON.
  • Check sample - Opens the sample JSON formatted, read only.
  • JSON Files - Upload one or more JSON files, saved in generate-data/generated. Only the first file is imported, the others stay available as referenced files.
  • Generator data - Paste JSON into the textarea. If not empty, this takes precedence over uploaded files.
  • Import - Runs the import after a confirmation.

JSON Structure

{
  "objects": [...],
  "defaults": {...},
  "attributesPerLevelFile": "generated/attributes-per-level.json",
  "experiencePerLevelFile": "generated/monsters-experience-per-level.json"
}
  • objects - Array of object definitions
  • defaults - Values merged into every object; useful for shared settings like classType, layer, roomsNames, or respawn
  • attributesPerLevelFile - Optional path, relative to the project generate-data folder, to output from the Attributes Per Level generator; auto-populates stats using level, attributesKey (the variation) and attributesSubTypeKey (the type)
  • experiencePerLevelFile - Optional path, relative to the project generate-data folder, to output from the Enemies Experience Per Level generator; auto-populates experience rewards using level and experienceKey (the variation)

Object Properties

Each entry in objects is mapped to the Objects entity fields: layer, tileIndex, classType (an object type key such as multiple, or its ID), clientKey, title, privateParams, clientParams and enabled. Fields specific to the importer:

  • roomsNames - Array of room names; one object record is created per room. Alternative: roomsId for room IDs
  • clientKey - Builds object_class_key automatically as {roomName}_{clientKey}
  • assets - Array of assets, each with assetType (default spritesheet), assetKey, assetFile and extraParams; see Object Sprites and Assets
  • stats - Plain object of stat key to value pairs; keys must match entries in the stats table
  • animations - Object keyed by animation name; stored as {layer}_{objectId}_{animationName}
  • respawn - Respawn config object; see Respawn Areas for field reference
  • experience - Set by the importer from experiencePerLevelFile; a value written directly in the object data is replaced, so the experience reward is only created when that file is provided
  • level, attributesKey, attributesSubTypeKey, experienceKey - Enrichment lookup keys; only used when the corresponding generator file is provided

What Gets Created

For each object x room combination, the importer writes to: objects, objects_assets, objects_animations, objects_stats, respawn, and rewards.

Code integration (advanced)

CLI Usage

npx reldens-import objects {theme} {json-file}

Example:

npx reldens-import objects my-game generate-data/objects.json

Classes

  • ObjectsImporter (lib/import/server/objects-importer.js) runs the import for both the CLI and the admin panel: import(data) merges defaults into each object, applies the generator files and creates the records per room.
  • ObjectsImporterSubscriber (lib/admin/server/subscribers/objects-importer-subscriber.js) adds the Objects Import wizard, the /objects-import routes and the upload to generate-data/generated; the page template is theme/admin/templates/objects-import.html and the sample data is built in theme/admin/js/objects-import-bindings.js.

Related Documentation

Go Up