roblox-luau
Script a Roblox experience in Luau: get services, create and parent Instances, connect events, run server Scripts vs client LocalScripts, and communicate across the client/server boundary with RemoteEvents/RemoteFunctions (server-authoritative). Use when building or debugging Rob
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/other-engines/roblox-luau
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Roblox Luau Scripting
Script a Roblox experience in Luau: services, Instances, events, the
server/client split, and secure cross-boundary communication. Targets the current
Roblox engine and Studio.
When to use
- Use when writing Roblox scripts: getting services, creating/parenting instances,
connecting events, deciding server vs client, or wiring
RemoteEvent/RemoteFunctioncommunication. - Use when the project has
Script/LocalScript/ModuleScriptobjects,.rbxl(x)places, or a Rojo*.project.json, and code callsgame:GetService(...).
When not to use: persisting data across sessions → roblox-datastores.
Remote protocol architecture, exploit hardening, rate limits, high-frequency replication, and
multi-client abuse testing → roblox-networking. Generic Lua questions unrelated to the Roblox
API. Engine-agnostic input/save architecture → input-systems / save-systems.
Core workflow
- Get services with
game:GetService("Name"). Common ones:Players,Workspace,ReplicatedStorage(shared client+server),ServerScriptService(server-only code),ServerStorage,RunService,UserInputService(client). - Know where code runs. A
Scriptruns on the server; aLocalScriptruns on a client (inStarterPlayerScripts,StarterGui, or the player's character). AScriptwhoseRunContextisClientalso runs on clients, fromReplicatedStorage; checkRunContextbefore deciding where aScriptruns. AModuleScriptis shared code yourequire. - Create instances deliberately.
local p = Instance.new("Part"), set its properties, then setp.Parentlast (parenting triggers replication). - React with events.
:Connectto signals likePlayers.PlayerAdded,part.Touched, orRunService.Heartbeat. Disconnect when done to avoid leaks. - Cross the client/server boundary with Remotes — and never trust the client.
Clients request via
RemoteEvent:FireServer(...); the server validates and applies. The server is authoritative for all game state. - Test in Studio with Test / Test Here / Server & Clients; use the Output window and the Client/Server toggle to confirm where code ran.
- Run static checks before Studio when the project already has the tools. Put
std = "roblox"in the rootselene.toml, then runselene .. For a Rojo project, write the sourcemap once withrojo sourcemap default.project.json --output sourcemap.json, then runluau-lsp analyze --sourcemap=sourcemap.json src, passing the Roblox type definitions with--definitions(luau-lsp analyze --helplists the flags). Studio Script Sync projects may not have a sourcemap.
Patterns
1. Server Script: react to players joining (leaderstats)
-- ServerScriptService/Leaderboard.server.luau (a Script = runs on the server)
local Players = game:GetService("Players")
local function onPlayerAdded(player: Player)
local stats = Instance.new("Folder")
stats.Name = "leaderstats" -- this name makes it show on the leaderboard
local coins = Instance.new("IntValue")
coins.Name = "Coins"
coins.Value = 0
coins.Parent = stats
stats.Parent = player -- parent LAST
end
Players.PlayerAdded:Connect(onPlayerAdded)
2. Create and configure an instance
local Workspace = game:GetService("Workspace")
local part = Instance.new("Part")
part.Size = Vector3.new(4, 1, 4)
part.Position = Vector3.new(0, 10, 0)
part.Anchored = true -- won't fall under gravity
part.BrickColor = BrickColor.new("Bright blue")
part.Parent = Workspace -- set Parent last so it replicates once, fully
3. Connect an event (and disconnect to avoid leaks)
local debounce = false
local connection
connection = part.Touched:Connect(function(hit: BasePart)
local character = hit.Parent
local humanoid = character and character:FindFirstChildOfClass("Humanoid")
if not humanoid or debounce then return end
debounce = true
humanoid.Health -= 10
task.wait(1) -- task.wait, NOT the deprecated wait()
debounce = false
end)
-- Later, when the part is removed or the round ends:
-- connection:Disconnect()
4. Client → server with a RemoteEvent (validate on the server!)
-- ReplicatedStorage: create a RemoteEvent named "BuyItem" (in Studio or via code).
-- CLIENT (LocalScript): request a purchase. The client can lie — this is only a request.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local buyItem = ReplicatedStorage:WaitForChild("BuyItem") -- wait: may not have replicated yet
buyButton.MouseButton1Click:Connect(function()
buyItem:FireServer("sword") -- send the item id only; never the price/result
end)
-- SERVER (Script): the ONLY place the transaction is decided.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local buyItem = ReplicatedStorage:WaitForChild("BuyItem")
local PRICES = { sword = 100, shield = 75 }
buyItem.OnServerEvent:Connect(function(player: Player, itemId)
-- TRUST NOTHING from the client. Validate types and values.
if type(itemId) ~= "string" then return end
local price = PRICES[itemId]
if not price then return end -- unknown item
local coins = player.leaderstats.Coins
if coins.Value < price then return end -- can't afford
coins.Value -= price -- server applies the change
grantItem(player, itemId)
end)
5. A per-frame loop with RunService
local RunService = game:GetService("RunService")
-- Heartbeat fires every frame AFTER physics; dt is seconds since the last step.
RunService.Heartbeat:Connect(function(dt)
spinner.CFrame *= CFrame.Angles(0, math.rad(90) * dt, 0) -- 90deg/sec, frame-independent
end)
6. Shared code in a ModuleScript
-- ReplicatedStorage/GameConfig (a ModuleScript) — usable by server and client.
local GameConfig = {}
GameConfig.MaxHealth = 100
function GameConfig.damageFor(weapon: string): number
return ({ sword = 25, bow = 15 })[weapon] or 0
end
return GameConfig
local GameConfig = require(game:GetService("ReplicatedStorage"):WaitForChild("GameConfig"))
print(GameConfig.MaxHealth)
Pitfalls
- Trusting the client is an exploit → clients can send any arguments to a
RemoteEvent/RemoteFunction. Validate every argument's type and range on the server and keep the server authoritative over health, currency, and inventory. LocalScriptdoesn't run where you put it → LocalScripts run inStarterPlayerScripts,StarterCharacterScripts,StarterGui, or tools — not inWorkspaceorServerScriptService. ServerScripts belong inServerScriptService/Workspace. AScriptwithRunContext = Clientplaced in aStarter*container runs twice (original and copy); keep those inReplicatedStorage.- Deprecated globals → use
task.wait/task.spawn/task.delay, not the oldwait()/spawn()/delay()(worse scheduling and throttling). - Parenting first, then setting properties → set properties first and
Parentlast so the instance replicates once in its final state. nilon the client right after join → objects stream/replicate over time; useparent:WaitForChild("Name")instead of indexing directly on the client.- Connections never disconnected → long-lived
:Connecthandlers leak and can fire on destroyed objects; store the connection and:Disconnect()(or useInstance:GetAttributeChangedSignal/:Oncewhere appropriate). - Using a RemoteFunction where a RemoteEvent fits →
RemoteFunctionblocks waiting for a return and a malicious/slow client can stall the server; prefer one-wayRemoteEvents unless you genuinely need a reply. - Assuming the old type checker -> Luau's New Type Solver reached general release
(out of Studio Beta) in Nov 2025.
nocheck/non-strict places get it automatically; strict-mode places opt in with theUseNewLuauTypeSolverworkspace property, andLuauTypeCheckModesets a place's default checking mode. It runs only at edit time (no runtime cost), so triage type warnings against the solver the place actually has enabled, not older behavior.
References
- For the full client/server model (replication,
RemoteFunctionvsRemoteEvent,:WaitForChildtiming,BindableEventfor same-context messaging, attributes,CollectionServicetags, and:Once/connection cleanup), readreferences/client-server.md.
Related skills
roblox-datastores— persist player data across sessions (server-only).roblox-networking— production remote contracts, server validation, rate limits, replication, streaming, prediction, and multi-client testing.save-systems— engine-agnostic persistence concepts.game-ai/input-systems— portable AI and input patterns to implement in Luau.
Files (awesome-gamedev-agent-skills)
-
references
-
client-server.md 4.7 KB
Loading…
-
-
SKILL.md 9.4 KB
--- name: roblox-luau description: > Script a Roblox experience in Luau: get services, create and parent Instances, connect events, run server Scripts vs client LocalScripts, and communicate across the client/server boundary with RemoteEvents/RemoteFunctions (server-authoritative). Use when building or debugging Roblox Studio scripts — when the user mentions Roblox, Luau, services, RemoteEvent, Instance.new, PlayerAdded, or client vs server. For saving player data use roblox-datastores. --- # Roblox Luau Scripting Script a Roblox experience in **Luau**: services, `Instance`s, events, the server/client split, and secure cross-boundary communication. Targets the current Roblox engine and Studio. ## When to use - Use when writing Roblox scripts: getting services, creating/parenting instances, connecting events, deciding server vs client, or wiring `RemoteEvent`/ `RemoteFunction` communication. - Use when the project has `Script`/`LocalScript`/`ModuleScript` objects, `.rbxl(x)` places, or a Rojo `*.project.json`, and code calls `game:GetService(...)`. **When *not* to use:** persisting data across sessions → `roblox-datastores`. Remote protocol architecture, exploit hardening, rate limits, high-frequency replication, and multi-client abuse testing → `roblox-networking`. Generic Lua questions unrelated to the Roblox API. Engine-agnostic input/save architecture → `input-systems` / `save-systems`. ## Core workflow 1. **Get services with `game:GetService("Name")`.** Common ones: `Players`, `Workspace`, `ReplicatedStorage` (shared client+server), `ServerScriptService` (server-only code), `ServerStorage`, `RunService`, `UserInputService` (client). 2. **Know where code runs.** A `Script` runs on the **server**; a `LocalScript` runs on a **client** (in `StarterPlayerScripts`, `StarterGui`, or the player's character). A `Script` whose `RunContext` is `Client` also runs on clients, from `ReplicatedStorage`; check `RunContext` before deciding where a `Script` runs. A `ModuleScript` is shared code you `require`. 3. **Create instances deliberately.** `local p = Instance.new("Part")`, set its properties, then set `p.Parent` **last** (parenting triggers replication). 4. **React with events.** `:Connect` to signals like `Players.PlayerAdded`, `part.Touched`, or `RunService.Heartbeat`. Disconnect when done to avoid leaks. 5. **Cross the client/server boundary with Remotes — and never trust the client.** Clients request via `RemoteEvent:FireServer(...)`; the server validates and applies. The server is authoritative for all game state. 6. **Test in Studio** with **Test** / **Test Here** / **Server & Clients**; use the Output window and the Client/Server toggle to confirm where code ran. 7. **Run static checks before Studio when the project already has the tools.** Put `std = "roblox"` in the root `selene.toml`, then run `selene .`. For a Rojo project, write the sourcemap once with `rojo sourcemap default.project.json --output sourcemap.json`, then run `luau-lsp analyze --sourcemap=sourcemap.json src`, passing the Roblox type definitions with `--definitions` (`luau-lsp analyze --help` lists the flags). Studio Script Sync projects may not have a sourcemap. ## Patterns ### 1. Server Script: react to players joining (leaderstats) ```lua -- ServerScriptService/Leaderboard.server.luau (a Script = runs on the server) local Players = game:GetService("Players") local function onPlayerAdded(player: Player) local stats = Instance.new("Folder") stats.Name = "leaderstats" -- this name makes it show on the leaderboard local coins = Instance.new("IntValue") coins.Name = "Coins" coins.Value = 0 coins.Parent = stats stats.Parent = player -- parent LAST end Players.PlayerAdded:Connect(onPlayerAdded) ``` ### 2. Create and configure an instance ```lua local Workspace = game:GetService("Workspace") local part = Instance.new("Part") part.Size = Vector3.new(4, 1, 4) part.Position = Vector3.new(0, 10, 0) part.Anchored = true -- won't fall under gravity part.BrickColor = BrickColor.new("Bright blue") part.Parent = Workspace -- set Parent last so it replicates once, fully ``` ### 3. Connect an event (and disconnect to avoid leaks) ```lua local debounce = false local connection connection = part.Touched:Connect(function(hit: BasePart) local character = hit.Parent local humanoid = character and character:FindFirstChildOfClass("Humanoid") if not humanoid or debounce then return end debounce = true humanoid.Health -= 10 task.wait(1) -- task.wait, NOT the deprecated wait() debounce = false end) -- Later, when the part is removed or the round ends: -- connection:Disconnect() ``` ### 4. Client → server with a RemoteEvent (validate on the server!) ```lua -- ReplicatedStorage: create a RemoteEvent named "BuyItem" (in Studio or via code). -- CLIENT (LocalScript): request a purchase. The client can lie — this is only a request. local ReplicatedStorage = game:GetService("ReplicatedStorage") local buyItem = ReplicatedStorage:WaitForChild("BuyItem") -- wait: may not have replicated yet buyButton.MouseButton1Click:Connect(function() buyItem:FireServer("sword") -- send the item id only; never the price/result end) ``` ```lua -- SERVER (Script): the ONLY place the transaction is decided. local ReplicatedStorage = game:GetService("ReplicatedStorage") local buyItem = ReplicatedStorage:WaitForChild("BuyItem") local PRICES = { sword = 100, shield = 75 } buyItem.OnServerEvent:Connect(function(player: Player, itemId) -- TRUST NOTHING from the client. Validate types and values. if type(itemId) ~= "string" then return end local price = PRICES[itemId] if not price then return end -- unknown item local coins = player.leaderstats.Coins if coins.Value < price then return end -- can't afford coins.Value -= price -- server applies the change grantItem(player, itemId) end) ``` ### 5. A per-frame loop with RunService ```lua local RunService = game:GetService("RunService") -- Heartbeat fires every frame AFTER physics; dt is seconds since the last step. RunService.Heartbeat:Connect(function(dt) spinner.CFrame *= CFrame.Angles(0, math.rad(90) * dt, 0) -- 90deg/sec, frame-independent end) ``` ### 6. Shared code in a ModuleScript ```lua -- ReplicatedStorage/GameConfig (a ModuleScript) — usable by server and client. local GameConfig = {} GameConfig.MaxHealth = 100 function GameConfig.damageFor(weapon: string): number return ({ sword = 25, bow = 15 })[weapon] or 0 end return GameConfig ``` ```lua local GameConfig = require(game:GetService("ReplicatedStorage"):WaitForChild("GameConfig")) print(GameConfig.MaxHealth) ``` ## Pitfalls - **Trusting the client is an exploit** → clients can send any arguments to a `RemoteEvent`/`RemoteFunction`. Validate every argument's type and range on the server and keep the server authoritative over health, currency, and inventory. - **`LocalScript` doesn't run where you put it** → LocalScripts run in `StarterPlayerScripts`, `StarterCharacterScripts`, `StarterGui`, or tools — not in `Workspace` or `ServerScriptService`. Server `Script`s belong in `ServerScriptService`/`Workspace`. A `Script` with `RunContext = Client` placed in a `Starter*` container runs twice (original and copy); keep those in `ReplicatedStorage`. - **Deprecated globals** → use `task.wait`/`task.spawn`/`task.delay`, not the old `wait()`/`spawn()`/`delay()` (worse scheduling and throttling). - **Parenting first, then setting properties** → set properties first and `Parent` last so the instance replicates once in its final state. - **`nil` on the client right after join** → objects stream/replicate over time; use `parent:WaitForChild("Name")` instead of indexing directly on the client. - **Connections never disconnected** → long-lived `:Connect` handlers leak and can fire on destroyed objects; store the connection and `:Disconnect()` (or use `Instance:GetAttributeChangedSignal`/`:Once` where appropriate). - **Using a RemoteFunction where a RemoteEvent fits** → `RemoteFunction` blocks waiting for a return and a malicious/slow client can stall the server; prefer one-way `RemoteEvent`s unless you genuinely need a reply. - **Assuming the old type checker** -> Luau's New Type Solver reached general release (out of Studio Beta) in Nov 2025. `nocheck`/non-strict places get it automatically; strict-mode places opt in with the `UseNewLuauTypeSolver` workspace property, and `LuauTypeCheckMode` sets a place's default checking mode. It runs only at edit time (no runtime cost), so triage type warnings against the solver the place actually has enabled, not older behavior. ## References - For the full client/server model (replication, `RemoteFunction` vs `RemoteEvent`, `:WaitForChild` timing, `BindableEvent` for same-context messaging, attributes, `CollectionService` tags, and `:Once`/connection cleanup), read `references/client-server.md`. ## Related skills - `roblox-datastores` — persist player data across sessions (server-only). - `roblox-networking` — production remote contracts, server validation, rate limits, replication, streaming, prediction, and multi-client testing. - `save-systems` — engine-agnostic persistence concepts. - `game-ai` / `input-systems` — portable AI and input patterns to implement in Luau.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.