5.6 KiB
Roblox Luau environment
A reusable starting point extracted from the parent project's development environment. Copy the contents of this folder, including dotfiles, into a new repository. It has its own project mapping, source examples, tools, and documentation; commands below run from that new root (or from luaenv while trying it here).
Requirements and first run
Install Nix with a configured nixpkgs channel, and install Roblox Studio on a supported operating system. Nix supplies the command-line tools; it does not install or run Studio. On Linux, use a separate Studio setup or machine. Studio must be able to reach the machine running Argon.
nix-shell
argon --version
stylua --version
bash tools/check.sh
argon serve default.project.json --sourcemap
Or run tools without entering an interactive shell:
nix-shell --run 'bash tools/check.sh'
nix-shell --run 'argon serve default.project.json --sourcemap'
Rename MyGame in default.project.json. Follow the Argon guide to connect Studio. Press Play: the starter prints Server ready on the server and Client ready on the client. Replace these examples with your game's startup code.
Included tools
| Tool | Purpose |
|---|---|
| Argon | Sync source into Studio; generate the instance sourcemap; build place files. |
| StyLua | Format Lua/Luau using stylua.toml. |
| luau-lsp | Editor language service and command-line Roblox type checking. |
| Luau | Run tests for pure Luau modules outside Studio. |
| Darklua | Optional source transformations for tests or builds. |
| Lua 5.4 | Optional execution of transformed code with game-specific Roblox mocks. |
| curl | Download Roblox type definitions for command-line analysis. |
shell.nix uses the same tool list as the source project. It imports <nixpkgs> from your local configuration, so versions are not pinned. Pin nixpkgs in your project if developers and CI need identical versions. No Wally, Selene, Rojo, or Aftman setup is required or bundled.
Source structure
src/
├── ReplicatedFirst/ # Optional early loading scripts
├── ReplicatedStorage/Modules/ # Shared code visible to clients
│ ├── Config/
│ ├── Handlers/
│ ├── Libraries/
│ │ ├── External/ # Third-party libraries
│ │ └── Internal/Numbers.lua # First-party example module
│ ├── Managers/
│ └── Types/
├── ServerScriptService/
│ └── InitServer.server.lua # Server entry point
├── ServerStorage/Modules/ # Private server code
│ ├── Config/
│ ├── Handlers/
│ ├── Libraries/
│ │ ├── External/ # Server-only third-party libraries
│ │ └── Internal/ # Server-only first-party libraries
│ └── Managers/GameManager.lua
└── StarterPlayer/StarterPlayerScripts/
└── InitClient.client.lua # Client entry point
tests/ # Native Luau tests
tools/ # Check script and Darklua config
docs/ # Setup and tooling notes
default.project.json maps these paths into Roblox services and creates ReplicatedStorage.Remotes and StarterGui. UI can be created in code or explicitly mapped later. Empty directories contain .gitkeep placeholders for Git. Add files under mapped directories without adding each script to the project file. Libraries go in Modules/Libraries/Internal for first-party code and Modules/Libraries/External for third-party code. Both sync automatically; .styluaignore excludes external libraries from formatting. Folders outside the mapped tree are not synced automatically.
Managers own state and rules, handlers connect behavior to events or presentation, libraries provide reusable operations, and Types holds shared contracts. This organization is a convention, not a runtime framework. Startup order remains explicit in the entry scripts. Code and configuration placed in ReplicatedStorage are visible to clients; keep server-only logic and secrets out of it.
Formatting, editing, and checks
Read CODE_STYLE.md. Use tabs displayed at four columns, a 120-column target, double-quoted strings, LF endings, strict runtime modules, and blank lines between logical steps. StyLua formats syntax; authors still choose meaningful grouping and names.
nix-shell --run 'stylua src tests tools'
nix-shell --run 'bash tools/check.sh'
The check script checks formatting, regenerates sourcemap.json, checks src against Roblox types, then runs each tests/*.luau file in its own native Luau process. It exits on the first failure. Add regression tests as behavior grows. See tooling notes for cached type definitions, editor setup, dependencies, and optional Lua 5.4 tests.
CLI tests do not provide the Roblox engine. Use Studio's Play and Server & Clients tests for services, networking, rendering, physics, input, and platform behavior. Test with multiple clients and the Device Emulator when those features matter to your game.
What was generalized
The Nix shell, StyLua configuration, EditorConfig, strict .luaurc, service-based layout, and style conventions come from the source project. The project mapping and startup scripts are new generic examples. Checks now regenerate the sourcemap and use the project-neutral ROBLOX_TYPES variable. Game code, assets, third-party packages, dependency stubs, and game-specific mock tests are omitted. Add those only as your new game needs them.