animdustry

Documentation

[!Warning] This is the legacy API. For new mods, use the new JavaScript API.

Folder structure

A mod is a folder containing files. This folder must be placed in the mods folder of the mod loader. The location of this folder depends on your operating system:

If the folder does not exist, you can create it, otherwise it will be created automatically on first startup of the mod loader.

The folder structure of a mod is as follows:

modfolder
├── mod.json
├── credits.txt
├── maps
│   └── exampleMap.json
├── music
│   └── exampleMusic.ogg
├── procedures
│   └── exampleProc.json
├── sprites
│   └── exampleSprite.png
├── units
│   └── exampleUnit.json
├── unitSplashes
│   └── exampleUnit.png
└── unitSprites
    ├── exampleUnit-angery.png
    ├── exampleUnit-happy.png
    ├── exampleUnit-hit.png
    └── exampleUnit.png

An example of a mod can be found here.

mod.json

A mod.json or mod.hjson file must be placed in the root folder of the mod. It is what tells the mod loader that this folder contains a mod. The content of the file is as follows:

{
    "name": "The name of your mod",
    "namespace": "example",
    "author": "You",
    "description": "Description of your mod",
    "enabled": true,
    "debug": false,
    "legacy": true
}

Custom Units

Unit scripts describe how a unit is drawn and how it interacts with the game. To define a unit, first place a JSON or Hjson file with the same name as your unit in the units folder. Its contents should look like this:

{
    "name": "exampleUnit",
    "title": "-EXAMPLE-",
    "subtitle": "lorem ipsum",
    "abilityDesc": "dolor sit amet",
    "abilityReload": 4,
    "unmoving": false,
    "draw": [
        {"type": "SetVec2", "name": "pos", "value": "basePos - vec2(0, 0.5) + _hoverOffset * 0.5"},
        {"type": "DrawUnit", "pos": "pos - shadowOffset", "scl": "getScl(0.165)", "color": "shadowColor"},
        {"type": "DrawUnit", "pos": "pos", "scl": "getScl(0.165)"}
    ],
    "abilityProc": [

    ]
}

To add a splash image to your unit, place an image file with the same name as your unit into the unitSplashes folder. To add in-game sprites of your unit, place the files example.png and example-hit.png in the unitSprites folder (replace “example” with the name of your unit). Those two files must exist for the unit to display properly. Additionally, an example-angery.png (not a typo) and example-happy.png file can be placed in the folder as well. The -angery sprite is displayed when the player misses a beat, and the -happy sprite is displayed one second before a level ends.

Custom Maps

Map scripts describe a playable level in the game. To add a custom map to the game, place a JSON or Hjson file into the maps folder. The contents of the file should look like this:

{
    "songName": "Anuke - Boss 1",
    "music": "boss1",
    "bpm": 100.0,
    "beatOffset": 0.0,
    "maxHits": 10,
    "copperAmount": 8,
    "fadeColor": "fa874c",
    "alwaysUnlocked": true,
    "drawPixel": [
        {"type": "DrawStripes", "col1": "#19191c", "col2": "#ab8711"},
        {"type": "DrawBeatSquare", "col": "#f25555"}
    ],
    "draw": [
        {"type": "DrawTiles"}
    ],
    "update": [
        {"type": "Condition", "condition": "state_newTurn", "then": [
            {"type": "Turns", "fromTurn": 7, "toTurn": 23, "interval": 4, "body": [
                {"type": "Formation", "name": "d4edge", "iterator": "v", "body": [
                    {"type": "MakeDelayBulletWarn", "pos": "playerPos + v * 2", "dir": "-v"}
                ]}
            ]}
        ]}
    ]
}

Procedures

Procedures are used the same way as API calls. They are placed as JSON or Hjson files in the procedures folder. They are called by putting the name of the procedure into the type field. Parameters are passed the same way as well. An example of a procedure:

{
    "name": "Example",
    "parameters": [
        {"name": "_param1", "default": 1.0},
        {"name": "_param2"},
        {"name": "_col1", "default": "#ff0000"}
    ],
    "script": [
        {"type": "Comment", "comment": "Useful function here."}
    ]
}

This procedure would be called from another script like so:

{"type": "Example", "_param1": 2.0, "_param2": 42.0}

You can also call procedures from another mod. To do that, you have to qualify the procedure you want to call with the namespace of the mod it is from, like so:

{"type": "utils::Example", "_param1": 2.0, "_param2": 42.0}

The parameters of the called procedure are stored as global variables, which means they are accessible from outside the procedure. Since all variables are global, even those used internally can be accessed (this way you can make a return value).

[!IMPORTANT] For technical reasons, color literals passed as parameters to a procedure must be prefixed with the # character!

A procedure can also call another procedure, even itself recursively. Keep in mind though that since all variables are global, this might overwrite other variables used in the procedure.

Procedures may have the same name as API calls, but the only way to call them then is by qualifying them with their namespace.

The Return call always jumps to the end of the current procedure.

Init procedure

If the mod contains a procedure with the name Init (case-sensitive), it is automatically called with default arguments when loading the mod. Use it to set constants or initialize variables for use in other scripts. Example:

{
    "name": "Init",
    "script": [
        {"type": "SetColor", "name": "colorWClear", "value": "#ffffff00"},

        {"type": "SetFloat", "name": "objFade", "value": 0}
    ]
}

API Reference

Functions

Functions can be used inside math formulas.

Variables

Available anywhere

Only available inside levels

Only available in unit splash drawing

Only available in unit ability procs

API Calls

API calls are JSON or Hjson objects that are used to call a function within the game. What function is called is determined by its type field. If the type field contains a function that does not exist, it is ignored. Parameters are also passed as JSON fields. An example for an API call for drawing a spinning regular pentagon:

{"type": "DrawPoly", "pos": "basePos", "sides": 5, "radius": 5.5, "stroke": 1.0, "color": "colorAccent", "rotation": "rad(fau_time * 90)"}

Parameters can either be constant or a formula. For example, the rotation field contains a formula for calculating the rotation based on game time, which is the standard way to animate shapes. What functions can be used inside formulas is defined in the chapter Functions. Other usable math functions and operators can be found here. Formulas are usable for vectors, ints and floats. In the case of vectors, the formula is applied to each coordinate separately. Formulas cannot be used for colors, but colors can reference a predefined color by name. Otherwise, colors can only use hexadecimal notation (e.g. #ff0000 for red). The alpha channel is added as two additional hexadecimal digits after the color (e.g. #ff00007f for half-transparent red), if not present the color is assumed to be fully opaque.

Fields that have a default value can be omitted from the call.

Setters

SetFloat

Sets a float variable that is accessible from anywhere.

SetVec2

Sets a 2D vector variable that is accessible from anywhere.

SetColor

Sets a color variable that is accessible from anywhere.

Flow control

Condition

Defines a condition. If the condition is met, the then block is executed, otherwise the else block is executed.

Alias: If

Iterate

Iterates over a range with an iterator variable. The iterator is incremented by 1 each iteration until it reaches a maximum value.

Alias: For

Repeat

Repeats an array of calls while a condition is met.

Alias: While

Break

Breaks out of the current loop. Stops execution if there is no current loop.

Return

Breaks out of all loops and stops execution.

Formation

Iterates over a list of 2D vectors with an iterator.

Alias: ForEach

Available formations:

Turns

Executes an array of calls only on specific turns. Only works inside levels.

If debug mode is enabled, the state_turns variable is evaluated instead of the actual turn count.

Pattern Drawing

DrawFft

Draws a circular audio spectrum. Never used in the base game.

DrawTiles

Draws the playing field with diagonal highlighted tiles that move with the beat. Should only be used inside levels.

DrawTilesFft

Draws the playing field with an audio spectrum. Never used in the base game. Should only be used inside levels.

DrawTilesSquare

Draws the playing field with tiles highlighted in a repeating square pattern. Should only be used inside levels.

DrawBackground

Draws a single color background.

DrawStripes

Draws construction-tape-like stripes. If used inside a level, scrolls from right to left with the beat.

DrawBeatSquare

Draws a square that flashes and changes size with the beat. Only works inside levels.

DrawBeatAlt

Same as DrawBeatSquare, but flashes in a different pattern. Only works inside levels.

DrawTriSquare

Draws regular polygons in a circle around a position.

DrawSpin

Draws stripes radially from the center. (TODO better explanation)

DrawSpinGradient

Draws a “fan” of triangles. (TODO better explanation)

DrawSpinShape

Draws a central layered regular polygon surrounded by smaller “sattelite” polygons. Flashes and rotates with the beat. Only works inside levels.

DrawShapeBack

Draws concentric polygons of alternating colors around the center.

DrawFadeShapes

Draws repeating rotated squares that move towards the center with the beat. Only works inside levels.

DrawRain

Draws pinkish squares with trails that move down-left with the beat. Only works inside levels.

DrawPetals

Draws cherry petals that fall down-left. Only works inside levels.

DrawSkats

Draws “skats”. Used for the credits. Behaves strangely in levels.

DrawClouds

Draws clouds in the upper half of the screen. Only works inside levels.

DrawLongClouds

Draws clouds in the upper half of the screen. Only works inside levels.

DrawStars

Draws stars in different shapes and sizes that flash with the beat. Only works inside levels.

DrawTris

Draws triangles that flash with the beat and move down-left. Only works inside levels.

DrawBounceSquares

Draws a lattice of squares with alternating sizes. The sizes of the squares swap with the beat. Only works inside levels.

DrawCircles

Draws circles in random sizes that move around the screen in random directions. This effect is used for Mono, Oct and Sei.

DrawRadTris

Draws triangles in random sizes that point away from the center and move around the screen in random directions. This effect is used for Crawler.

DrawMissiles

Draws moving circles with a trail of smaller circles (“missiles”). This effect is used for Zenith.

DrawFallSquares

Draws squares that fall down while spinning and changing color. This effect is used for Quad.

DrawFlame

Draws circles that move upwards while becoming smaller and changing color. This effect is used for Oxynoe.

DrawSquares

Draws squares that slowly move around the screen and periodically shrink and grow. This effect is used for Alpha.

DrawRoundLine

Draws a line with rounded endpoints.

DrawLines

Draws rounded lines that move around slightly (looks a bit like rays of light).

DrawRadLinesRound

Draws rounded lines pointing at the center of the screen that move around slightly.

DrawRadCircles

Draws circles in random sizes scattered around the center of the screen.

DrawSpikes

Draws rounded lines pointing to a position. The angle between all lines is the same.

DrawGradient

Draws a gradient across the screen.

DrawVertGradient

Draws a vertical gradient.

DrawZoom

Draws concentric polygons around the center of the screen that increase in thickness further out.

DrawFadeOut

The screen becomes light blue from the top left corner. This effect is used to transition between the menu and levels.

DrawFadeIn

A light blue screen disappears into the bottom right corner. This effect is used to transition between the menu and levels.

DrawSpace

Draws many stripes pointing towards the center. Only works inside levels.

DrawUnit

Draws the current unit’s splash image. Should only be used in unit splash drawing.

Basic Drawing

DrawFillQuadGradient

Draws a filled quad with a gradient.

DrawFillQuad

Draws a filled quad with a single color.

DrawFillRect

Draws a filled rectangle.

DrawFillSquare

DrawFillTri

Draws a filled triangle with a single color.

DrawFillTriGradient

Draws a filled triangle with a gradient.

DrawFillCircle

Draws a filled circle.

DrawFillPoly

Draws a filled polygon.

DrawFillLight

Draws a regular polygon with a gradient to the middle.

DrawLine

Draws a line between two points.

DrawLineAngle

Draws a line from a point at an angle.

DrawLineAngleCenter

DrawLineRect

Draws a rectangle outline.

DrawLineSquare

Draws a square outline.

DrawRadLines

Draws lines pointing at a target position.

DrawPoly

Draws a regular polygon outline.

DrawArcRadius

Draws a polygonal ring sector.

DrawArc

Draws a polygonal arc.

DrawCrescent

Draws a polygonal crescent shape.

DrawShape

Draws a polygon outline.

DrawBloom

Draws one or more patterns with bloom enabled. Only works in unit splash drawing.

Ability

MakeWall

Creates a wall that blocks bullets and conveyors.

DamageBlocks

Damages (usually destroys) bullets, conveyors, etc. on a target tile.

Makers

MakeDelay

Delays an action by a number of turns. Appears to be slightly bugged. Should only be used in map update scripts.

MakeBullet

Creates a bullet on the playing field. Should only be used in map update scripts.

MakeTimedBullet

Creates a bullet on the playing field that disappears after a set amount of turns. Should only be used in map update scripts.

MakeConveyor

Creates a conveyor on the playing field. Should only be used in map update scripts.

MakeLaserSegment

Makes a one tile long laser segment. You should probably use MakeLaser instead. Should only be used in map update scripts.

MakeRouter

Creates a router that shoots conveyors. Should only be used in map update scripts.

MakeSorter

Creates a sorter on the playing field that shoots conveyors and moves. Should only be used in map update scripts.

MakeTurret

Creates a turret on the playing field that moves and shoots bullets at the player. Should only be used in map update scripts.

MakeArc

Creates an Arc turret on the playing field that moves across the screen, bounces from walls and leaves a trail of stationary bullets. Should only be used in map update scripts.

MakeDelayBullet

Creates a bullet delayed by one turn.

MakeDelayBulletWarn

Creates a bullet delayed by one turn with an indicator at the position the bullet will appear.

MakeBulletCircle

Shoots 8 bullets from a position in all 8 directions.

MakeLaser

Creates a Lancer turret on the playing field that shoots a laser across the playing field two turns later.

Effects

EffectExplode

Creates an explosion effect on a tile.

EffectExplodeHeal

Creates a green explosion effect on a tile.

EffectWarn

Creates a warning effect (white square) on a tile.

EffectWarnBullet

Creates a warning effect (white bullet) on a tile.

EffectStrikeWave

Creates a warning effect (large square) around a tile.

Other

MixColor

Mixes two colors into a new color.

Blending modes:

ChangeBPM

Changes the BPM of the current map.