Skip to main content
skill CX Codex

roblox-architecture · el4cteo — Claude Code skill: setup and features

The roblox-architecture Claude Code skill explains Roblox project structure and the client-server model. It activates when setting up a project or troubleshooting replication and streaming.

MIT 1,200 installs ★ 131 updated 2026-11-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add EL4CTEO/roblox-skills --skill roblox-architecture -a claude-code
Open on GitHub

What roblox-architecture does

The skill maps Roblox scripts, modules, and assets to the right containers. It covers ServerScriptService, ServerStorage, ReplicatedStorage, and StarterPlayer, along with RunContext and module-based service and controller startup.

Other sections cover player and character lifecycle events, components tagged with CollectionService, and client code that accounts for streamed instances. Clients can download code in ReplicatedStorage, so server logic and secrets should stay elsewhere.

What it helps with

  • place scripts and assets in the right Roblox containers
  • trace why client changes do not replicate to the server
  • organize startup for server services and client controllers
  • handle character respawns and streamed instances

Example prompts for the agent

  • Suggest a Roblox project layout with server services, client controllers, and shared modules.
  • Explain why a script in ReplicatedStorage runs on the wrong side.
  • Show how to handle CharacterAdded and players who joined before startup.

How to install roblox-architecture

1Skills CLI (Vercel)

npx skills add EL4CTEO/roblox-skills --skill roblox-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/roblox-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/roblox-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about roblox-architecture

How do I install roblox-architecture in Claude Code?

Run npx skills add EL4CTEO/roblox-skills --skill roblox-architecture -a claude-code. The skill file is at ~/.claude/skills/roblox-architecture/SKILL.md.

What does roblox-architecture do?

It explains Roblox project layout, client-server code boundaries, module startup, and player lifecycle handling. It also covers CollectionService tags and client code that handles streaming.

Can I use roblox-architecture with a project that already uses Knit?

The skill shows service startup without a framework. For an existing Knit project, it recommends following that project's conventions.

Source text

SKILL.md · MIT
---
name: roblox-architecture
description: Roblox project structure and client/server model - replication, where code and assets belong (ServerScriptService, ReplicatedStorage, StarterPlayer), RunContext, service/controller bootstrapping, player/character lifecycle, CollectionService components, attributes, streaming-safe client code, library choices. Use when starting a project, deciding where code goes, or fixing replication/streaming bugs.
---

# 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

| Container | Runs/visible on | Put here |
| --- | --- | --- |
| `ServerScriptService` | Server only | Server `Script`s and server-only ModuleScripts (game logic, data, anti-cheat). |
| `ServerStorage` | Server only | Server-only assets: maps, NPC templates, tools to clone, secrets-adjacent config. |
| `ReplicatedStorage` | Both | Shared modules (types, config, pure utils), `RemoteEvent`s, assets clients clone. |
| `ReplicatedFirst` | Client, first | Loading screen only. Replicates before everything else. |
| `StarterPlayer.StarterPlayerScripts` | Client (copied once to `PlayerScripts`) | Client entry point and controllers. |
| `StarterPlayer.StarterCharacterScripts` | Client (copied per spawn into character) | Per-character client scripts (rarely needed). |
| `StarterGui` | Client (copied to `PlayerGui`) | `ScreenGui`s. Set `ResetOnSpawn = false` unless you want reset on death. |
| `Workspace` | Both (streamed to clients) | The 3D world only. Not a place for code or templates. |
| `Lighting`, `SoundService`, `Teams`, `TextChatService` | Both | Their respective config objects. |

Rules:
- Code in `ReplicatedStorage` is **downloadable by exploiters**. Never put server logic, secrets,
  admin lists, or anti-cheat thresholds there.
- `Script.RunContext`: `Legacy` (default: behavior depends on the container), `Server`, `Client`, or
  `Plugin`. A non-Legacy RunContext makes a `Script` run **regardless of container** (e.g. a `Client`
  Script in `ReplicatedStorage` runs on every client) — so templates you clone must not contain such
  scripts unintentionally. Legacy `Script`s don't run in `ReplicatedStorage`/`ServerStorage`.

## Project layout (Rojo-style, recommended)

```text
src/
  server/            -> ServerScriptService.Server   (init.server.luau = entry point)
    Services/        -> one ModuleScript per system (DataService, CombatService, ...)
  client/            -> StarterPlayer.StarterPlayerScripts.Client (init.client.luau)
    Controllers/     -> one ModuleScript per client system (InputController, UIController, ...)
  shared/            -> ReplicatedStorage.Shared (types, config, pure logic, network definitions)
Packages/            -> ReplicatedStorage.Packages (Wally/pesde dependencies)
ServerPackages/      -> ServerScriptService.ServerPackages
```

One entry script per side, everything else is a ModuleScript. This gives deterministic load order,
testable modules, and a single place to wire dependencies. Roblox's own recommendation is equivalent:
one `Script` (`RunContext = Server`) in `ServerScriptService` and one `Script` (`RunContext = Client`) in
`ReplicatedStorage`, each requiring modules and calling their `start()`. Tooling setup: `roblox-tooling`.

## Bootstrapping services (no framework needed)

```luau
--!strict
-- ServerScriptService/Server/init.server.luau
type Service = {
	init: ((self: Service) -> ())?, -- sync setup; may reference other services; must not yield
	start: ((self: Service) -> ())?, -- runs after every init; may yield / connect events
}

local servicesFolder = script:WaitForChild("Services")
local services: { [string]: Service } = {}

for _, module in servicesFolder:GetChildren() do
	if module:IsA("ModuleScript") then
		services[module.Name] = (require :: any)(module)
	end
end

for name, service in services do
	if service.init then
		debug.setmemorycategory(name)
		service:init()
		debug.resetmemorycategory()
	end
end

for name, service in services do
	if service.start then
		task.spawn(function()
			debug.setmemorycategory(name)
			service:start()
		end)
	end
end
```

- Services reference each other with plain `require` (no cycles) or receive dependencies in `init`.
- The client mirrors this with `Controllers`. Keep names symmetrical (`ShopService` / `ShopController`).
- Frameworks like Knit are unnecessary for this; if a project already uses one, follow its conventions.

## Player and character lifecycle

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

local function onCharacterAdded(player: Player, character: Model)
	local humanoid = character:WaitForChild("Humanoid") :: Humanoid
	humanoid.Died:Once(function()
		print(`{player.Name} died`)
	end)
end

local function onPlayerAdded(player: Player)
	-- Load data first (see roblox-data-stores), then set up character handling.
	if player.Character then
		task.spawn(onCharacterAdded, player, player.Character)
	end
	player.CharacterAdded:Connect(function(character)
		onCharacterAdded(player, character)
	end)
end

local function onPlayerRemoving(player: Player)
	-- Save data, release session locks, clear every table keyed by this player.
	print(`{player.Name} left`)
end

Players.PlayerAdded:Connect(onPlayerAdded)
Players.PlayerRemoving:Connect(onPlayerRemoving)
for _, player in Players:GetPlayers() do -- players who joined before this script connected
	task.spawn(onPlayerAdded, player)
end

game:BindToClose(function()
	-- Server shutdown: flush saves for remaining players (max ~30 s total).
end)
```

- Always handle players/characters that already exist when your code starts.
- Characters respawn: anything bound to a character must be re-created on `CharacterAdded`.
- On the client, character descendants may not exist yet (streaming): `WaitForChild` them.

## Components with CollectionService tags

Tag instances (Studio **Tags** section or `CollectionService:AddTag`) and attach behavior in code.
This scales better than copying scripts into every model and works with streaming because the
added/removed signals fire as instances stream in and out.

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

local TAG = "KillBrick"
local cleanups: { [Instance]: () -> () } = {}

local function onAdded(instance: Instance)
	if not instance:IsA("BasePart") then
		return
	end
	local connection = instance.Touched:Connect(function(hit)
		local humanoid = hit.Parent and hit.Parent:FindFirstChildOfClass("Humanoid")
		if humanoid then
			humanoid.Health = 0
		end
	end)
	cleanups[instance] = function()
		connection:Disconnect()
	end
end

local function onRemoved(instance: Instance)
	local cleanup = cleanups[instance]
	if cleanup then
		cleanup()
		cleanups[instance] = nil
	end
end

CollectionService:GetInstanceAddedSignal(TAG):Connect(onAdded)
CollectionService:GetInstanceRemovedSignal(TAG):Connect(onRemoved)
for _, instance in CollectionService:GetTagged(TAG) do
	task.spawn(onAdded, instance)
end
```

Configure components with **attributes** (`instance:GetAttribute("Damage")`,
`GetAttributeChangedSignal`) instead of `IntValue`/`StringValue` children. Attributes replicate
server → client, are cheaper, and show in the Properties panel.

## Sharing state

| Need | Use |
| --- | --- |
| Small per-instance/per-player values visible to clients | Attributes on the instance / `Player` (server sets). |
| Events and requests | `RemoteEvent` / `UnreliableRemoteEvent` (see `roblox-networking`). |
| Large or per-player private state (inventory, quests) | Server-owned tables + remotes that send snapshots/diffs to that player only. |
| Same-side communication | Module function calls or a typed Signal module — not `BindableEvent`, `_G`, or `shared`. |
| Persistent data | `roblox-data-stores`. Cross-server: MessagingService / MemoryStore. |

## Streaming (on by default for new places)

With `Workspace.StreamingEnabled`, clients only have nearby parts. Client code must:
- `WaitForChild` (with a timeout when it may never arrive) or nil-check anything in `Workspace`.
- Use `ModelStreamingMode = Atomic` for models whose parts scripts need together;
  `Persistent` only when a model must always be present (costs memory).
- Treat `GetChildren`, raycasts, and property reads of streamed-out parts as partial/stale; do full-world
  queries on the server.
- Pre-stream destinations on the server with `player:RequestStreamAroundAsync(position)` before teleporting a character.
- Scopes, racing, free cameras: `player.FrustumStreaming = Enum.FrustumStreamingMode.Automatic` streams what
  the camera sees instead of raising the radius.

Full pattern catalog and recommended Workspace settings: [references/streaming.md](references/streaming.md).

## Anti-patterns

- Dozens of loose `Script`s inside parts/models (use tags + one service).
- Polling loops (`while task.wait(0.1) do check() end`) instead of events or `Heartbeat` with `deltaTime`.
- Trusting the client for game state, or firing remotes every frame.
- `_G`/`shared` globals, circular requires, yielding at module top level.
- Cloning maps into `Workspace` from the client (client-only copies never get server updates).
- Storing per-player data in the character (it's destroyed on death).

Library ecosystem (signals, cleanup, networking, UI, ECS, data): [references/ecosystem.md](references/ecosystem.md).

## Related skills

`roblox-networking`, `roblox-security`, `roblox-data-stores`, `roblox-tooling`, `roblox-performance`, `roblox-game-systems`.

© EL4CTEO · MIT · EL4CTEO/roblox-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

roblox-architecture by other authors comes first.

roblox-architecture TabooHarmony roblox-architecture works out who owns each behavior in a Roblox project, where the client-server line sits, and why startup order breaks. CX Codex +1 3,500installs scenario-roblox-architecture scenario-labs The scenario-roblox-architecture Claude Code skill structures Roblox game code and helps diagnose script and module issues. It covers project layout, system communication, and cleanup when connections or character lifetimes cause bugs. CX Codex +1 349installs roblox-luau gamedev-skills This Claude Code skill helps write Roblox Luau and run project checks. It activates for a LocalScript that will not run, a client-side nil after joining, or legacy wait() calls. CX Codex +1 12,300installs roblox-datastores gamedev-skills A skill for Claude Code automates Roblox DataStoreService persistence, profile loading, and conflict prevention. Use it when player data goes missing or items duplicate after teleportation. CX Codex +1 11,400installs roblox-animation-vfx TabooHarmony roblox-animation-vfx — a skill that helps your coding agent write and fix Roblox animations, particles, beams, trails and tweens. CX Codex +1 4,200installs roblox-building TabooHarmony roblox-building — a skill for building geometry, maps and props in Roblox Studio through MCP or plain Luau. It keeps you from guessing coordinates and pushes each build to a verifiable result. CX Codex +1 4,200installs roblox-game-development greedychipmunk roblox-game-development — a skill that turns the agent into a Roblox developer: Luau scripts, game systems, UI and monetization, from a first script to a multiplayer game. CX Codex +1 2,400installs

From the same set22

The whole set →
roblox-npc-ai The roblox-npc-ai Claude Code skill helps build AI for Roblox enemies, pets, and other NPCs. It covers pathfinding, chasing, attacks, and fixes for NPCs that get stuck or jitter. CX Codex +1 1,200installs roblox-teleport-matchmaking roblox-teleport-matchmaking — a skill for Claude Code handles player teleports and matchmaking flows in Roblox via TeleportService. CX Codex +1 1,200installs roblox-input roblox-input — a Claude Code skill for Roblox player controls and cameras. It comes into play when adding keybinds, abilities, vehicle controls, touch buttons, or a custom camera. CX Codex +1 1,200installs roblox-analytics-liveops roblox-analytics-liveops — a skill for Claude Code sets up game analytics, funnels, economy, and live ops for Roblox. Runs when instrumenting gameplay, economy tuning, or setting up A/B tests. CX Codex +1 1,200installs roblox-audio The roblox-audio Claude Code skill covers sound in Roblox, from music and effects to spatial audio. It activates for audio setup or when a sound fails to play. CX Codex +1 1,200installs roblox-networking roblox-networking — a Claude Code skill for client-server communication in Roblox, helping configure remotes, validate server payloads, and reduce bandwidth. CX Codex +1 1,200installs roblox-data-stores roblox-data-stores — a Claude Code skill for Roblox persistence and cloud services. It covers player saves, leaderboards, queues, and fixes for lost or duplicated data. CX Codex +1 1,200installs roblox-studio-mcp Skill connects an AI agent to the built-in Roblox Studio MCP server for editing and playtesting games. CX Codex +1 1,200installs

Project sponsors

Companies that keep this analytics open