Mach4 Lua Tools

A small VS Code extension for the Mach4Hobby workspace.

This project is developed for Windows and Mach4 Hobby installations. It is not affiliated with or supported by the VS Code or Mach4 vendors unless they say otherwise.

Install

Download the latest .vsix from the repository's GitHub Releases page, then install it in VS Code with Extensions: Install from VSIX.... Install a Lua language server separately for Lua completion and diagnostics.

Commands

• Mach4: Start Mach4
• Mach4: Select Profile
• Mach4: Use VS Code Instead of ZeroBrane
• Mach4: Check Current Lua File
• Mach4: Configure Lua API

The profile command creates a timestamped backup before changing usezerobrane and refuses to edit a profile while Mach4 is running.

Install the Lua Language Server extension, then run Mach4: Configure Lua API once. It adds this extension's Mach4 API definitions to the workspace library without replacing any existing Lua libraries.

Setup

For a complete installation guide, see SETUP.md. It covers:

• Installing the VSIX on a new Windows machine
• Copying the Mach4 helper modules
• Configuring autocomplete and the Lua API
• Running syntax checks
• Starting Mach4 from VS Code
• Configuring VS Code workspace support
• Debugging with MobDebug
• Troubleshooting common setup errors

Automated installation

For a new Mach4 machine, copy only Mach4LuaToolsInstaller.exe to the new computer and run it:

.\Mach4LuaToolsInstaller.exe -Mach4Directory "C:\Mach4Hobby"

The executable contains the Mach4 helper modules, examples, documentation, prepared ScreenScript.lua, and VSIX. No separate payload folder or VSIX is required. The PowerShell version remains available for development and troubleshooting.

Alternatively, run the PowerShell installer directly:

Set-ExecutionPolicy -Scope Process Bypass
.\Install-Mach4LuaTools.ps1 -Mach4Directory "C:\Mach4Hobby"

The installer creates a timestamped backup, copies the helper modules and examples, configures the VS Code workspace, writes workspace settings, installs the VSIX, and installs the Screen Editor-to-VS Code bridge. It asks you to type INSTALL before changing files.

Mach4 Screen Editor always opens its built-in mcLuaEditor.exe; it cannot be redirected to VS Code through Machine.ini. Use Screen Editor for screen layout, then open the same workspace files directly in VS Code for Lua development.

The installed bridge opens the temporary .mcs script in VS Code, waits for you to save and close that tab, and then returns control to Mach4 so the Screen Editor can apply the edited script. Use -SkipVSCodeScreenEditor to omit this bridge.

Use -SkipScreenScript when the target machine has important custom screen logic and you want to merge ScreenScript.lua manually.

To rebuild the executable after changing the installer script:

Install-Module ps2exe -Scope CurrentUser -Force
.\Build-SelfContainedInstaller.ps1

The installer EXE is a release artifact, not a required part of extension development. Do not commit generated .vsix, .exe, out/, or node_modules/ files to the repository.

MobDebug debugging

Use the Debug Mach4 Lua configuration in the Mach4Hobby workspace. The adapter listens on 127.0.0.1:8172, launches Mach4 with an opt-in MobDebug environment flag, and supports breakpoints, continue, step in, step over, step out, stack frames, locals, upvalues, and hover evaluation.

The MobDebug hook in ScreenScript.lua is disabled unless Mach4 is launched by this configuration. Normal Mach4 launches are unaffected.

Development

npm ci
npm run check
npm run package

Open this folder in VS Code and press F5 to run the extension in an Extension Development Host window. Open the Mach4Hobby folder in that window before using the commands.

Release checklist

1. Update version in package.json and run npm install to update the lockfile.
2. Run npm run check.
3. Run npm run package and test the generated VSIX on a clean VS Code profile.
4. Create a Git tag matching the version, such as v0.1.2, and push it to GitHub.
5. Attach the VSIX to the GitHub Release. Build the optional installer separately with Build-SelfContainedInstaller.ps1 and attach it only after testing it on a clean Windows machine.

See CONTRIBUTING.md, SECURITY.md, and LICENSE before accepting outside contributions.