#快速开始

Lux 是面向 GLua 的离线编译语言。你在项目里写 .lux 文件，luxc 在游戏外完成 解析、宏展开、模块解析、运行域检查和 Lua 生成。进入 GMod 的仍然是普通 Lua 5.1 / GLua 文件，因此不需要游戏内解析器。

本页按当前 alpha 阶段的真实流程写：先安装发布版或从源码构建 luxc，再编译单文件、 创建模块和构建 GMod 项目。

#环境要求

• Lux alpha release；如果要从源码构建，则需要 Rust toolchain。
• Garry's Mod：只有构建、运行插件时需要。
• 可选的 gmad.exe：只有打包 .gma 时需要。

下载 Lux 主仓库里的当前 alpha release，解压后从解压目录运行安装脚本：

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

如果你需要当前 checkout，而不是已发布的 prerelease，可以从源码构建并安装这个构建产物：

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

Windows 下安装后的稳定入口是 %USERPROFILE%\.lux\bin\luxc.exe。如果不安装， 也可以直接使用构建产物：

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

下面示例都假设 luxc 已经在 PATH 中。

#编译单个文件

仓库里的 examples/features.lux 是单文件语法增强示例。它刻意不使用 import、export、package、macro 或 top-level realm，用来确认不创建项目时的 编译器输出：

luxc compile examples\features.lux --source-comments readable

compile 会把生成的 Lua 打印到标准输出。需要源码映射时加 --map：

luxc compile examples\features.lux `
  --map examples\features.lua.map.json `
  --source-comments boundary

--source-comments 控制生成 Lua 里的源码注释：

none      不写源码注释
readable  适合直接阅读
boundary  只标注关键边界
dense     尽量密集地标注

需要学习工程化写法时看 examples/gmod_project。那里才展示 manifest、跨模块 import/export、client / server / shared 归属、package 依赖和 GMod loader。

#写第一个模块

创建一个目录模块。目录里的所有 part 文件共同组成一个 Lux 模块，顶层声明默认只在 模块内部可见。

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

module.lux 是入口 part，适合放导出、初始化顺序和少量共享声明。

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

local items = {}

fn formatItem(item) =
  item?.name ?? "Unknown"

export { formatItem }

sv_store.lux 里的声明默认属于服务端运行域。

server fn grantItem(player, item) {
  items[player:SteamID64()] = item
}

export server { grantItem }

cl_panel.lux 可以直接使用同模块里的私有声明，不需要导入同级 part。

client fn drawItem(item) {
  draw.SimpleText(formatItem(item), "DermaDefault", 0, 0)
}

注意：导入只用于引用其他模块。模块内部的 part 共享同一个模块作用域。

#创建 GMod 项目

创建项目骨架。普通 init 离线执行，不写入依赖：

luxc init my_addon

当项目需要导入 @lux/std、@lux/gmod 等官方 package 时，再显式安装标准 package set：

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

最小项目只需要一个 lux.toml 和 src 目录：

my_addon/
  lux.toml
  addon.json
  src/
    shared/
      hud.lux
    server/
      init.lux
    client/
      ui.lux

推荐的 lux.toml：

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 = "boundary"

[target.gmod.realm]
unknown_external = "warn"

[dependencies]

字段含义：

• source_root：Lux 源码根目录。
• out：物理输出根。开发时建议先写到独立目录。
• runtime_base：生成 include / AddCSLuaFile 使用的 GMod 相对路径。
• autorun：是否额外生成 addon 风格 autorun forwarder。
• source_comments：生成 Lua 的源码注释密度。
• bundle_id：生成私有注册表命名用的稳定标识。
• unknown_external：未知外部符号策略，见 GMod 外部 API 文档。

Lux 没有 package registry。lux.toml 通过显式 github、url 或 path 选择包 来源，并可用 tag、branch 或 commit 固定 GitHub package set。lux.lock 记录解析后的依赖图。

构建：

luxc gmod build --manifest examples\gmod_project\lux.toml

输出会包含：

generated/
  lua/
    autorun/
      my_addon.lua
    lux/
      my-addon/
        loader_shared.lua
        loader_client.lua
        loader_server.lua
        client/...
        server/...

开发时可以先用 --dry-run 查看构建计划，不写任何文件：

luxc gmod build --manifest path\to\lux.toml --dry-run

确认生成内容后，再把 generated 目录里的 lua 合并到你的 GMod 插件目录，或让 out 直接指向开发用入口目录下的 Lua 根。不要把输出指向正在维护的原始源码目录。

#直接指定路径构建

没有 lux.toml 时也可以显式给出源码目录和输出目录：

luxc gmod build path\to\src --out path\to\generated\lua

这种形式适合临时测试；团队项目推荐使用 lux.toml，因为外部符号声明、源码注释 策略、包根目录和稳定 bundle 名称都需要配置。

#检查和格式化

luxc lint examples\features.lux
luxc format examples\features.lux --check
luxc format examples\features.lux --write

format --check 只检查，不修改文件。format --write 会原子写回，当前格式化器是 保守实现，会保留 token 文本和注释文本。

#映射运行时错误

如果 GMod 报的是生成 Lua 的行号，可以用源码映射查回 Lux 源文件：

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

这会输出对应的 Lux 文件、行号和列号。调试阶段建议保留 .lua.map.json 文件，不要 只复制 .lua。