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

Script Context

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 all relevant scripting information from the tag, such as AI squads, cutscene flags, point sets, camera points, object names and more. Scenario information that has nested blocks, such as ai squads, objective tasks, and point set points can be accessed by typing / (or . in the c-like Halo 4 style script) after entering the squad / objective / point set name. HaloScript reads the scenario context once when you open a file. If you ever update the scenario tag while scripting, you can execute HaloScript: Reload Scenario Info in the right click context menu.

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.

Debugging

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 debugging is designed to mirror what the halo script compiler checks for and should catch most issues before you hit 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.

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.

Tag Path Insertion

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

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.0