Roblox Luau (Rojo)

# AGENTS.md: Roblox Luau (Rojo)

## Layout (Rojo, see `default.project.json`)
```
src/server/   → ServerScriptService     server Scripts (*.server.luau) and server-only modules
src/client/   → StarterPlayerScripts    LocalScripts (*.client.luau)
src/shared/   → ReplicatedStorage       ModuleScripts used by both sides, plus Remotes
```
- `ServerStorage` and `ServerScriptService` are invisible to clients. Anything in `ReplicatedStorage` or the workspace is visible to exploiters.
- Run `rojo serve` and connect from the Studio plugin to sync. Do not edit synced scripts inside Studio — edits are overwritten.

## The golden rule: the server decides
- Clients can be fully controlled by exploiters. Every value from a `RemoteEvent`/`RemoteFunction` is an untrusted request.
- Remotes express intent ("I want to buy item X", "I pressed attack"), never outcomes ("give me 500 coins", "deal 999 damage").
- On the server, for every remote handler:
  1. Check argument types (`typeof(x) == "string"`) and ranges; reject NaN and huge numbers.
  2. Check the player is allowed (owns the item, has the cash, is close enough, cooldown passed).
  3. Rate-limit per player.
  4. Compute the result on the server.
- Never use `RemoteFunction:InvokeClient` — a client can yield forever and hang the server thread.
- Currency, inventory, damage, cooldowns and leaderboards live on the server.

## Luau style
- `--!strict` at the top of every file; type function signatures and module tables.
- `task.wait`, `task.spawn`, `task.delay`, `task.defer` — never the deprecated `wait`, `spawn`, `delay`.
- Get services once at the top: `local Players = game:GetService("Players")`.
- Use `WaitForChild` on the client for replicated objects; avoid it on the server for things the server creates.
- Disconnect connections you create per player or per round, or clean up with a maid/trove pattern.
- `PascalCase` for modules and services, `camelCase` for locals and functions.

## Data
- `DataStoreService` calls can fail: always wrap them in `pcall` and retry with backoff.
- Prefer `UpdateAsync` to `SetAsync` for player data so concurrent servers do not overwrite each other.
- Load on `PlayerAdded`, save on `PlayerRemoving` **and** in `game:BindToClose` (with a time budget), plus periodic autosave.
- Do not save if the initial load failed — you would overwrite real data with defaults.
- Studio needs "Enable Studio Access to API Services" switched on to test DataStores; remind the human.

## Before you say "done"
Code type-checks (`luau-lsp` or Studio's Script Analysis shows no errors), and you have listed what the human should test in a
Studio play-test — ideally with two players (Test → Clients and Servers).

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `remote-security-review`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Roblox Luau (Rojo)" v1.0.0 — https://loadout.jnw-it.com/loadouts/roblox-luau/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `remote-security-review`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Roblox Luau (Rojo)" v1.0.0 — https://loadout.jnw-it.com/loadouts/roblox-luau/ -->

---
description: Server-side remote handler rules for Roblox
globs: "src/server/**/*.luau"
alwaysApply: false
---

Every `OnServerEvent` / `OnServerInvoke` handler must:

1. Treat its arguments as untrusted. Check `typeof` for each one and bounds for numbers (reject NaN: `x ~= x`).
2. Check permission and game state on the server (ownership, cost, distance, cooldown).
3. Rate-limit per player.
4. Compute outcomes on the server. Never accept amounts, damage, prices or positions as facts.

```luau
--!strict
local Remotes = game:GetService("ReplicatedStorage"):WaitForChild("Remotes")
local Shop = require(script.Parent.Shop)

local lastCall: { [Player]: number } = {}

Remotes.BuyItem.OnServerEvent:Connect(function(player: Player, itemId: unknown)
	if typeof(itemId) ~= "string" or #itemId > 64 then return end
	local now = os.clock()
	if (lastCall[player] or 0) + 0.5 > now then return end
	lastCall[player] = now
	Shop.tryPurchase(player, itemId) -- looks up the price server-side and checks the balance
end)

game:GetService("Players").PlayerRemoving:Connect(function(player) lastCall[player] = nil end)
```

Never use `InvokeClient`. Never `loadstring` anything.

---
name: remote-security-review
description: Audit a Roblox game's RemoteEvents and RemoteFunctions for exploitable client trust. Use before publishing, after adding remotes, or when players report exploits like infinite money or teleporting.
---

# Remote security review

## 1. Inventory
- Find every remote: search for `RemoteEvent`, `RemoteFunction`, `UnreliableRemoteEvent` instances in the Rojo project files
  (`*.model.json`, `*.project.json`, `.rbxmx`) and in code (`Instance.new("RemoteEvent")`).
- Find every handler: `OnServerEvent`, `OnServerInvoke`, and on the client `FireServer`/`InvokeServer` calls.
- Build a table: remote name → server handler file → client call sites → arguments sent.

## 2. Review each handler
For each remote, answer:
1. **What does the client claim?** List each argument. Would an exploiter gain anything by changing it?
2. **Types checked?** Every argument `typeof`-checked, strings length-limited, numbers bounded and NaN-rejected, Instances checked
   to be the expected class and in an expected place.
3. **Authority:** does the server compute the outcome, or trust a client value (amount, damage, price, position, target)?
4. **Permission/state:** does it check ownership, cost, distance (`(char.HumanoidRootPart.Position - target.Position).Magnitude`),
   cooldown, round state?
5. **Rate limiting:** can it be spammed? What happens if it is fired 1,000 times a second?
6. **Errors:** can bad input throw and break the handler for everyone, or leave state half-updated?
7. **RemoteFunctions:** never `InvokeClient`. `OnServerInvoke` returns quickly and never yields on client data.

## 3. Also check
- Server-only modules are not in `ReplicatedStorage` (secrets, admin lists, prices that should be hidden).
- No `loadstring`, no `require` of asset IDs you do not control.
- Admin commands check a server-side list of `UserId`s (not names, which can change).
- Clients are not given network ownership of things that matter (e.g. other players' parts, shop NPCs).

## 4. Report
```
Remote review — <place> — <n> remotes
[Critical] AddCoins (src/server/Economy.server.luau:42) — trusts `amount` from the client. Any exploiter can grant themselves unlimited coins.
  Fix: remove the remote; award coins on the server when the qualifying event happens.
[High] Attack — no distance check or cooldown. Fix: check range ≤ weapon reach and a per-player cooldown.
[OK] RequestRespawn — no arguments, cooldown present.
```
Order by severity. Offer to write the fixes, one remote at a time.