--- name: roblox-luau-architecture description: Design, inspect, and refactor Roblox Luau game architecture. Use for ModuleScript/service boundaries, client-server flow, RemoteEvents/RemoteFunctions, ReplicatedStorage organization, reusable systems, script placement, and safe Studio MCP code-edit workflows. --- # Roblox Luau Architecture ## Goal Keep Roblox game code modular, server-authoritative, and easy to extend. Use Roblox Studio MCP to inspect existing scripts before changing architecture. ## MCP Workflow 1. Start with `list_roblox_studios`, `set_active_studio` if needed, and `get_studio_state`. 2. Locate code with `script_search` or `script_grep`. 3. Read relevant scripts with `script_read` before editing. 4. Apply edits with `multi_edit`. 5. Playtest with `start_stop_play`. 6. Check `get_console_output` for regressions. ## Placement Rules - Put authoritative game logic in `ServerScriptService` or server-owned modules. - Put shared constants, type definitions, remotes, and pure shared helpers in `ReplicatedStorage`. - Put player input, camera, local-only UI, and visual prediction in client scripts. - Keep workspace scripts rare and intentional; prefer service-style scripts that manage tagged instances or configured folders. - Avoid scattering duplicated constants across client and server. ## Remote Boundaries - Treat every client remote payload as untrusted. - Prefer narrow remotes with explicit action names and typed payload checks. - Rate-limit player-triggered remotes that can affect economy, inventory, combat, or placement. - Use RemoteFunctions sparingly; avoid long-yielding server calls from the client. - Never let the client decide currency, inventory, ownership, damage, quest completion, or purchase grants. ## Module Pattern Use modules for: - Services with `Init` and `Start` style lifecycle. - Data access wrappers. - Economy calculations. - Reward tables and balancing constants. - UI controllers on the client. - Shared utility functions that are deterministic and side-effect-light. Keep modules small enough that another system can depend on them without importing unrelated behavior. ## Prefer Deep Modules Aim for **deep** modules: a lot of behavior behind a small, stable interface. A **shallow** module — where the interface is nearly as complex as its implementation — earns its keep only if it hides real complexity. - **Interface** = everything a caller must know: the function signature *plus* invariants, ordering, error modes, and which side (client/server) may call it. In Roblox, a remote's contract is part of its interface. - **Deletion test:** imagine deleting a module. If complexity vanishes, it was a pass-through — inline it. If the same complexity reappears across several call sites, it was earning its keep — keep it and deepen it. - **Locality:** put related behavior and its valuable-state rules in one module so a change, a bug, or the knowledge to reason about it lives in one place — not scattered across a LocalScript, a server Script, and three constants files. - One adapter satisfying an interface is a hypothetical seam; two is a real one. Don't build indirection for a single implementation. Good seams get names from the game's own vocabulary (the "coin economy service", the "quest tracker"), not generic ones ("Handler", "Manager"). ## Refactor Output When proposing or making architecture changes, include: - Current script locations and responsibilities. - Proposed module/service boundaries. - Remote contract changes. - Migration steps. - Playtest and console checks. ## Next Slice the architecture work with `roblox-to-issues` so it lands one safe change at a time, and verify each with `roblox-playtest-qa`. For valuable-state modules, review the trust boundary with `roblox-security-economy`; for cleanup of existing debt, use `roblox-code-maintenance-refactor`.