Template
49 lines
3.7 KiB
Markdown
49 lines
3.7 KiB
Markdown
# Argon setup
|
|
|
|
1. Install the Argon Studio plugin using the official [Argon documentation](https://argon.wiki/docs/intro). Enable it in Studio's Plugins tab. The Nix shell supplies the CLI; the Studio plugin is installed separately.
|
|
2. Open a new or backed-up place in Studio. Set `name` in `default.project.json` to your game's name. The project tree defines which filesystem paths sync to which services.
|
|
3. From the project root, start the server:
|
|
|
|
```sh
|
|
nix-shell --run 'argon serve default.project.json --sourcemap'
|
|
```
|
|
|
|
4. In the Studio plugin, connect to the address and port printed by the CLI. Review the proposed changes before syncing. Allow any plugin permissions Studio requests for the connection. The starter owns its mapped instances; importing an existing place requires reconciling its instance tree with the filesystem first.
|
|
5. Keep the command running while editing, and press Play in Studio to run the game. Stop play and restart clients/server after startup or protocol changes. Stop Argon with Ctrl+C when done.
|
|
|
|
For different machines or a VM, configure a reachable host and port with `argon serve --host <address> --port <port>`. Use `argon serve --help` for your installed version's options. Use a trusted network and the printed port; a remote Studio instance cannot connect through its own `localhost` to another machine.
|
|
|
|
## File conventions
|
|
|
|
- `Name.server.lua` or `.server.luau` becomes a Script.
|
|
- `Name.client.lua` or `.client.luau` becomes a LocalScript.
|
|
- `Name.lua` or `.luau` becomes a ModuleScript.
|
|
- A directory containing `init.lua` or `init.luau` becomes a ModuleScript with children. Otherwise it becomes a Folder. Script variants such as `init.server.lua` set the corresponding script class.
|
|
|
|
For example, require the shared example as `require(ReplicatedStorage.Modules.Libraries.Internal.Numbers)`. Require a third-party module as `require(ReplicatedStorage.Modules.Libraries.External.Vendor)`. Filesystem-relative requires in native Luau tests are separate from Roblox instance-based requires in runtime code.
|
|
|
|
## Sourcemaps and builds
|
|
|
|
The sourcemap connects filesystem source to Roblox instance paths for luau-lsp; it is not runtime code. `--sourcemap` updates it while serving. Generate it without Studio with:
|
|
|
|
```sh
|
|
nix-shell --run 'argon sourcemap default.project.json --output sourcemap.json'
|
|
```
|
|
|
|
The check script runs this automatically. Generated maps are ignored by Git. Rebuild the map when adding, moving, or deleting modules; stale maps can cause incorrect require diagnostics.
|
|
|
|
To build a local place artifact:
|
|
|
|
```sh
|
|
mkdir -p output
|
|
nix-shell --run 'argon build default.project.json --output output/MyGame.rbxlx'
|
|
```
|
|
|
|
Building is separate from publishing to Roblox. Use Studio to inspect, playtest, and publish the resulting place.
|
|
|
|
## Adding packages or services
|
|
|
|
Put third-party runtime code in `src/ReplicatedStorage/Modules/Libraries/External/<Vendor>/`, retaining its license. Put your own reusable modules in `src/ReplicatedStorage/Modules/Libraries/Internal/`. For server-only libraries, use the equivalent directories under `src/ServerStorage/Modules/Libraries/`. These directories are already mapped, so no additional project entries are needed. A vendor's `init.lua` or `init.luau` becomes its module entry point. Import the runtime source rather than an entire vendor repository with tooling and examples. Do not run two sync sessions that own the same instances. `.styluaignore` excludes external libraries from first-party formatting commands.
|
|
|
|
To add file-based UI or other services, add the corresponding directory and `$path` mapping. Avoid copying game-specific device orientation, mouse lock, assets, or package mounts into every new game; choose those per project.
|