Skills Importer

The skills importer lets you bulk-create or update skills from a single JSON file. It handles the full skill data structure including attack configuration, effects, conditions, animations, class path assignments, and NPC associations.

Run the importer in the admin panel

  1. Log in to the administration panel at /reldens-admin.
  2. Open Wizards > Skills Import (/reldens-admin/skills-import).
  3. Click Set Sample Data in "Generator Data" to fill the Generator data textarea with a working example: the punch attack, the throwRock physical attack and the heal effect with its cast and hit animations, mana condition and effects. Click Check sample to read the same sample formatted in a read-only window.
  4. Edit the JSON for your game. The class path keys in classPathLevelRelations and the object keys in objectsRelations must already exist; the importer skips the ones it cannot find.
  5. Instead of pasting the JSON you can select files in JSON Files: they are saved in the generate-data/generated folder of your project and, when Generator data is empty, the first selected file is imported.
  6. 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.
  7. Open Skills > Skills (/reldens-admin/skills-skill) to check the imported skills; their attack properties, effects, conditions and animations are in the other Skills sections. Restart the server so the skills are loaded.
  8. To fine-tune one skill later, edit it in Skills > Skills or add a new one with Create New (/reldens-admin/skills-skill/edit). The importer is intended for bulk setup when configuring an entire skill tree or importing a complete skill set.
Admin Panel - Skills Import wizard with the sample buttons, JSON Files and Generator data Admin Panel - Skills list Admin Panel - Create new skill form

Configuration reference

Skills 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.
  • Generator data - Paste JSON into the textarea. If not empty, this takes precedence over uploaded files.
  • Import - Runs the import after a confirmation.

Import Modes

The options block controls what happens to existing skills:

  • removeAll: true - Deletes all existing skills and their related data before importing. Use with caution.
  • override: true - Deletes and recreates each skill that already exists by key.
  • update: true - Updates existing skills and their relations; skills that do not exist yet are created.
  • Default (all false) - Only creates new skills; skips any skill whose key already exists.

JSON Structure

A shortened version of the admin panel sample:

{
  "options": {
    "removeAll": false,
    "override": false,
    "update": true
  },
  "defaults": {
    "properties": {
      "skillDelay": 1500,
      "castTime": 0,
      "range": 0,
      "rangeAutomaticValidation": 1,
      "rangePropertyX": "state/x",
      "rangePropertyY": "state/y",
      "allowSelfTarget": 0,
      "criticalChance": 0,
      "criticalMultiplier": 1
    },
    "animations": {
      "appendSkillKeyOnAnimationImage": true,
      "defaults": {"enabled": true, "type": "spritesheet", "frameWidth": 64, "frameHeight": 70, "start": 0},
      "cast": {"img": "_cast", "end": 3, "repeat": -1, "destroyTime": 2000, "depthByPlayer": "above"},
      "hit": {"img": "_hit", "end": 4, "repeat": 0, "depthByPlayer": "above"}
    },
    "attack": {
      "affectedProperty": "stats/hp",
      "attackProperties": "stats/atk,stats/stamina,stats/speed",
      "defenseProperties": "stats/def,stats/stamina,stats/speed",
      "aimProperties": "stats/aim",
      "dodgeProperties": "stats/dodge"
    }
  },
  "skills": {
    "punch": {
      "classPathLevelRelations": {"all": "1"},
      "objectsRelations": {"enemy_1": "player"},
      "properties": {"skillDelay": 1000, "range": 50, "criticalChance": 10, "criticalMultiplier": 2},
      "typeData": {"key": "attack", "properties": {"hitDamage": 3}}
    },
    "heal": {
      "classPathLevelRelations": {"sorcerer": "3"},
      "properties": {"skillDelay": 1500, "allowSelfTarget": 1, "castTime": 2000},
      "typeData": {"key": "effect"},
      "animations": {"cast": {}, "hit": {}},
      "ownerConditions": [
        {"key": "available_mp", "propertyKey": "stats/mp", "conditional": "ge", "value": 2}
      ],
      "ownerEffects": [
        {"key": "dec_mp", "propertyKey": "stats/mp", "operationKey": "2", "value": 2}
      ],
      "targetEffects": [
        {"key": "heal", "propertyKey": "stats/hp", "operationKey": "1", "value": 5, "maxProperty": "statsBase/hp"}
      ]
    }
  }
}

Skill Properties

Each key in the skills object is the skill key. The value can include:

  • properties - Base skill fields merged over defaults.properties: autoValidation, skillDelay, castTime, usesLimit, range, rangeAutomaticValidation, rangePropertyX, rangePropertyY, rangeTargetPropertyX, rangeTargetPropertyY, allowSelfTarget, criticalChance, criticalMultiplier, criticalFixedValue and customData.
  • typeData.key (required) - Skill type: base, attack, effect, physical_attack, or physical_effect (the keys listed in Skills > Skill Types)
  • typeData.properties - Type properties merged over the defaults block named like the type; for attack skills they are merged over defaults.attack and saved as the skill Attack Properties (hitDamage, affectedProperty, attackProperties, defenseProperties, etc.)
  • physicalData - Physics properties for projectile-based skills, merged over defaults.physicalData: magnitude, objectWidth, objectHeight, validateTargetOnHit
  • targetEffects - Modifier operations applied to the target on hit: key, propertyKey, operationKey, value and optional minValue, maxValue, minProperty, maxProperty, merged over defaults.targetEffects
  • ownerEffects - Modifier operations applied to the skill owner on use, same fields as targetEffects, merged over defaults.ownerEffects
  • ownerConditions - Conditions checked before allowing skill use: key, propertyKey, conditional, value
  • animations - Object keyed by animation key (cast, bullet, hit); each one is merged over defaults.animations.defaults and defaults.animations[key]. With appendSkillKeyOnAnimationImage the skill key is prepended to img (heal + _cast = heal_cast). See Skill Sprites and Animations for the options and the sprite files.
  • classPathLevelRelations - Class path key (or all for every class path) to the level that unlocks the skill. The value selects the level by its position in the levels of the class path levels set, starting at 0.
  • objectsRelations - NPC/object associations: the key is the object_class_key of an existing object and the value is a target option key (player or object)
  • clearPrevious - Array with any of targetEffects, ownerEffects, ownerConditions and animations; the existing rows of those relations are deleted before the new ones are created on update

Effects and Conditions

The operationKey of the effects is a key of the operation_types table (Settings > Operation Types):

  • 1 - Increment
  • 2 - Decrease
  • 3 - Divide
  • 4 - Multiply
  • 5 - Increment Percentage
  • 6 - Decrease Percentage
  • 7 - Set
  • 8 - Method
  • 9 - Set Number

Condition conditional values: eq, ne, lt, gt, le, ge (equal, not equal, lower, greater, lower or equal, greater or equal).

Database Tables Modified

  • skills_skill - Main skill record
  • skills_skill_attack - Attack configuration (1:1)
  • skills_skill_physical_data - Physics properties (1:1)
  • skills_skill_animations - Animation definitions
  • skills_skill_target_effects - Effects on targets
  • skills_skill_owner_effects - Effects on the skill owner
  • skills_skill_owner_conditions - Use conditions
  • skills_class_path_level_skills - Class path / level unlock mapping
  • objects_skills - NPC skill assignments

Example File

A complete skills JSON example is available at:

https://cdn.reldens.com/assets/examples/generate-data/skills.json

Code integration (advanced)

CLI Usage

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

Where:

  • {theme} - Your project theme name (e.g. my-game)
  • {json-file} - Path to the skills JSON file (e.g. generate-data/skills.json)

Example:

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

Classes

  • SkillsImporter (lib/import/server/skills-importer.js) runs the import for both the CLI and the admin panel, and SkillDataFactory.mapData() (lib/actions/factories/skill-data-factory.js) merges the defaults into each skill.
  • SkillsImporterSubscriber (lib/admin/server/subscribers/skills-importer-subscriber.js) adds the Skills Import wizard and its /skills-import routes; the page template is theme/admin/templates/skills-import.html and the sample data is built in theme/admin/js/skills-sample-data-import.js.

Related Documentation

Go Up