Template
89 lines
5.6 KiB
Markdown
89 lines
5.6 KiB
Markdown
# 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](https://nixos.org/download/) 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.
|
|
|
|
```sh
|
|
nix-shell
|
|
argon --version
|
|
stylua --version
|
|
bash tools/check.sh
|
|
argon serve default.project.json --sourcemap
|
|
```
|
|
|
|
Or run tools without entering an interactive shell:
|
|
|
|
```sh
|
|
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](docs/argon.md) 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
|
|
|
|
```text
|
|
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](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.
|
|
|
|
```sh
|
|
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](docs/tooling.md) 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.
|