Mindustry Modding Guide
Modding documentation for Mindustry v104 (0cbd9a1fc)

Your project directory should look something like this:

project
├── mod.json
├── content
│   ├── items
│   ├── blocks
│   ├── mechs
│   ├── liquids
│   ├── units
│   └── zones
├── maps
├── bundles
├── sounds
├── schematics
├── scripts
├── sprites-override
└── sprites

• mod.json (required) metadata file for your mod,
• content/* directories for game Content,
• maps/ directory for Zone maps,
• bundles/ directory for Bundles,
• sounds/ directory for Sound files,
• schematics/ directory for Schematic files,
• scripts/ directory for Scripts,
• sprites-override/ Sprites directory for overriding ingame content,
• sprites/ Sprites directory for your content,

Every platform has a different user application data directory, and this is where your mods should be placed:

• Linux: ~/.local/share/Mindustry/mods/
• Steam: steam/steamapps/common/Mindustry/mods/
• Windows: %appdata%/Mindustry/mods/
• Apple: ~/Library/Application Support/Mindustry/mods/

Note that your filenames should be lowercased and hyphen separated:

• correct: my-custom-block.json
• incorrect: My Custom Block.json

Mindustry uses Hjson, which for anyone who knows Json, is simply a superset of the very popular serialization language known as Json. – This means that any valid Json will work, but you get extra useful stuff:

# single line comment

// single line comment

/* multiline
comment */

key1: single line string

key2:
'''
multiline
string
'''

key3: [ value 1
        value 2
        value 3 ]

key4: { key1: string
        key2: 0 }

If you don't know any of those words. – A serialization language, is simply a language which encodes information for a program, and encode means to translate informantion from one form to another, and in this case, to translate text into Java data structures.

At the root of your project directory, you must have a mod.json which defines the basic metadata for your project. This file can also be (optionally) named mod.hjson to potentially help your text editor pick better syntax highlighting.

name: Mod Name
displayName: Mod [red]Name[]
author: Yourself
description: This is a useless description.
version: "1.0"
minGameVersion: "100.3"
dependencies: [ ]

• name will be used to reference to your mod, so name it carefully;
• displayName this will be used as a display name for the UI, which you can use to add formatting to said name;
• description of the mod will be rendered in the ingame mod manager, so keep it short and to the point;
• dependencies is optional, if you want to know more about that, go to the dependencies section;
• minGameVersion is the minimum build version of the game.

At the root of your project directory you can have a content/ directory, and this is where all the Json/Hjson data goes. Inside of content/ you have subdirectories for the various kinds of content, these are the current common ones:

• content/items/ for items, like copper and surge-alloy;
• content/blocks/ for blocks, like turrets and floors;
• content/mechs/ for mechs, like tau and glaive;
• content/liquids/ for liquids, like water and slag;
• content/units/ for flying or ground units, like reaper and dagger;
• content/zones/ for zones, configuration of campaign maps.

Note that each one of these subdirectories needs a specific content type. The filenames of these files is important, because the stem name of your path (filename without the extension) is used to reference it.

Furthermore the files within theseb content/<content-type>/* directories may be arbitrarly nested into other sub-directories of any name, to help you organize them further, for example:

• content/items/metals/iron.hjson, which would respectively create an item named iron.

The content of these files will tend to look something like this:

type: TypeOfThing
name: Name Of Thing
description: Description of thing.
# ... more fields here ...

Other fields included will be the fields of the type itself.

Types have numerous fields, but the important one is type; this is a special field used by the content parser, that changes which type your object is. A Router type can't be a Turret type, as they're just completely different.

Types extend each other, so if MissileBulletType extends BasicBulletType, you'll have access to all the fields of BasicBulletType inside of MissileBulletType like damage, lifetime and speed. Fields are case sensitive: hitSize =/= hitsize.

What you can expect a field to do is up to the specific type, some types do absolutely nothing with their fields, and work mostly as a base types will extend from. One such type is Block.

type can be refer to the actual type field of the object. A type may also refer to other things like float is a type so it means you can type 0.3 in a field.

Here you can see, the type of the top level object is Revenant, but the type of the bullet is BulletType so you can use MissileBulletType, because MissileBulletType extends BulletType.

type: Revenant
weapon: {
  bullet: {
    type: MissileBulletType
    damage: 9000
  }
}

Much like type there exist another magical field known as research which can go at the root of any block object to put it in the techtree.

research: duo

This would put your block after duo in the techtree, and to put it after your own mods block you would write your <block-name>, a mod name prefix is only required if you're using the content from another mod.

Research cost will be 40 + round(requirements ^ 1.25) * 6 rounded down to the nearest 10, where requirements is the build cost of your block. (in otherwords you can't set requirements and research cost individually)

All you need to make sprites, is an image editor that supports transparency (aka: not paint). Block sprites should be 32 * size, so a 2x2 block would require a 64x64 image. Images must be .png files with 32 bit depth.

Sprites can simply be dropped in the sprites/ subdirectory. The content parser will look through it recursively, so you can organize them how ever you feel.

Content is going to look for sprites relative to it's own name. content/blocks/my-hail.json has the name my-hail and similarly sprites/my-hail.png has the name my-hail, so it'll be used by this content.

Content may look for multiple sprites. my-hail could be a turret, and it could look for the suffix <name>-heat and what this means is it'll look for my-hail-heat.

You can find all the vanilla sprites here:

• https://github.com/Anuken/Mindustry/tree/master/core/assets-raw/sprites

Another thing to know about sprites is that some of them are modified by the game. Turrets specifically have a black border added to them, so you must account for that while making your sprites, leaving transparent space around turrets for example: Ripple

To override ingame content sprites, you can simply put them in sprites-override/.

Custom sounds can be added through the modding system by dropping them in the sounds/ subdirectory. It doesn't matter where you put them. Two formats are needed:

• .ogg required for Desktop/Android
• .mp3 required for iOS

Just like any other assets, you reference them by the stem of your filenames, so pewpew.ogg and pewpew.mp3 can be referenced with pewpew from a field of type Sound.

Here's a list of built-in sounds:

• artillery
• back
• bang
• beam
• bigshot
• boom
• break
• build
• buttonClick
• click
• conveyor
• corexplode
• door
• drill
• empty
• explosionbig
• explosion
• fire
• flame2
• flame
• laserbig
• laser
• machine
• message
• missile
• pew
• place
• press
• release
• respawning
• respawn
• shootBig
• shoot
• shootSnap
• shotgun
• spark
• splash
• spray
• thruster
• unlock
• wave
• windowHide

You can add dependencies to your mod by simple adding other mods name in your mod.json:

dependencies: [
  other-mod-name
  not-a-mod
]

The name of dependencies are lower-cased and spaces are replaced with - hyphens, for example Other MOD NamE becomes other-mod-name.

To reference the other mods assets, you must prefix the asset with the other mods name:

• other-mod-name-not-copper would reference not-copper in other-mod-name
• other-mod-name-angry-dagger would reference angry-dagger in other-mod-name
• not-a-mod-angry-dagger would reference angry-dagger in not-a-mod

An optional addition to your mod is called bundles. The main use of bundles are give translations of your content, but there's no reason you couldn't use them in English. These are plaintext files which go in the bundles/ subdirectory, and they should be named something like bundle_ru.properties (for Russian).

The contents of this file is very simple:

block.example-mod-silver-wall.name = Серебряная Стена
block.example-mod-silver-wall.description = Стена из серебра.

If you've read the first few sections of this guide, you'll spot it right away:

• <content type>.<mod name>-<content name>.name
• <content type>.<mod name>-<content name>.description

Notes:

• mod/content names are lowercased and hyphen separated.

List of content type:

• item
• block
• mech
• bullet
• liquid
• status
• unit
• weather
• effect
• zone
• loadout
• typeid

List of filenames relative to languages:

• English bundle.properties
• Czech bundle_cs.properties
• German bundle_de.properties
• Spanish bundle_es.properties
• Estonian bundle_et.properties
• Basque bundle_eu.properties
• French BE bundle_fr_BE.properties
• French bundle_fr.properties
• Bergabung bundle_in_ID.properties
• Italian bundle_it.properties
• Japanese bundle_ja.properties
• Korean bundle_ko.properties
• Dutch BE bundle_nl_BE.properties
• Dutch bundle_nl.properties
• Polish bundle_pl.properties
• Portuguese BR bundle_pt_BR.properties
• Portuguese bundle_pt.properties
• Russian bundle_ru.properties
• Danish bundle_sv.properties
• Turkman bundle_tk.properties
• Turkish bundle_tr.properties
• Ukrainian bundle_uk_UA.properties
• Chinese CN bundle_zh_CN.properties
• Chinese TW bundle_zh_TW.properties

The text renderer uses a simple makeup language for coloring text.

• [name] sets the color by name, there's a few built-in colors;
• [#rrggbb] / [#rrggbbaa] sets the color by hex value, with each value being anything from 00 to ff:
  • rr is the red value,
  • gg is the green value,
  • bb is the blue value,
  • aa is the alpha value;
• [] sets the color back to the previous color;
• [[ escapes the left bracket, so you can write [[red] to write and it'll render as [red].

Notes:

• erros/unknown colors will be silently ignored.

Example:

[red]red
[#ff0000]full-red
[#ff000066]half-red
[#ff000033]half-half-red
[#00ff00]green
[]half-half-red

Fields that require the type Schematic can either take a built-in loadout (see the Zone section) a base64 string, or the stem name of a .msch file in the schematics/ subdirectory.

As of now, the only purpose of schematics is to give a zone a loadout.

Scripting in Mindustry is done with the Rhino JavaScript runtime. Scripts may be added to your mod by putting them in scripts/. Using the built-in extendContent function, you can extend existing Java types from JS, using allowed classes which are injected into your namespace.

For example:

• scripts/silo.js

  // create a simple shockwave effect
  const siloLaunchEffect = newEffect(20, e => {
  
      // color goes from white to light gray
      Draw.color(Color.white, Color.lightGray, e.fin());
  
      // line thickness goes from 3 to 0
      Lines.stroke(e.fout() * 3);
  
      // draw a circle whose radius goes from 0 to 100
      Lines.circle(e.x, e.y, e.fin() * 100);
  });
  
  // create the block type
  const silo = extendContent(Block, "scatter-silo", {
  
      // override the method to build configuration
      buildConfiguration(tile, table) {
          table.addImageButton(
              Icon.arrowUpSmall,
              Styles.clearTransi,
  
              // configure the tile to signal that it has been
              // pressed (this sync on client to server)
              run(() => tile.configure(0))
          ).size(50);
      },
  
      // override configure event
      configured(tile, value) {
  
          // make sure this silo has the items it needs to fire
          if (tile.entity.cons.valid()) {
  
              // make this effect occur at the tile location
              Effects.effect(siloLaunchEffect, tile);
  
              // create 10 bullets at this tile's location with
              // random rotation and velocity/lifetime
              for (var i = 0; i < 10; i++) {
                  Calls.createBullet(
                      Bullets.flakExplosive,
                      tile.getTeam(),
                      tile.drawx(),
                      tile.drawy(),
                      Mathf.random(360),
                      Mathf.random(0.5, 1.0),
                      Mathf.random(0.2, 1.0)
                  );
              }
  
              // triggering consumption makes it use up the
              // items it requires
              tile.entity.cons.trigger();
          }
      }
  });
  

• content/blocks/scatter-silo.hjson

  localizedName: "Scatter Silo"
  description: "A player-activatable block that scatters bullets everywhere upon use."
  
  category: turret
  size: 2
  
  update: true
  solid: true
  hasItems: true
  configurable: true
  
  requirements: [ "graphite/75"
                  "titanium/30" ]
  
  consumes: { items: { items: [ "scrap/10" ] } }
  

More examples:

• entity-lib

Once you have a mod of some kind, you'll want to actually share it, and you may even want to work with other people on it, and to do that you can use GitHub. If you don't know what Git (or GitHub) is at all, then you should look into GitHub Desktop, otherwise simply use your favorite command line tool or text editor plugin.

All you need understand is how to open repositories on GitHub, stage and commit changes in your local repository, and push changes to the GitHub repository. Once your project is on GitHub, there are three ways to share it:

• with the endpoint, for example Anuken/ExampleMod, which could then be typed in the ingame GitHub interface, and that would download it;
• with the zip file, for example https://github.com/Anuken/ExampleMod/archive/master.zip, which would download the repository as a zip file, and put in mod directory (unzipping is not required);
• add the typic/tags mindustry-mod on your repository, which should cause the #mods Discord bot to pick it up and render it in it's listh.

• time in game is calculated through ticks;
• ticks sometimes called frames, are assumed to be 60/1 second;
• tilesize is 8 units internally;
• to calculate range out of lifetime and speed you can do lifetime * speed = range;
• Abstract what is abstract? all you need to know about abstract types, is this is a Java specific term, which means you cannot instantiate/initialize this specific type by itself. If you do so you'll probably get an "initialization exception" of some kind;
• what is a NullPointerException? This is an error message that indicates a field is null and shouldn't be null, meaning one of the required fields may be missing;
• bleeding-edge what is bleeding-edge? This is the developer version of Mindustry, specifically it's refering to the Github master branch. Changes on bleeding-edge usually make it into Mindustry in the next release.

This is a log of changes done on the Mindustry Master branch that affected the modding API. The sections are ordered by date commited, and provide a description of what was changed, with a link to the diff on Github.

Extends BlockStorage

Block is the base type of all blocks in the game. All blocks have at least one sprite, which is picked relative to the blocks name.

Fields for all objects that are blocks.

Sprites:

• <name> the main sprite for the block.

This type is commonly used in block type with it's field consumes, it's a type that allows your block to consume something, and how this field works is up to the specific type extension you're using.

Notes:

• you shouldn't have power and powerBuffered.

For example with ConsumeItems and ConsumeLiquid:

items: {
  items: [
    copper/10
    surge-alloy/5
  ]
  booster: true
  optional: true
}
liquid: {
  water/1.0
}

Abstract type which defines a type of resource that a block can consume.

Abstract type that extends Content

Type for blocks which may store a buffer of items or liquid.

Environmental blocks are blocks that must be placed from the editor, and they're the ones that will generally dictate how the game can or will be played. These blocks wont appear on a map unless you've built a map to support them.

This section is for turret types. All turrets shoot BulletType, and this means LiquidTurret can shoot MissileBulletType and ItemTurret can shoot LiquidBulletType.

An object with an array of attribute. Used in the Floor type to give a tile specific properties, like hottness or sporness for efficiency of various systems, like ThermalPumps and WaterExtractors.

array has 4 items:

• index 0 is heat,
• index 1 is spores,
• index 2 is water,

• index 3 is oil.

  For example, this would give you 100 heat, 1 spores, 0.5 water and 0.1 oil.

  {
      "array": [ 100, 1, 0.5, 0.1]
  }
  

  You could use it inside of Floor type as such:

  {
      "type": "Floor",
      "name": "magma",
      "attributes": { "array": [ 0.75, 0, 0, 0 ] }
  }
  

New attributes cannot be added. List of built-in attributes:

• heat
• spores
• water
• oil

A flag used by the game to change a few special-case things. It may be one of the following strings:

• hidden
• shown
• debugOnly
• sandboxOnly
• campaignOnly
• lightingOnly

Groups for blocks to build on top of each other:

• none
• walls
• turrets
• transportation
• power
• liquids
• drills

Extends Content – It's the object that can ride conveyors, sorters and be stored in containers, and is commonly used in crafters.

A ItemStack can be a string or an object. It's used to describe the type and amount of items to a machine.

As a string:

copper/5

As an object:

item: copper
amount: 5

Extends Content

Type which defines the properties of a liquid. Like Item this will go into it's own subdirectory content/liquids/liquid-name.json, and from it's stem name you can reuse it from your other mod content.

Sprites:

• <name>, the sprite used when displaying the liquid from a menu.

A LiquidStack can be a string or an object. It's used to describe the type and amount of liquid to a machine.

As a string:

water/0.5

As an object:

liquid: water
amount: 0.5

Weapons are used by units and mechs alike. A weapon is a type used to shoot bullets bullets just like turrets (except that they don't have an ammo mapping). Weapons can only shoot one type of bullet, which you define in the bullet field.

Sprite:

• <name> or <name>-equip

Extends Content

Sprites:

• <name>
• <name>-leg
• <name>-base

Extends Content

Mechs are the player controlled entities. They shoot bullets just like turrets from their weapon.

Sprites:

• <name>
• <name>-leg
• <name>-base

Categories for building menu:

• turret Offensive turrets;
• production Blocks that produce raw resources, such as drills;
• distribution Blocks that move items around;
• liquid Blocks that move liquids around;
• power Blocks that generate or transport power;
• defense Walls and other defensive structures;
• crafting Blocks that craft things;
• units Blocks that create units;
• upgrade Things that upgrade the player such as mech pads;
• effect Things for storage or passive effects.

Extends Content

A Zone is a type that takes a map (named the same as the json's filename) and puts it into campaign. (a zone isn't a map)

Every Zone has a Generator, which once initialized, MapGenerator will run through the map and do initialization related stuff. One of those notable things, is deleting all cores on in your map and placing a loadout on top of a random one of them. This allows your campaign map to have multiple core locations. (it doesn't matter which core was previously on the map, loadout will dictate that)

It is entirely possible to produce a custom schematic, but take note that this schematic must contain a CoreBlock within it.

Sprites:

• zone-<name> preview
• <name>-zone preview

Built-in loadouts:

• basicShard

  bXNjaAB4nD2K2wqAIBiD5ymibnoRn6YnEP1BwUMoBL19FuJ2sbFvUFgYZDaJsLeQrkinN9UJHImsNzlYE7WrIUastuSbnlKx2VJJt+8IQGGKdfO/8J5yrGJSMegLg+YUIA==
  

  

• advancedShard

  bXNjaAB4nD2LjQqAIAyET7OMIOhFfJqeYMxBgSkYCL199gu33fFtB4tOwUTaBCP5QpHFzwtl32DahBeKK1NwPq8hoOcUixwpY+CUxe3XIwBbB/pa6tadVCUP02hgHvp5vZq/0b7pBHPYFOQ=
  

  

• basicFoundation

  bXNjaAB4nD1OSQ6DMBBzFhVu8BG+0X8MQyoiJTNSukj8nlCi2Adbtg/GA4OBF8oB00rvyE/9ykafqOIw58A7SWRKy1ZiShhZ5RcOLZhYS1hefQ1gRIeptH9jq/qW2lvc1d2tgWsOfVX/tOwE86AYBA==
  

  

• basicNucleus

  bXNjaAB4nD2MUQqAIBBEJy0s6qOLdJXuYNtCgikYBd2+LNmdj308hkGHtkId7M4YFns4mk/yfB4a48602eDI+mlNznu0FMPFd0wYKCaewl8F0EOueqM+yKSLVfJrNKWnSw/FZGzEGXFG9sy/px4gEBW1
  

  

Built-in zones:

• nuclearComplexe
• desolateRift
• tarFields
• overgrowth
• stainedMountains
• frozenForest
• saltFlats
• desertWastes
• groundZero

Extends Content

Not be be confused with Effect, a status effect will give an entity special properties. Status effects are used as transitions between intermediate effects. If some a wet unit gets shocked it then gets 20 damage.

• opposites: effect which reduces anothers lifetime.

Built-in status effects:

• none – Does nothing.

• burning

  field	value
  damage	0.06
  effect	burning

  • opposites: wet freezing
  • tarred: 1 damage and keeps burning

• freezing

  field	value
  speedMultiplier	0.6
  armorMultiplier	0.8
  effect	freezing

  • opposites: melting burning

• wet

  field	value
  speedMultiplier	0.9
  effect	wet

  • opposites: burning
  • shocked: 20 damage

• melting

  field	value
  speedMultiplier	0.8
  armorMultiplier	0.8
  damage	0.3
  effect	melting

  • opposites: wet freezing
  • tarred: keeps melting

• tarred

  field	value
  speedMultiplier	0.6
  effect	oily

  • burning: keeps burning
  • melting: keeps burning

• overdrive

  field	value
  armorMultiplier	0.95
  speedMultiplier	1.15
  damageMultiplier	1.4
  damage	-0.01
  effect	overdriven

• shielded

  field	value
  armorMultiplier	3

• boss

  field	value
  armorMultiplier	3
  damageMultiplier	3
  speedMultiplier	1.1

• shocked – Does nothing.

• corroded

  field	value
  damage	0.1

Layers is an enumeration type, which the renderer will use to group rendering order:

• block, base block layer;
• placement, for placement;
• overlay, first overlay stuff like conveyor items;
• turret, "high" blocks like turrets;
• power power lasers

Color is a hexadecimal string, <rr><gg><bb> for example:

• ff0000 is red,
• 00ff00 is green,
• 0000ff is blue,
• ffff00 is yellow,
• 00ffff is cyan,
• ect..

Flags used by for cache render:

• normal normal layer;
• walls walls layer;
• water water layer, adding tile water shaders, and giving wave reflections;
• tar tar layer, adding tar shaders, making it darker and giving it some bubble reflections;

Abstract type which extends Content

BulletType can either be an object {} or a "string", where a string would be reusing Built-in Bullets and an object would be making a custom one.

There are two major categories of bullet types:

• BasicBulletType and,
• other special bullets.

Here's an example of a custom bullet:

{
    "type": "MissileBulletType",
    "lifetime": 1000,
    "speed": 2,
    "splashDamageRadius": 2,
    "splashDamage": 9,
    "frontColor": "ffff00",
    "backColor": "00ffff",
    "homingPower": 1,
    "homingRange": 20,
    "fragBullets": 3,
    "fragBullet": {
        "type": "LiquidBulletType",
        "liquid": "oil",
        "lifetime": 2,
        "speed": 1,
        "fragBullets": 2,
        "fragBullet": {
            "type": "LiquidBulletType",
            "liquid": "slag",
            "lifetime": 1,
            "speed": 2,
            "damage": 1,
        }
    }
}

There are a few useful base unit types:

• FlyingUnit
  • HoverUnit
  • BuilderDrone
  • MinerDrone
  • RepairDrone
• GroundUnit

Type should be a string. You can't currently create custom effects. List of built-in effects are as follows:

• none placeBlock breakBlock smoke spawn tapBlock select
• vtolHover unitDrop unitPickup unitLand pickup healWave heal landShock reactorsmoke nuclearsmoke nuclearcloud
• redgeneratespark generatespark fuelburn plasticburn pulverize pulverizeRed pulverizeRedder pulverizeSmall pulverizeMedium
• producesmoke smeltsmoke formsmoke blastsmoke lava doorclose dooropen dooropenlarge doorcloselarge purify purifyoil purifystone generate
• mine mineBig mineHuge smelt teleportActivate teleport teleportOut ripple bubble launch
• healBlock healBlockFull healWaveMend overdriveWave overdriveBlockFull shieldBreak hitBulletSmall hitFuse
• hitBulletBig hitFlameSmall hitLiquid hitLaser hitLancer hitMeltdown despawn flakExplosion blastExplosion
• plasticExplosion artilleryTrail incendTrail missileTrail absorb flakExplosionBig plasticExplosionFlak burning fire
• fireSmoke steam fireballsmoke ballfire freezing melting wet oily overdriven dropItem shockwave
• bigShockwave nuclearShockwave explosion blockExplosion blockExplosionSmoke shootSmall shootHeal shootSmallSmoke shootBig shootBig2 shootBigSmoke
• shootBigSmoke2 shootSmallFlame shootPyraFlame shootLiquid shellEjectSmall shellEjectMedium
• shellEjectBig lancerLaserShoot lancerLaserShootSmoke lancerLaserCharge lancerLaserChargeBegin lightningCharge lightningShoot
• unitSpawn spawnShockwave magmasmoke impactShockwave impactcloud impactsmoke dynamicExplosion padlaunch commandSend coreLand

A higher ordinal means a higher priority. Higher priority blocks will always get targeted over those of lower priority, regardless of distance.

1. base
2. turret