@blamnetwork/megalo

Introduction ​

Foreword ​

Megalo was designed in March 2008 by Bungie's Tyson Green as a data-driven system for implementing Halo multiplayer game rules. End-user Megalo tooling was an objective from the start, but it was something Bungie never shipped during Reach's original development.

Since then, Halo Studios has released Bungie's MegaloEdit.exe with the Halo Reach Editing Kit (HREK), enabling players to build their own scripts. Little documentation has accompanied that tooling.

This documentation is the result of an extensive study of Halo: Reach Megalo. It deliberately follows Bungie's own Ubiquitous Language — naming things as Bungie would have named them, using the same vocabulary found in shipped scripts and the MegaloEdit tooling.

I would like to give my thanks to those modders who worked tirelessly to understand Megalo and make cool gametypes with it in the last 16 years including kornman, DavidJCobb, Pfoiffee, Soptive and countless others I have not had the pleasure of meeting. - Codie

What is Megalo? ​

Megalo is the scripting language Bungie built for Halo: Reach multiplayer rules. Authors edit human-readable .txt scripts with a Megalo-aware editor; Bungie shipped MegaloEdit.exe with Reach. We recommend MegaCrow as a free and open-source alternative.

Megalo is not a general-purpose language. It has no functions, loops, or arbitrary expressions — only the condition and action vocabulary the engine exposes, organized into triggers that fire on game events.

A Megalo program is a sequence of elements that describe a gametype or custom map variant:

ConceptRole
ElementsBlock and leaf keywords at the script root — metadata, teams, variables, triggers, HUD widgets, string tables, and more. See The element model; individual pages are listed under Elements in the sidebar.
TriggersEvent handlers. Each trigger runs when its conditions are satisfied, then executes its actions. See trigger.
ConditionsPredicates such as if, player_died, timer_expired, or object_in_area. See condition.
ActionsImperative statements — set, create_object, hud_post_message, for_each, and dozens of others. See action.
VariablesTyped slots (number, timer, object, team, player) scoped to global, team, player, or object storage. See Variable model.
ReferencesSymbolic operands that identify players, teams, objects, timers, and custom variables at runtime. See References.

Source files ​

Megalo editors store scripts as plain text. A typical gametype script begins with metadata and ends with triggers:

megalo
include "strings/slayer_strings.txt"

engine_data
	name slayer_title
	description slayer_description
	icon k_engine_icon_slayer
	category slayer
end

variables global
	local number my_counter 0
end

trigger initialization
	action set my_counter set_to 0
end

Scripts can include other files; the editor merges includes before compile. Some scripts also declare a base to inherit from a compiled parent variant — see Base files.

The exact set of valid conditions and actions depends on the Reach build. See Megalo Versions for per-build tables.

Reading guide ​

Work through these pages in order, or jump to a topic:

  1. Syntax & file format — comments, tokens, naming, includes, element model
  2. Base files — inheriting from a compiled parent variant
  3. Variable model — types, scopes, constants, built-ins
  4. trigger — kinds, action scope, execution, for_each
  5. condition — comparisons, events, and / or, negation
  6. action — opcodes, set, math operations, action families
  7. References — player, team, object, timer operands
  8. Example scripts — annotated walkthroughs of minimal scripts
  9. Object lists — engine lookup tables for symbolic names
  10. Compiler settings — compile-time strictness and temporary overflow

For using the TypeScript library, see the usage guide.

See also ​