roblox-lessons
Skill2 starsChanged 29 days agoMITView on GitHub
Hard-won Roblox/Luau gotchas from shipping real games with AI-driven development — UI layout traps (TextScaled, GuiInset, canvas sizing, aspect constraints, phone controls), Studio MCP and Rojo quirks, saving and migrations, purchases and paid-random-items policy, Open Cloud API limits, imported assets, particles and meshes, economy design. Use for ANY Roblox game work in Luau/Rojo before building or debugging UI, saving, monetization, Studio verification, publishing, or calling the Open Cloud API.
In this repository19 other files it gives its agents.
- template/CLAUDE.mdCLAUDE.md
- audio-designSkill
- game-feelSkill
- game-ui-uxSkill
- level-designSkill
- roblox-creator-store-security-auditSkill
- roblox-dataSkill
- roblox-debugging-bugfixSkill
- roblox-devSkill
- roblox-monetizationSkill
- roblox-networkingSkill
- roblox-publish-checklistSkill
- roblox-release-operationsSkill
- roblox-security-economySkill
- roblox-securitySkill
- roblox-studio-mcpSkill
- roblox-to-issuesSkill
- roblox-toolingSkill
- save-systemsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
When a game teaches a new lesson, add it to the right reference file (and to the top ten if it bites hard).
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Roblox lessons (from shipped games)
Facts below were each learned by breaking something. They override generic advice, including other skills. Read the matching reference file before working in that area.
The ten that bite most often
TextWrapped = falseafterTextScaled = trueturns TextScaled off. Set TextScaled last. →references/ui.mdAbsolutePositionis always measured from below the top bar (~58 px on phones), even inIgnoreGuiInsetguis. Screen Y = AbsolutePosition.Y + inset. →references/ui.mdAutomaticCanvasSizeundercounts rows sized byUIAspectRatioConstraint, cutting off the end of lists. Size the canvas fromUIListLayout.AbsoluteContentSize. →references/ui.md- Never rename a DataStore to change the save format — that's a new empty store (everyone's progress gone). Migrate step by step instead. →
references/data.md - Purchases: one receipt handler, dedupe by
PurchaseIdstored in the player's own save,NotProcessedYetwhenever unsure. →references/monetization.md - Coins buyable with Robux make every coin-funded random roll a paid random item: odds before purchase +
PolicyService.ArePaidRandomItemsRestrictedgating. →references/monetization.md shared.*read from MCPexecute_luauis a sandbox, not the game's. Use a temporary Script to call real server APIs. →references/studio-mcp.md- Kicking the only player during Play start wedges the MCP's Play button until Play/Stop is pressed by hand in Studio. →
references/studio-mcp.md - Open Cloud API keys can create passes/products and edit the game page, but can't make a game public, upload thumbnails, or create badges without a spend-Robux scope. →
references/open-cloud.md - Third-party models with any script are rejected outright (backdoors are common). →
references/assets-visuals.md
Sharing with the hub
These lessons and the reusable systems live in the public roblox-hub repo (usually next to the game as ../roblox-hub; github.com/rodrigo-guerraa/roblox-hub). When a game builds something reusable and not proprietary (a generic system, a template improvement, a new gotcha), say so once the feature is verified, and port it after the maintainer agrees, following the hub's CONTRIBUTING.md: what qualifies, what stays in the game, the quality bar and the process (scripts/check.sh, Studio verification in the hub's sandbox, clean commits, pushes only with a go-ahead).
Reference files
| File | Covers |
references/ui.md | Text scaling, insets, canvas sizing, aspect constraints, layering, phone controls, fonts, live-updating lists |
references/studio-mcp.md | Driving Studio through the MCP: contexts, Play, prompts, screenshots, emulator, multi-client, Rojo sync |
references/data.md | ProfileStore, Studio-only stores, migrations, initial-sync remotes, reading live saves |
references/monetization.md | Receipts, passes vs products, pricing, paid random items, ownership gotchas |
references/open-cloud.md | What API keys can and can't do, exact endpoints and scopes, key handling |
references/assets-visuals.md | Safe imports, textured meshes, pivots, particles in daylight, auras |
references/economy.md | Income-scaled rewards, sinks, pacing, exploit-proof product ladders |
references/ai-workflow.md | Habits that keep AI development honest: verification, tooling traps, untrusted content |
When a game teaches a new lesson, add it to the right reference file (and to the top ten if it bites hard).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.