Game modes and scripting

The modes

Every copy of the game has these four. They're variants of Slayer, so you find them under Slayer when you pick a game type. To make your own, copy one of them and change a number or two, or write one from the start.

Zone Control's hill is a ball that reaches 8 units out from its middle, with no visible edge: follow the Hill distance row on your HUD, which counts down as you get closer. While you're in it alone, a Controlling hill row fills up to each point and you move at 125% speed with a white aura. Hosts can change the points a second, from 1 to 10, under Game Options → Slayer rules → Custom mode options. It's written in version 2, so it's also the example to start from for objective modes.

Gun Game's ladder runs from the weapon with the hardest-hitting shot down: Spartan Laser, Rocket Launcher, Shotgun, Missile Pod, Sniper Rifle, Beam Rifle, Brute Shot, Fuel Rod Gun, Mauler, Battle Rifle, Machine Gun Turret, Magnum, Plasma Cannon, Carbine, Plasma Rifle, Spiker, Assault Rifle, Flamethrower, Plasma Pistol, SMG, Needler and Sentinel Beam, then the Gravity Hammer and the Energy Sword. Your score is always the number of weapons you've completed, so the scoreboard shows who's furthest along. Sword and hammer kills count as weapon kills, not melee strikes. A kill made after you died, with a grenade or rocket still in flight, counts too: you respawn with the next weapon. Drop a turret, the Missile Pod or the Flamethrower by switching weapons and you get it straight back.

In Growth, your size is also your damage and your health: at 10% you deal a tenth of normal damage and can take a tenth as much, at 300% three times both. Two 10% players fight each other like two normal players. Growing doesn't heal you; it keeps the share of health you had.

The game updates the bundled modes by itself: a mode you never changed gets its new rules the next time you open Host Game, as Gun Game and Growth did in 0.8.12. A copy you edited is kept as it is. To get the new version, move your copy out of the Game Modes folder and choose Refresh.

Play one

1. Host a gameChoose Host Game in the main menu.
2. Pick the modeChoose Game Type, select the Slayer card and choose Gun Game, Growth, One in the Chamber or Zone Control from its variants. The lobby's game type row shows the mode's name.
3. Pick a mapAny multiplayer map. For a first game, use one everyone has installed.
4. Change the basics (optional)Game Options changes the time limit, score to win and lives like for any game type. Leave weapons, pickups and ammo as the mode has them until you've played it: the modes depend on them. A mode with settings of its own, such as Zone Control's points a second, lists them under Slayer rules → Custom mode options, within the limits its author set.
5. StartPlayers join from the Server Browser as usual. Choose Start Game.

• Only the host needs the mode. The script runs on the host, or on the dedicated server, and players who join see what it does through the game itself. They don't download or run it. Everyone needs version 0.8.10 or later, and the host 0.8.12 or later for the new Gun Game and Growth and the script features added in 0.8.12. For Zone Control and other version 2 or Megalo modes, the host and every player need 0.8.14 or later: HUD rows, traits and object changes reach players through it.
• Every round starts fresh: sizes, weapon stages, zones, timers and the numbers a script keeps all reset.
• In a playlist: in the playlist editor, pick a map, choose the mode under Slayer as the game type and choose Add to Rotation. In a playlist file, name it like any saved game type: { "map": "Guardian", "game": "Gun Game" }. See custom playlists.
• On a dedicated server: the server folder gets the four modes in content/Game Modes/Project Reclaimer the first time dedicated check or dedicated runs. Name one in a playlist, or give a server map = "Guardian" and game = "Gun Game". See share and host.

How a mode works

A game mode is a Slayer game type saved as a JSON text file, the same kind Game Options → Save as variant writes, with one part added: script. The rest of the file holds the usual game type settings, such as the score to win, lives, time limit and which weapons are on the map. The script adds what those settings can't: changes that happen during the game, to one player at a time.

"script": {
  "version": 1,           1, or 2 for version 2
  "name": "Growth",
  "initial": [0.1],       each player's numbers when they join
  "on_spawn": [ … ],     actions when the player spawns
  "on_kill": [ … ],      actions when the player kills an enemy
  "on_death": [ … ]      actions when the player dies
}

• Events: a script reacts to three things that happen to a player: spawning, killing an enemy and dying. Each has a list of actions that run in order. See events.
• Numbers: each player carries up to 16 numbers through the round, such as their size or weapon stage. Actions read them and change them. See player numbers.
• Actions: set a number, change the player's size, health, damage, weapon or ammo, or give them points. Any action can carry a condition, when, so it runs only sometimes, such as for kills that weren't melee. See actions.

That's version 1, the language Gun Game, Growth and One in the Chamber are written in, and what the next sections cover. It has no loops or timers, which keeps modes simple to write. When a mode needs more, such as a hill, a countdown or a winner chosen by the script, version 2 adds events for the whole round, timers, loops, objects and zones, HUD rows, player traits and team changes. Everything in version 1 works in version 2 too. And if you know ReachVariantTool's script language, Megalo scripts compile into version 2 modes. Every version is limited to gameplay: no files, network or programs.

Your first mode

The quickest start is a copy of a mode that works. This makes a slower Growth, where each kill adds half of the victim's size instead of all of it.

1. Open the Game Modes folderIn Host Game, choose Game Type and then Open Folder. Or browse to Documents\My Games\Project Reclaimer\Game Modes. The bundled modes are in its Project Reclaimer folder.
2. Copy GrowthCopy Project Reclaimer\growth.json into Game Modes itself and rename the copy my-growth.json. Leave the original alone: the game puts back any bundled mode that's missing, but never overwrites one you changed.
3. Rename itOpen my-growth.json in a text editor. Change "name": "Growth" to "name": "My Growth" in two places: at the top, which is the name the game type picker shows, and inside "script".
4. Change the rewardIn "on_kill", the first action's "value" is ["self.0", "victim.0", "+", 3, "min"]. Change it to ["self.0", "victim.0", 0.5, "*", "+", 3, "min"]: the victim's size times a half. Save the file.
5. Check it Open a terminal in the game client's folder (in File Explorer, right-click inside the folder and choose Open in Terminal) and run mode-check with your file's path. Type .\project and press Tab for the program's name, and drag the file onto the terminal window to paste its path:
   PowerShell

   .\project-reclaimer-v0.8.14.exe mode-check "C:\Users\you\Documents\My Games\Project Reclaimer\Game Modes\my-growth.json"

   It answers Valid custom mode: My Growth (script version 1), or names what's wrong. See troubleshooting for the messages.
6. Play itIn Host Game's game type picker, choose Refresh. My Growth is now under Slayer. Select it and start a game with at least one other player.

After every change to the file, choose Refresh and select the mode again: the lobby keeps the copy it loaded, and a round that's running keeps its script until it ends.

A complete mode

This is a whole game type file, not just a script. Save it as small-growth.json in your Game Modes folder, or download it. Players start at normal size, each kill adds a tenth of the victim's size up to twice normal size, health and damage grow in step with size, and dying resets all three.

{
  "version": 1,
  "name": "Small Growth",
  "mode": "Slayer",
  "rules": {
    "score_to_win": 25,
    "kill_points": 1,
    "death_points": 0,
    "suicide_points": 0,
    "betrayal_points": 0
  },
  "options": {
    "rounds.teams": 0,
    "rounds.limit": 1,
    "rounds.minutes": 10
  },
  "script": {
    "version": 1,
    "name": "Small Growth",
    "initial": [1],
    "on_spawn": [
      {"op": "scale", "value": ["self.0"]},
      {"op": "health", "value": ["self.0"]},
      {"op": "damage", "value": ["self.0"]}
    ],
    "on_kill": [
      {"op": "set", "slot": 0, "value": ["self.0", "victim.0", 0.1, "*", "+", 2, "min"]},
      {"op": "scale", "value": ["self.0"]},
      {"op": "health", "value": ["self.0"]},
      {"op": "damage", "value": ["self.0"]}
    ],
    "on_death": [
      {"op": "set", "slot": 0, "value": [1]},
      {"op": "scale", "value": [1]},
      {"op": "health", "value": [1]},
      {"op": "damage", "value": [1]}
    ]
  }
}

The map isn't in the file: the host picks it in the lobby.

Events

When Alpha kills Bravo:

1. Alpha's on_killRuns first, so it can read Bravo's numbers (victim.0 and so on) before anything resets them. This is how Growth rewards bigger victims.
2. Bravo's on_deathRuns next: the place to reset Bravo's numbers and effects.
3. Bravo's on_spawnRuns when Bravo respawns: the place to equip the new body.

• Suicides, deaths from falling or the map, and betrayals of a teammate run only the victim's on_death. Nobody gets on_kill.
• A kill made after the killer died, with a grenade or rocket still in flight, still runs the killer's on_kill. What it gives them, such as a new weapon, comes with their next spawn.
• Actions run in the order they're written, and each sees what the ones before it changed.
• Each list is optional; leave out an event the mode doesn't need. One in the Chamber has no on_death, so dying changes nothing but the bullets a new body starts with.
• There's no event for damage, a timer, a round starting or a player joining. initial sets the numbers for joins and new rounds.

How the kill was made

on_kill and on_death can read two values about the death, in any expression. Both events of the same death see the same values.

They're most useful with when: Gun Game moves a player up only when kill.melee is 0, and sets the victim back when kill.assassination is 1. on_spawn can't use them, since nobody died.

Player numbers

Every player has 16 numbers, called slots 0 to 15, that the script can read and change. A slot can mean anything: a size, a weapon stage, a kill streak. The script just calls them by number: self.0 is the player's slot 0, self.3 their slot 3.

• initial lists the starting values, from slot 0 on. [1] starts slot 0 at 1; slots you don't list start at 0; [] starts them all at 0.
• A player gets the starting values when they join and at the start of every round. Leaving and rejoining starts them over.
• Numbers stay through deaths and respawns. Reset them yourself in on_death if they should start over.
• victim.0 to victim.15 read the victim's numbers, in on_kill only. kill.melee and kill.assassination aren't slots: they say how the kill was made.
• Only set changes a slot. Reading one in an expression leaves it as it is.

For example, to count each player's kills in slot 1 while slot 0 holds their size:

"initial": [1, 0],
"on_kill": [
  {"op": "set", "slot": 1, "value": ["self.1", 1, "+"]}
]

The effects work the same way: a player's size, health, damage and weapon stay as the last action set them, through death and respawn, until an action changes them again. To reset them, set them in on_death as well as the slot that drives them.

Expressions

Wherever an action needs a value, it takes an expression: a list of numbers, slots and operators in the order a calculator would take them, with each operator after the two values it works on. ["self.0", 2, "*"] is slot 0 times two. [10, 2, "/"] is 10 divided by 2.

Numbers go in as they are, slots and operators in double quotes. The operators:

How it's worked out

The game reads the list from left to right and keeps a pile of values. A number or a slot goes on top of the pile. An operator takes the top two off, works them out, and puts the answer back. At the end exactly one value must be left. My Growth's reward for a kill, when a 10% player kills a 150% player:

["self.0", "victim.0", 0.5, "*", "+", 3, "min"]

Common expressions

An operator always comes after its two values: ["self.0", 1, "+"], never ["self.0", "+", 1]. Slots are numbered, not named: "self.size" isn't a slot. Two comparisons both true is the min of them, either one true their max. Version 1 has no random numbers (version 2 does); min and max set the limits of anything that grows.

Actions

Each action is written as {"op": "name", …} with the fields it takes, and optionally a when. The game keeps values within the range shown, so a size of 5 becomes 3.

Run an action only sometimes: when

Any action can have a when: an expression that decides whether it runs. The action runs when when works out to more than 0, and is skipped otherwise; the event goes on with the next action either way. With a comparison, that means the action runs when the comparison is true.

"on_kill": [
  {"op": "score", "when": ["kill.melee", 0, "=="], "value": [1]},
  {"op": "set", "slot": 0, "when": ["kill.melee", 0, "=="], "value": ["self.0", 1, "+", 23, "min"]},
  …
]

For every kill except a melee strike, the player gets a point and moves up a stage. A melee strike skips both. Each action needs its own when: it covers that action only.

• And: the min of two comparisons is 1 only when both are. ["kill.assassination", "self.0", 0, ">", "min"] is a kill from behind while slot 0 is above 0.
• Or: the max of two comparisons is 1 when either is.
• Not: compare with 0: ["kill.melee", 0, "=="].
• A when is checked when its action's turn comes, so it sees what the actions before it changed.

Size, health and damage

• Health works as protection: at 2, the player takes half the damage from everything, at 0.1 ten times as much. Raising it doesn't heal, it keeps the share of health and shields the player had. The HUD's shield and health bars don't change.
• Damage multiplies what the player deals to other players. Where Halo 3 deals no damage, such as with friendly fire off, it stays none.
• Size changes the body: bigger players are bigger targets and may not fit through small doors or under low ceilings. Everyone in the game sees the same size, players who joined mid-game too. Players walk at normal speed at any size, and a tiny player's view sits near the floor.
• Lethal counts for melee too. It can't get past what Halo 3 makes immune, such as a player who can't be damaged.

Weapons

The weapons a weapon action can give:

assault_rifle battle_rifle smg carbine magnum plasma_pistol plasma_rifle spiker needler shotgun sniper_rifle beam_rifle rocket_launcher spartan_laser brute_shot mauler energy_sword gravity_hammer sentinel_beam fuel_rod_gun flamethrower missile_pod machine_gun_turret plasma_cannon

• index is an expression, rounded down and kept within the list: in a list of four, 0 is the first, 3 and anything higher the last.
• The weapon has to be one the map offers in multiplayer. Every Halo 3 multiplayer map has all 24; a mod map may not.
• Giving the weapon the player already holds doesn't refill it. Use ammo for that.
• The Flamethrower, the Missile Pod and the two turrets are support weapons: players drop them when they switch weapons. The host gives a dropped one straight back, with the ammo it had.

Ammo

• ammo counts the magazine and the reserve together. The magazine fills first, the rest goes to the reserve.
• add_ammo adds to what the player has actually left, so bullets they fired don't come back.
• Ammo actions need a weapon with a magazine; energy weapons such as the plasma rifle and the energy sword don't have one. In on_spawn, give the weapon before its ammo.
• Turn infinite ammo off in the game type's options for modes that count bullets.
• With unlimited ammo on, as in Gun Game, the host refills a weapon the script gave once its magazine and reserve are both empty, because the Missile Pod and the turrets can't reload. The Flamethrower keeps its fuel; only its heat limits it.

Rules and scoring

The game type decides who wins, with Halo 3's own score, lives and time limits, so a mode's win condition goes in rules and options. A script can add to that score with the score action, which counts like the points for a kill: the score limit still ends the round the moment a player reaches it.

A mode that scores its own points usually sets kill_points to 0, so kills give nothing by themselves. Gun Game does: its script gives a point for each weapon completed and takes one back for a set-back, so a player's score is always their stage, and its score limit is 24, the number of weapons. The Energy Sword kill is the 24th point and ends the round.

The simplest way to get options right is to let the game write them: host with your mode, set what you want in Game Options, and choose Save as variant. The saved file holds your script with every option you changed. Many options are stored as a number for a choice rather than an amount, "player.shields": 1 means no shields, for example, so don't guess them from their names.

• With more than one round (rounds.limit), scores start at 0 each round, and the total over all rounds decides the final standings.
• Leave Player size in Game Options → World & Forge at its default: a game type with a script can't set it too.
• Scripts work with Slayer only, in a .json game type. A Halo 3 .bin game variant, Forge or the campaign can't have one.

Version 2: timers, objects, HUD and rounds

Version 1 reacts to three things that happen to one player. Version 2 sees the whole round: it runs on every tick, keeps numbers for the round, for each team and for each object, counts timers down, places weapons and invisible zones on the map, writes rows on players' HUDs, changes traits and teams, and can end the round. Zone Control is written in it.

To use it, set the script's version to 2 and add a logic part. The file around the script stays the same: "version": 1 and "mode": "Slayer". Everything from version 1 still works, at the script's top level as before (initial, on_spawn, on_kill, on_death) and inside version 2's events, loops and functions. The host and every player need 0.8.14 or later.

A complete version 2 mode

Save this as timed-bonus.json in your Game Modes folder, or download it. It's Slayer with a bonus: every 10 seconds, each living player gets a point, and a HUD row shows their score as a bar toward 50. Hosts can change the 10 seconds, from 1 to 60, under Custom mode options.

{
  "version": 1,
  "name": "Timed Bonus",
  "mode": "Slayer",
  "rules": {
    "score_to_win": 50,
    "kill_points": 1,
    "death_points": 0,
    "suicide_points": 0,
    "betrayal_points": 0
  },
  "options": {
    "rounds.teams": 0,
    "rounds.limit": 1,
    "rounds.minutes": 10
  },
  "script": {
    "version": 2,
    "name": "Timed Bonus",
    "initial": [],
    "logic": {
      "options": {
        "interval": {"value": 10, "min": 1, "max": 60}
      },
      "on_round_start": [
        {"op": "timer_set", "scope": "global", "slot": 0, "value": ["option.interval"]},
        {"op": "timer_rate", "scope": "global", "slot": 0, "value": [-1]}
      ],
      "on_tick": [
        {"op": "if", "condition": ["global.timer.0", 0, "=="], "then": [
          {"op": "for_each_player", "actions": [
            {"op": "score", "when": ["self.alive"], "value": [1]},
            {"op": "hud", "slot": 0, "text": "Score", "value": ["self.score"], "max": [50]}
          ]},
          {"op": "timer_set", "scope": "global", "slot": 0, "value": ["option.interval"]}
        ]}
      ]
    }
  }
}

mode-check answers Valid custom mode: Timed Bonus (script version 2).

What logic holds

logic is required in version 2, even empty: "logic": {}. Every part of it is optional.

Round events

Events that run for nobody in particular have no self: use for_each_player to go through the players. Each round starts with fresh numbers, timers and objects. The first on_join events of a round see the players as they arrive; make decisions about everyone in on_round_start or on_tick.

More numbers and values

Besides each player's numbers, version 2 has numbers for the round, for each team and for each object: 16 of each, plus 8 timers each. All work in expressions like self.0.

More operators: "%" (remainder), "and" and "or" (both values are worked out first), and the one-value operators "not", "abs", "floor", "ceil", "neg" and "sqrt", which take the top value only: ["self.0", "floor"] rounds slot 0 down. A remainder of a division by zero or the square root of a negative number stops the script, like a division by zero; guard them with an if.

Conditions, loops and functions

Loops put back the player, team and object they started with when they finish. A slot number names whoever is in that slot now: if a player leaves and another joins, the newcomer gets the slot. when belongs to version 1's actions (set, scale, health, damage, weapon, ammo, add_ammo, lethal and score); put any other action inside an if.

Timers and random numbers

• {"op": "timer_set", "scope": "global", "slot": 0, "value": [30]} sets a timer to 30 seconds. scope is player, global, team or object; a player timer is the current player's, so set it in a player's event or loop.
• {"op": "timer_rate", …, "value": [-1]} makes it count down one second per second of play; 1 counts up and 0 stops it. Timers start at 0, stopped.
• A timer counting down stops at 0. Nothing happens by itself when it gets there: check it in on_tick, as Timed Bonus does. Setting a new value keeps its rate, so it counts down again.
• {"op": "random", "scope": "player", "slot": 0, "min": [1], "max": [3]} puts a whole number from 1 to 3 in the player's slot 0. logic.seed decides the sequence.

Objects and zones

logic.objects names up to 64 things on the map for the script to work with. Each has a source, and optionally a position, a label for for_each_object, and a shape for zones.

"objects": {
  "hill": {
    "source": {"kind": "zone"},
    "label": "objective",
    "shape": {"kind": "cylinder", "radius": 8, "half_height": 3}
  },
  "prize": {"source": {"kind": "weapon", "weapon": "rocket_launcher"}}
}

Shapes: sphere with a radius, box with half_extents [x, y, z], or cylinder with a radius and a half_height. They line up with the map's axes, and their edge counts as inside. Positions and sizes are in Forge units: one is ten feet.

A position is three expressions, x, y and z, each in its own list. In on_spawn, this places the prize beside the first player to spawn, at half size, once:

{"op": "with_object", "object": "prize", "actions": [
  {"op": "if", "condition": ["object.exists", "not"], "then": [
    {"op": "spawn_object", "object": "prize", "position": [
      ["self.x", 2, "+"], ["self.y"], ["self.z", 1, "+"]
    ]},
    {"op": "object_scale", "value": [0.5]}
  ]}
]}

• Zone Control puts its hill where the first player spawns with move_object, so it works on every map. For a hill in a set place, give the zone a position: in Forge, fly the monitor there and read X, Y and Z on the Forge menu's Map tab.
• Objects the script placed are removed when the round ends. Moved or deleted map objects stay that way for the rest of the round, and the map may respawn a deleted one by its own rules.
• Players who join mid-game see the objects and their sizes as they are.

Traits, teams, round end and HUD

Trait values are the position of the choice in Game Options' list, counting from 0, not a percentage: speed 7 is 125% and 8 is 150%, camouflage 4 is invisible, aura 4 is white. 0 leaves the trait as the game type has it. The traits and their highest value:

To pick the winner yourself, select them first, for example in on_kill: {"op": "if", "condition": ["self.score", 30, ">="], "then": [{"op": "end_round"}]}. To show everyone the same row, write it in a for_each_player loop; to show one player something, use with_player, as with "event.victim" in on_kill.

Settings hosts can change

Each entry in logic.options is a setting with a name, a value and the range hosts may choose from: "interval": {"value": 10, "min": 1, "max": 60}. Hosts change them in the lobby under Game Options → Slayer rules → Custom mode options, and Save as variant keeps their choice. The script reads one as "option.interval". Up to 32 per mode, with names of letters, digits and underscores.

Version 2 limits

When an event goes wrong while a game runs, everything that event did is taken back (numbers, timers, traits, HUD rows, points and its changes to the world) and the script stops until the next round, as in version 1. Changes made by earlier events stay. The host's log says why.

Recipes

Changes to the first three bundled modes, and two new modes, to copy from. Each change starts from the mode's file in Game Modes\Project Reclaimer; make a copy with a new name first, as in your first mode.

A shorter Gun Game

Gun Game keeps the player's stage in slot 0, from 0. on_spawn gives the stage's weapon. on_kill scores a point, moves up a stage and gives the next weapon, the first two only when the kill wasn't a melee strike. on_death handles the set-back: after a kill from behind it takes a point back, if the player has one to lose, and moves them down a stage, never below the first. Its script:

"script": {
  "version": 1,
  "name": "Gun Game",
  "initial": [0],
  "on_spawn": [
    {"op": "weapon", "index": ["self.0"], "choices": [
      "spartan_laser", "rocket_launcher", "shotgun", "missile_pod",
      "sniper_rifle", "beam_rifle", "brute_shot", "fuel_rod_gun",
      "mauler", "battle_rifle", "machine_gun_turret", "magnum",
      "plasma_cannon", "carbine", "plasma_rifle", "spiker",
      "assault_rifle", "flamethrower", "plasma_pistol", "smg",
      "needler", "sentinel_beam", "gravity_hammer", "energy_sword"
    ]}
  ],
  "on_kill": [
    {"op": "score", "when": ["kill.melee", 0, "=="], "value": [1]},
    {"op": "set", "slot": 0, "when": ["kill.melee", 0, "=="], "value": ["self.0", 1, "+", 23, "min"]},
    {"op": "weapon", "index": ["self.0"], "choices": [ the same 24 weapons ]}
  ],
  "on_death": [
    {"op": "score", "when": ["kill.assassination", "self.0", 0, ">", "min"], "value": [-1]},
    {"op": "set", "slot": 0, "when": ["kill.assassination"], "value": ["self.0", 1, "-", 0, "max"]}
  ]
}

For four stages, a Magnum, battle rifle, shotgun and energy sword:

1. Change both weapon listsMake the choices in on_spawn and in on_kill the same four weapons.
2. Change the last stageStages count from 0, so four stages end at 3: in on_kill's set, the 23 becomes 3.
3. Change the score to winSet rules.score_to_win to 4. Keep kill_points at 0 and nothing taken away for deaths, suicides or betrayals, so a player's score always matches their stage.

"on_spawn": [
  {"op": "weapon", "index": ["self.0"],
   "choices": ["magnum", "battle_rifle", "shotgun", "energy_sword"]}
],
"on_kill": [
  {"op": "score", "when": ["kill.melee", 0, "=="], "value": [1]},
  {"op": "set", "slot": 0, "when": ["kill.melee", 0, "=="], "value": ["self.0", 1, "+", 3, "min"]},
  {"op": "weapon", "index": ["self.0"],
   "choices": ["magnum", "battle_rifle", "shotgun", "energy_sword"]}
],
"on_death": [
  {"op": "score", "when": ["kill.assassination", "self.0", 0, ">", "min"], "value": [-1]},
  {"op": "set", "slot": 0, "when": ["kill.assassination"], "value": ["self.0", 1, "-", 0, "max"]}
]

The whole file is short-ladder.json: Gun Game with its ladder cut to four. For a ladder of any length, the last stage is one less than the number of weapons, and the score to win the same as the number of weapons.

• To leave the melee set-back out, delete both on_death actions.
• To let melee kills move players up too, delete the when from the two on_kill actions that have one.

Tune Growth

• For growth that only changes size, remove the health and damage actions from all three events.
• To start everyone at normal size, as Growth did before 0.8.12, make initial and the four on_death values 1. With all of the victim's size added, two kills then reach the largest size, so add a share too.
• Random starting weapons come from Halo 3's own starting-weapon list, which also holds a few campaign weapons, such as the Brute plasma rifle and the golf club. Pick fixed weapons in Game Options to leave them out.
• Change an effect in all three events together, or players keep the old one after a kill or a death. Keep the largest size at 3 or below and the smallest at 0.1 or above: sizes are kept between 0.1 and 3, and a stored size outside them would make those players worth more or less than they look.

Tune One in the Chamber

"script": {
  "version": 1,
  "name": "One in the Chamber",
  "initial": [],
  "on_spawn": [
    {"op": "weapon", "index": [0], "choices": ["magnum"]},
    {"op": "ammo", "value": [1]},
    {"op": "lethal", "enabled": true}
  ],
  "on_kill": [
    {"op": "add_ammo", "value": [1]}
  ]
}

A new mode: Momentum

Every kill without dying adds a fifth to the damage you deal, up to five kills, double damage. Dying resets it. Slot 0 holds the streak.

"script": {
  "version": 1,
  "name": "Momentum",
  "initial": [0],
  "on_spawn": [
    {"op": "damage", "value": [1, "self.0", 0.2, "*", "+"]}
  ],
  "on_kill": [
    {"op": "set", "slot": 0, "value": ["self.0", 1, "+", 5, "min"]},
    {"op": "damage", "value": [1, "self.0", 0.2, "*", "+"]}
  ],
  "on_death": [
    {"op": "set", "slot": 0, "value": [0]},
    {"op": "damage", "value": [1]}
  ]
}

The whole file is momentum.json. The damage expression is 1 plus a fifth of the streak: 1 with no kills, 2 at five. Build from this: make it the player's size instead with scale, or give the streak a weapon each with weapon.

A new mode: Style Points

A kill is worth a point, as in Slayer, but a kill from behind is worth three, and from the fifth kill in a row every kill is worth one more. Slot 0 holds the streak. Uses when, a comparison, kill.assassination and score.

"script": {
  "version": 1,
  "name": "Style Points",
  "initial": [0],
  "on_kill": [
    {"op": "set", "slot": 0, "value": ["self.0", 1, "+", 10, "min"]},
    {"op": "score", "when": ["kill.assassination"], "value": [2]},
    {"op": "score", "when": ["self.0", 5, ">="], "value": [1]}
  ],
  "on_death": [
    {"op": "set", "slot": 0, "value": [0]}
  ]
}

The whole file is style-points.json, with 50 points to win. kill_points stays at 1, so every kill still scores its point, and the two score actions add the bonuses: 2 more for a kill from behind, 1 more once the streak reaches 5. The streak stops counting at 10, well within the limits, since the bonus doesn't need more.

Share and host

Share a mode

A mode is one file, so share the file: your .json from Game Modes, not your whole profile folder. The other host puts it in their own Game Modes folder, checks it with mode-check and chooses Refresh. Players who join them don't need it.

Game Options → Save as variant saves the mode as the lobby has it, script and game options together, in your Game Modes folder. The file gets a random name; rename it if you like. It carries your nickname as its author, which the loading screen shows.

On a dedicated server

Copy the file into the server folder's content/Game Modes, then use it like any game type there:

[[server]]
name = "Gun Game"
port = 49178
map = "Guardian"
game = "Gun Game"

[[server]]
name = "Momentum"
port = 49179
variant = "content/Game Modes/momentum.json"

Or name it in a playlist with "game": "Momentum", or its file, "game": "Game Modes/momentum.json". dedicated check checks the mode along with the rest, and the server's log says when a mode's script runs into trouble.

Try it on one PC

To try a mode without setting up a lobby, run one server with it from the client's folder and join it from the Server Browser:

.\project-reclaimer-v0.8.14.exe local-server --variant "C:\Users\you\Documents\My Games\Project Reclaimer\Game Modes\momentum.json"

Test before you share

mode-check finds mistakes in the file, but not in how the mode plays. Play it with at least one other player and check:

• The first spawn, several kills, and the respawn after each death.
• A suicide and a fall off the map: they should run only on_death.
• A second round, which should start everyone over.
• A player leaving and joining again.
• Growth-like modes: killing a bigger player, and playing at the largest and the smallest size in tight spaces.
• Melee rules: a melee strike from the front, one from behind, and a sword or hammer kill, which count as weapon kills, not melee strikes.
• A kill made after dying, with a grenade still in flight.
• Ammo modes: a miss, a melee kill, a reload, and dying with bullets saved.
• Weapon ladders: the last stage, and the round ending on the right kill.
• Modes that score: the score limit ending the round on the right point, and the next round starting everyone at 0.
• The score, lives and time limit ending the game the way you meant.
• Version 2 timers: one that should repeat fires more than once, and one in a player's slot keeps going after they die.
• Zones: an empty zone, one player inside, two players inside, and a player dying inside.
• Objects: a placed object on several maps, its size, and that it's gone in the next round.
• HUD rows and traits for a player who joins mid-game, and rows clearing when they should.
• end_round picking the right winner, and the round ending without one when nobody's selected.

Limits and safety

Version 1's limits are below; version 2 has its own, and so do Megalo scripts.

If an event goes wrong while a game runs, such as a division by zero or a value past a million, that event changes nothing, and the script stops for the rest of the round: every player goes back to normal size, health and damage, and keeps the weapon they hold. The host's log says why. Fix the file and start a new game.

What a script can't do

A script is a list of allowed actions, not a program. Project Reclaimer checks every file against that list and turns away anything else, so a mode from someone you don't know can change how your game plays, and nothing more:

• No access to files, the network, other programs or the console, and no code of any kind: no Lua, JavaScript or Halo 3's own scripts.
• Version 1 has no loops or functions. Version 2's loops only go through players, teams and the mode's objects, its functions can't call themselves, and every event has a step limit, so no script can run forever. Megalo scripts are held to the same kind of limits.
• No text beyond the action, weapon and value names, and the plain text of HUD rows.
• Only the host runs it. Players receive what it does through the game, never the script.

A mode can still be unfair within those limits: try one before you host it for others.

Not yet

Version 1 has no random numbers, timers or way to pick a winner; version 2 adds all three. Neither has per-hit events. Of how a kill was made, both know only melee strikes and kills from behind: they can't tell a headshot from a body shot, or require that a kill was made with the weapon the script gave, so in Gun Game a rocket still in flight after moving up counts. Zones are invisible, with no boundary drawn on the map and no waypoint. Scripts can't play sounds or show icons, and there's no editor in the game. These may come in later versions.

Troubleshooting

The client's log is Documents\My Games\Project Reclaimer\Logs\client.log; a dedicated server's is data/<server>/server.log. Lines about modes start with Custom mode or Custom game mode stopped, and files left out with Skipped content file. When you report a problem, include the mode's file, the map, and what happened in the game before it.