roblox-opencode 1.0.0

package/skills/roblox-sharp-edges/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: roblox-sharp-edges
+description: >
+  12 production footguns ranked by severity. Data loss, exploits, memory leaks, mobile perf.
+last_reviewed: 2026-05-22
+---
+
+<!-- Source: brockmartin/roblox-game-skill (MIT) -->
+
+# Roblox Sharp Edges (Gotchas) Reference
+
+> Every entry here represents a real production footgun that has caused data loss, exploits,
+> crashes, or hours of debugging in Roblox games.
+>
+> **Severity Levels:**
+> - **Critical** - Data loss, security breach, or revenue loss. Fix before shipping.
+> - **High** - Server instability, degraded experience, or exploit surface. Fix in current sprint.
+> - **Medium** - Correctness bugs, performance issues, or dev confusion. Fix before scale.
+> - **Low** - Code quality, maintainability, or minor timing issues. Fix when convenient.
+
+---
+
+## SE-1 | Critical | DataStore Data Loss from Session Handling
+
+**See roblox-data → Session Locking and ProfileStore for full details.**
+
+When a player server-hops, the old server may still be saving while the new server loads stale data. ProfileStore handles session locking automatically - only one server owns a player's data at a time. Never use raw DataStoreService for player data without session locking.
+
+---
+
+## SE-2 | Critical | Client-Side Currency Manipulation
+
+**See roblox-networking → Security Hardening for full details.**
+
+Currency and all authoritative game state must live exclusively on the server. Never accept currency amounts from the client. The server computes all transactions internally and pushes display-only updates to the client. This is the single most common exploit in Roblox games.
+
+---
+
+## SE-3 | Critical | ProcessReceipt Mishandling
+
+**See roblox-monetization → ProcessReceipt for full details.**
+
+`MarketplaceService.ProcessReceipt` must return `PurchaseGranted` ONLY after the item is granted AND saved. If you return `PurchaseGranted` before granting, the player loses Robux. If you don't return it, Roblox retries on every join - potentially granting duplicates. Grant first, save second, return third.
+
+---
+
+## SE-4 | High | Memory Leaks from Undisconnected Events
+
+### Problem
+
+Every `:Connect()` returns an `RBXScriptConnection`. If you never `:Disconnect()` it, the connection persists for the script's lifetime - even after the object is destroyed. In per-player systems, memory grows linearly with every player who has ever joined.
+
+### Symptoms
+
+- Server memory climbs steadily over time.
+- Server FPS degrades after hours.
+- Callbacks fire for players who left.
+
+### Solution
+
+Use the vendored **Trove** module (`vendor/rbxutil/trove/`) to group connections per-player and clean them all on `PlayerRemoving`:
+
+```luau
+local Players = game:GetService("Players")
+local Trove = require(game.ReplicatedStorage.Packages.Trove)
+
+local playerTroves: { [Player]: typeof(Trove.new()) } = {}
+
+local function onPlayerAdded(player: Player)
+    local trove = Trove.new()
+    playerTroves[player] = trove
+
+    trove:Connect(player.CharacterAdded, function(character)
+        local humanoid = character:WaitForChild("Humanoid")
+        trove:Connect(humanoid.Died, function()
+            task.wait(3)
+            player:LoadCharacter()
+        end)
+    end)
+end
+
+local function onPlayerRemoving(player: Player)
+    local trove = playerTroves[player]
+    if trove then
+        trove:Clean()
+        playerTroves[player] = nil
+    end
+end
+
+Players.PlayerAdded:Connect(onPlayerAdded)
+Players.PlayerRemoving:Connect(onPlayerRemoving)
+```
+
+---
+
+## SE-5 | High | RemoteEvent Flooding
+
+### Problem
+
+RemoteEvents have no built-in rate limiting. Exploiters can fire thousands of times per second, flooding the server with DataStore calls, instance creation, or raycasts.
+
+### Solution
+
+Implement per-player, per-remote rate limiting on the server. See **roblox-networking → Rate Limiting** for production patterns.
+
+Minimal inline example:
+
+```luau
+local lastFire: { [Player]: number } = {}
+local COOLDOWN = 0.1
+
+AttackRemote.OnServerEvent:Connect(function(player: Player, targetId: number)
+    local now = os.clock()
+    if lastFire[player] and now - lastFire[player] < COOLDOWN then return end
+    lastFire[player] = now
+    -- process attack
+end)
+```
+
+---
+
+## SE-6 | High | BindToClose Timeout
+
+**See roblox-data → Best Practices (BindToClose Handler) for full details.**
+
+`game:BindToClose()` gives at most 30 seconds. If using ProfileStore, this is automatic. If using raw DataStore, save all players in parallel with `task.spawn` - sequential saves with 50 players will timeout.
+
+---
+
+## SE-7 | Medium | Part Count on Mobile
+
+Mobile devices struggle above ~10,000 visible parts. Enable **StreamingEnabled** and configure `StreamingMinRadius`/`StreamingTargetRadius`. Use `ModelStreamingMode` to mark distant models as Opportunistic and gameplay-critical models as Persistent.
+
+See **roblox-runtime → StreamingEnabled** for configuration details.
+
+---
+
+## SE-8 | Medium | Yielding in Module Require
+
+### Problem
+
+`require()` executes the module body synchronously. If it yields (`WaitForChild`, `task.wait`, HTTP), every script requiring that module blocks. Two modules requiring each other with yields = deadlock.
+
+### Solution
+
+Never yield in a module body. Use Init/Start lifecycle:
+
+```luau
+local CombatSystem = {}
+
+function CombatSystem:Init()
+    -- WaitForChild is safe here (called by bootstrap, not during require)
+    self._remotes = game.ReplicatedStorage:WaitForChild("Remotes", 10)
+end
+
+function CombatSystem:Start()
+    -- Connect events after all modules are Init'd
+end
+
+return CombatSystem
+```
+
+Bootstrap script calls `:Init()` on all modules, then `:Start()` on all modules.
+
+---
+
+## SE-9 | Medium | Table Length with Nil Gaps
+
+### Problem
+
+`#` is only reliable for sequence tables (consecutive integer keys, no nil gaps). Setting `tbl[3] = nil` creates a hole; `#tbl` may return any valid boundary.
+
+### Solution
+
+- Never set array elements to `nil`. Use `table.remove()` to shift elements.
+- Use generalized iteration (`for _, v in tbl do`) instead of `for i = 1, #tbl`.
+- For sparse data, use dictionary keys instead of integer indices.
+
+---
+
+## SE-10 | Low | Deprecated wait()/spawn()/delay()
+
+**See roblox-luau-mastery → Task Library for full details.**
+
+Replace `wait()` → `task.wait()`, `spawn()` → `task.spawn()`, `delay()` → `task.delay()`. Legacy functions have minimum yield issues, unpredictable timing, and swallow errors.
+
+---
+
+## SE-11 | Medium | Infinite Yield Warning
+
+### Problem
+
+`WaitForChild(name)` without a timeout yields forever if the child never appears. Common with renamed instances, StreamingEnabled, or race conditions.
+
+### Solution
+
+Always pass a timeout. Handle `nil` return:
+
+```luau
+local folder = ReplicatedStorage:WaitForChild("Weapons", 10)
+if not folder then
+    warn("[Init] Weapons folder not found after 10s")
+    return
+end
+```
+
+---
+
+## SE-12 | Low | String Patterns vs Regex
+
+### Problem
+
+Luau uses Lua string patterns, not regex. `\d` doesn't work - use `%d`. Escape with `%` not `\`. No alternation (`|`), no non-greedy `*?` (use `-` instead), no lookahead.
+
+### Key Differences
+
+- Digits: `%d` not `\d`
+- Word chars: `%w` not `\w`
+- Whitespace: `%s` not `\s`
+- Escape special chars: `%.` not `\.`
+- Non-greedy: `.-` not `.*?`
+- Literal `%`: `%%`
+
+---
+
+## SE-13 | Medium | Local Function Declaration Order
+
+### Problem
+
+Luau has no hoisting. A `local function` is invisible to code above its declaration. AI assistants frequently place helper functions below the functions that call them, causing nil-value runtime errors.
+
+### Rule
+
+**Callees above callers. Always.** If `functionA()` calls `helperB()`, then `helperB` must be declared first.
+
+```luau
+-- BAD: helperB is nil when functionA runs
+local function functionA()
+    helperB() -- ERROR: attempt to call a nil value
+end
+
+local function helperB()
+    print("I'm a helper")
+end
+
+-- GOOD: helper declared first
+local function helperB()
+    print("I'm a helper")
+end
+
+local function functionA()
+    helperB() -- works
+end
+```
+
+### When you need mutual recursion
+
+Use forward declaration:
+
+```luau
+local functionB -- forward declare
+local function functionA()
+    functionB()
+end
+function functionB() -- note: no 'local' (already declared above)
+    functionA()
+end
+```
+
+---
+
+## Quick Reference
+
+```
+CRITICAL (fix before shipping):
+  SE-1  DataStore session locking        → Use ProfileStore
+  SE-2  Client-side currency             → Server-authoritative only
+  SE-3  ProcessReceipt order             → Grant THEN PurchaseGranted
+
+HIGH (fix in current sprint):
+  SE-4  Undisconnected events            → Trove pattern (vendored)
+  SE-5  RemoteEvent flooding             → Per-player rate limiter
+  SE-6  BindToClose 30s timeout          → Parallel saves with task.spawn
+
+MEDIUM (fix before scale):
+  SE-7  Mobile part count                → StreamingEnabled + <10K parts
+  SE-8  Yielding in module require       → Init/Start lifecycle pattern
+  SE-9  Table # with nil gaps            → table.remove or explicit length
+  SE-11 Infinite yield WaitForChild      → Always pass timeout parameter
+  SE-13 Local function order             → Callees above callers (no hoisting)
+
+LOW (fix when convenient):
+  SE-10 Deprecated wait/spawn/delay      → task.wait/spawn/delay
+  SE-12 String patterns vs regex         → %d not \d, % not \
+```

package/skills/roblox-sync/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: roblox-sync
+description: >
+  Studio Script Sync setup, troubleshooting, mode detection.
+  Canonical filesystem sync path for Roblox development.
+last_reviewed: 2026-05-21
+---
+
+<!-- Source: Script Sync walkthrough compiled from Roblox DevForum + creator-docs (MIT) -->
+
+# Studio Script Sync
+
+## Why This Is the Canonical Sync Path
+
+| Tool | Setup steps | TeamCreate | Project file required |
+|------|-------------|------------|------------------------|
+| Studio Script Sync | 2 (toggle + right-click) | Yes | No |
+| Rojo | 6+ (install aftman, install Rojo, project.json, install plugin, serve, connect) | No | Yes |
+| Argon | 5 (install CLI, install plugin, init project, serve, connect) | No | Yes |
+| Pesto | 4 (install CLI, install plugin, init, sync) | Partial | Yes |
+
+## Setup Walkthrough
+
+1. In Roblox Studio, open **File → Beta Features**. Scroll to "Script Sync." Toggle it on. Restart Studio.
+2. In Explorer, right-click the top-level container holding your scripts (commonly ServerScriptService, ReplicatedStorage, StarterPlayer → StarterPlayerScripts). Click **Start Sync**.
+3. Pick a folder on disk. Suggested layout: `~/projects/<game-name>/src/<container-name>/`. Studio will mirror the script tree into that folder as `.luau` files.
+4. Repeat for each top-level container that holds scripts. Sync auto-resumes when Studio restarts.
+
+## Capacity
+
+- Up to 10000 scripts per top-level instance
+- Up to 128 top-level instances synced at once
+- Two-way real-time sync. Edits in either direction propagate.
+
+## What Sync Does and Doesn't
+
+**Does:**
+- Bidirectional `.luau` file mirror for scripts (Script, LocalScript, ModuleScript)
+- Auto-resume on Studio restart
+- Works with TeamCreate
+- Surfaces errors in UI when sync fails
+
+**Doesn't:**
+- Sync non-script instances (Parts, Models, Folders without scripts)
+- Sync empty folders (use `.gitkeep`)
+- Sync PackageLink instance metadata (package script contents do sync)
+- Provide sourcemaps (you still need Rojo for that)
+
+## Mode Detection
+
+Every session, the agent detects the active mode:
+
+- **Sync Mode** (filesystem `.luau` files exist): read/write/edit via filesystem. MCP only for verification, playtest, scene ops, asset insertion. Never read a script via MCP if its file exists on disk.
+- **MCP-Only Mode** (no `.luau` files on disk): minimize reads, prefer `run_code` for inspection, batch edits behind ChangeHistoryService Recording. Recommend enabling sync.
+
+If MCP-only and project exceeds light-touch scope (>500 lines/module or >10 modules), proactively recommend Sync Mode before continuing.
+
+## Common Issues
+
+- **Sync silently stops after Studio update**: restart Studio + re-Start Sync.
+- **Empty folders deleted on git pull**: add `.gitkeep`.
+- **Sync errors not auto-detected**: restart Studio. Roblox is fixing this.
+- **Duplicate-name hierarchy errors**: avoid duplicate names within a sync container.
+
+## Version Control with Git
+
+Script Sync puts `.luau` files on disk. Git works with files on disk. Use them together.
+
+### Setup (after sync is confirmed)
+
+```bash
+cd ~/projects/<game-name>
+git init
+git add .
+git commit -m "initial sync"
+```
+
+### .gitignore for Roblox projects
+
+```gitignore
+# OpenCode
+.opencode/
+
+# Roblox build files (binary, don't track)
+*.rbxl
+*.rbxlx
+*.rbxm
+*.rbxmx
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+### Agent responsibilities
+
+- **Suggest commits at natural breakpoints.** After completing a system, fixing a batch of bugs, or before a risky change: "Want to commit what we've built so far?"
+- **Use git diff to review changes.** Before committing, `git diff` to show the user what changed. This is the review loop.
+- **Commit messages should be descriptive.** "add DataService with ProfileStore session locking" not "update files."
+- **Branch for risky work.** If the user wants to experiment (new architecture, major refactor), suggest a branch first: `git checkout -b refactor/combat-system`.
+- **Don't auto-commit without asking.** Always confirm before `git commit`. The user should see what's being committed.
+
+### Common git operations the agent should know
+
+| Operation | Command | When |
+|-----------|---------|------|
+| See what changed | `git diff` | Before committing |
+| Stage changes | `git add -A` or `git add <file>` | Before committing |
+| Commit | `git commit -m "message"` | After staging |
+| See history | `git log --oneline -10` | When user asks "what changed" |
+| Undo last commit (keep changes) | `git reset --soft HEAD~1` | When user wants to redo commit |
+| Create branch | `git checkout -b <name>` | Before risky/experimental work |
+| Switch branch | `git checkout <name>` | When switching context |
+| Merge branch | `git merge <name>` | When experimental work is ready |
+
+### Conflict handling
+
+If git merge conflicts occur in `.luau` files, the agent should:
+1. Read the conflicting files
+2. Show the user the conflict markers
+3. Suggest a resolution based on what each side changed
+4. Help resolve and commit
+
+## If User Already Has Rojo/Argon
+
+Detect presence of `default.project.json` (Rojo) or `*.project.json` with Argon-specific fields. If found: filesystem is already source of truth, operate normally on disk. Don't suggest switching to Script Sync.