roblox-build-and-env — bootstrap and build-system traps

Overview

Every firebit Roblox project builds a game from plain files on disk; every tool in the chain (Aftman → Wally → Rojo → luau-lsp) depends on artifacts produced by the previous one, and most "mysterious" failures are a stale artifact, not a code bug. Regenerate the artifact (usually sourcemap.json) before debugging the code.

All commands run from the current project's repo root; all paths are repo-root-relative.

Jargon, once:

• Roblox Studio — Roblox's IDE/engine; opens .rbxl "place" files (a place = one built game world).
• Rojo — syncs/builds filesystem source into a Roblox place. A *.project.json file maps disk paths → the Roblox instance tree.
• Wally — Luau package manager (like npm). Installs into Packages/ and DevPackages/.
• Aftman — toolchain manager; pins CLI tool versions in aftman.toml (like asdf/mise).
• luau-lsp — Luau language server / analyzer; needs globalTypes.d.luau (Roblox API type definitions) and sourcemap.json (Rojo's file→instance map) to resolve requires and types.
• wally-package-types — patches Wally's thin package-link files so installed packages export their types to luau-lsp.

When to use / when NOT to use

Use for: fresh-machine setup, npm script anatomy, sourcemap/hook failures, Wally/Packages problems, Rojo project selection, .env expectations, identifying root .rbxl files.