# Roblox Luau Patterns

> OOP with metatables, inheritance, async (Promises, pcall), module structure, service pattern.

- **Type:** Skill
- **Install:** `agentstack add skill-tabooharmony-roblox-brain-roblox-luau-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TabooHarmony](https://agentstack.voostack.com/s/tabooharmony)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TabooHarmony](https://github.com/TabooHarmony)
- **Source:** https://github.com/TabooHarmony/roblox-brain/tree/main/skills/roblox-luau-patterns

## Install

```sh
agentstack add skill-tabooharmony-roblox-brain-roblox-luau-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## When to Load

- Designing classes with metatables (constructors, methods, inheritance)
- Async control flow (Promises, coroutines, pcall/xpcall, retry patterns)
- Module structure and organization (service pattern, singletons)
- Roblox-specific patterns (Instance creation, service access, events, task library)
- Choosing between architectural approaches (OOP vs modules vs flat functions)
- Error handling strategy (pcall wrapping, fallbacks, retry logic)

**Hand off when:** Pure syntax → `roblox-luau-core` · Type annotations → `roblox-luau-types` · Networking/data/security → `roblox-networking`, `roblox-data`, `roblox-security` · Performance → `roblox-performance`.

Full examples and code samples: `references/full.md`

## Quick Reference

**OOP (metatables):** Use for multiple instances with shared behavior.
```luau
local MyClass = {}
MyClass.__index = MyClass
function MyClass.new(...): MyClass  -- . for constructors
    return setmetatable({...}, MyClass)
end
function MyClass:method()           -- : for methods (implicit self)
end
-- Inheritance: setmetatable(Child, { __index = Parent })
```
Always set `__index`. Constructors use `.`, methods use `:`.

**Module Services:** Singleton pattern for managers. `Service.init()` wires events; clean up in `PlayerRemoving`.

**Instance Creation:** Configure ALL properties, set `Parent` LAST (prevents replication races).

**Task Library:** Always use `task.*`. `wait()`/`spawn()`/`delay()` are deprecated.

**Error Handling:**
```luau
local ok, result = pcall(fn, args...)       -- one-shot fallible calls
local ok, result = xpcall(fn, handler)      -- custom error handler + traceback
```
Wrap ALL DataStore/HTTP calls. Use Promise library for async chains (`:andThen`/`:catch`/`:finally`).

**Naming:** PascalCase (classes/modules/types), camelCase (vars/functions), UPPER_CASE (constants). Prefix `_` for private.

**Anti-Patterns:**
- `wait()`/`spawn()`/`delay()` → `task.*`
- Polling loops → events or Heartbeat
- String `..` in loops → `table.concat()`
- Missing `pcall` on DataStore/HTTP → silent crash
- Trusting client → validate types, ranges, ownership
- Parent before config → replication race
- Props on class table instead of `self` → shared across instances
- No connection cleanup → use Trove or manual `:Disconnect()`

**Libraries:** Promise · Trove · Signal · Comm (Sleitnick) · ProfileStore · t (runtime checks)

**Checklist:** `__index` set · `.`/`:` correct · pcall on fallible · connections cleaned · Parent last · no deprecated · clear API · async error handling · player data cleaned on PlayerRemoving

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TabooHarmony](https://github.com/TabooHarmony)
- **Source:** [TabooHarmony/roblox-brain](https://github.com/TabooHarmony/roblox-brain)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tabooharmony-roblox-brain-roblox-luau-patterns
- Seller: https://agentstack.voostack.com/s/tabooharmony
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.