Skip to content

Souvik-223/agent-skills-agentic-tools / .agents/skills/game-development/roblox-games

roblox-game

Verified

Expert Roblox game development companion — Luau, Roblox Studio, MCP integration, simulator, tycoon, obby, RPG, horror, battle royale, game design, security, performance.

FileKindSize
.gitignoreother9 B
README.mdmarkdown5.2 KB
SKILL.mdskill md5.1 KB
docs/plans/2026-03-04-roblox-game-skill-design.mdmarkdown11.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/_index.mdmarkdown5.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-001-create-directory-structure.mdmarkdown753 B
docs/plans/2026-03-04-roblox-game-skill-plan/task-002-write-skill-router.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-003-luau-mastery.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-004-architecture-patterns.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-005-mcp-orchestration.mdmarkdown2.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-006-security-hardening.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-007-datastore-persistence.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-008-gui-systems.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-009-performance-optimization.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-010-monetization-systems.mdmarkdown2.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-011-combat-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-012-inventory-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-013-game-design-roblox.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-014-tooling-ecosystem.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-015-animation-vfx.mdmarkdown2.0 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-016-multiplayer-networking.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-017-testing-patterns.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-018-sharp-edges.mdmarkdown2.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-019-game-scaffold.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-020-genre-simulator.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-021-genre-tycoon.mdmarkdown1.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-022-genre-obby.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-023-genre-rpg.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-024-genre-horror.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-025-genre-battle-royale.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-026-workflow-new-game.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-027-workflow-debug-loop.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-028-workflow-performance-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-029-workflow-security-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-030-workflow-publish-checklist.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-031-workflow-monetization-audit.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-032-workflow-code-review.mdmarkdown1.6 KB
references/animation-vfx.mdmarkdown38.4 KB
references/architecture-patterns.mdmarkdown32.2 KB
references/combat-systems.mdmarkdown42.0 KB
references/datastore-persistence.mdmarkdown31.6 KB
references/game-design-roblox.mdmarkdown34.9 KB
references/gui-systems.mdmarkdown46.2 KB
references/inventory-systems.mdmarkdown51.7 KB
references/luau-mastery.mdmarkdown42.9 KB
references/mcp-orchestration.mdmarkdown16.4 KB
references/monetization-systems.mdmarkdown24.4 KB
references/multiplayer-networking.mdmarkdown50.0 KB
references/performance-optimization.mdmarkdown17.7 KB
references/security-hardening.mdmarkdown35.2 KB
references/sharp-edges.mdmarkdown40.3 KB
references/testing-patterns.mdmarkdown29.6 KB
references/tooling-ecosystem.mdmarkdown29.2 KB
templates/game-scaffold.mdmarkdown57.6 KB
templates/genre-battle-royale.mdmarkdown44.2 KB
templates/genre-horror.mdmarkdown49.9 KB
templates/genre-obby.mdmarkdown26.0 KB
templates/genre-rpg.mdmarkdown43.2 KB
templates/genre-simulator.mdmarkdown48.7 KB
templates/genre-tycoon.mdmarkdown50.9 KB
workflows/code-review.mdmarkdown10.3 KB
workflows/debug-loop.mdmarkdown7.8 KB
workflows/monetization-audit.mdmarkdown11.3 KB
workflows/new-game.mdmarkdown19.6 KB
workflows/performance-audit.mdmarkdown7.6 KB
workflows/publish-checklist.mdmarkdown9.6 KB
workflows/security-audit.mdmarkdown9.1 KB

workflows/debug-loop.md

View on GitHub
# Iterative Debugging Workflow

A structured loop for diagnosing and fixing Roblox game bugs. Adapts to MCP Full, MCP Standard, and Offline environments. Caps at 5 iterations before escalating to the user.

---

## Step 1: Error Gathering

Collect the raw error output so there is concrete diagnostic data to work with.

### MCP Full
- Call `get_playtest_output` to retrieve runtime errors from the most recent playtest session.
- If no playtest is active, fall back to `get_console_output` to read the Studio output panel.

### MCP Standard
- Call `get_console_output` to read whatever is currently in the output panel.

### Offline
- Ask the user to paste the **full error message** including:
  - The error text itself.
  - The stack trace (script name, line number).
  - Any preceding warnings that may provide context.

### What to capture
- Exact error string (e.g., `ServerScriptService.CombatHandler:42: attempt to index nil with 'Character'`).
- Script path and line number.
- Whether the error fires once, intermittently, or in a loop.
- Client vs. server origin.

---

## Step 2: Code Discovery

Locate and read the source code surrounding the error.

### MCP Full
- Use `grep_scripts` with keywords from the error (function name, variable, service) to find all relevant scripts.
- Use `get_script_source` on each match to read the full source.

### MCP Standard
- Use `run_code` to print script contents via Luau:
  ```lua
  local src = game:GetService("ServerScriptService"):FindFirstChild("CombatHandler")
  if src then print(src.Source) end
  ```

### Offline
- Ask the user to share the contents of every script referenced in the stack trace.
- Also request any scripts that call into or are called by the erroring script (upstream/downstream).

### What to look for
- The exact line cited in the error.
- 10-20 lines of surrounding context for control flow.
- Related modules that feed data into the erroring function (require chains, event connections).

---

## Step 3: Root Cause Analysis

Categorize the error into one of the following buckets. Cross-reference with `references/luau-mastery.md` and `references/security-hardening.md` for common Roblox gotchas.

### Syntax Error
- Missing `end`, `then`, or `do`.
- Mismatched parentheses or brackets.
- Typo in keyword (e.g., `fucntion` instead of `function`).
- **Fix pattern:** Correct the typo or add the missing token. Luau's error message usually points directly at the problem.

### Runtime Error
- **Nil reference:** Accessing a property on a value that is `nil`. Common causes:
  - `Player.Character` before the character has loaded.
  - `FindFirstChild` returning `nil` and the result used without a guard.
  - Remote event payload that the client did not send.
- **Type mismatch:** Passing a string where a number is expected, or vice versa.
- **Missing service:** Calling `GetService` with a misspelled service name.
- **Fix pattern:** Add nil guards, type checks, or WaitForChild with a timeout.

### Logic Error
- Code runs without errors but produces wrong behavior.
- Incorrect calculation (damage formula, cooldown timer, currency math).
- Wrong conditional logic (using `or` instead of `and`, inverted boolean).
- Event fires but the handler does the wrong thing.
- **Fix pattern:** Trace the data flow step by step with print statements or breakpoints to find where actual values diverge from expected values.

### Security Issue
- Client sending unvalidated data through RemoteEvents.
- Trusting `Player.Character.Humanoid.Health` from the client.
- Missing server-side sanity checks on purchase amounts, damage values, or item IDs.
- **Fix pattern:** Move authority to the server. Validate every remote argument. See `references/security-hardening.md`.

### Performance Issue
- Server or client frame rate dropping.
- Memory climbing over time (leak).
- High part count, excessive raycasting, or unthrottled loops.
- Runaway `RenderStepped` / `Heartbeat` connections that never disconnect.
- **Fix pattern:** Profile with MicroProfiler, reduce unnecessary computation, pool objects, debounce events. See `references/performance-optimization.md`.

---

## Step 4: Generate Fix

Produce corrected Luau code. Every fix must include:

1. **What was wrong** -- a plain-language explanation of the bug.
2. **Why the fix works** -- the specific change and the reasoning behind it.
3. **The corrected code** -- full function or block, not just a one-line diff, so it can be dropped in without ambiguity.

### Fix guidelines
- Preserve the original code's style and naming conventions.
- Do not introduce unrelated refactors in the same fix (keep the diff minimal and focused).
- If the fix requires a new guard or validation, explain what happens when the guard triggers (e.g., early return, warning log, fallback value).
- If the bug is in a pattern that appears in multiple scripts, note all locations so they can all be patched.

---

## Step 5: Apply and Test

### MCP Full
1. Call `execute_luau` to inject the corrected code into the running session or update the script source.
2. Call `start_playtest` to launch a new playtest.
3. Call `get_playtest_output` to capture output and check for the original error.

### MCP Standard
1. Call `run_code` to apply the fix:
   ```lua
   local script = game:GetService("ServerScriptService"):FindFirstChild("CombatHandler")
   script.Source = [[ --[[ corrected source here ]] ]]
   ```
2. Call `start_stop_play` to restart the playtest.
3. Call `get_console_output` to read the results.

### Offline
1. Provide the corrected code in a fenced Luau block.
2. Give step-by-step manual testing instructions:
   - Where to paste the code (which script, which service).
   - How to trigger the scenario that caused the bug.
   - What output or behavior to look for to confirm the fix.

---

## Step 6: Verify

Check whether the original error is resolved.

### Error is gone
- Confirm no new errors were introduced by scanning the full output (not just filtering for the original error string).
- If clean, proceed to Step 7.

### Error persists or a new error appears
- Capture the new diagnostic info.
- Return to **Step 1** with the updated error data.
- On each iteration, append findings to a running log:
  ```
  Iteration 1: Nil reference on Character -- added WaitForChild guard -- error persists (different line).
  Iteration 2: ...
  ```

### Iteration cap
- **Maximum 5 iterations.** If the bug is not resolved after 5 passes:
  - Stop attempting automatic fixes.
  - Present the user with a **findings summary**:
    - Each iteration's hypothesis, attempted fix, and result.
    - Remaining theories that have not been tested.
    - Suggested next steps (e.g., enable MicroProfiler, add verbose logging, isolate in a minimal repro place).

---

## Step 7: Summary

Once the bug is resolved, document the outcome. This serves as a record for future debugging and helps prevent recurrence.

### Template

```
## Bug Report

**Error:** [exact error message]
**Script:** [full script path]
**Line:** [line number]

**Root Cause Category:** [Syntax | Runtime | Logic | Security | Performance]

**Root Cause Description:**
[Plain-language explanation of why the bug occurred.]

**Fix Applied:**
[Description of the change. Include the key code diff or corrected block.]

**Iterations Required:** [1-5]

**Preventive Advice:**
- [Actionable recommendation to avoid this class of bug in the future.]
- [E.g., "Always nil-check Player.Character before accessing Humanoid."]
- [E.g., "Validate all RemoteEvent arguments on the server before processing."]
```

### After documenting
- If the bug revealed a pattern that should be caught earlier, suggest adding a lint rule, a helper function, or a note to the project's coding conventions.
- If the root cause was a common Roblox gotcha, verify it is covered in the relevant reference docs (`luau-mastery.md`, `security-hardening.md`, `performance-optimization.md`). If not, flag it for addition.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall