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.rvtfiles 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 yourGame Modesfolder. - 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.
- Open your Game Modes folderIn Host Game, choose Game Type, then Open Folder. It's in your player folder:
System Game ModesfolderWindows %LOCALAPPDATA%\ProjectReclaimer\Game ModesmacOS ~/Library/Application Support/ProjectReclaimer/Game ModesLinux ~/.local/share/ProjectReclaimer/Game Modes(or under$XDG_DATA_HOME) - Make the fileSave this as
my-first-mode.rmegin that folder, as plain UTF-8 text, or download it as megalo-timed-score.rmeg. Keep the extension: a file ending in.rmeg.txtis 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 - 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.
- 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.

.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
- Slow it downChange
declare interval = 1todeclare interval = 2. Points now arrive every two seconds. - 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 - 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.
- 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:
.\project-reclaimer.exe mode-check "$env:LOCALAPPDATA\ProjectReclaimer\Game Modes\my-first-mode.rmeg"
"/Applications/Project Reclaimer.app/Contents/MacOS/project-reclaimer" mode-check ~/Library/Application\ Support/ProjectReclaimer/Game\ Modes/my-first-mode.rmeg
./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).
| Command | What it does |
|---|---|
mode-check FILE | Checks 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 FILE | Reads 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.json | Checks 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 MODE | For a source without a mode in its header: the game type, such as Territories. |
mode-compile … --template PRESET.json | Lays 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.
--[=[ 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.
| Setting | What it holds |
|---|---|
name | The name the picker and lobby show, 1 to 48 characters. Without one, the file's name. |
mode | The game type it plays. Slayer without one. |
author | Who 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_layout | How 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_end | true: 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.seed | Where 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:
[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:
| Option | Values |
|---|---|
rounds.teams, rounds.reset_players, rounds.reset_map, rounds.friendly_fire, rounds.betrayal_booting | 0 off, 1 on. Capture the Flag, Assault, Territories and VIP always play in teams; Infection and Juggernaut never do. |
rounds.limit | 1 to 10 rounds. |
rounds.minutes | 0 (unlimited) to 60. |
rounds.early_victory | Wins for an early victory, 0 (off) to 5. |
rounds.team_changing | 0 disabled, 1 enabled, 2 balancing only. |
respawn.lives, respawn.team_lives | 0 (unlimited) to 50; to 100. |
respawn.seconds, respawn.suicide, respawn.betrayal | 0 to 240 seconds. |
respawn.growth, respawn.traits_duration | 0 to 15; 0 to 60 seconds. |
respawn.synchronize, respawn.on_kills | 0 off, 1 on. |
map.weapons | 0 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.vehicles | 0 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_vehicles | 0 or 1. |
powerups.red_duration, powerups.blue_duration, powerups.yellow_duration | 0 to 120 seconds. |
player.… and the other trait sets below | The 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 type | mode. options |
|---|---|
| Slayer | score, kill, assist, death, suicide, betrayal, leader_kill, elimination, assassination, headshot, beatdown, sticky, splatter, spree, team_scoring |
| Capture the Flag | score, reset, sudden_death, touch_return, flag_at_home, flag_waypoint, flag_type, objective_respawn |
| Oddball | score, carrying, kill, ball_kill, carrier_kill, ball_count, spawn_delay, reset, auto_pickup, ball_effect, team_scoring |
| King of the Hill | score, uncontested, kill, inside, outside, opaque_hill, team_scoring, hill_movement, hill_order |
| VIP | score, 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 |
| Juggernaut | score, 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 |
| Territories | capture, sudden_death, one_sided, lock_on_capture, objective_respawn |
| Assault | score, sudden_death, reset, arming, disarming, fuse, reset_on_disarm, objective_respawn, bomb_type, bomb_waypoint |
| Infection | initial_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.
| Source | What 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 header | Game type | game.get_game_type() | More than eight teams |
|---|---|---|---|
Slayer | Slayer | 2 | Yes |
CaptureTheFlag | Capture the Flag | 1 | No: eight teams |
Oddball | Oddball | 3 | Yes |
KingOfTheHill | King of the Hill | 4 | Yes |
Vip | VIP | 6 | Yes |
Juggernaut | Juggernaut | 7 | No: no teams |
Territories | Territories | 8 | Yes |
Assault | Assault | 9 | No: eight teams |
Infection | Infection | 10 | No: no teams |
EscalationSlayer | Escalation Slayer | 12 | No |
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.
| Mode | File | Shows |
|---|---|---|
| Growth | growth.rmeg | Reading deaths and killers; size, damage and resistance together. The shortest bundled mode. |
| One in the Chamber | one-in-the-chamber.rmeg | Ammunition and lethal damage. |
| Gun Game | gun-game.rmeg | set_weapon, how a player died, altif chains. |
| Zone Control | zone-control.rmeg | A declared zone moved at run time, per-player widgets and meters. |
| Flood Infection | flood-infection.rmeg | Roles, teams, a body for each life, trait sets, a winner chosen by the script. |
| UNSC vs Covenant vs Flood | faction-battlefront.rmeg | 70 classes on a two-page class picker built from widgets, other games' characters, reinforcement bars. |
| UNSC vs Covenant: Reach | reach-battlefront.rmeg | Halo: Reach's characters and weapons as classes, bodies that fly, and a spare class for when a map can't have the others. |
| Conquest | bf-conquest.rmeg | Squads, 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.
| Design | How |
|---|---|
| Capturing | Halo 3's own Territories: mode = "Territories", on every map that has them. |
| Tickets | Each 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. |
| Squads | A 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. |
| Deploying | Each 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. |
| Classes | Assault, Medic, Support, Engineer and Recon. Weapons are reserved with set_weapon_pickup, and abilities are as in Combined Arms. |
| HUD | Both 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.
| Design | How |
|---|---|
| Power weapons reserved for a class: rockets, Spartan Lasers, Fuel Rod Guns and Missile Pods for Anti-Armor, Sniper and Beam Rifles for Recon | Each 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 vehicles | set_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 stands | Hold 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, regenerators | on 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, overshields | place_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 drain | give_equipment(trip_mine); place_at_me(power_drainer, …). |
| Recon: invisibility, marked targets | A trait set with camouflage; get_crosshair_target() and a bullseye waypoint for the Recon's team for 10 seconds. |
| Squad spawns | for 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 beacons | Objects 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 vehicles | Vehicles 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:
| Option | Script reads | Default | Range |
|---|---|---|---|
initial_infected | script_option[0] | 1 | 1 to 8; at the outbreak, one survivor is always left. |
round_seconds | script_option[1] | 180 | 30 to 900 seconds. |
warmup_seconds | script_option[2] | 10 | 0 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 to | Numbers | Objects | Players | Teams | Timers |
|---|---|---|---|---|---|
global | 12 | 16 | 8 | 8 | 8 |
object | 8 | 4 | 4 | 2 | 4 |
player | 8 | 4 | 4 | 4 | 4 |
team | 8 | 6 | 4 | 4 | 4 |
temporaries | 10 | 8 | 3 | 6 | 0 |
- 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. declareis only needed for a starting value:declare player.number[0] = 3. Numbers and timers otherwise start at 0, references atno_object,no_playerorno_team. Only numbers and timers take a starting value, and temporaries none.with network priority loworhighis accepted and ignored;localisn't accepted.alias points = player.number[0]gives a slot a name, used ascurrent_player.points.alias scratch = allocate temporary numberorallocate global.numbertakes a free one for you; don't also write to that slot by number. An alias can name a constant or ascript_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_playerorno_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_objectandcurrent_teamare the one being visited;team[0]toteam[7](to the last of the teams a script declares) andneutral_teamare 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.
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, thenglobal.number[0] += 2. There's no5 + 2. - A call that gives a value goes in an assignment.
current_player.get_death_count()can't stand alone, go straight in anif, 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_heldandis_driver.
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
| Loop | Goes through |
|---|---|
for each player do | Every player in the game, dead ones too. Check current_player.is_not_respawning() for the living. |
for each player randomly do | The same players in a shuffled order. |
for each team do | The playable teams (8, or as many as the mode declares) and the neutral team, empty ones too. |
for each object do | Every 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" do | The 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:
| Event | current_… in it | Values in it |
|---|---|---|
| The script's body | None until a loop sets one | Runs every tick. |
on init: do … end | None | Once, as each round starts. |
on widget click: do … end | The player who clicked | clicked_widget: the widget's number. See script menus. |
on button press: do … end | The player who pressed | pressed_button: button.melee and so on. See buttons. |
on object damaged: do … end | current_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 … end | The player whose body died | killed_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.
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 callset_rateagain 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
| Quantity | Unit |
|---|---|
Positions (get_x, set_position), distances (get_distance_to), creation and attachment offsets | Tenths of a Forge unit. A Forge unit is 10 feet, so a tenth is a foot. |
move_to, a position in the header, zone sizes | Whole Forge units. |
Velocities (set_velocity) | Forge units a second. |
Speeds (get_speed) | Feet a second. |
| Facings | Whole 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, damage | Percent. |
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
| Call | What it gives or does |
|---|---|
biped | The player's body, or no_object while they're dead. |
score | Their 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. |
team | Their 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
| Call | What 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
| Call | What 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
| Call | What 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_look | See looks. |
Teams and the game
| Call | What it does |
|---|---|
team[0].score | The 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_sound | See 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 body | What it does |
|---|---|
max_health = 200, max_shields = 50 | The 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 = 150 | How 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.
truelets 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:
-- 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
| Call | What 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:
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.

| Call | What 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:
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.
| Call | What 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. |
| Piece | Names |
|---|---|
| Spartan helmets | mark_vi, cqb, eod, eva, hayabusa, mark_v, odst, recon, rogue, scout, security |
| Spartan shoulders | mark_vi, cqb, eod, eva, hayabusa, recon, scout, security |
| Spartan chests | mark_vi, bungie, cqb, eod, eva, hayabusa, katana, recon, scout |
| Elite, every region | combat, assault, flight, commando, ascetic |
| Colors | steel, 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 |
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:
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" = 1in 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:
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
| Call | What 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.
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.
--[=[ 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:
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.
| Name | Character | Comes from | Model variants (looks) |
|---|---|---|---|
spartan | Spartan (multiplayer) | Every multiplayer map | default, blue, red, green, orange, purple, gold, brown, pink |
elite | Elite (multiplayer) | Every multiplayer map | default |
forge_monitor | Forge's monitor | Every multiplayer map | monitor |
master_chief | Master Chief (campaign) | The Storm (040_voi) | default, cinematic |
arbiter | Arbiter (co-op player) | The Storm (040_voi) | default_arb |
arbiter_ai | Arbiter (campaign AI) | The Storm (040_voi) | default_arb, nude, nude_branded |
elite_coop | Elite (co-op players 3 and 4) | The Storm (040_voi) | default, player4 |
marine | Marine | The 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_female | Marine (female) | The Storm (040_voi) | default, fem1, fem2, fem3, no_helmet, anete, chan, hartmann, michelle, cinef1, cinef2 |
odst | ODST | The Ark (070_waste) | default, captain |
johnson | Sergeant Johnson (Halo) | Halo (120_halo) | As marine |
crewman | Naval crewman | Crow's Nest (020_base) | ethnic, lessethnic |
lord_hood | Lord Hood | Crow's Nest (020_base) | default, no_hat, dress, dress_no_hat |
miranda | Miranda Keyes | Crow's Nest (020_base) | default, combat, dress, dead |
worker | Civilian worker | The Storm (040_voi) | default, cv1, cv2, dead |
cortana | Cortana | Cortana (110_hc) | default |
cortana_near_death | Cortana (High Charity) | Cortana (110_hc) | default |
grunt | Grunt | The Storm (040_voi) | minor, major, ultra, spec_ops, heavy |
jackal | Jackal | The Storm (040_voi) | minor, major, shieldless, sniper |
drone | Drone | The Storm (040_voi) | minor |
elite_warrior | Elite (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 |
brute | Brute | The Storm (040_voi) | minor, major, ultra, captain, captain_major, captain_ultra, bodyguard, jumppack, stalker, tracker, chieftain_armor, chieftain_weapon |
brute_chieftain | Brute Chieftain | The Storm (040_voi) | As brute |
brute_jumppack | Brute (jump pack) | The Ark (070_waste) | As brute, without ultra and captain_ultra |
hunter | Hunter | The Storm (040_voi) | minor |
truth | Prophet of Truth | Crow's Nest (020_base) | default, floodified |
truth_hologram | Prophet of Truth (hologram) | The Storm (040_voi) | None to choose: use none |
guilty_spark | 343 Guilty Spark | The Ark (070_waste) | monitor, monitor_combat |
sentinel | Sentinel | The Ark (070_waste) | default |
sentinel_constructor | Sentinel constructor | The Ark (070_waste) | default |
flood_infection | Flood Infection form | The Covenant (100_citadel) | default |
flood_human | Flood combat form (Human) | Floodgate (050_floodvoi) | standard_fch |
flood_elite | Flood combat form (Elite) | Floodgate (050_floodvoi) | standard_fce |
flood_brute | Flood combat form (Brute) | Floodgate (050_floodvoi) | default |
flood_carrier | Flood carrier form | Floodgate (050_floodvoi) | default, shielded |
flood_ranged | Flood pure form (ranged) | Floodgate (050_floodvoi) | None to choose: use none |
flood_stalker | Flood pure form (stalker) | Floodgate (050_floodvoi) | None to choose: use none |
flood_tank | Flood 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.
| Game | Names | Where |
|---|---|---|
| Halo: Reach | reach_spartan, reach_elite | Reach'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 Firefight | reach_trooper, skirmisher, reach_grunt, reach_jackal, reach_brute, reach_brute_chieftain, reach_hunter, reach_drone, reach_engineer, reach_guta | Reach'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 Evolved | halo1_chief, halo1_marine, halo1_elite, halo1_grunt, halo1_jackal, halo1_hunter, halo1_flood_human, halo1_flood_elite, halo1_flood_carrier, halo1_flood_infection | Halo 3's, ODST's, Reach's and Halo 2's maps; on Combat Evolved's own, halo1_chief alone |
| Halo 2 | halo2_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_infection | Halo 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:
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_sclforelite_warrior,johnsonformarine,captainforodst. - 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_weaponand 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.bipedis 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_objecttarget does nothing. - Classes take the same names in their
bipedand the same looks inmodel_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,eliteandforge_monitorneed 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:
--[=[ 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 heregoalis 0 andintervalis 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 withset_position, as Zone Control does, to find its place at run time. Before you play Zone Traits, set the hill'spositionto a place on your map: in Forge, fly the monitor there and read Where it is on the Forge menu's Map tab.
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.
| Trait | Values |
|---|---|
resistance | 1: 10%; 2: 50%; 3: 90%; 4: 100%; 5: 110%; 6: 150%; 7: 200%; 8: 300%; 9: 500%; 10: 1000%; 11: 2000%; 12: invulnerable. |
recharge | 1: −25%; 2: −10%; 3: −5%; 4: disabled; 5: 50%; 6: 90%; 7: 100%; 8: 110%; 9: 200% shield recharge. |
vampirism | 1: off; 2: 10%; 3: 25%; 4: 50%; 5: 100%. |
headshots | 1: immune; 2: vulnerable. |
shields | 1: none; 2: normal; 3: 2×; 4: 3×; 5: 4×. |
damage | 1: 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_regeneration | 1: on; 2: off; 3: on, with firebombs. |
ammo | 1: normal; 2: infinite; 3: bottomless clip. |
pickup | 1: allowed; 2: disabled. |
speed | 1: 25%; 2: 50%; 3: 75%; 4: 90%; 5: 100%; 6: 110%; 7: 125%; 8: 150%; 9: 200%; 10: 300%. |
gravity | 1: 50%; 2: 75%; 3: 100%; 4: 150%; 5: 200%. |
vehicles | 1: none; 2: passenger only; 3: full use. |
camouflage | 1: off; 2: poor; 3: good; 4: invisible. |
waypoint | 1: off; 2: allies; 3: everyone. Controls player waypoints, not the script's waypoints. |
aura | 1: off; 2: team color; 3: black; 4: white. |
radar | 1: off; 2: allies only; 3: normal; 4: enhanced. |
radar_range | 1: 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.
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:
| Call | What 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.
| Call | What 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.
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.
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.
--[=[ 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 |
|---|---|
title | The picker's title, up to 48 bytes. |
teams | 2 to 8 team names, up to 24 bytes each. |
script_menu | true: 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 setting | What it holds |
|---|---|
name, description | Up to 32 and 120 bytes. A team's classes have different names. |
team | Its team's number; 0 is the first of teams. |
cost | The deployment points it takes, 0 to 100,000. |
max_active | The most players in it at once; 0 for any number. A choice waiting to deploy counts. |
biped | The body, from the body list. |
model_variant | The body's model variant. |
camera | "native", Halo 3's, or "third_person", on foot. |
primary, secondary | Weapons 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_wield | true: the secondary in the left hand. Two plasma rifles only. |
grenades | Frag, plasma, spike and firebomb grenades, 0 to 4 each: [2, 0, 0, 0]. |
traits | Traits while in the class, as a table: [logic.deployment.classes.traits]. |
health | The 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.
| Call | What 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:
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.

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 want | Use |
|---|---|
| A key that triggers an ability | The 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 held | Built in: one event per press. is_button_held says the key is still down. |
| To react to Halo 3's own actions | button.jump, crouch, melee, grenade, equipment and flashlight. |
| Active camouflage for a time, with a recharge | A 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 carries | current_player.give_equipment(name). |
| An ammunition point, repairs | refill_ammo() for the players near your object; is_of_type(vehicle), get_distance_to and the vehicle's health. |
| A spawn point the player chooses | A key or a script menu, then set_primary_respawn_object. |
| Classes and their loadouts | Classes 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:
| Key | Keyboard | Controller |
|---|---|---|
| Ability 1 | X | D-pad right |
| Ability 2 | 2 | D-pad left |
| Ability 3 | 3 | D-pad down |
| Ability 4 | H | Not 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
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
| Button | A press is | Held while |
|---|---|---|
ability_1 … ability_4 | The player's ability key going down | It's down |
jump | Jump | Jump is held |
crouch | Starting to crouch | Crouching; a controller's stick click toggles it |
melee | A melee attack starting | The attack lasts |
grenade | A grenade throw starting | The throw lasts |
equipment | The player using their equipment | A throw lasts |
flashlight | Flashlight: 4, D-pad up | It'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,grenadeandequipmentcount only when the player really attacks, throws or uses something. Multiplayer characters have no flashlight, soflashlightis 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:
[[logic.megalo_traits]]
camouflage = 4
Then apply it while a player timer runs, and start a recharge:
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:
| Kind | Names | Maps |
|---|---|---|
| Equipment as thrown: it works at once | bubble_shield, deployable_cover, radar_jammer, power_drainer, regenerator, trip_mine, grav_lift, grav_lift_permanent, flare, auto_turret | Every stock multiplayer map |
| Equipment to pick up | bubble_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_pickup | Every stock multiplayer map |
| Mounted guns, to man | machine_gun_emplacement, plasma_cannon_emplacement, missile_pod_emplacement | Machine gun: every stock multiplayer map. Plasma cannon: all but one. Missile pod: where the map has one. |
| Vehicles | mongoose, ghost, warthog, gauss_warthog, troop_warthog, chopper, prowler, banshee, hornet, scorpion, wraith, shade, elephant | Where the map has them |
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_emplacementandplasma_cannon_emplacementare the guns to man, not themachine_gun_turretandplasma_cannonweapons, which are the guns carried after tearing them off.grav_lift_permanentis the Grav Lift Forge places, which never runs out.auto_turretis 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
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:
-- 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:
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:
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 withis_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. Deletingno_objectdoes nothing. - How many: count with
for each object with label "cover" dobefore making another. - Where:
get_distance_tofrom 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_collectkeeps 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.timerandplayer.objectvariables. 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_pointon 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.
| Call | What 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. |
team | The 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_shields | Health 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_sequence | The 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_priority | See waypoints. |
set_damage_from, set_damage_team, set_damage_player | See damage. |
set_deploy_point, get_territory_owner | See squads and the deployment map. |
Creating objects
typeis 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.labelis a text or number forfor each object with label, ornone.flagsisnone,absolute_orientationornever_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 isnoneor, 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_orientationmakes offsets follow the object's full orientation; the other flags use its heading.- A
no_objectbasis givesno_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:
-- 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
| Call | What 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:
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:
| Type | Names | Takes it |
|---|---|---|
| An object kind | biped, vehicle, weapon, equipment | is_of_type |
| A kind of vehicle | aircraft (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 object | Equipment, emplacements and vehicles | Both |
| A weapon | assault_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_cannon | Both |
| A body | The body list | place_at_me |
| An objective item | flag, bomb, oddball (or skull) | is_of_type |
| A tag path | "objects/vehicles/mongoose/mongoose", as text | Both |
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.
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:
| Call | What 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.
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:
| Call | What 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
| Call | What 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.
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.
- 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.
- Save the mapThe values belong to the map: save it as for any edit.
- 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.
-- 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.aliasonly 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 7finds objects labelled7. - Only the host edits labels, but players see them and can save them with the map. Move a frozen object before labelling it.
Limits
| Limit | Value |
|---|---|
| Source file | 128 KiB; the script stored with its source and settings must fit 256 KiB |
Saved .json game type | 2 MiB |
| Source structure | 32,768 tokens; 4,096 statements a block; 16 arguments a call |
| Nesting | 32 levels in the file, 64 calls and blocks while running |
| Steps per event | 65,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 visits | 8,192 |
| Created objects | 2,048 at once |
| World changes in one tick | 4,096 |
| Trait sets | 16 |
| Options | 32 declared; script_option[0] to [15] read |
| Declared objects | 64 |
| Teams | 8, or up to 64 with declare team_count in Slayer, Oddball, King of the Hill, VIP and Territories; team names 1 to 24 bytes |
| Classes | 128, at most 48 a team; 2 to 8 teams with classes |
| Squads | 16 a team |
| Deploy points, waypoints | 64 deploy points at once; 64 waypoints shown at once |
| Aliases | An alias names a variable or a constant; its value has at most 64 parts |
| Sounds | 8 a tick; 16 looping at once |
| Weapon pickup bars, driver bars | 16 of each per player |
| HUD widgets | 32 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 |
| Attachments | Chains of up to 32 objects |
| Labels, model variants | 32 bytes |
| Tag paths | 256 bytes |
| Button presses | 10 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:
pregameruns beforeinitas a round starts.localruns each tick once for each player, withhud_playerthat player, and the widgets it changes are theirs alone.host migrationanddouble host migrationare read too. - Players:
is_spartan,is_eliteandis_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 propertiesfrag_grenadesandplasma_grenades, read and written. - Objects:
set_shapeandset_shape_visibility,set_pickup_permissions,set_spawn_location_permissions,set_progress_bar,set_waypoint_range,set_waypoint_timerandset_waypoint_text,push_upward,add_weaponandremove_weapon,get_orientation,is_out_of_bounds,is_in_use, and the device calls.kill(1), Reach's silent kill, is the same kill askill(0). - The game:
show_message_to,send_incident,play_sound_forandget_random_object; thegame.values such asgame.score_to_winandgame.current_round; and the timersgame.round_timer,game.sudden_death_timerandgame.grace_period_timer, which take a value,reset()andset_ratelike 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 inkiller_type_is(kill | betrayal)or aplace_at_mewithnever_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].
| Call | What 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 variant | What 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 vehicle | The 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 death | Runs 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 biped | None, 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
- Run
mode-checkwith the version you'll host. Then refresh and reselect the mode. - 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.
- For teams, check joining, leaving, changing teams and a team becoming empty. For objects and zones, check their positions and any assets they need.
- 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
| Problem | What to do |
|---|---|
| My mode isn't in the list | Run 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.nope | That name isn't a game option of this game type. See game options by name. |
Round limit must be 1..=10 | A game option's value is out of range. |
1:1: Unterminated block comment | The 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 property | The 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 = 1 | Add "rounds.teams" = 1 under [options]. |
Every deployment team needs an unlimited free class | Give each team a class with cost = 0 and no max_active. |
team_count must match the deployment's teams | A 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 scale | Remove player_scale_percent, and use set_scale in the script. |
Assault can't have more than 8 teams | Only Slayer, Oddball, King of the Hill, VIP and Territories can. See game types. |
Script exceeds 256 KiB | The 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:0 | The 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:zealot | That 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.money | The 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_points | That call needs classes in the header. |
Unsupported Megalo API: Game.play_sound_for | That call doesn't exist. Check this page for the name. |
A value-returning call needs an assignment or condition | Assign the result, even of deploy_class and place_at_me: see values and conditions. |
Comparisons take values, not action function calls | Read the call into a variable first, then compare the variable. |
Expected a condition function | Only the condition calls go straight in an if. |
Global.Number[12] exceeds Reach variable capacity | There are fewer slots of that kind; see the variables table. |
Timer rate must be a constant percentage | Write 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_1 | Pass 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 game | Look 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 moment | Code outside on init runs on every tick. Give points behind a timer or a change. |
| A timer fires only once | Call reset() and set_rate(-100%) again when it reaches zero. |
| Traits flicker or don't stay | Apply the trait set on every tick the player should have it. |
| A HUD widget is empty or out of date | Call 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 clicks | Open 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 nothing | Check 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 map | Check 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 fewer | Check the game type, and that it plays with teams. |
| Players on Team 9 or later start anywhere | A 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 body | The 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 Spartan | The host lacks the body's campaign map. |
| Nobody is ever in the zone | Give the zone a position on your map and a size that fits; it has no visible edge. |
| An object can't be created | The map may not have it, or the script has 2,048 created objects already. Delete the ones it's done with. |
| An invincible object disappears | The game cleans up objects lying around: set_garbage_collection_disabled(true). Kill boundaries still remove it. |
| My changes don't show in the lobby | Save 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.
