Custom Races

Custom races are playable races you add to DragonMineZ with config files alone. No Java code or add-on jar is needed: a folder with a few JSON files defines the race's look, its classes, its racial skill and its transformations, and the race then shows up in character creation.

How DragonMineZ finds races

DragonMineZ loads its built-in races first (human, saiyan, namekian, frostdemon, bioandroid, majin, glind), then scans the subfolders of config/dragonminez/races/. Any other folder name there is treated as a custom race key (use lowercase). Each race folder holds:

config/dragonminez/races/<race_key>/
  character.json      # appearance, model, racial skill, form skill prices
  stats.json          # per-class base stats and scaling
  forms/*.json        # the race's transformation groups

If you create an empty folder, DragonMineZ generates a character.json and a stats.json with neutral defaults the next time configs load. It does not generate any forms for a custom race: you add those yourself (see step 3).

For a good starting point, copy an existing race folder (for example races/saiyan/), rename it and tune the values inside.

Source: src/main/java/com/dragonminez/common/config/ConfigManager.java (loadAllRaces, createOrLoadRace).

Config version Every file carries a "configVersion" string (currently "2.2.0"). A custom file with an older or missing version is backed up to config/dragonminez/oldBackup/ and saved again with the current version; your values are kept. A file with broken JSON syntax is never overwritten: it is reported and skipped until you fix it. See How to JSON and Reloading and Updating Changes.

Step 1: Configure the character

character.json sets the race's appearance, model, racial skill and form skill prices:

{
  "configVersion": "2.2.0",
  "hasGender": false,
  "useVanillaSkin": false,
  "customModel": "saibaman",
  "isLayered": true,
  "headBones": ["ears1"],
  "racialSkill": "namekian",
  "hasSaiyanTail": false,
  "auraType": "kakarot",
  "auraType3D": "userPreference",
  "defaultModelScaling": [0.9375, 0.9375, 0.9375],
  "defaultBodyType": 0,
  "slimBodyTypes": [],
  "defaultHairType": 0,
  "defaultEyesType": 0,
  "defaultNoseType": 0,
  "defaultMouthType": 0,
  "defaultTattooType": 0,
  "defaultBodyColor": "#3E8E2E",
  "defaultBodyColor2": "#2A5C20",
  "defaultBodyColor3": "#9BD36A",
  "defaultHairColor": "#222629",
  "defaultEye1Color": "#B40000",
  "defaultEye2Color": "#B40000",
  "defaultAuraColor": "#7FFF00",
  "formSkillsCosts": {
    "superforms": { "buyFromMaster": false, "prices": [20000, 45000, 80000] },
    "godforms": { "buyFromMaster": false, "prices": [] },
    "legendaryforms": { "buyFromMaster": false, "prices": [] }
  }
}

Field	Type	What it does
hasGender	Boolean	true gives the race a male/female choice. Custom models and textures then use _male / _female suffixes (see Custom Models and Assets).
useVanillaSkin	Boolean	When true, body type 0 renders the player's own Minecraft skin; the race's own body textures start at body type 1.
customModel	String	Model key. Empty means the race looks like a Human. A built-in key (for example namekian, majin or frostdemon) reuses that model and its textures; any other key loads your own model. The built-in keys are listed on Custom Models and Assets.
isLayered	Boolean	true: the body is drawn from three tintable texture layers (body colors 1, 2 and 3) and the race uses its own face textures. false: one plain body texture and borrowed Human faces. Any body texture can have an optional <texture>_shadow.png mask next to it (for example ..._layer1_shadow.png next to ..._layer1.png): it is drawn in a shadow tone of that texture's body color (same hue, shifted saturation), so the shading follows the colors the player picks.
headBones	List of strings	Bone names the player can choose from in character customization (one at a time, plus a "none" option), for example ears, horns or antennas. Join bones with + to show several at once ("ears1+horns2"). The special entry "hair" enables the hair editor for the race. Bones are looked up in geo/entity/raceparts.geo.json first, then in the race model.
racialSkill	String	Which racial skill the race uses: human, saiyan, namekian, frostdemon, bioandroid, majin or glind. A custom race uses the same tuning as the race it borrows from (general-server.json → racialSkills.<skill>). See Racial Skills.
hasSaiyanTail	Boolean	Gives the race a Saiyan tail. Hiding and showing it plays the same animation as for Saiyans, which wraps the tail around the waist.
auraType	String	2D aura sprite set: kakarot or god.
auraType3D	String	3D aura style of the base form: smooth, sparking, god or userPreference (follows each player's own setting).
aura3DStyle	Object	Fine-tuning of the base 3D aura shape. The keys are listed on Custom Forms.
defaultModelScaling	[x, y, z]	Base model size.
defaultBodyType	Integer	Body type selected by default in character creation.
slimBodyTypes	List of integers	Body types (other than 0) that use slim arms. Body type 0 always follows the player's skin model.
defaultHairType, defaultEyesType, defaultNoseType, defaultMouthType, defaultTattooType	Integer	Default customization indices.
defaultBodyColor, defaultBodyColor2, defaultBodyColor3, defaultHairColor, defaultEye1Color, defaultEye2Color, defaultAuraColor	Hex string	Default colors in character creation.
formSkillsCosts	Object	One entry per form skill the race can level (see below).

Schema source: src/main/java/com/dragonminez/common/config/RaceCharacterConfig.java.

Resource packs In 2.2 the built-in humansaiyan body shading textures were renamed from bodytype_*_layer2.png to bodytype_*_layer1_shadow.png (in textures/entity/races/humansaiyan/). A resource pack that replaced the old files must rename them.

Form skill prices

Each key of formSkillsCosts is a form skill: superforms, legendaryforms, godforms or androidforms. The value is either a plain array of prices or an object with these fields:

Field	Type	What it does
prices	List of numbers	TP price of each level, in order. The number of entries is the skill's maximum level, so an empty list means the race cannot level that skill.
buyFromMaster	Boolean	true: the first level has to be bought from a master before the skill can be leveled from the Skills menu.

A form unlocks when this skill reaches the form's unlockOnSkillLevel (see step 3).

Android upgrade for custom races

Dr. Gero's android upgrade is offered to any race whose formSkillsCosts has at least one price under androidforms (by default only Humans). The upgrade puts the player into the androidbase form of the androidforms group, so the race also needs an androidforms form group in its forms/ folder. The easiest way is to copy races/human/forms/androidforms.json into your race's forms/ folder. See Android for the upgrade itself.

Step 2: Configure the classes

stats.json holds a classes object with one block per class. DragonMineZ generates the eight default classes: warrior, spiritualist, martialartist, berserker, paladin, tank, cleric and unversed (see Classes). You can add your own class by duplicating a block under a new key; it shows up in character creation for that race. A player whose class isn't in the race's file uses the warrior values.

Inside each class block:

Field	Type	What it does
baseStats	Object	Starting stats: STR, SKP, RES, VIT, PWR, ENE.
statScaling	Object	STR_scaling, SKP_scaling, STM_scaling, DEF_scaling, VIT_scaling, PWR_scaling, ENE_scaling. The optional VIT_scaling_max and DEF_scaling_max make the scaling grow from the normal value towards this maximum as the stat rises (up to the curve knee set in general-server.json); leave them out for flat scaling.
baseHp5, hp5VitScaling	Number	Health regenerated every 5 seconds, plus a share of VIT.
baseEp5, ep5EneScaling	Number	Ki regenerated every 5 seconds, plus a share of ENE.
baseSp5, sp5StmScaling, sp5ResScaling	Number	Stamina regenerated every 5 seconds, plus a share of VIT (sp5StmScaling, despite its name) and a share of RES (sp5ResScaling, 0 when missing).
tpCostMultiplier, tpGainMultiplier	Number	Class-wide multipliers on TP costs and TP gains.
passive	Object	enabled plus a values map with the tuning of the class passive (the keys depend on the class).

Schema source: src/main/java/com/dragonminez/common/config/RaceStatsConfig.java. See Stats and Attributes for what each stat does.

Step 3: Add form groups

Main article: Custom Forms

Each file in races/<race_key>/forms/ defines one form group. Race forms use exactly the same schema as stack forms, so the full field reference is on Custom Forms. The fields that matter most for a race group are:

• groupName: the group key (lowercase). Groups are identified by this value, not by the filename.
• formType: the form skill that unlocks the group: superforms, legendaryforms, godforms or androidforms. The race needs prices for that skill in formSkillsCosts.
• forms: the forms of the group, in transformation order. Each form's unlockOnSkillLevel is the skill level that unlocks it.
• customModel: a model key for the form (looked up the same way as the race's customModel).

Files whose name starts with old_ are ignored. See Transformations for how forms work in game.

Step 4: Add translation keys

Race and form names are translated with these keys:

• race.dragonminez.<race_key>: the name of the race.
• race.dragonminez.<race_key>.desc: a short description shown in character creation.
• race.dragonminez.<race_key>.group.<group_key>: the name of a form group.
• race.dragonminez.<race_key>.form.<group_key>.<form_key>: the name of a form.

The default language file is src/main/resources/assets/dragonminez/lang/en_us.json. Feel free to edit your en_us.json or create a new language file for your custom race. You don't need to add translation keys for anything else: DragonMineZ automatically merges the translations already made on Crowdin with your own.

Step 5: Reload and validate

1. Save your JSON files.
2. Run /dmzreload config (see Reloading and Updating Changes).
3. Open character creation and check that your race appears.
4. Check its forms, colors and scaling in game.

Modding

Basics

How to JSON · Locating Specific Folders

Characters and forms

Custom Races · Custom Forms · Custom Models and Assets

Story and NPCs

Custom Quests · Custom Wishes · NPC Placement and Alignment · NPC Dialogue

Datapacks

Space Pod Destinations · Weapon Attributes

Related

Add-on Development · Configuration · Reloading and Updating Changes