Reclaimer Kit · Lesson 7 of 11

Write and test HaloScript

Start with a command you can call on demand, then connect a named trigger volume to a one-time event. Keep compile errors separate from runtime behavior.

Level
Intermediate
Before you start
A saved Halo 3 scenario. No Editing Kit tags needed for the scripts in this lesson. Understand basic object and marker placement first.
You will make
A callable test script and a named-volume event, saved and checked in a compiled map.

Shortcuts use Ctrl; Cmd also works on macOS, and Alt is Option. Keep the pointer over the viewport for editing shortcuts. Save before switching projects.

Use the right scripting system

HaloScript belongs to a map's scenario and is edited in the Scripts workspace. Megalo defines a game mode. This lesson uses HaloScript: its statements are parenthesized, and names refer to things in this scenario.

Save as courtyard_scripts. Open Scripts and use New Script. Replace the new item's entire text with the following static script. Give each new script in this lesson its own item.

Make a command you can call again

HaloScript
(script static void kit_ping
    (print "kit tutorial: ping")
)
  1. CompileChoose Compile or press Ctrl+Enter. Every kept script and global is compiled together. Wait for a success report and the map reload.
  2. Call itOpen View → Console with the map running, type (kit_ping) and press Enter. The console should show kit tutorial: ping. You can call a static script again to repeat the check.
  3. Try one deliberate errorTemporarily remove the final closing parenthesis and compile. Read the reported line and message, restore the parenthesis and compile again. Do not continue to gameplay testing while compilation fails.
  4. SavePress Ctrl+S. Compiling loads scripts into the game; saving keeps the source edits in your scenario. They are separate operations.

Prepare a named trigger volume

For an event tied to a place, add a Trigger volume with the Add menu, position it across a doorway and size it to cover the route. In the Object tab, name it kit_arrival and confirm the name. Use a unique name, and leave the player's start outside the volume. Its position is a corner of the box: extend the box below the player's feet and above their head so a player standing on the floor is actually inside it.

In 0.10.5, the compiler reads the scene's new and renamed markers directly. You can use kit_arrival in the script below as soon as you confirm its name. Compile loads the new volume with your scripts; F5 also reloads first if you have added or removed markers since the last load. You do not need to compile and reopen an intermediate base map.

An existing named trigger volume works too: substitute its exact name. Save the scenario to keep the volume and script together, and compile the finished map when you are ready to share it.

Wait for a player to enter

HaloScript
(script startup kit_arrival_event
    (sleep_until (volume_test_players kit_arrival) 15)
    (print "kit tutorial: arrival volume entered")
)

startup begins when the scenario starts. sleep_until waits until its condition is true, checking every 15 game ticks here. At Halo 3's 30 script ticks per second, that is about half a second. This script then prints once and ends; leaving and re-entering does not restart it.

Compile, wait for the map to reload, press F5 and walk into the volume. Open the console to check for the message. A startup script can run while the editor's world is running, before you press Play, so use the callable script above when you need a repeatable diagnostic. Pausing the world pauses scripts as well.

Debug the condition before the event

In the console, evaluate (volume_test_players kit_arrival) outside and inside the volume. The condition should be false outside and true inside. This isolates a misplaced volume from an event that already ran.

SymptomCheck
Unknown volume, flag or camera-point nameConfirm the name in the Object tab and use its exact spelling. The compiler reads the scene's marker names. If you deleted a marker, update every script that still names it.
Play reports that the map's original scripts are being usedRead the name in the status message. A missing marker, or a newly named object that only a compiled map contains, prevents the edited scripts from loading. Correct it or compile and open the finished map before testing that object.
Compilation succeeds but nothing printsWorld paused, startup script already completed, player never entered the volume, or output visible in the console rather than the HUD.
A command is dimmed in completionSome retail debug commands are unavailable in release builds. Use the functions the running Kit lists as supported.
Unexpected old behaviorWait for the successful compile reload. A failed compile does not replace the running scripts.

Check the compiled map

Save the final scenario, compile it under a unique final package name and verify the result. Open that package and call (kit_ping). Start with the player outside the volume, enter it, and check the event message. Save your source scenario alongside its dependencies; the map package is the playable output.

Do not remove existing scripts or globals merely to make the list shorter. The rest of a mission can depend on them. Avoid removing or reordering markers that existing compiled scripts name.

Next step

Learn squads, areas and objectives or package the result. Reference: Scripts workspace, Console.