EL4CTEO/roblox-skills

# Analytics and live operations

## Analytics events (server-side, `AnalyticsService`)

Standard events feed the Creator Hub dashboards automatically (economy, funnels, progression,
custom). The `Fire*` methods are deprecated; use the `Log*` family.

```luau
--!strict
local AnalyticsService = game:GetService("AnalyticsService")

local Analytics = {}

-- Currency sources and sinks → Economy dashboard.

# Roblox game architecture

## The model in one paragraph

Every Roblox game is a **server** (authoritative, runs `Script`s, sees everything, owns DataStores)
plus one **client** per player (runs `LocalScript`s / client `Script`s, renders, reads input).
The server's DataModel **replicates** to clients automatically. Client changes do **not** replicate
back, except: physics of parts the client has network ownership of (its character by default),
its own `Humanoid` state/animations, and remote calls. Assume every client is compromised
(see `roblox-security`). Design every feature as: *client requests → server validates and
decides → state replicates → clients render*.

## Where things go

# Roblox audio

Two systems coexist:
- **Audio API** (modular, current): `AudioPlayer` → `Wire` → (`AudioEmitter` … `AudioListener`) → `Wire`
  → `AudioDeviceOutput`, with effect objects inserted in the chain. Required for voice-chat processing,
  mixing graphs, analyzers, text-to-speech/speech-to-text.
- **`Sound`** (classic, still supported): one object, parented to a part for 3D or to `SoundService`/UI for 2D;
  routed through `SoundGroup`s with `SoundEffect` children. Fine for simple games and existing code.

Don't mix both for the same feature; follow what the project uses.

## 2D audio (music, UI) with the Audio API

```luau

# Characters and animation

## Character basics

- A player character is a `Model` with a `Humanoid`, `HumanoidRootPart` (the root; move the character
  with `character:PivotTo(cframe)`), R15 body parts, and an `Animate` LocalScript.
- Defaults (walk speed, jump, health, R6/R15, collisions, body scaling) are configured in Studio's
  **Avatar Settings** window and `StarterPlayer` (`CharacterWalkSpeed`, `CharacterJumpHeight` or
  `CharacterUseJumpPower` + `CharacterJumpPower`).
- Custom character: put a `Model` named `StarterCharacter` in `StarterPlayer`. Custom per-player
  spawns: `Players.CharacterAutoLoads = false`, then `player:LoadCharacterAsync()` when ready
  (e.g. after data loads). `LoadCharacter` (non-Async) is deprecated.
- Characters are destroyed and recreated on death/respawn: bind per-character logic in `CharacterAdded`.
- Client-set `WalkSpeed`/`JumpHeight` are trivially exploitable; enforce limits on the server or use

# Roblox code review

Review in severity order. Report each finding with **file:line, severity, what breaks, and the fix**.
Verify claims against the code (and the engine reference when unsure) — don't pattern-match blindly.

## Severity guide

| Severity | Examples |
| --- | --- |
| **Critical** | Client-authoritative rewards/damage/currency; unvalidated remote args (NaN, instance spoofing); purchases granted outside `ProcessReceipt` or non-idempotent; data saved with `SetAsync` from multiple servers without session locking; secrets/API keys in replicated code; unfiltered player text shown to others. |
| **High** | Data loss paths (no `BindToClose`, saving default data after a failed load, no retry); memory leaks (connections, player-keyed tables); `InvokeClient`; per-frame remotes; infinite yields (`WaitForChild` without timeout on optional instances, `RemoteFunction` handlers that can yield forever); streaming-unsafe client indexing. |
| **Medium** | Deprecated/superseded APIs; `wait`/`spawn`/`delay`; polling loops; server-side tweens; missing `pcall` on network/yielding APIs; missing late-joiner handling; race conditions on `CharacterAdded`. |
| **Low** | Style, naming, missing types, magic numbers, dead code, minor inefficiencies. |

# Roblox data stores and cloud services

## Choose the service

| Need | Service | Notes |
| --- | --- | --- |
| Player progress, inventory, settings | **DataStore** via ProfileStore (session-locked) | One key per player (`User_{UserId}`), ≤ 4 MB. |
| Global leaderboards | `OrderedDataStore` | Integer values only; periodic updates, cached reads. |
| Fast, temporary, cross-server state | `MemoryStoreService` | Sorted maps, queues, hash maps; everything expires (TTL ≤ 45 days). |
| Matchmaking queues, live events, server lists | MemoryStore queue / sorted map | Not durable — never the only copy of valuable data. |
| Broadcast to all servers | `MessagingService` | ≤ 1 kB per message, best effort, no delivery guarantee. |
| Values changed by live-ops without publishing | Experience configs (`ConfigService`) | See `roblox-analytics-liveops`. |

## Player data: use session locking

# Game systems recipes

Every recipe follows the same contract:
1. **State lives on the server** in a service module; persistent parts go through the data layer
   (`roblox-data-stores`).
2. **Clients send intents** through validated, rate-limited remotes (`roblox-security`,
   `roblox-networking`) and render state they receive (attributes, snapshots/deltas).
3. **Config is data**: tunables in a shared/server config module (or live `ConfigService` configs).
4. **Lifecycle-safe**: handles late joiners, respawns, leaving mid-action, and server shutdown.

| System | Reference |
| --- | --- |
| Leaderstats, currency service, XP/levels, daily rewards, obby checkpoints | [references/progression.md](references/progression.md) |
| Round loop (intermission → match → results), teams, spawning | [references/round-system.md](references/round-system.md) |

# Roblox input and camera

## Choose an approach

| Approach | Use when |
| --- | --- |
| **Input Action System** (`InputContext` → `InputAction` → `InputBinding`) | New gameplay controls. Cross-device bindings configured as instances, contexts you enable/disable, built-in on-screen button binding, prompt display. Recommended. |
| `UserInputService` events | Raw input, text-free hotkeys, mouse position/delta, touch gestures, device detection. |
| `ContextActionService:BindAction` | Legacy/simple bind-with-mobile-button; existing code. |

All input handling is **client-side**. Send *intent* to the server via remotes; the server validates.

## Input Action System

# Modern Luau for Roblox

Luau is Roblox's gradually-typed Lua 5.1 derivative. Engine and language move fast; many
patterns from older tutorials (and older training data) are deprecated. Apply these defaults
to **every** script you write unless the project clearly uses another convention.

## Defaults for all generated code

1. `--!strict` at the top of new ModuleScripts (and Scripts when practical). Type public functions.
2. Get services with `game:GetService("Name")` at the top of the file, never `game.Name`.
3. Use the `task` library: `task.wait`, `task.spawn`, `task.defer`, `task.delay`, `task.cancel`.
   Never `wait`, `spawn`, `delay` (deprecated, throttled, imprecise).
4. Yielding engine calls that can fail (DataStore, HTTP, Marketplace, Teleport, `*Async`) go inside `pcall`.
5. Prefer the `*Async` variants of APIs; Roblox renamed most yielding methods

# Roblox monetization

## Product types

| Type | Buy | Use for | Grant via |
| --- | --- | --- | --- |
| Developer product | Repeatedly | Currency, consumables, boosts, revives | `MarketplaceService.ProcessReceipt` (server) |
| Pass | Once, permanent | VIP, permanent perks, extra slots | `UserOwnsGamePassAsync` check on join + purchase-finished event |
| Subscription | Monthly, revocable | Recurring perks (daily currency, VIP) | `GetUserSubscriptionStatusAsync` + `UserSubscriptionStatusChanged` |
| Rewarded video ad | Free (watch ad) | Small rewards (≈3–10 Robux value) | Developer product granted through `ProcessReceipt` |
| Commerce product | Real money (physical goods) | Merch with bundled digital benefits | `CommerceService`; digital benefits via `ProcessReceipt` |
| Private server | Monthly | Paid private servers | Configured in Creator Dashboard |

All granting happens on the **server**. Never grant from client events like

# Roblox networking

## Pick the right channel

| Channel | Delivery | Use for |
| --- | --- | --- |
| `RemoteEvent` | Reliable, ordered | Requests (client→server), game events, UI updates. The default. |
| `UnreliableRemoteEvent` | May drop or reorder; payload ≤ **1000 bytes** (larger payloads are dropped) | Continuous, superseded-by-next data: aim direction, cosmetic VFX, positions of non-physics objects. |
| `RemoteFunction` | Request/response, yields caller | Client→server queries that need an answer (e.g. "can I buy X?"). |
| Attributes / properties | Automatic replication server→client | Persistent state clients read (health, team, round state). |
| Physics replication | Automatic for owned assemblies | Moving parts; see `roblox-physics`. |

Never use `RemoteFunction:InvokeClient`: if the client errors, disconnects, or never returns, the server
throws or **yields forever**. Use a `RemoteEvent` to the client and another back if you need a reply.

# NPCs and AI

## Architecture

- NPC **logic runs on the server** (authoritative targets, damage, drops). Visual extras (idle
  animations, nameplates, effects) can run on clients.
- One NPC service drives all NPCs from a single loop (e.g. 5–10 Hz "think" rate, staggered), not one
  script + `while true` per NPC. Tag NPC models (`CollectionService`) and keep per-NPC state in a table.
- Server-owned physics: `npc.PrimaryPart:SetNetworkOwner(nil)` after spawning, so NPCs don't stutter
  when ownership moves between nearby players (and exploiters can't push them).
- Use `Humanoid` for NPCs that need walking/jumping/climbing; for simple movers (turrets, floating
  enemies, crowds) use an `AnimationController` + `Animator` and move with constraints or CFrames.

## Pathfinding

# Roblox Open Cloud and HttpService

Base URL: `https://apis.roblox.com`. Prefer **Open Cloud** endpoints (API key or OAuth 2.0, stable).
Legacy cookie-authenticated `*.roblox.com` web APIs can break without notice — don't build on them.

## Authentication

- **API keys** (Creator Dashboard → Open Cloud → API Keys): for your own/your group's resources and
  automation. Grant the minimum scopes per universe, set an **IP allowlist** (CIDR) and **expiration**,
[Credential-related source omitted]
  key created under the group. Introspect a key with `POST /api-keys/v1/introspect`.
- **OAuth 2.0** (authorization code + PKCE): apps acting on behalf of other users (third-party tools).
- Never ship keys in game scripts, attributes, or client code.

# Roblox performance

**Measure before optimizing.** Identify whether the bottleneck is server compute, client compute
(CPU/GPU), memory, network, or load time, then use the matching tool.

## Tools

| Tool | Open | Use for |
| --- | --- | --- |
| Developer Console | F9 (in game) | Errors, server/client memory by category, network, script activity. Works in live servers. |
| MicroProfiler | Ctrl+Alt+F6 (⌘⌥F6); Dev Console for server | Per-frame timing; spikes; dump a frame for detail. |
| Script Profiler | Studio / Dev Console | Which functions consume Luau time (sampling). |
| Luau heap snapshots | Dev Console → Memory → Luau Heap | What tables/closures/instances are held and by what (leaks). |
| Scene Analysis | Studio | Script memory, unparented instances (leaks), instance composition, audio/animation memory, triangles. Also `SceneAnalysisService` via Studio MCP. |

# Roblox physics and spatial queries

## Spatial queries (use these, not Touched, for gameplay decisions)

```luau
--!strict
local params = RaycastParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {} -- e.g. { character } of the shooter
params.IgnoreWater = true

local function castRay(origin: Vector3, direction: Vector3): RaycastResult?
	-- direction's length is the max distance
	return workspace:Raycast(origin, direction, params)

# Roblox security

**Exploiters fully control their client**: they can run any Luau, read every replicated script
(decompiled), fire any remote with any arguments at any rate, edit any local property (WalkSpeed,
prompt `Enabled`, `MaxActivationDistance`), and move anything they have network ownership of.
Client-side anti-cheat is at best a speed bump. Security comes from server design.

## Core rules

1. **The server decides.** Clients send *intent* ("I pressed attack aiming here"), never *results*
   ("I dealt 50 damage", "give me 100 coins").
2. **Validate every argument** of every `OnServerEvent`/`OnServerInvoke`: type, structure, range, finiteness.
3. **Validate context**: is the player alive, in range, not on cooldown, owns the item, allowed to act?
4. **Rate limit** everything a client can trigger (remotes, prompts, touches, clicks).

# Working in Roblox Studio through MCP

Roblox Studio ships a **built-in MCP server** (stdio). With it, an agent can explore the open place,
edit scripts, run Luau in edit/server/client contexts, playtest, read the Output, capture the viewport,
and simulate player input. It is the fastest way to **verify** Roblox changes instead of guessing.

## Setup

1. Latest Studio → open **Assistant** → **…** → **Manage MCP Servers** → enable **Enable Studio as MCP server**.
2. Use **Quick connect** (Claude Code, Claude Desktop, Codex CLI, Cursor, Gemini CLI, VS Code, Antigravity)
   or configure the client manually:

| OS | Command |
| --- | --- |

# Teleports, places, and matchmaking

## Structure

- A **universe** (experience) contains a start place plus sub-places. All places share DataStores,
  MemoryStores, MessagingService, developer products, and passes.
- Typical layouts: Lobby (start place) → Match place (reserved servers) → back to Lobby; or a hub with
  separate world places. Keep shared code in packages or a shared Rojo tree.
- **Access Control for Places** (Creator Dashboard): `Fully open`, `Limited to same universe`, or
  **`Secure within universe only`** (only server-initiated teleports into non-start places — recommended
  for progression gates and test places). Clients can otherwise teleport themselves anywhere in the universe.

## Teleporting (server)

# Testing Roblox games

## Make code testable first

- Keep game rules in **pure ModuleScripts** (inputs → outputs, no services, no yields): damage formulas,
  inventory operations, shop pricing, state machines, serialization, validation. These are trivially testable.
- Services take their dependencies as parameters (**dependency injection**) so tests can pass fakes
  instead of real DataStores, remotes, or `Players`.

```luau
--!strict
-- ReplicatedStorage/Shared/Inventory.luau — pure logic, no Roblox services.
export type Inventory = { [string]: number }

# Chat and text safety

## Non-negotiable rules (Roblox Community Standards)

1. Player-to-player conversation must go through **TextChatService** `TextChannel`s (handles filtering,
   privacy/parental settings, and abuse reporting). The legacy `Chat` service/`ChatService` Lua modules
   are gone — `TextChatService` is the only chat system.
2. **Any text authored by one player and shown to another** (pet names, signs, guild names, trade notes,
   custom UI) must be filtered with `TextService:FilterStringAsync` on the server before display — and
   re-filtered when loaded from a DataStore later.
3. Editable text others can see (signs, bulletin boards) needs a rate limit of at least 1 minute.
4. Respect privacy settings with `CanUserChatAsync`/`CanUsersChatAsync`/`CanUsersDirectChatAsync` and mark
   direct-message channels with `TextChannel:SetDirectChatRequester()`.

# Roblox tooling

## Pick a sync model

| Need | Use |
| --- | --- |
| Edit scripts in an external editor / git for code only; keep Studio as source of truth; Team Create | **Studio Script Sync** (built in: right-click a folder → **Sync to…**) |
| Whole project as files, file system is the source of truth, CI builds, packages | **Rojo** (`rojo serve` + Studio plugin) |

Script Sync syncs only `Script`/`LocalScript`/`ModuleScript`/`Folder` (≤ 10,000 scripts per synced
root, ≤ 128 roots); don't sync scripts that carry attributes/tags (they're not written to disk).
Pair either with the **Luau Language Server** VS Code extension + its **Luau Language Server Companion**
Studio plugin (sends the DataModel tree so requires and instance paths type-check).

# Roblox UI

## Foundations

- Put UI in `StarterGui` as `ScreenGui`s (copied to each player's `PlayerGui`), or create it from a
  client controller. UI code is client-only; the server never touches `PlayerGui` in normal designs.
- `ScreenGui` defaults to set: `ResetOnSpawn = false` (keep UI across deaths), `ZIndexBehavior = Sibling`,
  `IgnoreGuiInset` per design, `ScreenInsets = CoreUISafeInsets` for interactive UI (clears notches and
  the Roblox top bar); `DeviceSafeInsets`/`None` only for full-bleed backgrounds.
- **Size and position with Scale** (`UDim2.fromScale`) plus constraints; use Offset only for fixed
  details (padding, strokes, icons). Pure-Offset UI breaks on phones and 4K screens.
- `AnchorPoint = Vector2.new(0.5, 0.5)` + `Position = UDim2.fromScale(0.5, 0.5)` centers an element.
- `UIAspectRatioConstraint` keeps shapes square/consistent; `UISizeConstraint` caps sizes;
  `UITextSizeConstraint` with `TextScaled` bounds text size (prefer fixed `TextSize` + `AutomaticSize`

# World building with code

## Parts and models

```luau
--!strict
local function makePart(size: Vector3, cframe: CFrame, props: { [string]: any }?): Part
	local part = Instance.new("Part")
	part.Anchored = true
	part.Size = size
	part.CFrame = cframe
	part.TopSurface = Enum.SurfaceType.Smooth
	part.BottomSurface = Enum.SurfaceType.Smooth
	for key, value in props or {} do