4.4 KiB
Tooling details
Editor setup
Open the new project root in your editor. .editorconfig defines UTF-8, LF, final newlines, no trailing whitespace, and four-column tabs for Lua/Luau. stylua.toml defines formatting; .luaurc sets strict analysis by default.
The optional .vscode files recommend Luau Language Server, StyLua, and EditorConfig, associate both source extensions with Luau, and enable format-on-save. Install these extensions yourself. Ensure the editor and extensions can locate tools from nix-shell, for example by launching the editor from that shell. An already-running editor may retain its old environment.
The editor configuration disables Rojo-based sourcemap autogeneration because Argon generates sourcemap.json. Run Argon with --sourcemap or run tools/check.sh before expecting instance-aware requires to resolve. Editor Roblox definitions are managed by the language-server extension; the CLI check supplies its own definitions explicitly.
Roblox definitions and analysis
On first use, tools/check.sh downloads globalTypes.d.luau from luau-lsp into .cache/. This requires internet access. Later checks reuse the cached file. To use your own downloaded or pinned definitions, pass an absolute path:
ROBLOX_TYPES=/absolute/path/globalTypes.d.luau nix-shell --run 'bash tools/check.sh'
For reproducible CI, pin compatible tooling and the definitions revision together. The default download follows upstream main; refresh .cache/globalTypes.d.luau deliberately when upgrading tools. A nonempty cache is reused, so delete that file to fetch an updated copy. ROBLOX_TYPES replaces the source project's game-specific PONG_ROBLOX_TYPES name.
The check command analyzes runtime source, then executes native tests. Runtime modules use Roblox instance requires, whereas standalone tests use relative file requires. Roblox services and globals such as game, Instance, and Vector3 do not exist in the standalone runtime merely because the analyzer knows their types.
Test strategy
Prefer pure modules for algorithms that can be tested directly with luau. tests/numbers.luau demonstrates this using the starter module. Add test files directly under tests/ with a .luau extension for automatic execution by the check script. Organize more elaborate suites behind their own entry points when needed.
Use Studio for engine behavior. If you need external integration tests, design explicit mocks and a loader for your own game's Roblox dependencies. The parent project's Lua mocks, Jolt integration harness, and declaration stubs are tied to its game and are intentionally not included here.
Optional Darklua / Lua 5.4 path
The shell includes Darklua and Lua 5.4 to support the parent project's testing approach. tools/darklua.json removes types, if-expressions, compound assignments, and continue, producing readable output. This step is optional and is not part of the starter check script:
mkdir -p output
nix-shell --run 'darklua process src output/lua -c tools/darklua.json'
nix-shell --run 'lua -e '\''assert(_VERSION == "Lua 5.4")'\'''
Always transform into a separate generated directory. Studio runs the original strict Luau source. These transformations do not emulate Roblox, rewrite all instance-based requires, or guarantee compatibility for every Luau feature. Lua 5.4 tests need appropriate mocks, module loading, and compatibility helpers; native Luau is preferable when those adaptations are unnecessary.
Dependencies and future tools
Place runtime dependencies in Modules/Libraries/External under the appropriate shared or server-only source tree; Argon already maps these directories. First-party libraries belong in Modules/Libraries/Internal. .styluaignore keeps third-party formatting intact. The type checker still analyzes source under src, including external libraries. If luau-lsp cannot analyze a dependency, add narrowly scoped declarations or an analysis strategy for that dependency; analysis stubs never replace its runtime implementation. Document versions and licenses. Wally or other package managers can be added later, but this template uses no dependency installer or generated package tree.
This shell does not install Selene. StyLua checks formatting and luau-lsp checks types; add a linter and its Roblox configuration explicitly if desired. Keep builds, downloaded types, and sourcemaps out of source control. Commit the project mapping, source, tests, shell, and formatter settings.