HaloScript extension for Visual Studio Code

HaloScript provides rich support for the Halo Scripting language, covering all Halo: The Masterchief Collection modding tools and Halo: Campaign Evolved.

HaloScript works with the file formats in the Halo Editing Kits. It is able to read the context each .hsc file has access by directly parsing scenario tags. Through this it understands exactly which other .hsc files are available in context as well as being able to access variables in the scenario tag (such as AI squads, point sets, cutscene flags).

HaloScript now provides full error checking as you write. Halo 2, Halo 4, and Halo 2 Anniversary Multiplayer allow direct script compilation in VSCode.

You can easily navigate to any functions or variables you have defined whenever they are called by using the VSCode Go To Definition function, as well as seeing all other places these are referenced by using Go to Declarations.

Both the lisp-like syntax used in the Halo Reach and earlier (including Halo: Campaign Evolved as it is based on the Reach engine) as well as the C like syntax used in Halo 4 and Halo 2 Anniversary Mutliplayer. Mixing both old and new syntaxes in Halo 4 and Halo 2 Anniversary Multiplayer is supported.

The extension also holds a complete list of all valid globals and functions for each game. Providing auto-complete and argument hints as you type.

Setting the language

This extension contributes each game's Halo Script iteration as a separate language. For a saved .hsc file inside a detected Editing Kit's canonical data or tags folder, HaloScript automatically switches to the matching game language.

Files outside an Editing Kit keep their current language selection. You can select a language manually from the Status Bar, or disable atlas.compiler.autoDetectScriptLanguage if you always prefer manual language selection.

Features

Editor actions are grouped under right-click → HaloScript, including Compile Scenario Scripts, tag insertion, scenario context, warning controls and compiler output. These commands are also available through the Command Palette.

Script Context

The HaloScript Scenario Context status bar item shows the current game and associated scenario, including loading and error states. Click it, or run HaloScript: Show Scenario Context, to search related scripts and open them, reveal scenario tags in Explorer, or reload the context. When several scenarios contribute context, the status item shows the first name and the number of additional scenarios; its tooltip lists their full paths. This view describes language context, rather than selecting the compiler's target scenario.

HaloScript automatically detects which over .hsc files are compiled together with the currently open file. It does this by reading the related scenario tag for the current file. If the current file is not used by any scenario tag, a warning is displayed.

Functions and variables from other .hsc files in context are available through intellisense. Right clicking on any variable or function will provide options to quickly jump to where a custom variable/function is defined, and conversely list all places that a function or variable is used.

The context extends to the scenario tag too. HaloScript reads scripting information such as AI squads, cutscene flags, point sets, camera points and object names. Nested values, such as squad members, objective tasks and point set points, can be accessed by typing / (or . in modern Halo 4 syntax) after the parent name.

HaloScript loads scenario context when you open a saved script, then checks its associated scenario tags for saved changes approximately every two seconds. To force a refresh or rediscover associations after adding or moving scenario tags, use right-click → HaloScript → Reload Scenario Info, run HaloScript: Reload Scenario Info from the Command Palette, or choose Reload scenario context from the scenario-context status item.

The Halo 4 iteration of HaloScript is also able to pull the context from object scripts provided the object variable used is defined in the scenario tag. If the object script is ambiguous, you can tell HaloScript which object script is being referenced by declaring the relative object tag path in a comment after a variable declaration, for example:

global object lich none; // objects\vehicles\covenant\storm_lich\storm_lich.vehicle

If you ever need quick access to a tag path, see the right click context menu options HaloScript: Insert Tag Path and HaloScript: Insert Tag Path (Browse). The former will show a searchable list of all tags within the current editing kit, and the latter will open a file browser dialog.

Renaming Scripts and Variables

Press F2 on a user-defined script, global, local variable or parameter to rename it. HaloScript previews the changes across the current script context, using unsaved editor contents and preserving comments, strings and shadowed variables. Same-name script overloads and stub/static declarations are renamed together. Names that conflict with an existing symbol, built-in, keyword or scenario value are rejected.

Rename covers the active script and its related source files, not references stored in binary tags or other scenarios. Instanced object members are not supported yet. Check the preview before applying changes, especially for shared scripts and scripts referenced by scenario tags.

Error Checking

HaloScript checks your code as you write to validate that you are writing with the correct syntax, and not trying to access variables and functions that do not exist within the current context. This error checking is designed to mirror what the HaloScript compiler checks for and should catch most issues before you compile in Sapien.

Some warnings have Quick Fixes available. Simply quick on an error, and click fix to check if a fix is available for the error in question.

To help reduce uncessary warnings when working on scripts that aren't yet attached to a scenario, there is an option in the right click context menu to disable warnings for missing variables: HaloScript: Disable Missing References Warnings.

Right-click a HaloScript editor and choose HaloScript: Disable Error Checking to clear live errors and warnings and stop further checks, including unused dormant script warnings. Choose HaloScript: Enable Error Checking to resume checking.

Snippets

Snippets are templates you can add to help you quickly add code to your scripts. HaloScript includes a large number of snippets for quickly creating template scripts, variables and loops. Snippets are also the method for quickly accessing the various enum values present in HaloScript.

If snippets are not showing when you start typing, you can press CTRL+SPACE to trigger Intellisense. Snippets can be distinguished from other autocomplete suggestions by the square icon. Once the snippet is highlighted, you can press TAB to insert it. Certain snippets included multiple parts, you can use TAB to jump between these.

The full snippets list can be accessed through the Command Palette (shortcut CTRL+SHIFT+P), and selecting Insert Snippet.

Autocompletion

HaloScript offers automcompletion for functions, built-in globals, value types, script types, and keywords. Autocomplete suggestions will show as you type. Use TAB to accept the autocomplete suggestion.

Autocomplete suggestions will also display relevant information, such as descriptions and accepted arguments for a function. When accepting an autocomplete suggestion for a function, parentheses will be automatically inserted if they are not already present. You can disable this with autocomplete.insertFunctionParentheses.

Formatting

Use Format Selection to format selected scripts or blocks without changing surrounding lines. Partial-line selections expand to complete lines; a selection ending at the start of the next line excludes that next line. Indentation comes from the surrounding script, using the same settings as Format Document. Selections cutting through multiline strings or comments, or whose formatting cannot be safely isolated, are left unchanged.

Atlas includes an opinionated formatter for both classic Lisp-style HaloScript and the newer Halo 4 / Halo 2 Anniversary MP syntax. Run Format Document from the editor context menu or use the standard VS Code formatting shortcut.

The wrap width defaults to 100 characters and can be changed with atlas.formatting.maxLineLength. Atlas is selected as the default formatter for HaloScript languages. To format automatically when saving, enable editor.formatOnSave for the relevant HaloScript language in VS Code settings. Pressing Enter also follows the active syntax's script, block, and parenthesis indentation.

Tag Path Insertion

Search starts with the selected text, with surrounding quotes removed. Use the picker's filter button to choose a tag type or return to all types. With an empty search, the most recently inserted tags appear first; up to 20 are remembered separately for each Editing Kit, including tags inserted through Browse.

Insertion preserves existing string quotes and leaves comment paths unquoted. New modern-syntax paths and paths containing spaces are quoted automatically. Replacing a complete quoted path preserves its quotes. Both insertion commands retain the original editor and selections; if the document changes while the picker is open, run the command again.

While editing a saved .hsc file inside an Editing Kit, right-click in the editor and run HaloScript: Insert Tag Path to search files under the active tags folder and insert the selected relative tag path, including its tag extension. Use HaloScript: Insert Tag Path (Browse) from the same menu to choose a tag file with a file browser instead.

Argument Hints

Argument hints are displayed when writing out a HaloScript function. These hints will highlight the structure of the arguments required for a function, the function description, the current argument to input, and a description of the type of argument to supply.

Arguments that end with ? are optional.

Hover Descriptions

Simply hover over any HaloScript function, built-in global, value type, or keyword to prompt a description of that item.

Compiling Scenario Scripts

The compile status button shows the scenario that will be compiled, or indicates that a scenario must be chosen. While Tool runs, its notification and status button show the selected scenario. Use Cancel in the notification, click the running compile status button, or run HaloScript: Cancel Compilation to stop Tool. Cancellation can interrupt scenario tag writes; the addon waits for Tool to exit before allowing another compile.

After compilation, a Last compile status item shows success, failure or cancellation. Hover to see the scenario, game and time, or click it to open compiler output. The result is retained for the current extension session and hidden while another compilation is in progress.

Compiler errors and warnings with recognised script locations appear in VS Code's Problems panel under HaloScript Compiler. Select an entry to jump to its script line, or use Show Problems.

While editing a saved .hsc file, select the Compile HaloScript tools button in the editor title or status bar. You can also run HaloScript: Compile Scenario Scripts from the Command Palette or the editor context menu. This feature is only avaible for Halo 2, Halo 4, and Halo 2 Anniversary Multiplayer.

Halo: Campaign Evolved Support

HaloScript extends syntax support for Halo: Campaign Evolved. To properly use it you will need to extract tags and source scripts from Halo: Campaign Evolved and place them in the same format as you would for Halo: Reach, with scripts in a data folder and tags in a tags folder. A tool like Baboon can be used to extract Halo: Campaign Evolved pak files into raw tags.

Credits

Crisp - Extension Developer

Alexis Jonsson - Icon design

tdanese - Fixing an issue with matching parentheses error handling

GeneralKidd - Adding support for automatic editing kit detection

Camden & Zoephie - For developing blam-tags & Baboon, which was used as reference for decoding scenario tag files for all games

3.1