Guide

Megalo scripts

A game mode in Project Reclaimer is one text file: its rules, its options and its script, written in the Megalo language ReachVariantTool uses for Halo: Reach, with many Halo 3 extensions. Write one in a text editor, drop it in a folder and play it. You need nothing but the game and this page.

New in 0.10A source is a whole mode, so there's no template to pick and nothing to compile. Scripts can now hear damage and deaths, name any object on the map by its path, copy objects, show waypoints, play sounds, set who can hurt what, revive players where they fell, run squads and a deployment map and dress players in armor of their choosing. Conquest and Combined Arms show it all at work. Reach's own calls play in any source, and classes can be Reach's troopers and Covenant, some of which fly.

New in 0.10.5: weapon tag paths in loadouts, waypoint timers and text on Halo 3's HUD, and Reach objective items and announcer lines on Halo 3 and ODST maps.

19mode sources to read, play and change
38player bodies: every Halo 3 character, Flood forms included
64teams and 128 classes a mode can have
32HUD widgets, placed anywhere and different for each player

What Megalo is

Megalo powers the scripted game types of Halo: Reach. Project Reclaimer has its own interpreter for the text language ReachVariantTool writes, and extends it for Halo 3. All of the game's bundled modes are written in it.

  • A mode is one file. Reclaimer's Megalo files end in .rmeg; ReachVariantTool's .rvt files read the same. The file's mode header holds the game type, rules, options and script settings, and the rest is the script. It plays as it is, from your Game Modes folder.
  • Only the host runs it. Players don't install or run the script. What it does reaches them through the game: scores, teams, traits, HUD widgets and menus, sizes, waypoints, sounds, bodies and looks.
  • It's checked before it runs. The game reads the whole file, the parts that never run included, and leaves out a mode that has a mistake or needs something Halo 3 can't play. Map assets, object lifetime and some argument limits can only be checked as the mode runs, so play your mode too.
  • It's Reach's language, not all of Reach's game. Many of Reach's calls work, Halo 3 adds many more, and a few of Reach's have nothing to do here: see Reach's calls, and what doesn't play. Compiled game variants (.bin, .mglo) and MegaloEdit's syntax aren't read.

The next three sections take you from nothing to a mode with a setting of its own. Then come the examples and the reference. To change a bundled mode instead, start from change a mode; to play the bundled ones, see game modes.

Your first mode

Every living player earns a point a second, a HUD row counts the seconds, and the round ends after a minute. All it takes is the game and a text editor, such as Notepad, TextEdit or Visual Studio Code.

  1. Open your Game Modes folderIn Host Game, choose Game Type, then Open Folder. It's in your player folder:
    SystemGame Modes folder
    Windows%LOCALAPPDATA%\ProjectReclaimer\Game Modes
    macOS~/Library/Application Support/ProjectReclaimer/Game Modes
    Linux~/.local/share/ProjectReclaimer/Game Modes (or under $XDG_DATA_HOME)
  2. Make the fileSave this as my-first-mode.rmeg in that folder, as plain UTF-8 text, or download it as megalo-timed-score.rmeg. Keep the extension: a file ending in .rmeg.txt is a different file.
    my-first-mode.rmeg
    -- Every living player earns a point a second; the round ends after a minute.
    --[=[ mode
    name = "My First Mode"
    ]=]
    
    alias interval = global.timer[0]
    alias elapsed = global.number[0]
    declare interval = 1
    
    on init: do
       interval.set_rate(-100%)
    end
    
    if interval.is_zero() then
       for each player do
          if current_player.is_not_respawning() then
             current_player.score += 1
          end
       end
       elapsed += 1
       interval.reset()
       interval.set_rate(-100%)
    end
    
    script_widget[0].set_text("Elapsed: %n", elapsed)
    script_widget[0].set_visibility(all_players, true)
    
    if elapsed >= 60 then
       game.end_round()
    end
  3. Choose itIn the game type picker, choose Refresh, select the Megalo card after the game types and click My First Mode. It's also among the variants of Slayer, the game type it plays. If the lobby runs a playlist, set Playlist to Off.
  4. Play itPick a multiplayer map and choose Start Game. While you're alive you earn a point a second, the HUD row counts up, and the round ends after a minute of play.
The game type picker, with a card for each game type and a Megalo card after them
The game type picker: every .rmeg in Game Modes is on the Megalo card.

Here's what you wrote. The block from --[=[ mode to ]=] is the mode header; all this one does is name the mode. What it leaves out keeps the default: Slayer, with no points per kill and no score limit. alias gives timer 0 and number 0 of the round names, and declare starts the timer at one second. on init runs once when the round starts, and sets the timer counting down. Everything outside it runs on every tick of the game: when the timer reaches zero, every living player scores, the count goes up and the timer starts again.

If the mode isn't listed, the file has a mistake: check it.

Make your first change

  1. Slow it downChange declare interval = 1 to declare interval = 2. Points now arrive every two seconds.
  2. Let hosts choose the lengthAdd a setting to the header, name it in the script, and use it in place of the 60:
    my-first-mode.rmeg, with a setting
    --[=[ mode
    name = "My First Mode"
    
    [logic.options]
    intervals = { value = 30, min = 5, max = 300 }
    ]=]
    
    alias intervals = script_option[0]
    alias interval = global.timer[0]
    alias elapsed = global.number[0]
    declare interval = 2
    
    on init: do
       interval.set_rate(-100%)
    end
    
    if interval.is_zero() then
       for each player do
          if current_player.is_not_respawning() then
             current_player.score += 1
          end
       end
       elapsed += 1
       interval.reset()
       interval.set_rate(-100%)
    end
    
    script_widget[0].set_text("Intervals: %n of %n", elapsed, intervals)
    script_widget[0].set_visibility(all_players, true)
    
    if elapsed >= intervals then
       game.end_round()
    end
  3. Reload itSave the file, choose Refresh and select the mode again: the lobby keeps the copy it loaded, and a round that's running keeps the script it started with.
  4. Change the settingIn Game Options, open Slayer Rules. intervals is listed under Custom Mode Options, on a track from 5 to 300. Save as Variant keeps your choice in a new file.

Change one rule at a time and check its result before building a larger mode. To play in teams, add "rounds.teams" = 1 under [options] in the header. Team scores add up their players' points, so a team with more living players earns faster.

Check a mode

The game itself has three commands for mode files. You don't need any of them to play a mode, but mode-check tells you what's wrong with one that isn't listed, with the line and column. Open a terminal and run the game with the command after its name:

Windows: PowerShell, in the game's folder
.\project-reclaimer.exe mode-check "$env:LOCALAPPDATA\ProjectReclaimer\Game Modes\my-first-mode.rmeg"
macOS: Terminal
"/Applications/Project Reclaimer.app/Contents/MacOS/project-reclaimer" mode-check ~/Library/Application\ Support/ProjectReclaimer/Game\ Modes/my-first-mode.rmeg
Linux: a terminal, in the game's folder
./project-reclaimer mode-check ~/.local/share/ProjectReclaimer/Game\ Modes/my-first-mode.rmeg

On Windows, a game that updated from 0.9 keeps its download's name: type .\project and press Tab. You can drag a file onto the terminal window to paste its path. A good file answers Valid custom mode: My First Mode (script version 2).

CommandWhat it does
mode-check FILEChecks a .rmeg, .rvt or .json mode the way the game does when it lists one: the header, the script, and that Halo 3 plays everything it asks for.
megalo-check FILEReads the script alone, checks its types and lists what it needs, such as timer.set_rate or write.player.score. It doesn't read the header or check that Halo 3 can do all of it.
mode-compile FILE --output NEW.jsonChecks the mode and writes the JSON game type it plays. Never needed to play a mode. The name comes from the header, else --name NAME, else the file. It never overwrites a file.
mode-compile … --mode MODEFor a source without a mode in its header: the game type, such as Territories.
mode-compile … --template PRESET.jsonLays the header over a saved JSON game type's settings instead of the defaults. Can't go with --mode.

The mode header

A block comment from a line --[=[ mode to ]=] holds the mode's settings as TOML. It can stand anywhere in the file; the bundled modes put it at the top, under a comment that says what the mode is. A source without a header plays as Slayer, with no points per kill and no score limit, named after its file.

zone-control.rmeg's header
--[=[ mode
name = "Zone Control"

[rules]
score_to_win = 30
kill_points = 0
death_points = 0
suicide_points = 0
betrayal_points = 0

[options]
"rounds.teams" = 0
"rounds.limit" = 1
"rounds.minutes" = 10

[logic.options]
points_per_second = { value = 1, min = 1, max = 10 }

[logic.objects.hill]
source = { kind = "zone" }
label = "objective"
shape = { kind = "sphere", radius = 8.0 }

[[logic.megalo_traits]]
aura = 4
speed = 7
]=]

A setting the game doesn't know, or a value out of range, keeps the mode out of the game type list; mode-check and the log say why. Option names have dots, so TOML needs them in quotes.

SettingWhat it holds
nameThe name the picker and lobby show, 1 to 48 characters. Without one, the file's name.
modeThe game type it plays. Slayer without one.
authorWho made it, up to 32 characters. The loading screen shows it.
[rules]Slayer's scoring: score_to_win (−1 to 500), kill_points, death_points, suicide_points and betrayal_points (−10 to 10). Other game types score through mode. options.
[options]Game options by name, as Game Options saves them.
[world]sprint ("off", "unlimited" or "stamina"), sprint_speed_percent, sprint_stamina_seconds, exposure (0.1 to 4) and atmospheric_fog (true or false). player_scale_percent isn't allowed: a script controls player size itself.
[base_map]The map the mode plays when nobody picks one, such as a server's variant, by id, stem and title: id = 380, stem = "riverworld", title = "Valhalla". In a lobby the host picks the map.
[logic.options]Settings hosts can change, each { value, min, max }. See options, traits and zones.
[logic.objects.NAME]Zones and objects the mode declares. See below.
[[logic.megalo_traits]]Trait sets, script_traits[0] and on, up to 16. See trait values.
[logic.deployment]Classes. See classes and class pickers.
logic.hud_layoutHow the script's first four widgets are laid out when they have no position: "objective_rows", the default, or "team_tickets": widget 0 blue, widget 1 red, then widgets 2 and 3 as centered status lines.
logic.scripted_round_endtrue: the game type's score, time and objective limits no longer end a round. The script ends it, with game.end_round() or team.end_round().
logic.seedWhere rand starts, a whole number from 0 up. The same seed gives the same numbers: call rand while players wait, as Flood Infection does, to vary them.

Write [logic] as a table of its own for the last three, as Conquest does:

Part of a header
[logic]
scripted_round_end = true
hud_layout = "team_tickets"
seed = 7

Game options by name

[options] takes every setting of Game Options. The quickest way to find one: change it in Game Options, choose Save as Variant and read the options of the .json file it saves. These are the names, with their values:

OptionValues
rounds.teams, rounds.reset_players, rounds.reset_map, rounds.friendly_fire, rounds.betrayal_booting0 off, 1 on. Capture the Flag, Assault, Territories and VIP always play in teams; Infection and Juggernaut never do.
rounds.limit1 to 10 rounds.
rounds.minutes0 (unlimited) to 60.
rounds.early_victoryWins for an early victory, 0 (off) to 5.
rounds.team_changing0 disabled, 1 enabled, 2 balancing only.
respawn.lives, respawn.team_lives0 (unlimited) to 50; to 100.
respawn.seconds, respawn.suicide, respawn.betrayal0 to 240 seconds.
respawn.growth, respawn.traits_duration0 to 15; 0 to 60 seconds.
respawn.synchronize, respawn.on_kills0 off, 1 on.
map.weapons0 default, 1 assault rifles, 2 dual wield, 3 hammers, 4 lasers, 5 rockets, 6 shotguns, 7 sniper rifles, 8 swords, 9 no power weapons, 10 no snipers, 11 no weapons, 12 random, 13 ODST weapons.
map.vehicles0 default, 1 none, 2 Mongooses, 3 light ground, 4 tanks, 5 aircraft, 6 no light ground, 7 no tanks, 8 no aircraft, 9 all.
map.grenades, map.indestructible_vehicles0 or 1.
powerups.red_duration, powerups.blue_duration, powerups.yellow_duration0 to 120 seconds.
player.… and the other trait sets belowThe trait names, with grenades (1 the map's, 2 none), forced_color (0 to 12), camera (1 third person, 2 first person), primary_weapon and secondary_weapon.
mode.…The game type's own options, below.

Trait sets: player, respawn_traits, red_powerup, blue_powerup and yellow_powerup in every game type, then Slayer's leader, Capture the Flag's flag_carrier, Oddball's ball_carrier, King of the Hill's hill_occupant, Infection's infected, initial_infected, safe_haven and last_survivor, VIP's vip_team, vip_proximity and vip, Juggernaut's juggernaut, Territories' defender and attacker, and Assault's bomb_carrier and bomb_arming.

Starting weapons: −3 random, −2 unchanged, −1 the map's, 0 Battle Rifle, 1 Assault Rifle, 2 Plasma Pistol, 3 Spiker, 4 SMG, 5 Carbine, 6 Energy Sword, 7 Magnum, 8 Needler, 9 Plasma Rifle, 10 Rocket Launcher, 11 Shotgun, 12 Sniper Rifle, 13 Brute Shot, 14 unarmed, 15 Beam Rifle, 16 Spartan Laser, 17 no weapon, 18 Gravity Hammer, 19 Mauler, 20 Flamethrower, 21 Missile Pod, 22 Sentinel Beam, 23 Fuel Rod Gun, 24 Silenced SMG, 25 Automag, 26 Brute Plasma Rifle, 27 Machine Gun Turret, 28 Plasma Turret, 29 Golf Club.

Game typemode. options
Slayerscore, kill, assist, death, suicide, betrayal, leader_kill, elimination, assassination, headshot, beatdown, sticky, splatter, spree, team_scoring
Capture the Flagscore, reset, sudden_death, touch_return, flag_at_home, flag_waypoint, flag_type, objective_respawn
Oddballscore, carrying, kill, ball_kill, carrier_kill, ball_count, spawn_delay, reset, auto_pickup, ball_effect, team_scoring
King of the Hillscore, uncontested, kill, inside, outside, opaque_hill, team_scoring, hill_movement, hill_order
VIPscore, kill, takedown, vip_kill, vip_death, arrival, suicide, betrayal, vip_suicide, radius, single_vip, destinations, end_on_vip_death, vip_selection, destination_movement, destination_order
Juggernautscore, kill, takedown, juggernaut_kill, arrival, suicide, betrayal, juggernaut_delay, allied_against_juggernaut, respawn_on_lone_juggernaut, destinations, initial_juggernaut, next_juggernaut, destination_movement, destination_order
Territoriescapture, sudden_death, one_sided, lock_on_capture, objective_respawn
Assaultscore, sudden_death, reset, arming, disarming, fuse, reset_on_disarm, objective_respawn, bomb_type, bomb_waypoint
Infectioninitial_count, haven_seconds, kill, infection, arrival, suicide, betrayal, last_survivor, respawn_on_haven_move, safe_havens, next_infected

Declared objects and zones

[logic.objects.NAME] declares up to 64 things by name, in letters, digits and underscores. A zone is there from the start of the round; the others are types that place_at_me takes by name.

SourceWhat it is
{ kind = "zone" }An invisible area with a shape. Players can't see it or bump into it; shape_contains tests it, and set_position moves it.
{ kind = "weapon", weapon = "rocket_launcher" }A weapon.
{ kind = "biped", biped = "marine" }A body.
{ kind = "stock", object = "warthog" }Equipment, a mounted gun or a vehicle.
{ kind = "tag", path = "objects/vehicles/mongoose/mongoose" }A tag path.
{ kind = "placement", index = 42 }An object of the saved map, by its place in it, 0 to 639. It works on that map only.

An object can also have a label for for each object with label, up to 32 bytes, and a position = [x, y, z], in Forge units, within 100,000. A shape is { kind = "sphere", radius = 8 }, { kind = "box", half_extents = [4, 4, 2] } or { kind = "cylinder", radius = 8, half_height = 3 }, each size above 0 and at most 10,000 Forge units. A declared shape lines up with the map's axes, and its edge counts as inside. Forge objects' own zones are turned with the object.

Game types

A mode plays any multiplayer game type. Its objectives, scoring, role traits and round rules keep running alongside your script. Forge and the campaign can't be scripted.

mode in the headerGame typegame.get_game_type()More than eight teams
SlayerSlayer2Yes
CaptureTheFlagCapture the Flag1No: eight teams
OddballOddball3Yes
KingOfTheHillKing of the Hill4Yes
VipVIP6Yes
JuggernautJuggernaut7No: no teams
TerritoriesTerritories8Yes
AssaultAssault9No: eight teams
InfectionInfection10No: no teams
EscalationSlayerEscalation Slayer12No

Keep the game type's own limits in mind, so they don't end a round your script means to go on: leave them off, or set scripted_round_end = true. A mode shows on the Megalo card, and among the variants of the game type it plays. A game type's map must have its objectives: Conquest needs Territories objectives, and a mode on Capture the Flag needs flags.

team.get_native_score() reads a team's score in the game type itself, game.get_territory_count() and team.get_territory_count() read Territories, and object.get_territory_owner() tells who holds one. is_of_type finds a flag, a bomb or an oddball. Scores your script keeps in its own numbers, such as tickets, are separate from the scoreboard's.

The examples

Every mode here passes mode-check, and plays as it is from your Game Modes folder. Download one, or read the same file in the Project Reclaimer folder of Game Modes for the bundled eight. Keep a changed copy under a new file name and a new name.

To learn from

Timed Score

The first mode above: timers, a player loop, scoring and the HUD. megalo-timed-score.rmeg

Grunts

Every player becomes a Grunt each time they spawn. Change grunt to another body, and the last none to a look such as heavy. megalo-player-bipeds.rmeg

Player Looks

Everyone plays as a white Spartan in Hayabusa armor with a blue visor. See looks. megalo-player-looks.rmeg

Object Controls

Each life gets a half-size, invincible Shotgun stuck to the player for five seconds; then it comes loose and drifts away. megalo-object-controls.rmeg

Expansions

A tour of the new calls: a training dummy that counts hits by kind, a barrel from its tag path and a copy of it, a Mongoose that takes you for a ride, and a respawn vehicle of your own. megalo-expansions.rmeg

Zone Traits

A hill that speeds up and lights up whoever stands in it, with points on a timer and two settings hosts can change. Set the hill's position in the header to a place on your map first. megalo-zone-traits.rmeg

Forge Labels

Finds the object you labelled door with Spawn Sequence 1 in Forge and makes it invincible. See Forge objects by label. megalo-forge-labels.rmeg

Battle Royale

Everyone is dealt into numbered squads of two on 32 teams, one life each; the last squad with a player alive wins. See the example. megalo-battle-royale.rmeg

Class Abilities

Team Slayer with an Infiltrator, an Engineer and a Medic on the players' ability keys. See the example. megalo-class-abilities.rmeg

Combined Arms

Two teams of six classes, reserved weapons and vehicles, revives, and four ways back into the fight. See Combined Arms. megalo-combined-arms.rmeg

Megalo Conquest

A small Conquest: tickets over Territories, with no classes or squads. See Conquest. megalo-conquest.rmeg

The bundled modes

The real thing, from a page of script to a whole class battle. The rules are on the game modes page.

ModeFileShows
Growthgrowth.rmegReading deaths and killers; size, damage and resistance together. The shortest bundled mode.
One in the Chamberone-in-the-chamber.rmegAmmunition and lethal damage.
Gun Gamegun-game.rmegset_weapon, how a player died, altif chains.
Zone Controlzone-control.rmegA declared zone moved at run time, per-player widgets and meters.
Flood Infectionflood-infection.rmegRoles, teams, a body for each life, trait sets, a winner chosen by the script.
UNSC vs Covenant vs Floodfaction-battlefront.rmeg70 classes on a two-page class picker built from widgets, other games' characters, reinforcement bars.
UNSC vs Covenant: Reachreach-battlefront.rmegHalo: Reach's characters and weapons as classes, bodies that fly, and a spare class for when a map can't have the others.
Conquestbf-conquest.rmegSquads, tickets, revives, beacons and the deployment map.

Conquest

bf-conquest.rmeg is the bundled mode built around the deployment map: two teams of five classes, in squads, fight over the map's territories for tickets. Its rules are on the game modes page; this is how it's made.

DesignHow
CapturingHalo 3's own Territories: mode = "Territories", on every map that has them.
TicketsEach team's in a global number. A death (on object death) costs its team one, and a Medic's revive gives it back. While one team holds more territories (team.get_territory_count()), the other loses one every few seconds. scripted_round_end = true, so the round ends only when the script says: out of tickets, or out of time.
SquadsA player new to a team joins the first squad with room for them: get_squad() counted over the team, then set_squad. player.team[0] remembers the team, to catch a change.
DeployingEach territory is its holder's deploy point. Each player's body is their squad's while they've been out of combat for five seconds. A Recon's beacon, a deployed radar jammer, is their squad's until the enemy destroys it.
ClassesAssault, Medic, Support, Engineer and Recon. Weapons are reserved with set_weapon_pickup, and abilities are as in Combined Arms.
HUDBoth teams' tickets as meters, the territories held and the time, then the class's abilities while alive. Widget 3 is the class picker's own status line: the class's name.

It has six settings: bleed_seconds, death_cost, round_seconds, squad_size, squad_spawn_seconds and tickets, read in that order as script_option[0] to [5].

megalo-conquest.rmeg is a smaller Conquest to read first. Red and Blue start with 300 tickets each. Every death costs a ticket; holding more than half of all flags, neutral flags included in the total, drains one enemy ticket a second. At zero tickets the other team wins; after 30 minutes, the side with more tickets wins, and equal tickets are a draw. It places its ticket counters with widgets, and its settings are bleed_interval, death_cost, round_seconds and tickets.

Combined Arms

megalo-combined-arms.rmeg is a class mode built from the calls on this page: two teams of six classes, picked in the class picker, with four ways back into the fight. Its first lines say what each class does.

DesignHow
Power weapons reserved for a class: rockets, Spartan Lasers, Fuel Rod Guns and Missile Pods for Anti-Armor, Sniper and Beam Rifles for ReconEach new life, set_weapon_pickup(all, 1), then a bar on each weapon of the other classes.
Only Pilots fly crewed aircraft, only Armor drives crewed ground vehiclesset_driver_use(multi_seat_aircraft, 0) for every class but the Pilot, and the same for ground vehicles. Anyone rides as a passenger or gunner.
Repairing a vehicle that still standsHold Ability 3: is_of_type(aircraft) or ground_vehicle, get_distance_to, and health up 5% twice a second while above 0.
Medic: revive the fallen, regeneratorson object death keeps the body and shows it to the team with a dead_teammate waypoint. Holding Ability 3 over it for two seconds revives. place_at_me(regenerator, …) deploys one.
Support: ammunition, overshieldsplace_at_me with an ammunition case's tag path, and refill_ammo for teammates beside it every 3 seconds; biped.shields = 200.
Anti-Armor: land mines, power draingive_equipment(trip_mine); place_at_me(power_drainer, …).
Recon: invisibility, marked targetsA trait set with camouflage; get_crosshair_target() and a bullseye waypoint for the Recon's team for 10 seconds.
Squad spawnsfor each player randomly, the first teammate with get_time_out_of_combat() >= 5 near an object labelled objective; set_primary_respawn_object(mate.biped).
Spawn beaconsObjects labelled spawn_beacon: attach_to its carrier, planted with detach and set_position. Ten enemy hits (on object damaged) send it back to its Forge place.
Spawn vehiclesVehicles labelled spawn_vehicle belong to their last driver's team (get_vehicle, is_driver), deploy after three seconds with get_speed() at most 2, and are destroyed when health is 0.

Label a map's objects in Forge to use the last three; without them, players spawn at the base.

Flood Infection

A complete team mode on Slayer: flood-infection.rmeg puts players in campaign Flood bodies, supplies the infection rules and picks the winning team. It's bundled, so choose it on the Megalo card. It needs Halo 3's campaign on the host. For a server, copy the campaign maps too: see files the host needs.

  • At least two living players start the ten-second outbreak countdown. One randomly chosen player becomes infected by default; the first count always leaves a survivor.
  • Survivors start with a Shotgun and Magnum. Only a lethal bite from a small Infection Form converts a survivor; ordinary melee, explosions, suicides and environmental deaths don't.
  • The infected get a random Human, Elite, Brute or Carrier form each life. Combat forms use unarmed melee; a carrier's melee sets off its self-destruct and a damaging explosion. Native death effects release Infection Forms. The infected can't pick up weapons or use vehicles.
  • Survivors win by lasting three minutes. The infected win when no survivors remain. The last survivor gains resistance and speed. The mode plays three rounds.
  • Players arriving after the outbreak join the infected. If the last infected player leaves while at least two players remain, a replacement is chosen.

Hosts can change it under Game Options → Slayer Rules → Custom Mode Options:

OptionScript readsDefaultRange
initial_infectedscript_option[0]11 to 8; at the outbreak, one survivor is always left.
round_secondsscript_option[1]18030 to 900 seconds.
warmup_secondsscript_option[2]100 to 60 seconds.

It shows team assignment, infection death counts and team round endings, bodies, and per-player HUD visibility. Test conversions, respawns, a late join and both winning conditions before sharing an edited version.

The language

The dialect is ReachVariantTool's: alias, declare, enum, function, on EVENT: do … end, for each, and if … then … altif … then … alt … end. Comments start with --; Lua's block comments, --[[ … ]] and --[==[ … ]==], work anywhere. do … end makes a block of its own. Text goes in double or single quotes; \n, \t, \\, \" and \' are escapes.

Variables

Scripts keep whole numbers, references to objects, players and teams, and timers, in numbered slots that belong to the round (global), to a player, a team or an object, or to the current tick only (temporaries):

Belongs toNumbersObjectsPlayersTeamsTimers
global1216888
object84424
player84444
team86444
temporaries108360
  • Slots count from 0 and must be plain numbers: global.number[11] is the last global number. A player's slots belong to that player: current_player.number[0]. A reference holds at most two indexed levels.
  • declare is only needed for a starting value: declare player.number[0] = 3. Numbers and timers otherwise start at 0, references at no_object, no_player or no_team. Only numbers and timers take a starting value, and temporaries none. with network priority low or high is accepted and ignored; local isn't accepted.
  • alias points = player.number[0] gives a slot a name, used as current_player.points. alias scratch = allocate temporary number or allocate global.number takes a free one for you; don't also write to that slot by number. An alias can name a constant or a script_option[n] too. Aliases last to the end of their block.
  • References stay on what they point at: when a player leaves or an object is deleted, a saved reference becomes no_player or no_object, never someone or something else. A call on one does nothing and gives 0 or nothing back. A player's variables stay through respawns, and every round starts fresh.
  • Inside loops, current_player, current_object and current_team are the one being visited; team[0] to team[7] (to the last of the teams a script declares) and neutral_team are fixed teams.

Numbers, enums and functions

Numbers are whole, from about −2.1 billion to 2.1 billion, and wrap around past that. Write them as decimal, 0x hexadecimal or 0b binary. Arithmetic is done with assignments: =, +=, -=, *=, /= (rounds toward zero), %=, and the bit operations &=, |=, ^=, ~= (clear bits), <<= and >>=. A call takes values, not sums: get_z() + 1 isn't accepted as an argument, so work the number out in a variable first (next_z = current_player.biped.get_z(), next_z += 1) and pass the variable. References only take =. rand(4) is a whole number from 0 to 3, following the mode's seed; zero or less gives 0. abs(-7) is 7. Dividing by zero stops the script.

Enums and functions
enum Points
   ordinary = 1
   bonus
end

function award_bonus()
   current_player.score += Points.bonus
end

Enum entries count up from the last value, starting at 0. Functions take no arguments and return nothing; they work on the caller's current player, team and object. Declare a function before using it. A function may call itself, within the step limits.

Values and conditions

  • Arithmetic is one step at a time. Write global.number[0] = 5, then global.number[0] += 2. There's no 5 + 2.
  • A call that gives a value goes in an assignment. current_player.get_death_count() can't stand alone, go straight in an if, or take a call after it: current_player.get_weapon(primary).get_x() is two steps, through a variable.
  • **Condition calls go in an if, and nowhere else:** is_zero, is_not_respawning, has_any_players, has_alliance_status, shape_contains, is_of_type, has_forge_label, is_button_held and is_driver.
Part of a script
for each player do
   global.number[0] = current_player.get_death_count()
   if global.number[0] > 3 and current_player.is_not_respawning() then
      current_player.score += 1
   end
end

if … then … end tests comparisons (== != < <= > >=, and only == and != on references) and condition calls, joined with not, and and or. As in ReachVariantTool, or binds first: A or B and C means (A or B) and C; nest ifs for anything else. altif and alt check their conditions again rather than remembering which branch ran, so a branch that changes the value being tested can let a later one run too.

Loops

LoopGoes through
for each player doEvery player in the game, dead ones too. Check current_player.is_not_respawning() for the living.
for each player randomly doThe same players in a shuffled order.
for each team doThe playable teams (8, or as many as the mode declares) and the neutral team, empty ones too.
for each object doEvery object in the world, up to 8,192: players' bodies, the map's objects, the script's own and its zones.
for each object with label "gift" doThe objects with that label: the mode's own, the script's, and Forge's. A label is a text or a whole number.

A loop gives its current player, team or object back when it ends.

Events and timers

Everything outside an event runs on every tick of the game, after that tick's deaths and spawns. A paused game has no ticks. An event has one handler, at the top level of the file:

Eventcurrent_… in itValues in it
The script's bodyNone until a loop sets oneRuns every tick.
on init: do … endNoneOnce, as each round starts.
on widget click: do … endThe player who clickedclicked_widget: the widget's number. See script menus.
on button press: do … endThe player who pressedpressed_button: button.melee and so on. See buttons.
on object damaged: do … endcurrent_object: the object hit (no_object once gone). current_player: who's responsible (no_player for the world or the AI).damage_category: damage.bullet and so on. See damage.
on object death: do … endThe player whose body diedkilled_object: the body, while it lies there. killer_player: no_player after a suicide, a betrayal or a death to the world or the AI. killer_object: the killer's body.

Outside their events, clicked_widget, pressed_button and damage_category are −1. on object damaged runs once for every hit on every object while a round is played: each round of automatic fire, and each object a blast reaches. Keep its handler short.

A death, as it happens
on object death: do
   if killer_player != no_player then
      killer_player.score += 1
      current_player.score -= 1
   end
end

Reach's pregame runs before init as a round starts, and local each tick once for each player: see Reach's calls.

Timers

  • Timers count seconds, fractions included. set_rate(-100%) counts down one second per second of play, 100% counts up, 0% stops. Other rates: 10, 25, 50, 75, 125, 150, 175, 200, 300, 400, 500 and 1000%, either sign, written as a plain value.
  • A timer counting down stops at 0. reset() puts back its declared value but keeps its rate, so call set_rate again for a timer that repeats. is_zero() is a test, not an event: check it every tick.
  • A timer counting up stops at its declared value if that value is above 0. Assignment and arithmetic can change a timer's value; it can't go below zero. Reading a timer into a number drops the fraction.

Units

QuantityUnit
Positions (get_x, set_position), distances (get_distance_to), creation and attachment offsetsTenths of a Forge unit. A Forge unit is 10 feet, so a tenth is a foot.
move_to, a position in the header, zone sizesWhole Forge units.
Velocities (set_velocity)Forge units a second.
Speeds (get_speed)Feet a second.
FacingsWhole degrees. Yaw from the world's x axis towards its y axis, 0 to 359; pitch nose up, −90 to 90; roll right side down, −180 to 180.
Health, shields, sizes, damagePercent.

Players, teams and the round

current_player means the player selected by a loop or event; saved player and team references work too.

The player

CallWhat it gives or does
bipedThe player's body, or no_object while they're dead.
scoreTheir score this round, to read or change, by up to 100 points at a time. The game type's score limit still ends the round.
teamTheir team, to read or change. Changing it needs a team game and a team the map allows or the mode declares; neutral_team and no_team aren't teams to join.
is_not_respawning()(condition) True while the player is alive.
get_death_count()Their deaths this round, including one followed by a respawn between ticks. Stays through respawns, resets on leaving or a new round.
get_kill_count()Enemy kills this round, including by a projectile that lands after the player died. Suicides and kills of teammates don't count.
get_infection_death_count()Deaths to a lethal Infection Form bite this round.
get_respawn_time()Whole seconds left on their respawn countdown; 0 while alive or once they may respawn.
get_killer()The player who killed them last; no_player after a suicide, a betrayal or a death to the world.
get_death_damage_mod()How they died last: damage_mod.none, damage_mod.pummel (a beat-down; the sword's and the hammer's strikes are weapon kills) or damage_mod.assassination (an attack from behind, theirs too).
get_time_out_of_combat()Whole seconds since an enemy last hurt them or they hurt one: a player, in a body or a vehicle, or the AI. Falls and their own damage don't count.
get_crosshair_target()The object under their crosshair, up to 100 Forge units away, unless the level is in the way; no_object for none or a dead player.
apply_traits(script_traits[0])Gives them a trait set for this tick. See traits.
play_sound("path")Plays a sound once, for that player alone.
set_ui_menu(true), is_ui_menu_open()Opens or closes their script menu; 1 while it's open.
is_button_held(button.ability_1)(condition) True while they hold that button. See buttons.

Weapons and damage

CallWhat it does
get_weapon(primary), get_weapon(secondary)The weapon in the body's hands, and the other it carries.
set_weapon(weapon)The weapon the mode keeps in their hands: a name such as battle_rifle, or a weapon's tag path, including a mod's or another game's weapon loaded on this map. Given at once, again to each new body, and again if they drop it. none stops.
get_ammo(), set_ammo(rounds)The rounds of the weapon in their hands, 0 to 999.
refill_ammo()Every weapon the living player carries gets a full magazine and its most rounds.
give_equipment(name)Equipment for their body to use, in place of what it carried; none takes it away. See give equipment.
set_weapon_pickup(weapon, 0 or 1)Whether they may pick up a weapon: a weapon's name, a weapon's tag path, or all. all, 0 bars every weapon and all, 1 lifts every bar; at most 16 bars. The mode's own gives still arm them.
set_damage_modifier(percent)The damage they deal, 10% to 300% of their own.
set_damage_resistance(percent)How much damage they shrug off: what they take is divided by this, 10% to 1000%.
set_lethal_damage(0 or 1)Whether their damage to other players kills outright.

Vehicles

CallWhat it does
get_vehicle()The vehicle the body rides.
get_seat()The seat's number in the vehicle; −1 on foot.
is_driver()(condition) The body has a driver's seat.
force_into_vehicle(vehicle)The body takes a free seat of the vehicle it may take, the driver's first, wherever it is; nothing when none is free or the vehicle is overturned. The script sees the seat at once: get_vehicle, get_seat and is_driver read it in the same tick when a player on foot is forced into a vehicle with a seat no player sits in, and the game's own answer follows the next tick.
set_respawn_vehicle(name)Each new body rides a new vehicle of this kind, made where it stands: a stock vehicle's name such as mongoose, a vehicle's tag path, or none to stop. The player's empty one from a life before goes.
set_driver_use(vehicles, 0 or 1)Whether they may take the driver's or pilot's seat: vehicle (every one), a kind of vehicle, a stock vehicle's name such as hornet, or a vehicle's tag path. They still ride as passengers and gunners; vehicle, 1 lifts every bar. At most 16 bars.
set_vehicle_use(0 or 1), set_turret_use(0 or 1)Whether their bodies may ride vehicles, or use turrets. See health, shields and seats.

The body

CallWhat it does
set_biped(body)Moves a living player into a living, unattached biped no other player has. See players in other bodies.
set_max_health(percent), set_max_shields(percent)Their bodies' health and shields, 1% to 1000% of the normal, for every life from now on.
set_camera_mode(0 or 1), get_camera_mode()0 Halo 3's camera, 1 third person on foot. Vehicles and death keep Halo 3's.
get_squad(), set_squad(n), get_last_deployment_class()See squads and classes.
set_primary_respawn_object(object), set_respawn_time(seconds)See spawning and reviving.
set_model, set_armor, set_armor_color, set_visor_color, reset_lookSee looks.

Teams and the game

CallWhat it does
team[0].scoreThe team's score: its players' scores added up. Read only.
team[0].has_any_players()(condition) True when someone's on the team.
team[0].has_alliance_status(team[1], enemies)(condition) Tests two teams, with allies, enemies or neutral: a team is allied with itself, two different teams are enemies, and the neutral team is neutral. It doesn't change alliances.
team[0].end_round()Ends the round with this team as winner. Needs a team game and an occupied playable team; a neutral or empty team stops the script.
team[0].get_native_score()The team's score in the game type itself, such as Territories' points.
team[0].get_territory_count()The territories it holds.
team[0].set_name("Squad %n", 1), team[0].set_color(255, 140, 0)See team names and colors.
game.end_round()Ends the round. Points the script gave first still count; the round has no chosen winner, so the score decides.
game.get_round()The round's number, 0 the first.
game.get_game_type()The game type's number.
game.get_territory_count()The map's territories in a Territories game.
game.set_ai_team(label, team)See Forge and AI.
game.play_sound("path"), game.start_looping_sound, game.stop_looping_soundSee sounds.
game.respawn_objects("label")See taken away and made again.

Scripted team changes can leave a team empty without the game type's last-team forfeit, so give the mode a round-ending rule of its own.

Health, shields and seats

A script can give any character more or less health and shields than Halo 3 does, and keep it out of vehicles or turrets. On a body, such as current_player.biped:

On a bodyWhat it does
max_health = 200, max_shields = 50The maximum health and shields, in percent of the character's own, 1 to 1000. 100 is as Halo 3 has it; 200 takes twice the damage to drain. Shields change only on characters that have them. Changing a maximum keeps the share of each that's left.
health = 50, shields = 150How much is left right now, in percent of the maximum. health takes 1 to 100; use kill(false) for none. shields takes 0 to 400, past 100 an overshield like an overshield powerup's. Health and shields set lower wait to recharge, as after a hit.
set_vehicle_use(false)Keeps the character out of every vehicle seat: driver, gunner and passenger, a Warthog's or Scorpion's gun included.
set_turret_use(false)Keeps it out of turrets: the stand-alone guns, such as the machine-gun turret, plasma cannon and missile pod, and the Shade.
  • Refused seats: a player trying to get in sees Halo 3's “can't use” prompt, AI stops choosing those seats, and a character already in one gets out. true lets it in again.
  • On a player's body the values belong to the player and stay for every life from then on; each new life starts full at the new maximum.
  • On an AI's body they belong to that AI, and on any other object, such as a vehicle, to that object.
  • The host sets them, and every player sees the result.

UNSC vs Covenant vs Flood gives each of its classes its own this way, on every body:

Part of faction-battlefront.rmeg
-- Hunters: twice the health, too big for any seat.
if class == 33 then
    current_player.set_max_health(200)
    current_player.set_vehicle_use(false)
    current_player.set_turret_use(false)
end

Spawning and reviving

CallWhat it does
set_primary_respawn_object(object)The dead player spawns beside the object while it's there: on clear ground just past its bounds, each player their own way round, else on top of it. A teammate's body, a beacon, a vehicle or a body that fell all work, for joiners too. no_object spawns them where Halo 3 does.
set_respawn_time(seconds)A dead player's respawn countdown, 0 to 3,600; 0 respawns them at once. A class mode still waits for their class (deploy_class).

To revive a fallen player where they fell, keep their body from the object death event and respawn them beside it at once:

A medic's revive
alias fallen = global.player[0]

on object death: do
    current_player.object[0] = killed_object
end

-- With fallen the dead teammate:
global.number[0] = fallen.get_last_deployment_class()
global.number[1] = fallen.deploy_class(global.number[0])
fallen.set_primary_respawn_object(fallen.object[0])
fallen.set_respawn_time(0)
-- Once they are back (is_not_respawning), the old body can go:
-- current_player.object[0].delete()

Pick spots with room around them. For Conquest-style rules, check who holds a point before you send a player there, and send them elsewhere, or no_object, once the enemy takes it.

Squads and the deployment map

A mode with classes and deploy points shows its dead the deployment map in place of the class cards: the classes and the places to deploy on a panel, beside the game seen from high above, with the territories in their holders' colors, the places the player may deploy, their squad, named and in green, and every living teammate. It works on every map; an indoor map is cut away above its highest places. The map shows from the player's death. They choose a class and a place on the panel or on the map while the respawn countdown runs, and deploy as it ends: beside the place they chose, if they still may deploy there, else at the team's own spawn points, HQ. Split screen keeps the class cards.

The deployment map: the battle seen from above, with territories and deploy points marked
Conquest's deployment map.
CallWhat it does
set_squad(n), get_squad()A player's squad in their team, 1 to 16; 0 for none. The map shows a player their squad, and a squad's own deploy points.
object.set_deploy_point(team)The team's players may deploy beside the object, on clear ground just past it. no_team takes it away. At most 64 at once. One goes with its object, and a body only counts while its player lives.
object.set_deploy_point(team, squad)Only that squad of the team's; 0 for every one.
object.get_territory_owner()The team holding a territory of Halo 3's Territories, by its marker object, else no_team.

The map shows the places a player may use, named for what they are: a territory by its number, a player's body by the player's name, anything else as a deploy point. In a Territories game, the objects with a zone of their own are the territories' markers:

Part of a script
for each object do
    if current_object.shape_contains(current_object) then
        global.team[0] = current_object.get_territory_owner()
        current_object.set_deploy_point(global.team[0])
    end
end
-- Squad mates out of combat for five seconds.
for each player do
    global.number[0] = current_player.get_squad()
    global.number[1] = current_player.get_time_out_of_combat()
    if current_player.is_not_respawning() and global.number[1] >= 5 then
        current_player.biped.set_deploy_point(current_player.team, global.number[0])
    alt
        current_player.biped.set_deploy_point(no_team)
    end
end

Looks

A mode can give a player a look over the one they picked; what it leaves out stays theirs. Every machine in the game draws it.

CallWhat it does
set_model(spartan), set_model(elite)From the player's next body.
set_armor(region, piece)At once. Regions: helmet, left_shoulder, right_shoulder, shoulders (both) and chest. A Spartan piece dresses the player when they play a Spartan, an Elite piece when they play an Elite.
set_armor_color(channel, color)At once. Channels: primary, secondary and detail. Colors win over team colors.
set_visor_color(r, g, b)The visor, 0 to 255 each.
reset_look()The player's own look again.
PieceNames
Spartan helmetsmark_vi, cqb, eod, eva, hayabusa, mark_v, odst, recon, rogue, scout, security
Spartan shouldersmark_vi, cqb, eod, eva, hayabusa, recon, scout, security
Spartan chestsmark_vi, bungie, cqb, eod, eva, hayabusa, katana, recon, scout
Elite, every regioncombat, assault, flight, commando, ascetic
Colorssteel, silver, white, red, mauve, salmon, orange, coral, peach, gold, yellow, pale, green, sage, lime, teal, aqua, cyan, blue, cobalt, sapphire, violet, orchid, lavender, crimson, ruby, pink, brown, tan, khaki
megalo-player-looks.rmeg, in short
for each player do
    current_player.set_model(spartan)
    current_player.set_armor(helmet, hayabusa)
    current_player.set_armor(shoulders, hayabusa)
    current_player.set_armor(chest, hayabusa)
    current_player.set_armor_color(primary, white)
    current_player.set_visor_color(40, 90, 255)
end

A look lasts until the round ends. A body other than Halo 3's Spartan and Elite, set_biped's or a customization mod's character, keeps its own armor, and a customization mod's character keeps its own colors and team rules.

To make players Elites, use set_model(elite): their next body is an Elite the way Halo 3 makes one, with the Elite's first-person arms and HUD and their own Elite armor. set_biped with an Elite body gives the Elite's HUD and body, but the first person stays the player's own model's arms. Halo 3 draws no first-person legs for any character.

More teams, names and colors

A team game's script can have up to 64 teams, where Halo 3 stops at eight. Declare how many once, at the top level of the script, from 2 to 64:

Part of a script
declare team_count = 32

team[0] to team[31] then exist, for each team visits all 32 and the neutral team, and current_player.team can be set to any of them. They work like Halo 3's teams: teammates can't hurt each other, the scoreboard, game-over screen and carnage report group and score them, and team chat and team voice follow them. Without a declaration the map and game type decide, with at most eight. A mode with classes has as many teams as its teams, and a team_count must match them. Game types says which can have more than eight.

  • Play it with teams: set "rounds.teams" = 1 in the header.
  • VIP: every team has its own VIP. A one-VIP game gives the VIP to one of the first eight teams.
  • Territories: any team captures and holds territories. One-sided Territories defends with one of the first eight teams.
  • The declaration replaces the map's own team count in the game types that can have more than eight, so a map made for four Territories teams can play eight or more. In the others it can only lower it.
  • Rotating sides in one-sided and attack/defend variants keep rotating among the first eight teams.
  • In the lobby players are put on two teams as usual. The script deals them into the others, for example at the start of the round.

Team names and colors

The first eight teams keep Halo 3's names and colors, Red, Blue and so on to Pink. Teams 9 to 64 are “Team 9” to “Team 64”, each with a color of its own. A script renames and recolors any of them:

Part of a script
declare team_count = 16

on init: do
   for each team do
      if current_team != neutral_team then
         current_team.set_name("Squad")
      end
   end
   team[0].set_name("Alpha")
   team[0].set_color(255, 140, 0)
end
CallWhat it does
team[3].set_name("Squad %n", 4)The team's name everywhere players see it: the score display, scoreboard, game-over screen, carnage report, team chat, HUD messages and the team picker. As in widget text, %n puts in a number, up to three, and %% is a percent sign. 1 to 24 bytes, with no control characters. The neutral team has no name to set.
team[3].set_color(255, 140, 0)The team's color, red, green and blue from 0 to 255 each: the armor its players wear, the score display and every menu that colors the team. Players already alive change color at once.

Names and colors set to constants, such as team[3].set_name("Bravo"), show in the lobby before the game starts; others appear once the script runs.

Forge and AI

In Forge, every object's Team row lists all 64 teams: starting and respawn points, team barriers and AI spawners can belong to Team 9 and later as they can to Red or Blue. A team past the first eight with no spawn points of its own starts at any start point, as in free for all.

game.set_ai_team(label, team) puts the AI of every Forge AI spawner with that Forge label on a team for the rest of the game: team[5] or any other, neutral_team (enemy of all), all_players (ally of all players) or no_team (the spawner's own Team again). AI already alive changes to its new team.

Part of a script
declare team_count = 16

on init: do
   game.set_ai_team("wardens", team[12])
end

Battle royale example

megalo-battle-royale.rmeg plays battle royale in squads of two on 32 teams. Its header turns teams on and gives everyone one life, so a player who dies stays out. Five seconds into the round it names the teams Squad 1 to Squad 32 and deals the players into them two at a time, in order. From then on it counts the squads with a player who hasn't died, and when one is left, that squad wins the round.

Part of megalo-battle-royale.rmeg
--[=[ mode
name = "Battle Royale"

[options]
"rounds.teams" = 1
"respawn.lives" = 1
]=]
declare team_count = 32
-- Each squad's next squad, and whether it has a player alive.
alias next = team.team[0]
alias alive = team.number[0]

-- Number the squads and chain each to the next.
previous = no_team
squad_number = 0
for each team do
   if current_team != neutral_team then
      squad_number += 1
      current_team.set_name("Squad %n", squad_number)
      if previous != no_team then
         previous.next = current_team
      end
      previous = current_team
   end
end

Each team's own variables, team.team[0] and team.number[0], chain the squads in order and mark the ones still standing. For squads of three or more, change the 2 in if in_squad == 2 then; for fewer teams, lower team_count.

Players in other bodies

A script can create a character and hand a player's control over to it, with every character in Halo 3's maps and, with them installed, other games', and the last argument of place_at_me picks the character's look. The Grunts example does it each time a player spawns:

megalo-player-bipeds.rmeg
for each player do
    if current_player.is_not_respawning() then
        if current_player.object[0] != current_player.biped then
            global.object[0] = current_player.biped
            global.object[1] = current_player.biped.place_at_me(grunt, "player_body", none, 0, 0, 0, none)
            current_player.set_biped(global.object[1])
            global.object[0].delete()
            current_player.object[0] = current_player.biped
        end
    end
end

Name the body in place_at_me, then hand the new object to current_player.set_biped. set_biped takes the object the call returns, not a character name.

Every body

Each body comes from one of Halo 3's maps, named below with its file. Only Floodgate's female civilian is missing: the one map that has her keeps her without her model, textures or shaders, so she can't be drawn.

NameCharacterComes fromModel variants (looks)
spartanSpartan (multiplayer)Every multiplayer mapdefault, blue, red, green, orange, purple, gold, brown, pink
eliteElite (multiplayer)Every multiplayer mapdefault
forge_monitorForge's monitorEvery multiplayer mapmonitor
master_chiefMaster Chief (campaign)The Storm (040_voi)default, cinematic
arbiterArbiter (co-op player)The Storm (040_voi)default_arb
arbiter_aiArbiter (campaign AI)The Storm (040_voi)default_arb, nude, nude_branded
elite_coopElite (co-op players 3 and 4)The Storm (040_voi)default, player4
marineMarineThe Storm (040_voi)default, ma1…ma6, sg1, sg2, pilot, wounded, blind, dead, sarge_lehto, johnson, johnson_combat, johnson_dress, johnson_beatup, johnson_dead, cinem1…cinem7, cinem8a…cinem8j
marine_femaleMarine (female)The Storm (040_voi)default, fem1, fem2, fem3, no_helmet, anete, chan, hartmann, michelle, cinef1, cinef2
odstODSTThe Ark (070_waste)default, captain
johnsonSergeant Johnson (Halo)Halo (120_halo)As marine
crewmanNaval crewmanCrow's Nest (020_base)ethnic, lessethnic
lord_hoodLord HoodCrow's Nest (020_base)default, no_hat, dress, dress_no_hat
mirandaMiranda KeyesCrow's Nest (020_base)default, combat, dress, dead
workerCivilian workerThe Storm (040_voi)default, cv1, cv2, dead
cortanaCortanaCortana (110_hc)default
cortana_near_deathCortana (High Charity)Cortana (110_hc)default
gruntGruntThe Storm (040_voi)minor, major, ultra, spec_ops, heavy
jackalJackalThe Storm (040_voi)minor, major, shieldless, sniper
droneDroneThe Storm (040_voi)minor
elite_warriorElite (campaign)The Storm (040_voi)minor_scl, minor_dog, major_scl, major_dog, spec_ops_scl, spec_ops_dog, stealth_scl, stealth_dog, stealth_major_scl, stealth_major_dog, soc, soc_cinematic
bruteBruteThe Storm (040_voi)minor, major, ultra, captain, captain_major, captain_ultra, bodyguard, jumppack, stalker, tracker, chieftain_armor, chieftain_weapon
brute_chieftainBrute ChieftainThe Storm (040_voi)As brute
brute_jumppackBrute (jump pack)The Ark (070_waste)As brute, without ultra and captain_ultra
hunterHunterThe Storm (040_voi)minor
truthProphet of TruthCrow's Nest (020_base)default, floodified
truth_hologramProphet of Truth (hologram)The Storm (040_voi)None to choose: use none
guilty_spark343 Guilty SparkThe Ark (070_waste)monitor, monitor_combat
sentinelSentinelThe Ark (070_waste)default
sentinel_constructorSentinel constructorThe Ark (070_waste)default
flood_infectionFlood Infection formThe Covenant (100_citadel)default
flood_humanFlood combat form (Human)Floodgate (050_floodvoi)standard_fch
flood_eliteFlood combat form (Elite)Floodgate (050_floodvoi)standard_fce
flood_bruteFlood combat form (Brute)Floodgate (050_floodvoi)default
flood_carrierFlood carrier formFloodgate (050_floodvoi)default, shielded
flood_rangedFlood pure form (ranged)Floodgate (050_floodvoi)None to choose: use none
flood_stalkerFlood pure form (stalker)Floodgate (050_floodvoi)None to choose: use none
flood_tankFlood pure form (tank)Floodgate (050_floodvoi)default

Halo 3 has no Zealot: Elites come in the ranks above, and elite_warrior's soc is the spec ops commander.

A player in a body keeps its abilities: the Sentinel fires its beam and the ranged form its spines, the Flood forms and the Hunter melee with their own body, a carrier's melee bursts it into infection forms that fight for its player (their kills are the player's), and the jump-pack Brute flies while jump is held in the air.

A body that flies does for its player: jump climbs and crouch descends, at the body's own speeds. The Sentinel and Reach's Engineer are always in the air and move where their player looks. The Drones, Halo 3's and Reach's, take wing when jump is held, hover and fly while in the air, and walk again once back on the ground.

Other games' bodies

With Halo: Reach, Halo: Combat Evolved or Halo 2 installed, a mode can name their characters too, in place_at_me, set_biped and a class's biped, on its own game's maps and on the classic games' maps too. Each keeps its own game's health, shields, movement and animations, and a class's traits and health go over them. Players who join then need that game.

GameNamesWhere
Halo: Reachreach_spartan, reach_eliteReach's maps; Halo 3's and ODST's with every armor piece; Combat Evolved's and Halo 2's. On another game's map only while the host's Halo: Reach Spartans and Elites is on
Halo: Reach's missions and Firefightreach_trooper, skirmisher, reach_grunt, reach_jackal, reach_brute, reach_brute_chieftain, reach_hunter, reach_drone, reach_engineer, reach_gutaReach's maps only, with one of Reach's missions or Firefight maps that holds the character installed. The Drone and the Engineer fly; the Gúta, five metres tall, is for open ground. A class's model_variant picks a look: trooper_heavy, odst_light, jackal_sniper, skirmisher_major, a Grunt's heavy and so on
Halo: Combat Evolvedhalo1_chief, halo1_marine, halo1_elite, halo1_grunt, halo1_jackal, halo1_hunter, halo1_flood_human, halo1_flood_elite, halo1_flood_carrier, halo1_flood_infectionHalo 3's, ODST's, Reach's and Halo 2's maps; on Combat Evolved's own, halo1_chief alone
Halo 2halo2_spartan, halo2_elite, halo2_master_chief, halo2_marine, halo2_arbiter, halo2_brute, halo2_grunt, halo2_jackal, halo2_drone, halo2_hunter, halo2_flood_human, halo2_flood_elite, halo2_flood_carrier, halo2_flood_infectionHalo 3's, ODST's, Reach's and Combat Evolved's maps; on Halo 2's own, halo2_spartan and halo2_elite alone

A character a map can't have makes nothing: place_at_me gives no_object, and a class of it is left out of the picker. Host Settings' Other games' characters, on by default, and a server's other_game_characters turn them off, so anyone with the map's game may join. Reach's Spartan and Elite also follow the host's Halo: Reach Spartans and Elites permission (a server's reach_characters), on Halo 3's, ODST's, Combat Evolved's and Halo 2's maps alike. Halo 3's and ODST's own characters come onto Reach's, Combat Evolved's and Halo 2's maps as they do onto Halo 3's.

Choosing a look

The last argument of place_at_me picks one of the body's model variants from the table, as a plain name or as text. none gives the body its default look, as Halo 3's own spawns do:

Part of a script
global.object[1] = current_player.biped.place_at_me(brute, "boss", none, 0, 0, 0, chieftain_armor)
global.object[2] = current_player.biped.place_at_me(grunt, "heavy", none, 0, 0, 0, "heavy")
  • Other examples: spec_ops_scl for elite_warrior, johnson for marine, captain for odst.
  • Only bodies take a variant. A variant name is ASCII letters, digits and underscores, at most 32 bytes.
  • The name is checked against the body when the body is created: a variant that body doesn't have stops the script, and the host's log says why.

What changes and what stays

  • What changes: the player plays as that character, with its animations, weapon handling, camera and vehicle seats as Halo 3 made them. They start unarmed: weapons aren't carried over, but set_weapon and ammo effects follow the new body. There are no new first-person arms.
  • Characters players never controlled: Cortana, the Prophet of Truth, Guilty Spark and the like move and attack only as far as their own animations and physics allow.
  • What stays: their variables, team and score. current_player.biped is the new body at once.
  • The old body stays where it was until the script deletes it, as the example does, or the game cleans it up.
  • Death: players respawn as usual, in their normal body. Keep the body you gave them in a player variable and compare it with current_player.biped, as the example does, to change each new life once. Creating a body on every tick runs out of objects.
  • Refused: a dead player, a target that isn't a living, unattached character, or one another player controls stops the script. A no_object target does nothing.
  • Classes take the same names in their biped and the same looks in model_variant; see classes and class pickers.

Files the host needs

  • The host needs the Halo 3 campaign map each body comes from, as named in the table. The game adds the characters the mode names to the map when the game starts, for any map the mode plays on. spartan, elite and forge_monitor need nothing extra.
  • A body no installed map has falls back to the game's own Spartan or Elite, and the host's log says so.
  • Players who join make the same map from their own files, mid-game too, and download what they lack from the host.
  • Dedicated servers: copy the campaign maps with dedicated init --from --maps campaign. See campaign files.
  • Forge's AI spawners are unchanged: these bodies are for scripts, and Forge's palette keeps its own characters.

Carrier melee sets off its native self-destruct; the other forms use their native unarmed attacks. These body types don't turn on the Infection game type's rules.

Options, traits and zones

Settings hosts can change, trait sets and zones live in the mode header, and the script reads them by number. megalo-zone-traits.rmeg has one of each:

Part of megalo-zone-traits.rmeg
--[=[ mode
name = "Zone Traits"

[logic.options]
goal = { value = 30, min = 1, max = 100 }
interval = { value = 1, min = 1, max = 10 }

[logic.objects.hill]
source = { kind = "zone" }
position = [0, 0, 0]
label = "objective"
shape = { kind = "sphere", radius = 8 }

[[logic.megalo_traits]]
speed = 7
aura = 4
]=]
  • Options: script_option[0] is the first option in alphabetical order, so here goal is 0 and interval is 1; an option added earlier in the alphabet moves the others up. A name is up to 32 letters, digits and underscores. A mode can declare 32, and the script reads the first 16 by number, as whole numbers, so keep ranges whole. Hosts change them under Game Options → Slayer Rules → Custom Mode Options, or the rules of the game type the mode plays.
  • Traits: script_traits[0] is the first set, up to 16 sets. Values are choices, not percentages: see the trait values. Apply the set on every tick the player should have it: traits last one tick, over those of their class. Several sets merge nonzero choices in call order; 0 leaves what's there.
  • Zones: loop over them by label and test current_object.shape_contains(current_player.biped). A zone is invisible and has no collision. Move one with set_position, as Zone Control does, to find its place at run time. Before you play Zone Traits, set the hill's position to a place on your map: in Forge, fly the monitor there and read Where it is on the Forge menu's Map tab.
Part of megalo-zone-traits.rmeg
for each object with label "objective" do
   for each player do
      if current_player.is_not_respawning() then
         if current_object.shape_contains(current_player.biped) then
            current_player.apply_traits(script_traits[0])
         end
      end
   end
end

Trait values

A trait set in [[logic.megalo_traits]] and a class's traits name Halo 3's player traits, each a choice by its place in Game Options' list. 0 means unchanged for every trait.

TraitValues
resistance1: 10%; 2: 50%; 3: 90%; 4: 100%; 5: 110%; 6: 150%; 7: 200%; 8: 300%; 9: 500%; 10: 1000%; 11: 2000%; 12: invulnerable.
recharge1: −25%; 2: −10%; 3: −5%; 4: disabled; 5: 50%; 6: 90%; 7: 100%; 8: 110%; 9: 200% shield recharge.
vampirism1: off; 2: 10%; 3: 25%; 4: 50%; 5: 100%.
headshots1: immune; 2: vulnerable.
shields1: none; 2: normal; 3: 2×; 4: 3×; 5: 4×.
damage1: 0%; 2: 25%; 3: 50%; 4: 75%; 5: 90%; 6: 100%; 7: 110%; 8: 125%; 9: 150%; 10: 200%; 11: 300%; 12: instant kill.
grenade_regeneration1: on; 2: off; 3: on, with firebombs.
ammo1: normal; 2: infinite; 3: bottomless clip.
pickup1: allowed; 2: disabled.
speed1: 25%; 2: 50%; 3: 75%; 4: 90%; 5: 100%; 6: 110%; 7: 125%; 8: 150%; 9: 200%; 10: 300%.
gravity1: 50%; 2: 75%; 3: 100%; 4: 150%; 5: 200%.
vehicles1: none; 2: passenger only; 3: full use.
camouflage1: off; 2: poor; 3: good; 4: invisible.
waypoint1: off; 2: allies; 3: everyone. Controls player waypoints, not the script's waypoints.
aura1: off; 2: team color; 3: black; 4: white.
radar1: off; 2: allies only; 3: normal; 4: enhanced.
radar_range1: 10 m; 2: 15 m; 3: 25 m; 4: 50 m; 5: 75 m; 6: 100 m; 7: 150 m.

Starting weapons and grenades aren't in script trait sets. Set them in the header's [options], or a class's primary, secondary and grenades.

HUD widgets

A mode has 32 widgets, script_widget[0] to script_widget[31]. Each shows text and an optional bar, and every player has their own copy, so text, bars and visibility can differ from player to player. Widgets start hidden.

Part of a script
script_widget[0].set_text("Progress: %n", global.number[0])
script_widget[0].set_value_text("of %n", 30)
script_widget[0].set_meter_params(number, global.number[0], 30)
script_widget[0].set_visibility(all_players, true)

Reach's calls change the widget for every player:

CallWhat it does
set_text(text, …)The widget's text. %n puts in the next value as a whole number, up to three; %% is a percent sign.
set_value_text(text, …)More text after it, the same way; "" removes it.
set_meter_params(number, value, maximum)A bar filled to value out of maximum. set_meter_params(none, 0, 0) removes it. A timer meter stops the script: read the timer into a number.
set_visibility(all_players, true)Shows the widget to everyone, or hides it with false. Use current_player to show or hide it for one player.

Numbers are put in when the call runs, so call it again when they change. Text and value text, with the space between them, must fit 96 UTF-8 bytes with no control characters. A meter's maximum must be above 0, and meters don't print their values: add text for numbers. Widgets stay until changed; players who join mid-game and each split-screen player get them too.

Per-player text and placement

These calls take whose widget to change first: a player, such as current_player, or all_players. What all_players sets is also what players who join later start with.

CallWhat it does
set_text_for(who, text, …), set_value_text_for(who, text, …)The text, for who only. Same rules as set_text.
set_meter_for(who, number, value, maximum)The bar, for who only; none, 0, 0 removes it.
reset(who)Clears the widget: text, bar, placement and style. It's hidden afterwards.
set_position(who, x, y)Places the widget on the script screen below. A widget without a position is a row laid out by hud_layout.
set_anchor(who, anchor)Which point of the widget's box the position names: top_left (the default), top, top_right, left, center, right, bottom_left, bottom or bottom_right.
set_size(who, width, height)The box's size. 0 for a side fits it to the content; a width also wraps the text.
set_alignment(who, center)How the text sits in its box: left, center or right.
set_color(who, r, g, b, a)Text and bar color, each 0 to 255. White by default.
set_background(who, r, g, b, a)Fills the box. None by default.
set_border(who, r, g, b, a)Outlines the box. None by default.
set_font_size(who, size)8 to 72, in script-screen units. 16 by default.
set_clickable(who, true)Lets a placed widget take clicks in its player's script menu.

The script screen is 1280 by 720 units, with 0, 0 at the top left. Each player's view, or their part of the screen in split screen, shows it scaled to fit and centered, so a layout keeps its proportions on every display. Positions must be on the screen and sizes no larger than it. Rows without a position use the widget's text color and font size; boxes, backgrounds, borders and clicks need a position.

A counter at the top center, different for each player
on init: do
   script_widget[4].set_position(all_players, 640, 20)
   script_widget[4].set_anchor(all_players, top)
   script_widget[4].set_size(all_players, 300, 0)
   script_widget[4].set_alignment(all_players, center)
   script_widget[4].set_background(all_players, 8, 16, 28, 170)
   script_widget[4].set_font_size(all_players, 20)
end

for each player do
   global.number[0] = current_player.get_kill_count()
   script_widget[4].set_text_for(current_player, "%n kills", global.number[0])
   script_widget[4].set_visibility(current_player, true)
end

A call whose result breaks a limit, such as text that's too long, a position off the screen or a size or font size out of range, stops the script, as other errors while it runs do.

Script menus and clicks

current_player.set_ui_menu(true) opens that player's script menu. Their cursor appears over the game, and their game input stops while it's open. Clicking one of their visible, placed widgets marked with set_clickable(…, true) runs the script's on widget click event for that player:

Part of a script
on widget click: do
   -- current_player clicked script_widget[clicked_widget].
   if clicked_widget == 5 then
      current_player.score += 1
      current_player.set_ui_menu(false)
   end
end
Call or nameWhat it does
current_player.set_ui_menu(true)Opens that player's script menu; false closes it.
current_player.is_ui_menu_open()1 while it's open. It gives a value: read it into a number.
on widget click: do … endRuns once for each click the host accepts. current_player is the player who clicked.
clicked_widgetThe clicked widget's number, inside the event.
  • Clickable widgets light up under the cursor. A click counts only on a widget that has a position, is clickable and is shown to that player, while their menu is open.
  • Escape opens the ordinary pause menu, for settings or leaving the game; Resume or Escape returns to the script menu. Only the script closes the menu.
  • Widgets are plain text, numbers and colors sent by the host. Players' PCs never run script code, and a click only tells the host which widget was pressed.

Classes and class pickers

[logic.deployment] in the header declares the classes players choose from before each life, bought with deployment points. A mode with classes needs "rounds.teams" = 1. A free, unlimited class on each team is required, so nobody is ever stuck.

A whole mode with two classes a team
--[=[ mode
name = "Two Classes"

[rules]
kill_points = 1
score_to_win = 25

[options]
"rounds.teams" = 1

[logic.deployment]
title = "Choose a class"
teams = ["Red", "Blue"]

[[logic.deployment.classes]]
name = "Rifle"
description = "A Battle Rifle and two frag grenades."
team = 0
cost = 0
biped = "spartan"
primary = "battle_rifle"
grenades = [2, 0, 0, 0]

[[logic.deployment.classes]]
name = "Sniper"
description = "A Sniper Rifle, for 100 points."
team = 0
cost = 100
max_active = 1
biped = "spartan"
primary = "sniper_rifle"

[[logic.deployment.classes]]
name = "Rifle"
description = "A Carbine and two plasma grenades."
team = 1
cost = 0
biped = "elite"
primary = "carbine"
grenades = [0, 2, 0, 0]

[[logic.deployment.classes]]
name = "Sniper"
description = "A Beam Rifle, for 100 points."
team = 1
cost = 100
max_active = 1
biped = "elite"
primary = "beam_rifle"
]=]

-- 50 deployment points a kill.
alias kills = player.number[0]
for each player do
   global.number[0] = current_player.get_kill_count()
   if global.number[0] != current_player.kills then
      current_player.kills = global.number[0]
      global.number[1] = current_player.get_deployment_points()
      global.number[1] += 50
      current_player.set_deployment_points(global.number[1])
   end
end
[logic.deployment]What it holds
titleThe picker's title, up to 48 bytes.
teams2 to 8 team names, up to 24 bytes each.
script_menutrue: the script draws its own picker with its widgets (deploy_class), and the built-in one stays hidden.
[[logic.deployment.classes]]2 to 128 classes, at most 48 a team, numbered from 0 in their order: the numbers deploy_class and get_deployment_… take. Each team needs a free class without a limit.
Class settingWhat it holds
name, descriptionUp to 32 and 120 bytes. A team's classes have different names.
teamIts team's number; 0 is the first of teams.
costThe deployment points it takes, 0 to 100,000.
max_activeThe most players in it at once; 0 for any number. A choice waiting to deploy counts.
bipedThe body, from the body list.
model_variantThe body's model variant.
camera"native", Halo 3's, or "third_person", on foot.
primary, secondaryWeapons by name, from the weapon list, or by tag path. A path can name a mod's or another game's weapon loaded on the map; the class picker shows the tag's own name. If the map lacks it, the class starts without that weapon. Reach's own names include dmr, needle_rifle, plasma_repeater, spike_rifle, grenade_launcher, plasma_launcher and flak_cannon (its fuel rod gun); there brute_shot is its concussion rifle and beam_rifle its focus rifle.
dual_wieldtrue: the secondary in the left hand. Two plasma rifles only.
grenadesFrag, plasma, spike and firebomb grenades, 0 to 4 each: [2, 0, 0, 0].
traitsTraits while in the class, as a table: [logic.deployment.classes.traits].
healthThe damage the body takes is divided by this, 0.1 to 10; 1 by default.

Without script_menu, players choose in the built-in class cards, or on the deployment map when the mode has deploy points. With the built-in picker, widget 3 shows each player's class and points, and the other widgets are the script's. A roster with script_menu leaves all 32 to the script.

CallWhat it does
current_player.deploy_class(n)A waiting player of class n's team, with its cost and no class chosen this life, takes it while it has room: 1 if they did, else 0. It gives a value: assign it.
get_deployment_class()The class chosen for their next life, −1 while they choose.
get_last_deployment_class()The class of their last life, kept after they die; −1 before their first.
get_deployment_points(), set_deployment_points(n)Their points, 0 to 100,000.
game.get_deployment_class_count()How many classes there are.
game.get_deployment_cost(n), game.get_deployment_limit(n), game.get_deployment_team(n)Class n's cost, max_active and team; −1 for no such class.
game.get_deployment_occupied(n)Players in it now, waiting choices too.

Your own class picker

With script_menu = true, the script draws the picker with widgets. Purchases, class limits, the respawn countdown and spawning work as with the built-in one. The script opens each player's script menu, draws cards with placed, clickable widgets, and deploys the clicked class with deploy_class, which spends the player's points:

Part of a mode with script_menu = true
alias choosing = player.number[0]
alias class = global.number[0]
alias deployed = global.number[1]
alias wait = global.number[2]

on init: do
    script_widget[8].set_position(all_players, 80, 190)
    script_widget[8].set_size(all_players, 270, 88)
    script_widget[8].set_background(all_players, 15, 27, 39, 255)
    script_widget[8].set_clickable(all_players, true)
end

on widget click: do
    if clicked_widget == 8 then
        class = 0
        if current_player.team == team[1] then class = 2 end
        deployed = current_player.deploy_class(class)
    end
end

for each player do
    current_player.choosing = 0
    class = current_player.get_deployment_class()
    wait = current_player.get_respawn_time()
    if not current_player.is_not_respawning() and class == -1 and wait == 0 then
        current_player.choosing = 1
    end
    current_player.set_ui_menu(current_player.choosing)
    script_widget[8].set_text_for(current_player, "Free infantry")
    script_widget[8].set_visibility(current_player, current_player.choosing)
end

A dead player without a class whose respawn countdown has ended is choosing: the script opens their menu and shows them the card, and closes it once they have a class. This fragment assumes class 0 is a free class of the first team and class 2 a free class of the second.

Class names, costs and loadouts stay in the header; write the card text to match. faction-battlefront.rmeg draws its whole picker this way: a backdrop, the faction's title, the player's points, a line that explains a refused click, and cards that dim when the player can't afford them and show live counts for limited classes.

A class picker drawn by a mode's script, with a card for each class
UNSC vs Covenant vs Flood's picker, all script widgets.

Buttons, equipment and class abilities

A script can hear the buttons players press, deploy Halo 3's equipment, mounted guns and vehicles, hand out equipment, refill ammunition, repair vehicles and spawn players where they chose. Together they make class abilities, such as active camouflage on a key or cover an engineer deploys. Only the host runs them: a player's PC sends nothing but which of their keys they pressed.

You wantUse
A key that triggers an abilityThe players' Ability 1 to Ability 4 keys, heard by on button press, with current_player as the player who pressed. See buttons in the script.
No repeats while a key is heldBuilt in: one event per press. is_button_held says the key is still down.
To react to Halo 3's own actionsbutton.jump, crouch, melee, grenade, equipment and flashlight.
Active camouflage for a time, with a rechargeA trait set with camouflage 4 and two player timers (below), or the active_camo equipment.
Deployable cover, a turret, a Bubble Shield, a vehicle…place_at_me with their names.
Equipment a class carriescurrent_player.give_equipment(name).
An ammunition point, repairsrefill_ammo() for the players near your object; is_of_type(vehicle), get_distance_to and the vehicle's health.
A spawn point the player choosesA key or a script menu, then set_primary_respawn_object.
Classes and their loadoutsClasses and get_deployment_class(), or a class number the script keeps, as the Class Abilities example does.

Ability keys

Every player has four keys for game modes, under Game Mode Abilities in Settings → Keyboard & Mouse and Settings → Controller:

KeyKeyboardController
Ability 1XD-pad right
Ability 22D-pad left
Ability 33D-pad down
Ability 4HNot bound
  • The controller column is Halo 3's default button layout. MCC's universal layouts and Infinite choose grenades with the D-pad, so there Ability 1 is D-pad down and Abilities 2 and 3 have no button until the player picks one.
  • Players rebind them like any other key, and each split-screen player has their own.
  • They do nothing in modes whose script doesn't listen, and never reach Halo 3 itself. They wait while chat, the pause menu or a script menu is open.
  • Halo 3's button prompts don't name them. Say which key does what in your HUD text.

Buttons in the script

Part of a script
on button press: do
   -- current_player pressed pressed_button.
   if pressed_button == button.ability_1 then
      current_player.score += 1
   end
end

for each player do
   if current_player.is_button_held(button.ability_2) then
      -- Still held on this tick.
   end
end
ButtonA press isHeld while
ability_1 … ability_4The player's ability key going downIt's down
jumpJumpJump is held
crouchStarting to crouchCrouching; a controller's stick click toggles it
meleeA melee attack startingThe attack lasts
grenadeA grenade throw startingThe throw lasts
equipmentThe player using their equipmentA throw lasts
flashlightFlashlight: 4, D-pad upIt's held
  • Halo 3's own buttons still do what they always do; the script hears them too, and can't stop them. They're what the host sees the player do: melee, grenade and equipment count only when the player really attacks, throws or uses something. Multiplayer characters have no flashlight, so flashlight is a free button that needs no new key.
  • Dead players can press too. Check current_player.is_not_respawning() when an ability needs a body; while they wait, a key can choose their class or spawn point.
  • Holding a key doesn't repeat it. The host takes at most ten presses a second from a player.

Active camouflage on a key

Give the header a trait set with camouflage 4, invisible:

Part of a header
[[logic.megalo_traits]]
camouflage = 4

Then apply it while a player timer runs, and start a recharge:

Part of a script
alias camo = player.timer[0]
alias recharge = player.timer[1]

on button press: do
    if pressed_button == button.ability_1 and current_player.is_not_respawning() and current_player.recharge.is_zero() then
        current_player.camo = 8          -- invisible for 8 seconds
        current_player.camo.set_rate(-100%)
        current_player.recharge = 28     -- ready 20 seconds after
        current_player.recharge.set_rate(-100%)
    end
end

for each player do
    if not current_player.camo.is_zero() then
        current_player.apply_traits(script_traits[0])
    end
end

To show the recharge in a placed widget, assign the timer to a number, such as current_player.number[0] = current_player.recharge, and put that number in the text. Halo 3's campaign camouflage is also equipment: give_equipment(active_camo) gives ten seconds of it on Use equipment.

Equipment, guns and vehicles by name

place_at_me takes these names, besides weapons, bodies and tag paths:

KindNamesMaps
Equipment as thrown: it works at oncebubble_shield, deployable_cover, radar_jammer, power_drainer, regenerator, trip_mine, grav_lift, grav_lift_permanent, flare, auto_turretEvery stock multiplayer map
Equipment to pick upbubble_shield_pickup, deployable_cover_pickup, radar_jammer_pickup, power_drainer_pickup, regenerator_pickup, trip_mine_pickup, grav_lift_pickup, flare_pickup, auto_turret_pickup, active_camo_pickup, invincibility_pickupEvery stock multiplayer map
Mounted guns, to manmachine_gun_emplacement, plasma_cannon_emplacement, missile_pod_emplacementMachine gun: every stock multiplayer map. Plasma cannon: all but one. Missile pod: where the map has one.
Vehiclesmongoose, ghost, warthog, gauss_warthog, troop_warthog, chopper, prowler, banshee, hornet, scorpion, wraith, shade, elephantWhere the map has them
Part of a script, as the Class Abilities example does it
alias deployed = player.object[0]
alias emplacement = player.object[1]

on button press: do
    -- Cover a short way in front of the player, facing where they face.
    current_player.deployed = current_player.biped.place_at_me(deployable_cover, "cover", none, 15, 0, 2, none)
    -- A machine gun emplacement anyone can man; a new one replaces the last.
    current_player.emplacement.delete()
    current_player.emplacement = current_player.biped.place_at_me(machine_gun_emplacement, "emplacement", none, 20, 0, 2, none)
end
  • Offsets are in tenths of a Forge unit, along the body's heading, as for any created object. Only bodies take a model variant: the last value is none.
  • Deployed equipment is the player's. Made at a player's body, it counts as theirs and their team's, as if they had thrown it. It runs out as Halo 3's own does and disappears, and your reference to it becomes no_object.
  • Mounted guns, vehicles and pickups stay until something destroys them, the script deletes them or the round ends.
  • A name the map lacks stops the script. Use the names every stock multiplayer map has, or check the maps you'll play.
  • machine_gun_emplacement and plasma_cannon_emplacement are the guns to man, not the machine_gun_turret and plasma_cannon weapons, which are the guns carried after tearing them off. grav_lift_permanent is the Grav Lift Forge places, which never runs out.
  • auto_turret is the Automated Turret, equipment Halo 3's multiplayer maps carry but its multiplayer never used. It appears and stands where you put it, as Halo 3 left it: try it in your mode before you rely on it.
  • Declared objects take the same names: { kind = "stock", object = "warthog" }. See declared objects.

Give equipment

Part of megalo-class-abilities.rmeg
if current_player.class == Class.engineer then current_player.give_equipment(bubble_shield) end

The player's body carries the equipment in place of anything it carried, and they use it with Use equipment, which the script hears as button.equipment. The names are bubble_shield, deployable_cover, radar_jammer, power_drainer, regenerator, trip_mine, grav_lift, flare, auto_turret, active_camo (ten seconds of invisibility) and invincibility (ten seconds without damage). give_equipment(none) takes it away. Only living players receive it: give it again on each new life, for example when current_player.biped changes.

Ammunition, repairs and object kinds

refill_ammo() leaves energy weapons as they are, and grenades: use a grenade_regeneration trait or a class's grenades. An ammunition point refills the players beside an object every few seconds, behind a timer rather than on every tick. The Class Abilities example does it for each Medic's regenerator:

Part of megalo-class-abilities.rmeg
-- Regenerators refill the ammunition of everyone beside them.
if ammo_pulse.is_zero() then
    for each player do
        station = current_player.deployed
        if current_player.class == Class.medic and station != no_object then
            for each player do
                if current_player.is_not_respawning() then
                    distance = current_player.biped.get_distance_to(station)
                    if distance <= 25 then current_player.refill_ammo() end
                end
            end
        end
    end
    ammo_pulse.reset()
    ammo_pulse.set_rate(-100%)
end

Repairs work the same way: while an Engineer holds Ability 3, the example raises the health of the vehicles within reach a little at a time, twice a second:

Part of megalo-class-abilities.rmeg, in its for each player loop
if current_player.class == Class.engineer and current_player.is_not_respawning() and current_player.is_button_held(button.ability_3) and current_player.repair_pulse.is_zero() then
    current_player.repair_pulse = 1
    current_player.repair_pulse.set_rate(-200%)
    for each object do
        if current_object.is_of_type(vehicle) then
            distance = current_object.get_distance_to(current_player.biped)
            health = current_object.health
            if distance <= 30 and health > 0 and health < 100 then
                health += 5
                if health > 100 then health = 100 end
                current_object.health = health
            end
        end
    end
end

Spawn where the player chose

Mark the spots on your map with Forge's labels, then let players choose with a key or a script menu, and hand the object to set_primary_respawn_object:

Part of a script
on widget click: do
    if clicked_widget == 10 then
        for each object with label "command_point" do
            if current_object.spawn_sequence == 1 then
                current_player.set_primary_respawn_object(current_object)
            end
        end
    end
end

Cooldowns, limits and cleanup

  • Cooldowns: a player timer per ability, started with set_rate(-100%) when the ability is used and checked with is_zero(). Timers survive death, so a recharge carries on into the next life.
  • One at a time: keep the object in a player variable and delete() the old one before making a new one. Deleting no_object does nothing.
  • How many: count with for each object with label "cover" do before making another.
  • Where: get_distance_to from an objective, a spawn or an enemy's body lets you refuse a spot. Objects are placed from the body, not where the player aims: keep offsets short so they stay on the same floor.
  • Lifetime: deployed equipment ends by itself. For anything else, start a timer when you create it and delete it when the timer runs out. never_garbage_collect keeps an object Halo 3 would otherwise clean up.
  • Leaving: objects a player made stay after they leave; the round's end removes everything the script created. A script can have at most 256 created objects at once.
  • Per-player state, such as cooldowns, deployed objects and the chosen class, belongs in player.number, player.timer and player.object variables. They follow the player through deaths and are cleared when they leave.

Class Abilities example

megalo-class-abilities.rmeg is a team Slayer mode with three classes, one 15-minute round to 50 points. To choose spawn points, label objects spawn_point in Forge and save the map; without them, everyone spawns where Halo 3 puts them.

  • Ability 4 chooses your class for your next life. You start as an Infiltrator.
  • Infiltrator: Ability 1 turns you invisible for 8 seconds, ready again 20 seconds after.
  • Engineer: spawns with a Bubble Shield. Ability 1 deploys cover (30 seconds to recharge), Ability 2 a machine gun emplacement (60 seconds; a new one replaces the last), and holding Ability 3 beside a damaged vehicle repairs it.
  • Medic: Ability 1 deploys a regenerator (45 seconds), which also refills the ammunition of everyone beside it every 5 seconds.
  • While you wait to respawn, Ability 1 chooses the next object labelled spawn_point on the map, then Halo 3's own spawns again.

Placed widgets on the right, above Halo 3's score, show your class and each ability's recharge; while you wait, a line in the middle shows where you'll spawn.

What abilities can't do

  • Abilities are what the script makes of buttons, objects, traits and timers. There are no new animations, models or HUD icons.
  • A script can't stop Halo 3's own buttons from acting, only hear them.
  • Objects are placed from the player's body and heading, not where they aim, and the script can't test the ground first. Short offsets work best. get_crosshair_target() tells you what they aim at.
  • Vehicles appear only on maps that have them, unless you name a tag the map loads; equipment and the machine gun emplacement on every stock multiplayer map.

Objects, attachments and physics

Any object reference works with these: a player's biped, an object in a loop, or one the script created.

CallWhat it does
place_at_me(type, label, flags, x, y, z, variant)Creates an object at this one and returns it. See creating objects.
delete(), kill(false)Removes it, or destroys it as damage would. kill(true), a silent kill, stops the script.
despawn()See taken away and made again.
attach_to(other, x, y, z, relative)Sticks it to another object, offset by −128 to 127 tenths of a Forge unit. relative follows the other object's facing, absolute the map's. Detach before attaching it elsewhere.
detach()Lets it go where it is.
get_carrier()The player found through the attachment parents, or no_player.
set_hidden(true)Hides it, for every player.
set_invincibility(true)Makes it take no damage. Kill boundaries still remove it.
set_garbage_collection_disabled(true)Stops the game from cleaning it up when it lies around. Invincibility alone doesn't.
set_scale(50)Its size in percent, 10 to 300. A player's body: each of theirs from now on. 0 or less does nothing; other values out of range stop the script.
set_velocity(x, y, z)Sets it moving, in Forge units a second along the world's axes, at most 100 each. A player's body moves on every PC, so a player who joined is pushed just as the host is.
get_speed()Feet a second, as a whole number.
get_distance_to(other)Distance in tenths of a Forge unit, rounded up, at least 1 for objects that exist and 0 for no_object.
get_x(), get_y(), get_z()Where it is, in tenths of a Forge unit.
get_yaw(), get_pitch(), get_roll()Which way it faces, in degrees.
set_position(x, y, z)Moves it there, in tenths. An attached object stays with its parent until it's detached. A zone the mode declares moves with it.
set_rotation(yaw, pitch, roll)Turns it, in degrees. An attached object keeps its facing.
copy_rotation_from(other, true)Turns it to face as the other does: true fully, false heading only. An attached object keeps its facing.
move_to(x, y, z)Kept for older scripts: set_position in whole Forge units, within 100,000.
teamThe team it belongs to, such as a flag's or a team's Forge object, else no_team. Read only.
health, shields, max_health, max_shieldsHealth and shields left, in percent of the maximums, and the maximums, in percent of the character's own. See health, shields and seats.
set_vehicle_use(0 or 1), set_turret_use(0 or 1)A player's body: as the player's own call. Another biped: whether it may ride vehicles or use turrets.
is_of_type(type)(condition) Tests what it is. See object types.
has_forge_label("gift")(condition) Tests for a label, on a Forge object, one the script made, or one the mode declares.
shape_contains(other)(condition) Whether another object is inside this zone.
spawn_sequenceThe Spawn Sequence saved on a Forge object, −128 to 127, read only. 0 for objects without one.
play_sound("path"), start_looping_sound("path")See sounds.
set_waypoint_visibility, set_waypoint_icon, set_waypoint_prioritySee waypoints.
set_damage_from, set_damage_team, set_damage_playerSee damage.
set_deploy_point, get_territory_ownerSee squads and the deployment map.

Creating objects

  • type is anything in object types that can be made, or the name of an object the mode declares. It must be a constant: a name, a text, or an object to copy.
  • label is a text or number for for each object with label, or none. flags is none, absolute_orientation or never_garbage_collect, one at a time. The offsets are constants in tenths of a Forge unit, −128 to 127, along the object's heading. The last value is none or, for a body, one of its model variants.
  • Up to 256 created objects at a time: delete the ones you're done with. Created objects are removed when the round ends, except bodies players are in, and sizes, hiding and invincibility go back to normal.
  • An attached object can sit where a loose one can't survive: check where things land when you detach them on your map.
  • absolute_orientation makes offsets follow the object's full orientation; the other flags use its heading.
  • A no_object basis gives no_object. Named objects the map lacks, or that the engine refuses, stop the script.

You can use a newly returned object in the same event; its position and rotation are provisional until the next tick. A biped reached through a player and through an object loop is the same reference, with the same variables.

Attachment cycles and chains over 32 objects stop the script. Attaching to yourself or no_object, or attaching an object that's already attached, does nothing. Attachments keep the object's world orientation and size. Round cleanup restores size, visibility, protection and garbage collection; moves, deletions and attachment changes aren't generally reversed. Pass false to set_hidden, set_invincibility or set_garbage_collection_disabled to take that back.

The Object Controls example puts it together:

megalo-object-controls.rmeg
-- Each life gets a miniature shotgun, attached to the player for five
-- seconds before it drops into the world. Halo 3 must supply the weapon tag.
alias gift = player.object[0]
alias previous_body = player.object[1]
alias stage = player.number[0]
alias release_time = player.timer[0]
declare player.timer[0] = 5
declare global.timer[0] = 60

on init: do
    global.timer[0].set_rate(-100%)
end

for each player do
    if current_player.is_not_respawning() then
        if current_player.previous_body != current_player.biped then
            current_player.previous_body = current_player.biped
            current_player.stage = 0
        end
        if current_player.stage == 0 then
            current_player.gift = current_player.biped.place_at_me(shotgun, "gift", never_garbage_collect, 0, 0, 5, none)
            current_player.gift.set_scale(50)
            current_player.gift.set_invincibility(true)
            current_player.gift.attach_to(current_player.biped, 0, 0, 5, relative)
            current_player.release_time.reset()
            current_player.release_time.set_rate(-100%)
            current_player.stage = 1
        end
        if current_player.stage == 1 and current_player.release_time.is_zero() then
            current_player.gift.detach()
            current_player.gift.set_invincibility(false)
            current_player.gift.set_velocity(0, 1, 0)
            current_player.stage = 2
        end
    end
end

global.number[0] = 0
for each object with label "gift" do
    global.number[0] += 1
end
script_widget[0].set_text("Scripted gifts: %n", global.number[0])
script_widget[0].set_visibility(all_players, true)
if global.timer[0].is_zero() then game.end_round() end

Taken away and made again

CallWhat it does
despawn()Takes the object away. A Forge-placed one stays away, its respawn timer doesn't make it again, until respawn_objects names its label; another goes for good, as delete does.
game.respawn_objects("label")Makes again, at their Forge places, the objects labelled label the mode took away.

A new round makes every Forge object again. To hold back a phase's vehicles and weapons, label them in Forge and take them away when the round starts:

Part of a script
on init: do
    for each object with label "phase_2" do
        current_object.despawn()
    end
end

Forge zones

shape_contains(object) tests a Forge object's zone too: the shape and size its Forge properties give it (Properties → Zone shape: a sphere's radius; a cylinder's radius, top and bottom; a box's width, length, top and bottom), turned with the object, as Halo 3's King of the Hill hills, territories and Forge's own zones have them. A zone the mode declares in its header keeps its own shape. An object's zone holds its own place, so current_object.shape_contains(current_object) tells whether it has one. A box's width and length are whole sizes, centered on the object.

Object types and tag paths

is_of_type(…) and place_at_me(…) take:

TypeNamesTakes it
An object kindbiped, vehicle, weapon, equipmentis_of_type
A kind of vehicleaircraft (one that flies: Banshee, Hornet), ground_vehicle, multi_seat_aircraft and multi_seat_ground_vehicle (more than one seat a player may take: the Hornet; the Warthog, Mongoose, Scorpion…). A turret, mounted or not, is of none of them.is_of_type, set_driver_use
A stock objectEquipment, emplacements and vehiclesBoth
A weaponassault_rifle, battle_rifle, smg, smg_silenced, carbine, magnum, automag, 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, hunter_cannonBoth
A bodyThe body listplace_at_me
An objective itemflag, bomb, oddball (or skull)is_of_type
A tag path"objects/vehicles/mongoose/mongoose", as textBoth

A name matches only those objects, whoever made them. Halo 3 makes mounted guns and the Automated Turret as vehicles. hunter_cannon is the Hunter's own weapon, from the campaign. Weapons are the same names set_weapon and a class's primary take.

A Megalo mode's game gets every Forge object, on a saved Forge map too, since a script may create any of them; a plain game type on a saved map loads only what the map places.

Tag paths

A tag path names any object tag the map has: vehicles, weapons, equipment, bodies, scenery, crates and devices, such as machines and controls, modded ones included. Write it with forward slashes, since a backslash in text starts an escape; case doesn't matter. set_weapon, a class's primary and secondary, set_respawn_vehicle, set_weapon_pickup and set_driver_use take paths too. The Reclaimer Kit shows you a map's tags.

New in 0.10.5: weapon paths work in loadouts as well as object creation. For example, current_player.set_weapon("objects/weapons/rifle/battle_rifle/battle_rifle") keeps that weapon in the player's hands. In a class header, use primary = "objects/weapons/rifle/battle_rifle/battle_rifle". Replace the path with the weapon tag shown in your map's Tags workspace to use a mod's weapon.

A path first finds the map's own tag, then another game's content brought onto it. With the host's Sandbox set to Halo 3 on a Reach map, Halo 3 weapon paths still find Halo 3's imported weapons. A stock name such as battle_rifle follows the chosen sandbox's replacement; a path keeps the particular tag it names. A path alone does not install a game or import a missing weapon.

Part of megalo-expansions.rmeg
alias barrel = player.object[0]

for each player do
   if current_player.is_not_respawning() and current_player.barrel == no_object then
      current_player.barrel = current_player.biped.place_at_me("objects/gear/human/industrial/h_barrel_rusty/h_barrel_rusty", "barrel", none, 20, 3, 5, none)
   end
end

A map's cache file holds more tags than the map loads. A path names only a tag whose model and its parts the map loads: the engine makes objects of no other, a crate needs its physics, and a tag the map lacks never matches. The host's log lists, once a round, which of the script's types the map has and which it lacks: [modes] 'NAME' names what this map lacks: …. Guardian, for example, loads its rusty barrels and pallets but not its packing crates or street cones.

Copies

place_at_me(object, label, flags, x, y, z, none) given an object in place of a type makes a new object of its tag, while the original stays. A copy of no_object makes nothing.

A tag path or a copy the engine refuses there, because it's placed outside the map, makes nothing: the host logs it once, and the script goes on with an empty reference. A stock or named object the map lacks, or the engine refuses, stops the script.

Waypoints

Halo 3's objective navpoints over an object, with Reach's calls:

CallWhat it does
set_waypoint_visibility(who)everyone, allies (the players of its team), enemies (the other teams; everyone, when it has none), a player, a team such as current_player.team, or no_one. None show until this is set.
set_waypoint_icon(icon)speaker, dead_teammate (a cross), check, bullseye, diamond (the default), bomb, flag, skull, crown, vip (a star), padlock, or territory, N (the number N, 1 to 9).
set_waypoint_priority(p)blink makes it blink; low, normal and high draw the same.
set_waypoint_timer(n | none)Show this object's timer n over its icon, or hide the timer with none. Halo 3's HUD shows whole seconds left; Reach's HUD uses its own timer ring.
set_waypoint_text("text", values)Show text over the waypoint icon. Timer and text changes reach every player, including joiners, on Halo 3's HUD too.

A waypoint is blue to its object's team, red to the others and gray over an object with no team; off screen, an arrow at the screen's edge points to it, as Halo 3's objectives' do. Assigning current_object.team also gives the object itself that team until the round ends: a flag takes the team's color on every PC. A player's body keeps its player's team. Any number of objects may keep waypoint settings; at most 64 show at once, the highest priorities first, then the oldest objects'. One goes with its object.

Mark a fallen teammate for their team
on object death: do
    killed_object.set_waypoint_icon(dead_teammate)
    killed_object.set_waypoint_visibility(current_player.team)
end

Sounds

The map's own sound tags, by path:

CallWhat it does
game.play_sound("path")Once, everywhere, for everyone.
current_player.play_sound("path")Once, for that player alone.
current_object.play_sound("path")Once, from the object.
game.start_looping_sound("path"), current_object.start_looping_sound("path")A looping sound tag, everywhere or from the object, until stopped. One of each tag plays at once: starting it again moves it.
game.stop_looping_sound("path")Stops it.

A sound is a sound tag, and a looping sound a looping sound tag, of the map's, such as "sound/game_sfx/multiplayer/pickup_invis" or "sound/weapons/equipment/tripmine/tripmine_beep/tripmine_beep". The path must be a constant. One the map lacks plays nothing, and the host's log says so. At most 8 sounds a tick and 16 looping sounds at once.

Damage

CallWhat it does
set_damage_from(category, 0 or 1)Whether damage of a category reaches the object.
set_damage_team(team)Only that team's players' damage reaches it; no_team: anyone's.
set_damage_player(player)Only that player's damage reaches it; no_player: anyone's.

A hit an object's rules refuse never reaches it: no damage, and no side effect, where melee would otherwise kill an unaware body outright. The script still hears it in on object damaged. Rules last the round; scripted and forced kills (kill) always go through.

Damage categories, as damage.NAME: none, falling (collisions too), bullet, grenade, high_explosive, sniper, melee, flame, mounted_weapon, vehicle, plasma, needle and shotgun. A category's number is its place in that list. The map's damage effects decide: on the stock maps the Sniper Rifles' and the Shotgun's rounds are bullet, and a fusion coil's blast is grenade.

Part of a script
on object damaged: do
    if current_object.has_forge_label("target") and damage_category == damage.bullet then
        current_player.score += 1
        current_object.delete()
    end
end

Forge objects by label

A script can find objects placed in Forge by a label saved with the map, so the same script works on any map whose objects carry it, with no positions or placement numbers in the source.

  1. Label the objectsIn Forge, as the host, aim at an object and open its Properties. Under Megalo scripting, enter a Label and a Spawn sequence, then choose Apply scripting.
  2. Save the mapThe values belong to the map: save it as for any edit.
  3. Find them in the scriptLoop over the label and tell the objects apart with current_object.spawn_sequence. Host the mode on that saved map.
megalo-forge-labels.rmeg
-- In Forge, give two placed objects the label "door" and Spawn Sequences 1 and 2.
-- Save the map, then host this mode on that map.
-- The first door becomes invincible; the second is left alone.
alias door = global.object[0]

if door == no_object then
    for each object with label "door" do
        if current_object.spawn_sequence == 1 then
            door = current_object
            door.set_invincibility(true)
        end
    end
end

script_widget[0].set_visibility(all_players, true)
if door == no_object then
    script_widget[0].set_text("Waiting for an object labelled door with Spawn Sequence 1")
end
if door != no_object then
    script_widget[0].set_text("Door 1 found and protected")
end

The loop runs until it finds the door, then door keeps the reference.

  • A label is a group name, not a unique name: several objects can share one, and capitals count. Up to 32 UTF-8 bytes without control characters; an empty label means none.
  • Spawn sequence is a number from −128 to 127 that scripts read and can't change. It's separate from the Forge menu's Spawn Order, spare clips and teleporter channel. Objects without one, and objects the script creates, read 0.
  • References last while the object does. When it's destroyed, a saved reference becomes no_object. If the object respawns, find the new one with the loop again. alias only names a variable; it doesn't look an object up by label.
  • A missing label isn't an error. The game can't know which map you'll use, so a loop over a label no object has just visits nothing.
  • Numbers match text. with label 7 finds objects labelled 7.
  • Only the host edits labels, but players see them and can save them with the map. Move a frozen object before labelling it.

Limits

LimitValue
Source file128 KiB; the script stored with its source and settings must fit 256 KiB
Saved .json game type2 MiB
Source structure32,768 tokens; 4,096 statements a block; 16 arguments a call
Nesting32 levels in the file, 64 calls and blocks while running
Steps per event65,536 in a game of up to 16 players; in a bigger game that many times the square of the players in sixteens, begun ones counted (262,144 with 17 to 32 players, 4,194,304 with 113 to 128), since a script's loops over the players nest
World objects a loop visits8,192
Created objects2,048 at once
World changes in one tick4,096
Trait sets16
Options32 declared; script_option[0] to [15] read
Declared objects64
Teams8, or up to 64 with declare team_count in Slayer, Oddball, King of the Hill, VIP and Territories; team names 1 to 24 bytes
Classes128, at most 48 a team; 2 to 8 teams with classes
Squads16 a team
Deploy points, waypoints64 deploy points at once; 64 waypoints shown at once
AliasesAn alias names a variable or a constant; its value has at most 64 parts
Sounds8 a tick; 16 looping at once
Weapon pickup bars, driver bars16 of each per player
HUD widgets32 a mode, with a copy for each player; 96 UTF-8 bytes of text each, value text included; a 1280 × 720 script screen; font sizes 8 to 72
AttachmentsChains of up to 32 objects
Labels, model variants32 bytes
Tag paths256 bytes
Button presses10 a second from each player

If an event fails, such as a division by zero, a value out of range or too many steps, its changes to the script's state are thrown away and the script stops for the rest of the game: the game goes on without it, and the host's log says why and where, by the line and column of the assignment, call or condition it stopped at, such as (line 948, column 16). Once world changes begin applying, a later failure can't undo earlier moves, deletions, points or team changes. A loop over every object on a busy map can reach the step limit even when each call is fine.

Reach's calls, and what doesn't play

Reach's own calls play in any source, as they do in Halo: Reach's game variants, which run through the same interpreter. A mode plays on every game's maps: what a map lacks, such as an object type, a label, a sound or a character, the mode goes without, and the host's log names it.

  • Events: pregame runs before init as a round starts. local runs each tick once for each player, with hud_player that player, and the widgets it changes are theirs alone. host migration and double host migration are read too.
  • Players: is_spartan, is_elite and is_monitor (by the body's model), killer_type_is, get_spree_count, get_scoreboard_pos, assisted_kill_of, get_death_damage_type, get_fireteam, set_fireteam, is_fireteam_leader, get_armor_ability, set_loadout_palette, set_co_op_spawning, set_vehicle_spawning_enabled, the round card calls, and the properties frag_grenades and plasma_grenades, read and written.
  • Objects: set_shape and set_shape_visibility, set_pickup_permissions, set_spawn_location_permissions, set_progress_bar, set_waypoint_range, set_waypoint_timer and set_waypoint_text, push_upward, add_weapon and remove_weapon, get_orientation, is_out_of_bounds, is_in_use, and the device calls. kill(1), Reach's silent kill, is the same kill as kill(0).
  • The game: show_message_to, send_incident, play_sound_for and get_random_object; the game. values such as game.score_to_win and game.current_round; and the timers game.round_timer, game.sudden_death_timer and game.grace_period_timer, which take a value, reset() and set_rate like a script's own. A round timer the script writes is the round's clock, and the script ends the round.
  • Widgets: timer meters, set_meter_params(timer, t), show a timer's seconds left. Widget text takes %n (a whole number), %s (a value as text; a timer as minutes and seconds), %p (a player) and %%. Halo: Reach's own game variants write text by Reach's rule.
  • Round cards: a player's round card is sent to them only when it changes, so a script may write it on every tick.
  • Flags: names joined by | are one constant, as in killer_type_is(kill | betrayal) or a place_at_me with never_garbage_collect | suppress_effect.
  • First values: a declaration may start from a script option or one of the game's values as well as a constant: declare object.timer[0] = script_option[3].
CallWhat it does
player.give_weapon(object)The player's body takes that weapon object, as add_weapon gives one. With no player or no object, nothing happens.
object.place_between_me_and(other, type, radius)Makes an object of the type halfway between the two, lying along the line between them, with a cylinder shape of that radius (tenths) as long as the line. Without the other object it makes nothing. Test both first: if a != no_object and b != no_object then x = a.place_between_me_and(b, type, radius) end.
object.face_toward(target, x, y, z)Turns the object about its own up until it faces the target's position, offset (tenths) along the target's own axes. An attached object, or a target at its own position or straight above or below it, stays as it is.
player.set_fireteam(n)Puts the player in fireteam 0 to 7. A number outside what Reach takes, such as −1, leaves it as it is.
player.record_griefer_penalty(n)Read, and changes nothing.

Reach's objectives and announcer on Halo 3 maps

On Halo 3 and ODST maps, Reach's area, stand and destination use Halo 3's corresponding objective markers. When a mode names Reach objects Halo 3 has none of, such as unsc_data_core and cov_power_module, the game brings the supported weapons, equipment, scenery and crates from Reach before the map loads. It brings the weapons the game type's loadouts and base traits arm players with that Halo 3 lacks too: Invasion's Elite spawns with its plasma repeater, not the plasma pistol alone. A weapon Halo 3 has of the same name stands for the rest.

An item a mode gives a team, such as Invasion's core or a flag or bomb played in its place, takes its team's color on every PC but keeps no owner team, so attackers can pick it up; who may take it is set_pickup_permissions' to decide. Reach's scenario interpolators come from one of Reach's Invasion maps, so set_scenario_interpolator_state plays and Invasion's alarms sound while a territory is being taken.

The host must have Reach installed and enable Other games' characters in Host Settings (other_game_characters on a server). Players joining also need Reach when the map uses its content. This does not bring vehicles or bodies through object names: use Forge's object sources for vehicles and the character choices for bodies.

play_sound_for, show_message_to and incident calls use Halo 3's matching announcer lines where available. With Reach installed and its content enabled, the remaining lines use Reach's own audio, including Invasion's Spartan and Elite announcers. Without it, those lines are silent. A source's object and sound names count even in branches it never reaches.

A map still needs the Forge labels its mode expects, such as Invasion's inv_objective and inv_obj_flag. Reach's respawn-zone types and armor abilities are not supplied on Halo 3 maps.

How Reach's game variants play

Halo: Reach's own game variants (MCC's, the Workshop's and those ReachVariantTool writes) run through the same interpreter as a .rmeg, but where Reach and Halo 3's extensions differ, a Reach variant plays by Reach's rules. A .rmeg or .rvt source keeps the rules on the rest of this page.

In a Reach variantWhat it does
object.max_health, max_shields (written)The object's own maximum in points, such as an objective's 20,000 shield points, not a percent of its own. =, +=, -=, *= and /= work on what it has, with no upper limit. The points left stay. With no maximum, shields are empty and an object with no health dies. Nothing changes on a dead object.
object.health, shields (written)Any number, kept between none and all of its health (none kills it) and between none and four times its shields.
player.force_into_vehicle(object)With no object, a seated player is put out of their vehicle at once. A seated player forced into another vehicle stays where they are. A player on foot takes the first free seat, the driver's first, of the vehicle or of one mounted on it.
player.get_vehicle()The outermost vehicle the body rides: a gunner's is the ship, not its gun.
object.delete() of a vehicleThe first living player seated in the vehicle itself is put out of it first; whoever else rides it, and a gun on it, goes with it.
on object deathRuns for every unit's death: a player's body, a vehicle's, a giant's or an AI's, but not a weapon's or a crate's, and not for a silent kill or a delete. For a unit other than a player's body there is no current_player, and killer_player is the player Reach credits: the one whose hit destroyed it, or, when it blew up by itself or hit something, the last enemy to hit it in the six seconds before. It runs on the game's next pass after the hit.
player.is_not_respawning()The player is in the game and hasn't left it, dead or alive.
A gone object's team, a gone player's bipedNone, where a number reads 0.
Text codes in show_message_to, widgets and round cards%n, %o, %p, %s and %t each mark the place of the next value, whatever the letter, and each value is written as what it is: a number whole, a timer as its seconds rounded up (0:07, 3:07, 1:03:07), a player as Player and their number, a team as nothing, an object as unknown and no object as none. A code past the values writes nothing.
The loadout camera (game.loadout_cam_time)For that many seconds from each round's start nobody gets a body, and a respawn countdown that would end sooner shows the camera's. The script and its timers run meanwhile. The round's clock doesn't wait for it, as Reach's does.

What doesn't play. A source that writes a player's or a team's money is refused, even in a part that never runs: mode-check names it, and the game type list leaves the mode out. rating always reads 0. A call the game doesn't know at all says Unsupported Megalo API. Halo 4 game variants (.mglo) and MegaloEdit's syntax aren't read. Campaign and Forge can't be scripted.

Like every game mode, a Megalo script can't reach files, the network, other programs or the console.

ReachVariantTool's documentation can help explain the language, but this page is the reference for what Project Reclaimer plays. ReachVariantTool itself doesn't know Halo 3's extensions, so it's a guide rather than a checker: mode-check is the check.

Test and share

  1. Run mode-check with the version you'll host. Then refresh and reselect the mode.
  2. On the intended map, verify scoring, the timer or score limit, deaths and respawns, and a second round. Check that your variables reset as intended.
  3. For teams, check joining, leaving, changing teams and a team becoming empty. For objects and zones, check their positions and any assets they need.
  4. Join with another PC, then test a late join. Check traits, bodies, objects and HUD on the joining player's screen, and for a script menu, click its widgets from the joined player's PC.

See the full checklist. To share a mode, share your .rmeg with other hosts, and state the map and assets it needs. Joining players only need the map's content; they don't install the script. A saved .json game type holds your source text too, so it isn't a way to hide your script. See install, share and host.

Troubleshooting

ProblemWhat to do
My mode isn't in the listRun mode-check on it, or look for Skipped content file in the log. Check the file ends in .rmeg, not .rmeg.txt.
The mode header: unknown field ...A setting in the header's top level isn't one the game knows; the message lists those that are. Check the table, and that script settings sit under [logic].
The mode header: unknown variant ...A value isn't one of the names the message lists, such as a mode that should be KingOfTheHill.
Unknown game option for Slayer: rounds.nopeThat name isn't a game option of this game type. See game options by name.
Round limit must be 1..=10A game option's value is out of range.
1:1: Unterminated block commentThe header has no ]=]. The numbers are the line and column where it started.
3:1: Expected "end", found ""A block isn't closed. The numbers are the line and column where the game noticed.
3:9: Assignment needs a writable typed variable or propertyThe statement assigns to a name that isn't a variable, such as one with no alias. The numbers are where the statement starts; for a call or a condition of the wrong kind, where the call or the condition's test starts.
Deployment classes require rounds.teams = 1Add "rounds.teams" = 1 under [options].
Every deployment team needs an unlimited free classGive each team a class with cost = 0 and no max_active.
team_count must match the deployment's teamsA mode with classes has as many teams as its teams list. Drop declare team_count, or make them match.
Scripted modes require an unpacked multiplayer game variant (not Forge or campaign)Choose a multiplayer game type. Campaign and Forge can't be scripted.
Scripted modes control player size; clear the world player scaleRemove player_scale_percent, and use set_scale in the script.
Assault can't have more than 8 teamsOnly Slayer, Oddball, King of the Hill, VIP and Territories can. See game types.
Script exceeds 256 KiBThe script, stored with its source and settings, is too big. Shorten it: long comments count.
Halo 3 Megalo adapter does not implement: option:0 or traits:0The script reads an option or trait set the header doesn't declare. Count options in alphabetical order.
Halo 3 Megalo adapter does not implement: spawn:zealotThat name isn't a body in the body list, a weapon, or one of the equipment, gun and vehicle names. Check its spelling, or use a tag path.
Halo 3 Megalo adapter does not implement: write.player.moneyThe script uses something the game does not play. Remove or replace it, even in a part that never runs.
Halo 3 Megalo adapter does not implement: player.get_deployment_pointsThat call needs classes in the header.
Unsupported Megalo API: Game.play_sound_forThat call doesn't exist. Check this page for the name.
A value-returning call needs an assignment or conditionAssign the result, even of deploy_class and place_at_me: see values and conditions.
Comparisons take values, not action function callsRead the call into a variable first, then compare the variable.
Expected a condition functionOnly the condition calls go straight in an if.
Global.Number[12] exceeds Reach variable capacityThere are fewer slots of that kind; see the variables table.
Timer rate must be a constant percentageWrite the rate as a value, such as -100%, not a variable.
Unknown button jump_twice: buttons are ability_1, ...Use one of the names the message lists after button.; see buttons in the script.
give_equipment takes none or one of bubble_shield, ...Write one of the names the message lists, such as give_equipment(regenerator). A variable isn't accepted, and pickup names such as regenerator_pickup are for place_at_me.
is_button_held takes a button, such as button.ability_1Pass a button by name, such as button.ability_2, or pressed_button inside on button press.
Cannot create NEW.json: ...mode-compile doesn't overwrite files. Pick a new --output name, or move the old file away.
game mode '...' stopped: This map has no object tag ...The map doesn't load that tag. See tag paths; the log's [modes] line lists what the map lacks.
The script stopped during a gameLook in the host's log for game mode '...' stopped:, the reason and the line and column it stopped at. Fix the file and start a new game.
The score goes up every momentCode outside on init runs on every tick. Give points behind a timer or a change.
A timer fires only onceCall reset() and set_rate(-100%) again when it reaches zero.
Traits flicker or don't stayApply the trait set on every tick the player should have it.
A HUD widget is empty or out of dateCall set_visibility, since widgets start hidden, call set_text or set_text_for again when its numbers change, keep the text within 96 bytes and give a meter a maximum above 0.
A widget doesn't take clicksOpen the player's menu with set_ui_menu(true), give the widget a position, make it clickable and visible for that player, and add an on widget click event.
A key does nothingCheck that the script has an on button press event, that the player's key is bound under Game Mode Abilities, and that no chat or menu is open.
A for each object with label loop finds nothing on a Forge mapCheck the label's spelling and capitals in the Forge menu's Properties, that the map was saved after Apply scripting, that you host the mode on that saved map, and that the labelled objects are spawned. See Forge objects by label.
declare team_count = 16 still plays eight teams or fewerCheck the game type, and that it plays with teams.
Players on Team 9 or later start anywhereA team past the first eight with no spawn points of its own starts at any start point. In Forge, give its starting points that team in their Team row.
The script stops when it creates a bodyThe model variant may not be one that body has; check the body list. The host's log says why it stopped.
A body stays a SpartanThe host lacks the body's campaign map.
Nobody is ever in the zoneGive the zone a position on your map and a size that fits; it has no visible edge.
An object can't be createdThe map may not have it, or the script has 2,048 created objects already. Delete the ones it's done with.
An invincible object disappearsThe game cleans up objects lying around: set_garbage_collection_disabled(true). Kill boundaries still remove it.
My changes don't show in the lobbySave the file, choose Refresh, select the mode again and start a new game.

The game's log is Logs/client.log in your player folder; a dedicated server's is data/<server>/server.log. When you report a problem, include the .rmeg, the map and what happened.