Roblox

roblox

Engine API Reference (always the source of truth for classes/properties): https://create.roblox.com/docs/reference/engine

Full documentation indexes for agents:

• https://create.roblox.com/docs/llms.txt (start here, then route to Engine vs Open Cloud sub-indexes)
• Engine-specific: https://create.roblox.com/docs/reference/engine/llms.txt

This hub skill exists because individual topics are deep and interconnected. It gives you the big picture, decision frameworks, and explicit pointers (with relative file paths) into the specialized skills' references/ folders so agents can load only the exact detailed material needed.

When to Activate

Any mention of Roblox, Luau scripting inside experiences, building places, characters, UI/HUD/menus, saving data, animations, particles/effects, gamepasses/shops/monetization, services, client-server code, or "make this look good / feel responsive / be secure".

The sub-skills have very specific descriptions for precise activation. This hub is the safe default when the task is broad Roblox development.

The Specialized Skills (with direct references)

Load the full specialized SKILL.md when the task narrows. Then follow its "Read references/xxx.md for details" instructions for granular depth.

• Data persistence (datastores of all types, limits, versioning, safe patterns, leaderboards, manager/observability): roblox-datastores/SKILL.md

Its references/ cover types-of-datastores.md, core-operations-and-patterns.md, limits-quotas-throttling-error-codes.md, versioning-metadata-recovery.md, best-practices-and-gotchas.md (listing/caching/advanced profiles covered in these and the main SKILL.md).

• Animation & tweening (3D rigs/Animator/Tracks/IK/markers + all UI and 3D tweening with TweenService, easing, sequences, typewriter, integration): roblox-animation/SKILL.md

Its references/ cover 3d-animations.md, ui-tweens-and-sequences.md, integration-and-events.md (IK and TweenService details in 3d-animations and ui-tweens).

• User interfaces (containers, positioning, interaction, and "particles in the UI" techniques): roblox-user-interfaces/SKILL.md

Its references/ cover gui-containers.md, particles-in-ui.md. scripts/UIParticlePool.lua is a 2D UI particle burst example.

• Monetization & gamepasses (creation, selling flow, ownership + purchase finished handlers, rules/policy changes, secure granting): roblox-gamepasses/SKILL.md

Its references/ expand on creation-and-setup.md, purchase-flow-and-granting.md, rules-policies-and-security.md, policyservice.md (per-player policy gating: ArePaidRandomItemsRestricted, IsEligibleToPurchaseSubscription, China policies, trade rules), subscriptions.md (recurring monthly benefits: GetUserSubscriptionStatusAsync, PromptSubscriptionPurchase, UserSubscriptionStatusChanged, payout rules, migration from passes).

• Visual effects & particles (full ParticleEmitter mastery + Beams/Trails/Highlight, performance, flipbooks, shapes, marker integration): roblox-vfx/SKILL.md

Its references/ cover particle-emitter-properties.md, shapes-flipbooks-and-advanced.md.

• Core services, Luau types, and architecture (every important service, Luau primitives + tables/enums/metatables/queues/stacks, type checking, serialization, script locations, no runtime FS reality, data model): roblox-core/SKILL.md

Its references/ break down services-catalog-and-usage.md, luau-data-types-and-serialization.md, script-locations-contexts-and-architecture.md. Hub-level architecture principles live in references/architecture-principles.md.

• Client-server networking and security (remotes vs bindables, authority, network ownership, exploits & defenses, capabilities, secure data/monetization flows): roblox-networking/SKILL.md

Its references/ cover remote-and-bindable-patterns.md, server-authority-and-validation.md, exploits-and-defenses.md. Cross-skill secure flows are covered in references/cross-skill-integration.md.

• Roblox Studio MCP server (connect AI agents to Studio via MCP, Script Sync, tool reference, security/troubleshooting): roblox-mcp/SKILL.md

Its references/ cover setup-and-connection.md, tool-reference.md, script-sync-integration.md, security-and-troubleshooting.md. Diagnostic scripts are in scripts/MCPReadyChecker.lua and scripts/StudioModelProbe.lua.

• Physics and constraints (rigid bodies, assemblies, mechanical/mover constraints, network ownership, collisions, sleep system, adaptive timestepping, units, vehicles, mechanisms): roblox-physics/SKILL.md

Its references/ cover mechanical-constraints.md, mover-constraints.md, network-ownership.md, collisions-and-filtering.md, units-and-physical-properties.md. Example scripts are in scripts/VehicleController.lua, scripts/DoorHinge.lua, scripts/PlatformMover.lua, and scripts/Suspension.lua.

• Pathfinding and NPCs (PathfindingService, modifiers/links, waypoint following, state machines, patrol/chase/follow, streaming, performance at scale): roblox-npcs/SKILL.md

Its references/ cover pathfinding-service-details.md, modifiers-links-and-streaming.md, npc-behavior-patterns.md, performance-and-scaling.md. Example scripts are in scripts/NPCPathFollower.lua, scripts/PatrolBehavior.lua, and scripts/PathfindingUtility.lua.

• Testing and debugging (Developer Console, MicroProfiler, Scene Analysis, Script Profiler, logging, pcall, unit tests, common bugs and fixes): roblox-testing/SKILL.md

Its references/ cover testing-patterns.md, debugging-tools.md, performance-profiling.md, common-bugs-and-fixes.md. Example scripts are in scripts/TestRunner.lua, scripts/Logger.lua, and scripts/DebugDraw.lua.

• Audio (modern modular audio graph: AudioPlayer, AudioEmitter, AudioListener, AudioDeviceOutput/Input, Wire, TTS/STT, effects; legacy Sound/SoundGroup; 2D vs 3D; acoustic simulation; performance; asset permissions): roblox-audio/SKILL.md

Its references/ cover audio-effects.md, audio-graph-vs-sound.md. Example script in scripts/AudioBus.lua.

• Open Cloud (REST API for Roblox resources from outside the engine or via HttpService: API keys/OAuth2, data & memory stores, assets, universes/places, users, groups, subscriptions, webhooks, in-experience calling, rate limits, security): roblox-open-cloud/SKILL.md

Its references/ cover auth-and-keys.md, calling-from-in-experience.md. Example script in scripts/OpenCloudRequest.lua.

• TeleportService and multi-place (TeleportAsync, TeleportOptions, TeleportAsyncResult, ReserveServerAsync, reserved servers, matchmaking patterns, DataStore handoff, cross-experience teleports, teleport data, custom loading screens, security, Studio limitation): roblox-teleport/SKILL.md

Its references/ cover teleport-options.md, matchmaking.md. Example script in scripts/TeleportHelper.lua.

Overarching Principles (apply to everything)

1. Server authority first. Validate or simulate on the server. Client is for input, prediction, and cosmetics. 2. Everything that talks to the cloud is fallible. Wrap DataStore, Marketplace, Http, etc. calls in pcall. Have a plan for transient vs permanent errors. 3. Preload assets. ContentProvider:PreloadAsync for animations, images, sounds, models. 4. Use modern APIs. Animator + LoadAnimation, task. scheduler, TweenService, IKControl, CollectionService tags, Attributes, etc. Avoid deprecated BodyMovers, wait/spawn/delay, Humanoid:LoadAnimation, etc. 5. Respect limits. DataStore budgets scale with concurrent users but are still finite. Particles and transparent UI are fill-rate expensive. Profile early. 6. Structure for maintainability. ServerScriptService for authority, ReplicatedStorage for shared modules, StarterGui for client UI roots, clear module boundaries, consistent naming. 7. Test the hard parts. Studio with API access only on test places. Multiple device classes. Low graphics quality for effects/UI. Concurrency (multiple servers touching the same keys). 8. Progressive disclosure & references.* The sub-skills are deliberately split so the agent only loads the exact deep material it needs. Follow the "read references/xxx.md" pointers inside each specialized skill.

Quick Reference Patterns (hub level)

See the individual skills for full versions with error handling.

Service acquisition:

--!strict
local TweenService: TweenService = game:GetService("TweenService")
local DataStoreService: DataStoreService = game:GetService("DataStoreService")
local MarketplaceService: MarketplaceService = game:GetService("MarketplaceService")
local RunService: RunService = game:GetService("RunService")

Safe datastore (see roblox-datastores skill for the full SafeDataStore wrapper in its scripts/):

--!strict
-- assumes `store`, `key`, `newValue`, `userIds`, and `metadata` are already in scope
local success: boolean, value: any, keyInfo: DataStoreKeyInfo? = pcall(function(): (any, DataStoreKeyInfo?)
    return store:UpdateAsync(key, function(current: any, info: DataStoreKeyInfo?): (any, {number}?, {[string]: any}?)
        -- pure transform, no yielding
        return newValue, userIds, metadata
    end)
end)

Modern animation play:

--!strict
-- Player characters: the engine creates the Animator; load animations client-side.
-- For local NPCs/rigs without one, create the Animator once and reuse it.
local humanoid: Humanoid = (script.Parent :: Instance):WaitForChild("Humanoid") :: Humanoid
local animator: Animator = humanoid:WaitForChild("Animator") :: Animator
local animInstance: Animation = script:WaitForChild("Animation") :: Animation
local track: AnimationTrack = animator:LoadAnimation(animInstance)
track:Play(0.1, 1, 1)
track:GetMarkerReachedSignal("MarkerName"):Connect(function(param: string)
    -- spawn effect, play sound, start tween, etc.
end)

UI tween (scale + AnchorPoint):

--!strict
local TweenService: TweenService = game:GetService("TweenService")
local obj: GuiObject = (script.Parent :: Instance) :: GuiObject
obj.AnchorPoint = Vector2.new(0.5, 0.5)
TweenService:Create(obj, TweenInfo.new(0.3, Enum.EasingStyle.Quad, Enum.EasingDirection.Out), {
    Size = UDim2.fromScale(1.1, 1.1)
} :: { [string]: any }):Play()

Purchase flow (see gamepasses skill):

• Client prompts only.
• Server grants in PromptGamePassPurchaseFinished and re-verifies on PlayerAdded.

Audio:

• Modern audio uses AudioPlayer + AudioEmitter + AudioDeviceOutput (the new audio graph API).
• Legacy Sound objects still work but are the older API.

Modern API notes

• Deferred events: Set Workspace.SignalBehavior = Enum.SignalBehavior.Deferred (or use the corresponding project setting) so events queue and flush, avoiding re-entrancy issues.
• Chat: Use TextChatService for modern chat; the legacy Chat service still exists but is the older API.
• MemoryStore: Use MemoryStoreService for cross-server, short-lived, or high-throughput data, not regular DataStores.
• Parallel Luau: Use Actor instances and task.synchronize() / task.desynchronize() for compute-heavy work, with careful shared-state rules.
• buffer type: Use the buffer Luau type for compact binary data, serialization, and bit/byte manipulation.
• UI safe zones: Use ScreenGui.ScreenInsets and related properties to respect device notches and safe areas.
• ConfigService: Use a centralized configuration system (commonly a custom ConfigService module or Configuration instances) for live configuration and feature flags.

How to Work Effectively With This Toolset

1. Start with this hub + roblox-core if the task is broad. 2. Activate the most specific sub-skill(s) that match the request. 3. Inside the sub-skill, follow the explicit "Read references/..." instructions for the exact sub-topic. 4. Load the referenced .md file(s) for the deep tables, code samples, decision trees, and gotchas. 5. Use the scripts/ examples as starting points (adapt the SafeDataStore wrapper, particle pools, animation loaders, etc.). 6. Cross-link: datastores + networking for secure persistence; animation + vfx + UI for synchronized VFX; gamepasses + datastores for perk application; etc. 7. When in doubt, fall back to the Engine API reference and the llms.txt indexes.

This collection is intentionally deeper and more structured than generic "Roblox scripting" advice precisely because current models have gaps in the current Roblox API surface, limits details, modern patterns (Animator, IKControl, full DataStore v2, configurable rate limits, ViewportFrame previews for 3D UI — note ViewportFrame does not render ParticleEmitter, Beam, Trail, or most 3D effects, etc.), and security realities.

Use it, follow the references, and the resulting code will be correct, efficient, secure, and maintainable.

Overarching Roblox Architecture & Development Principles

This reference collects the cross-cutting principles that apply no matter which specialized skill (data, UI, animation, etc.) you are using.

Server Authority as Default Posture

• The server decides outcomes for anything that affects shared state, economy, progression, or competitive fairness.
• Client sends intent ("I want to buy this", "I attacked with this swing").
• Server validates (range, timing, cost, line of sight, cooldowns, etc.) then either applies the change (and lets replication or a targeted Remote carry the result) or rejects it.
• Replicated display values such as leaderstats are visible to clients, but they remain authoritative on the server and are commonly used to drive server logic. Update them from the server result and never trust the client version for logic.

Progressive Data Loading & Saving

• On join: load from DataStore (with pcall + fresh read option after previous errors), merge defaults, re-verify ownership on PlayerAdded (gamepasses, etc.), sync safe derived state to client.
• During play: mutate in-memory profile, periodic auto-saves + immediate saves on important events using UpdateAsync for contended values.
• On leave / BindToClose: final save.
• Always have a plan for "the write appeared to fail but might have succeeded on the backend" — verify with UseCache=false Get.

Asset & Code Loading Discipline

• Preload animations, sounds, images, important models via ContentProvider:PreloadAsync early in the loading sequence.
• Use WaitForChild when requiring modules or waiting for services/children whose load order is not guaranteed.
• Structure: ReplicatedStorage for shared pure modules + asset containers, ServerScriptService for server authority, StarterGui for client UI roots (with LocalScripts or required client modules).

Performance Mindset

• Transparent overdraw and fill-rate (lots of overlapping particles + UI) is the #1 mobile/GPU killer.
• Instance count, part count, and streaming matter for world performance.
• Tween many things or play many complex animations at once? Profile.
• Use the lowest sufficient animation priority, particle rate, and UI transparency layers.
• Test at both lowest and highest graphics quality in Studio.

Organization That Scales

• One data store (or small number) per major domain with key prefixes for organization, rather than hundreds of tiny stores.
• Consistent key naming (e.g. "PlayerData_" .. userId or "Profiles/" .. userId).
• Module boundaries that mirror the skills (DataManager, UIManager, AnimationManager, Economy, etc.).
• Tags (CollectionService) and Attributes for lightweight dynamic grouping instead of deep fragile hierarchies.

Security Basics (applies everywhere)

• No client datastore writes or economy logic.
• All Marketplace prompts on client; all granting on server with re-verification.
• Rate limit sensitive Remotes with per-player buckets; track timestamps/counters per Player.UserId, not shared globals.
• Sanitize and validate all input: type checks, range checks, whitelist allowed values, reject malformed payloads before processing.
• Filter user-generated text with TextService:FilterStringAsync / TextFilterResult before displaying it anywhere.
• Keep HttpService secrets and API keys server-side; use SecretsService to store and retrieve them instead of embedding in scripts.
• Keep confidential data and anti-cheat parameters server-side; minimize client anti-cheat and assume the client is compromised.
• Audit third-party assets.
• Use capabilities where available.

Testing & Deployment Hygiene

• Studio "Enable Studio Access to API Services" only on dedicated test experiences, never production.
• Use multiple places or a staging universe for testing data changes.
• Take snapshots before risky publishes that touch data logic.
• Monitor Data Stores Dashboard + Manager + general performance stats after every meaningful update.

When to Reach for Each Specialized Skill

• Anything that reads or writes persistent state across sessions → roblox-datastores skill (and its references/).
• Motion, character actions, or UI transitions → roblox-animation (and its references/).
• Any 2D interface, HUD, menu, or "particle" effect inside UI → roblox-user-interfaces (and its references/, especially particles-in-ui.md).
• Robux purchases, passes, or shops → roblox-gamepasses.
• Fire, smoke, sparks, trails, or other 3D world VFX → roblox-vfx.
• "How do I even structure this?" or "which service?" or "what can I actually store?" → roblox-core.
• "Is this safe on the client?" or "how do I securely call from client to server?" → roblox-networking.

Follow the file references inside each specialized skill. The depth is there when you need it; the hub keeps you from getting lost.

Cross-Skill Integration Patterns

The power of this toolset comes from combining the skills rather than using them in isolation.

Data + Client-Server + Monetization

• Client prompts purchase (roblox-gamepasses skill).
• Server receives PromptGamePassPurchaseFinished, validates, grants perks, and immediately saves ownership + perks via your data manager (roblox-datastores skill).
• On every PlayerAdded, re-verify with UserOwnsGamePassAsync (monetization) and load profile (data), then apply benefits.
• All sensitive Remotes that touch money or perks go through validation + rate limiting (roblox-networking skill).

Animation + Particles + UI

• Animation marker "AbilityCast" fires (animation skill).
• Handler spawns a 3D particle burst at a rig Attachment (roblox-vfx skill).
• Same handler or a follow-up tween starts a UI cooldown ring or floating text using CanvasGroup + tweens (roblox-user-interfaces + roblox-animation skills).
• For 3D previews in a shop UI, use a ViewportFrame containing a rig model (note that ViewportFrame does not render ParticleEmitter, Beam, Trail, or most 3D effects; use 2D UI particles for overlay effects instead) (user-interfaces particles-in-ui reference).

roblox-core + Everything

roblox-core is the base layer. Every other skill assumes you:

• Acquire services correctly with GetService.
• Know which code runs on client vs server.
• Understand what data can actually be stored in DataStores.
• Use proper module loading and initialization patterns.

Load roblox-core first when the task is broad.

Performance Across Skills

• Heavy animation + many particles + lots of transparent UI = mobile killer.
• Use the performance notes in each skill (especially particles and UI).
• Profile with Developer Console + MicroProfiler.
• Prefer fewer, well-tuned effects over many cheap-looking ones.

Follow the file references inside each skill for the detailed "how" while using this hub for the "when and why to combine them".