The .dmod format (api 1)

A .dmod is a zip file. The Mod Studio makes it for you; this page is for making or changing mods outside the game, and for knowing exactly what is allowed. The site checks every upload against these rules and repacks it (every file stored, uncompressed, manifest.json first) — the game server reads it without unpacking.

Limits: 25 MB and 2000 files in all, scripts up to 512 KB each, JSON files up to 4 MB, pictures up to 4096 pixels a side (2048 in sprites/).

The files

File names inside the folders: lower case, digits, _ . -. Nothing else is allowed in the package.

manifest.json

{
  "id": "hot_potato",
  "name": "Hot Potato",
  "version": "1.0.0",
  "api": 1,
  "author": "you",
  "description": "Pass the potato before it blows up.",
  "maps": "add",
  "bots": false,
  "settings": [
    {"key": "fuse", "name": "Fuse (seconds)", "type": "int", "default": 20, "min": 5, "max": 120}
  ]
}

A setting: key (lower case, unique), name (what the host sees), type and default:

Maps: maps/<name>.json

Coordinates are pixels, y going down. The map editor writes all of this; an editor object it adds is ignored by the game.

{
  "name": "Test Hill",
  "description": "Slopes, platforms and springs.",
  "width": 3200, "height": 1024,
  "time": 150,
  "music": "mus_hill", "chase_music": "mus_hill_chase",
  "background": {"image": "maps/sky.png", "color": "#203050", "parallax": 0.3},
  "art": [{"image": "maps/castle.png", "x": 900, "y": 300}],
  "tileset": "maps/tiles.png",
  "tiles": {"data": "2:5,196:0,4:5,196:0"},
  "solids": [[0, 800, 3200, 224]],
  "platforms": [[300, 680, 160]],
  "slopes": [[1072, 672, 128, 128, 1]],
  "objects": [
    {"type": "spawn", "x": 100, "y": 799},
    {"type": "exe_spawn", "x": 3000, "y": 799},
    {"type": "ring", "x": 600, "y": 760},
    {"type": "exit", "x": 1600, "y": 800},
    {"type": "spring_up", "x": 2000, "y": 800}
  ],
  "preview": "maps/preview.png"
}

A map needs a spawn, an exe_spawn and an exit; at most 255 rings. Tiles are only pictures: what players stand on is solids, platforms and slopes (the editor makes them from the tile flags when it saves). An exit's y is where the big ring stands (its bottom): on the ground, players run into it. The map's left and right edges are walls; falling off the bottom brings a player back to the nearest spawn, hurt.

sprites.json

{"sprites": {
  "spr_ring": {"image": "sprites/blue_ring.png", "frames": 4, "origin": [8, 8]},
  "potato":   {"image": "sprites/potato.png", "frames": 1, "origin": [16, 16], "speed": 0.2}
}}

A sprite named like one of the game's (spr_ring, spr_tails_idle...) is drawn instead of it and keeps the game's hit box. Other names are new sprites for client.lua (hud.sprite), for map backgrounds, or for characters. frames: a strip left to right (1-256). origin: the point placed on the position. speed: frames per game frame (default: the game sprite's, or 0.25).

characters/<name>.json

{
  "replaces": "tails",
  "name": "Speedy Tails",
  "stats": {"speed": 1.25, "acceleration": 1.2, "jump": 1, "gravity": 1, "damage_taken": 1, "hp": 120},
  "sprites": {"spr_tails_idle": "speedy_idle"}
}

replaces: tails, knuckles, eggman, amy, cream, sally, exe, chaos, exetior, exeller. The stats multiply the character's own (1 = unchanged): speed, acceleration, jump and gravity 0.3-3, damage taken 0-5; hp 10-127 is its starting HP. sprites swaps the character's game sprites for sprites of sprites.json.

objects/<name>.json (api 2)

{
  "sprite": "coin",
  "box": [-8, -8, 16, 16],
  "front": false,
  "vars": {"value": 5}
}

An object the mod's maps place and its scripts make (game.spawn). sprite: a sprite of the mod (sprites.json) or of the game (spr_ring); none: it is not drawn. box: where players touch it, [left, top, width, height] from its x, y. front: drawn in front of the players. solid: "solid" (players stand on it and bump into it) or "platform" (they stand on its top, and jump through it from below); a moving one carries who stands on it. vars: the fields each one starts with (numbers, texts, true / false), as self.<name>.

Its events are in objects/<name>.lua, each a function: create(self), step(self) (60 times a second), touch(self, player), leave(self, player) and destroy(self). They run on the server with the game rules' functions.

lobby.json

{
  "title": "`HOT POTATO",
  "text": "Touch another survivor to pass the potato.",
  "background": "maps/preview.png",
  "music": "mus_waiting"
}

Shown while players wait. title and text up to 300 characters; background a picture of the mod or a sprite; music a game music or a sound of the mod.

Colour codes

Texts (lobby, map names, game.say, hud.text...) take the game's colour codes: ` yellow, @ green, & purple, / blue, | grey, \ red, ~ back to the normal colour.

Checking a package

The Mod Studio's Check runs the same checks as the upload page: open your .dmod with Open a .dmod file and check it there.