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
• 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
• 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: 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

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!