Change
the rules.

How modding works

Three levels, one folder.

The engine runs the physics, the weapons, flags, capture points and the ball. Everything a match plays by is data you can change, and you go only as deep as you need:

{ "movement":
  { "gravity": 12.0 } }

{ "base": "ctf",
  "score_limit": 5 }

fn on_frag(g, k, v) {
  add_score(g.team(k), 2);
}

How players get it.

Players never install anything by hand. The server lists what it runs, the game compares that with what it already has, and asks.

1. Your folderMaps and mods in content/ beside server.json. --check proves them.
2. Your serverRuns them, lists them, and keeps rules scripts to itself.
3. Find matchShows your mods and the download size before anyone clicks.
4. Their game"Download and join": every file checked, kept for next time. Leave, and their game is its own again.

Make one in 4 steps.

{ "name": "Moon CTF", "note": "Low gravity, five captures.", "api": 1 }

{ "base": "ctf", "label": "Moon CTF", "short": "MOON",
  "goal": "First to 5 captures", "score_limit": 5 }

The folder.

A mod holds only these files; anything else is refused. Each file is up to 64 KB.

content/
├─ maps/
│  └─ river-fort/          a map: map.json, its files, info.json
└─ mods/
   └─ moon-ctf/
      ├─ mod.json            name, note, api (required)
      ├─ defs.json           only the numbers you change
      ├─ modes/
      │  └─ moon-ctf.json    a mode, varying another
      ├─ armors/ weapons/ packs/ …  the engine's classes
      ├─ sounds/             short WAVE sounds
      ├─ rules/
      │  └─ moon.rhai        server only
      └─ hooks/
         └─ guardian.rhai    server only

Build new things.

Everything in the game is an entry of one of the engine's classes: armors, weapons, projectiles, blasts, throwables, deployables, damage kinds, effects, packs, items and vehicles. A mod adds its own entries or changes the game's by id, one folder per class, and entries name the ones they use, so capabilities mix freely: put the disc on a turret, a drain orb on a gun, a plate on an armor, a shield in a pack.

// deployables/disc-turret.json: the base turret, firing discs
{ "disc-turret": { "extends": "turret", "name": "Disc turret",
    "turret": { "range": 60, "sensed_range": 80, "speed": 95, "life": 5,
      "cooldown": 1.6, "leads": true, "fires": true, "projectile": "disc" } } }

Armors get class keys (C) and mounts, packs are switched or used, effects shield, cloak or poison, maps add moving parts and zones, modes add a purse, and hooks (server scripts named by entries) answer what happens. The full reference, generated from the engine so it can't drift, is docs/mod-format.md in the server download; peakrunner-server --schema prints it.

Tune numbers.

defs.json names only what changes; everything else stays as the game ships it. There are sections for movement (gravity, jumps, speed limits, skiing and air control, the energy tank), armors (light, heavy, football), weapons (disc, chaingun (the Repeater), grenade launcher, mortar, laser, railgun, plasma gun, blaster), blasts, throwables, repair, equipment and deployables.

{ "movement": { "gravity": 12.0 },
  "weapons":  { "disc": { "speed": 120.0, "reload": 0.8 } } }

Every number must be from 0 to 1,000,000. A misspelled field is refused with the list of the right ones, so a typo never slips through.

Add a mode.

A mode varies an existing one (ctf, capture_and_hold, team_deathmatch, rabbit, team_rabbit, football, duel, or another mode in your mod) and changes any of its fields. A variant of duel (heavy armor, first to 5) makes a duel server when a rotation names only it. The file name is the new mode's key.

Write rules.

Numbers and switches can't invent a new way to score. A rules script can. Name it in your mode ("script": "spree") and put it in rules/spree.rhai. The engine still runs every mechanic; the script answers what happens.

// Spree: every third frag in a row scores double.
fn on_frag(game, killer, victim) {
  if !game.playing { return; }
  if type_of(this.streaks) != "map" { this.streaks = #{}; }
  this.streaks.remove(`${victim}`);
  if !game.hostile(killer, victim) { return; }
  let streak = (this.streaks[`${killer}`] ?? 0) + 1;
  this.streaks[`${killer}`] = streak;
  let bonus = streak % 3 == 0;
  add_score(game.team(killer), if bonus { 2 } else { 1 });
  if bonus {
    feed(`${game.name(killer)} is on a spree!`);
    sound("point");
  }
}

Scripts are written in Rhai, a small language that reads like Rust or JavaScript. The base game's own rules are written this way too, and tested to match the engine's exactly.

Add a map.

A map is a folder in content/maps/<key>/: map.json, the files it lists (terrain, collision, textures, lighting, props) and an info.json with its menu name and description. Name its key in your rotation, and players who don't have it download it when they join. A map's identity is the fingerprint of its map.json, so change anything and it's a new map to everyone.

Changing a map's look (sun, sky, fog and exposure) in map.json is the quickest variant. New terrain comes from the map pipeline.

Script reference.

Handlers

Define any of these; a missing one does nothing. Players are numbered from 0; teams are 0 (Ember) and 1 (Glacier).

Reading the game

Commands

Examples.

The server download has these in examples/mods/: copy one into content/mods/ and run --setup.

What keeps it safe.