#Getting Started

This guide walks through the smallest useful Lux workflow during the alpha: install or build luxc, compile one file, write a multi-part module, then build a GMod addon layout.

#Requirements

Lux currently targets Lua 5.1 / GLua. For normal addon work you need:

• A Lux alpha release, or a Rust toolchain if you want to build luxc from source.
• A Garry's Mod addon directory when testing generated artifacts in game.
• Optional gmad.exe when packaging .gma files.

Download the current alpha release from the Lux repository, extract it, and run the installer script from the extracted directory:

Expand-Archive .\luxc-windows-x64.zip -DestinationPath .\luxc-windows-x64 -Force
.\luxc-windows-x64\install-lux-path.ps1
luxc --version

If you want the current checkout instead of the published prerelease, build from source and install that executable:

git clone https://github.com/TimeWatcher/lux.git
cd lux
cargo build --manifest-path compiler\Cargo.toml --release
.\scripts\install-lux-path.ps1 -LuxcPath .\compiler\target\release\luxc.exe
luxc --version

The installed user entrypoint is %USERPROFILE%\.lux\bin\luxc.exe on Windows. If you skip installation, call the explicit build output instead:

.\compiler\target\release\luxc.exe --help

The examples below assume luxc is on PATH.

#Compile One File

Start with a single file:

examples/
  hello.lux

luxc compile examples\hello.lux

Single-file compilation is useful for checking syntax, generated Lua shape, and small language examples. GMod projects normally use luxc gmod build so the compiler can discover modules, split realms, and emit loaders.

The repository's examples/features.lux is deliberately a single-file syntax tour. It does not teach imports, exports, packages, macros, or top-level realm ownership. Use examples/gmod_project for the project/module model.

#Write a First Module

Create a module directory. A multi-file module needs an entry part.

src/
  inventory/
    module.lux
    sv_store.lux
    cl_panel.lux

The entry part is where the public module shape and part order are easiest to find.

part order { "module", "sv_store", "cl_panel" }

fn normalizeItemId(id) tostring(id)

export { normalizeItemId }

Server parts can use the private function from the entry part without importing it. All parts in the same module share module-private scope.

server fn grantItem(ply, itemId) {
  local normalized = normalizeItemId(itemId)
  print(`grant ${normalized} to ${ply:Nick()}`)
}

export server { grantItem }

Client parts can expose client-only UI without leaking it into the server artifact.

client fn openInventoryPanel() {
  local panel = vgui.Create("DFrame")
  panel:SetTitle("Inventory")
  panel:MakePopup()
}

export client { openInventoryPanel }

The module has one public API, but each exported name is available only in the realm where it is valid.

#Create a GMod Project

Create a project skeleton. Plain init is offline and writes no dependencies:

luxc init my_addon

Add the official standard package set when your project imports packages such as @lux/std or @lux/gmod:

luxc init my_addon --std
Push-Location my_addon
luxc install @lux/gmod --from github:TimeWatcher/lux-packages
Pop-Location

Create lux.toml at the project root:

package_id = "my_addon"
bundle_id = "my_addon"

[target.gmod]
source_root = "src"
out = "generated/lua"
runtime_base = "lux/my-addon"
autorun = true
source_comments = "readable"

[dependencies]

Lux has no package registry. lux.toml chooses concrete package sources with github, url, or path, and can pin GitHub package sets with tag, branch, or commit. lux.lock records the resolved package graph.

Recommended layout:

my_addon/
  lux.toml
  src/
    inventory/
      module.lux
      sv_store.lux
      cl_panel.lux
  generated/
    lua/
      autorun/
      lux/

Build GMod artifacts:

luxc gmod build --manifest lux.toml

The build step discovers modules under source_root, infers realms from file prefixes and folders, resolves package imports, emits Lua artifacts under out, writes a relative-path-safe Lux loader tree under runtime_base, and writes an optional addon autorun forwarder.

#Build from Explicit Paths

For experiments and CI slices, you can build from an explicit source root and output root:

luxc gmod build src --out generated/lua

Use a manifest for real projects. It keeps package ids, output roots, source map settings, autorun policy, and extern policy in one stable place.

#Check and Format

Run linting without emitting artifacts:

luxc lint src\inventory\module.lux

Format a file:

luxc format src\inventory\module.lux --write

Format whole project sources through your editor or a script until the CLI grows full project formatting commands.

#Map Runtime Errors

GMod reports Lua stack traces. Lux emits source maps so you can map generated Lua locations back to Lux source.

luxc map-error generated\lua\lux\client\my_addon\inventory.lua.map.json 42

With readable source comments enabled, generated Lua also contains source anchors around functions and branch blocks. Use source_comments = "none" for production-sized artifacts and sidecar source maps for debugging.