built template

2026-10-16 07:33:08 +00:00
commit a92978489f
30 changed files with 496 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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.