mast README

An extension for developing missions for Artemis Cosmos. It is intended to facilitate developing mission scripts using the MAST language.

MAST references:
sbs_utils repository
LegendaryMissions repository
MAST Starter repository
Artemis Cosmos bug reporting

Features (Non-exhaustive!)

Includes:

• Basic formatting and coloring, based on Python
• Error checking
  • Checks if labels are defined, and defined properly
  • Checks for proper route label usage
  • Proper f-string usage
  • Checks if label names are overriden by a variable name
  • Some possible syntax errors
  • Warning for deprecated functions
• Autocompletion and hover information for applicable functions within the sbs and sbs_utils packages, as well as built-in python functions
• Autocompletion for variables etc in current file and files in scope
  • NOTE: It's very difficult to determine the type of a variable programmatically for python (and, therefore, MAST). The extension can't really do it, so you'll have to keep track of what each variable represents. The extension will try to give you options that show the object type associated with that option.
• Autocompletion for labels in current file and files in scope
• Autocompletion for roles, inventory keys, shared string, keys, shared variable keys, data set (blob) keys, and link keys.
• Function signature information (i.e. notes on argument types)
• Checks for correct function argument counts
• Go To Definition functionality for sbs_utils and modules for functions and labels in scope.
• Hover information functionality
• Rename Symbol functionality for variables in the current label
• Find References functionality (functions, inventory, data set, and link keys, and roles)
• Checks for module versions
  • Can update all to latest version, or manually update
• In mission folders, checks for __init__.mast in the folder you're working in. If it doesn't exist, will promt with an option to auto-generate the file, with all .mast and .py files included automatically.
• Autocompletion of filenames for __init__.mast
• When loading packages, if an equivalent source folder exists, then the source folder will be loaded instead (to help with developing a mission and its dependencies at the same time when needed.) If multiple missions have the same name in description.yaml, then the one with a .git folder, or if the category or keywords incldue "Dev" or "Development, then that folder will be used.
• Checks for root artemis directory existence - most functionality requires the opened folder to be in the artemis mission directory

Fun special features:

• Two custom GUIs. Both of these offer a prompt under applicable circumstances to open them.
  • Face Builder: Build a specific face string with a handy GUI. Press Ctrl+Shift+P and type "Face Builder".
  • Ship Viewer: Find and view ships specified in shipData.yaml. Press Ctrl+Shift+P and type "Ship Viewer".
• Documentation syntax for inventory, blob, link, and role keys. The documentation string will be displayed in autocompletion (hover is TODO).

#@link LinkName: The link to describe
link(x, "LinkName", y)
#@inventory side_name: The name of the side
set_inventory_value(id, "side_name", name)
#@blob example_blob: The blob key description
blob.set("example_blob", val)
#@data_set example_data_set: The data set key description (Same as blob key!)
set_data_set_value(id, "example_data_set", val)
#@role example_role: The role's descrption
role("example_role")

• Documentation syntax for label-scoped variables (especially useful for label data!). Both of these are acceptable.

#@arg: The message to present 
default message = "Whoo good workout."
#@arg time: The duration  the boost lasts
default time = random.randint(10,16)

• Python autocompletion and auto-imports! NOTE: If using the Pylance extension, the mast extension will have delayed initial loading in python files.

Requirements

Dependencies should be packaged with the extension. If you encounter an issue with a dependency, or it is not included, please let me know ASAP. Included dependencies:

• adm-zip
• hjson
• js-yaml
• python-shell
• vscode-uri

Known Issues

• See GitHub for documented issues, or to create a new issue.

Planned Features

• Additional error checking

Release Notes

See the Changelog

Contributions

Contributions are more than welcome! I am by no means an expert when it comes to language servers, VS Code extensions, or even programming in general - I'm just able to muddle through and figure things out as I go. I will not claim that this extension is optimized in any way, I'm just trying to make it functional. Help would be great!

Extension Settings

This extension contributes the following settings:

• mastLanguageServer.enablePythonCompletions: Enable MAST language-server function-related completions in Python files, including blob keys, inventory keys, roles, links, argument hints, and related call completions. Default: true

• mastLanguageServer.maxNumberOfProblems: Controls the maximum number of problems produced by the server. Scope: resource Default: 100

• mastLanguageServer.trace.server: Traces the communication between VS Code and the language server. Allowed values: off, messages, verbose Scope: window Default: off

• mastLanguageServer.allowMultipleCaches: If enabled, the extension caches applicable files for every mission opened during the session. If disabled, it only caches files for the currently active mission. Default: true

• mastLanguageServer.cacheTimout (Deprecated): If not 0, the cache expires after the specified number of minutes to clear memory. Default: 0

• mastLanguageServer.autoCompile: Enables MAST compiler checks during normal diagnostics updates. The manual MAST: Compile Mission command still runs regardless of this setting. Scope: resource Default: true

• mastLanguageServer.compileDiagnosticsDelayMs: Controls the delay in milliseconds after the last edit before automatic compile diagnostics run. Regular non-compiler diagnostics still update on the normal short debounce. Scope: resource Default: 250

• mastLanguageServer.enableProfilingCollection: Collects language-server profiling summaries by recording mission-load timing stages and writing a summary when a load or reload completes. Disabled by default for normal users; it is automatically active during debug sessions. Scope: window Default: false

Profiling

Use the profiler when you want to diagnose slow mission loads or cache rebuilds. Enable the setting mastLanguageServer.enableProfilingCollection in VS Code settings, then reload the project or trigger a mission load. The language server will log a summary like the following to the server log output:

[profile:MissionName] trigger=load:complete mode=setting samples=12 | loadMissionPackageLayout: count=1, total=134ms, avg=134ms, max=134ms || storyJson.readFile: count=1, total=48ms, avg=48ms, max=48ms

This output shows the slowest stages, how many times each stage ran, and the average and maximum timing for each stage. The same data is also collected automatically while running a debug session, even if the setting is off. The extension also writes the same summary to a file named mast-profiler.log in the mission folder, so you can attach it to a bug report or send it to the developer for debugging. This is primarily intended for diagnosing performance issues in the extension itself, not for regular end-user workflows.

Memory Profiling

Use the command MAST: Profile Memory Usage from the Command Palette when you want a quick memory snapshot for both the extension client process and the language server process.

Each snapshot reports:

• Process id and uptime
• RSS (resident memory)
• V8 heap used and total heap size
• External and array buffer memory

The language server snapshot also includes V8 heap limit and available heap values.

Where to find results:

• MAST Client Output channel: client-side snapshot ([memory:client])
• MAST Language Server output log: server-side snapshot ([memory:server])
• Mission-local mast-profiler.log (when a mission is detected): both snapshots with timestamps

This command is lightweight and useful for regression checks while editing large missions or repeatedly reloading cache data.

Cache Size Profiling

Use the command MAST: Profile Cache Size to generate a detailed report of what the language-server cache is retaining for the active mission.

The report includes:

• Parsed file counts (.py and .mast)
• Approximate token counts (Python tokens and MAST tokens)
• Memory deltas before vs after cache reload (rss, heapUsed, heapTotal, external, arrayBuffers)
• Top 20 largest cached files by retained source text size, with token counts

Where to find results:

• MAST: Cache Profile output channel (primary)
• MAST Language Server output log (same report)
• Mission-local mast-profiler.log (when mission context is available)

For multi-mission sessions, use MAST: Profile All Loaded Caches to run the same analysis across all currently loaded mission caches in one shot. This is especially useful when mastLanguageServer.allowMultipleCaches is enabled.

Working with Markdown

You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts:

• Split the editor (Cmd+\ on macOS or Ctrl+\ on Windows and Linux).
• Toggle preview (Shift+Cmd+V on macOS or Shift+Ctrl+V on Windows and Linux).
• Press Ctrl+Space (Windows, Linux, macOS) to see a list of Markdown snippets.

For more information

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

Enjoy!