roblox-opencode 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/README.md +112 -122
  2. package/commands/setup-game.md +108 -108
  3. package/commands/sync-check.md +53 -53
  4. package/core/roblox-core.md +93 -93
  5. package/dist/server.js +189 -167
  6. package/package.json +35 -35
  7. package/skills/roblox-analytics/SKILL.md +277 -277
  8. package/skills/roblox-analytics/references/event-batcher.luau +75 -75
  9. package/skills/roblox-animation-vfx/SKILL.md +1325 -1325
  10. package/skills/roblox-architecture/SKILL.md +863 -863
  11. package/skills/roblox-architecture/references/combat-systems.md +1381 -1381
  12. package/skills/roblox-code-review/SKILL.md +686 -686
  13. package/skills/roblox-data/SKILL.md +889 -889
  14. package/skills/roblox-data/references/inventory-systems.md +1729 -1729
  15. package/skills/roblox-debug/SKILL.md +98 -98
  16. package/skills/roblox-gui/SKILL.md +1103 -1103
  17. package/skills/roblox-gui-fusion/SKILL.md +150 -150
  18. package/skills/roblox-gui-fusion/references/inventory.luau +427 -427
  19. package/skills/roblox-gui-fusion/references/settings-menu.luau +579 -579
  20. package/skills/roblox-gui-fusion/references/shop.luau +411 -411
  21. package/skills/roblox-luau-mastery/SKILL.md +1519 -1519
  22. package/skills/roblox-monetization/SKILL.md +1084 -1084
  23. package/skills/roblox-monetization/references/process-receipt.luau +131 -131
  24. package/skills/roblox-networking/SKILL.md +669 -669
  25. package/skills/roblox-networking/references/remote-validator.luau +193 -193
  26. package/skills/roblox-publish-checklist/SKILL.md +127 -127
  27. package/skills/roblox-runtime/SKILL.md +753 -753
  28. package/skills/roblox-sharp-edges/SKILL.md +294 -294
  29. package/skills/roblox-sync/SKILL.md +126 -126
  30. package/skills/roblox-testing/SKILL.md +943 -943
  31. package/skills/roblox-tooling/SKILL.md +149 -149
  32. package/vendor/LICENSES/ProfileStore-LICENSE +201 -201
  33. package/vendor/LICENSES/RbxUtil-LICENSE +7 -7
  34. package/vendor/LICENSES/promise-LICENSE +20 -20
  35. package/vendor/LICENSES/t-LICENSE +21 -21
  36. package/vendor/LICENSES/testez-LICENSE +200 -200
  37. package/vendor/README.md +83 -83
  38. package/vendor/fusion/Animation/ExternalTime.luau +83 -83
  39. package/vendor/fusion/Animation/Spring.luau +321 -321
  40. package/vendor/fusion/Animation/Stopwatch.luau +127 -127
  41. package/vendor/fusion/Animation/Tween.luau +187 -187
  42. package/vendor/fusion/Animation/getTweenDuration.luau +27 -27
  43. package/vendor/fusion/Animation/getTweenRatio.luau +47 -47
  44. package/vendor/fusion/Animation/lerpType.luau +163 -163
  45. package/vendor/fusion/Animation/packType.luau +99 -99
  46. package/vendor/fusion/Animation/springCoefficients.luau +80 -80
  47. package/vendor/fusion/Animation/unpackType.luau +102 -102
  48. package/vendor/fusion/Colour/Oklab.luau +70 -70
  49. package/vendor/fusion/Colour/sRGB.luau +54 -54
  50. package/vendor/fusion/External.luau +167 -167
  51. package/vendor/fusion/ExternalDebug.luau +69 -69
  52. package/vendor/fusion/Graph/Observer.luau +113 -113
  53. package/vendor/fusion/Graph/castToGraph.luau +28 -28
  54. package/vendor/fusion/Graph/change.luau +80 -80
  55. package/vendor/fusion/Graph/depend.luau +32 -32
  56. package/vendor/fusion/Graph/evaluate.luau +55 -55
  57. package/vendor/fusion/Instances/Attribute.luau +57 -57
  58. package/vendor/fusion/Instances/AttributeChange.luau +46 -46
  59. package/vendor/fusion/Instances/AttributeOut.luau +63 -63
  60. package/vendor/fusion/Instances/Child.luau +21 -21
  61. package/vendor/fusion/Instances/Children.luau +147 -147
  62. package/vendor/fusion/Instances/Hydrate.luau +32 -32
  63. package/vendor/fusion/Instances/New.luau +52 -52
  64. package/vendor/fusion/Instances/OnChange.luau +49 -49
  65. package/vendor/fusion/Instances/OnEvent.luau +53 -53
  66. package/vendor/fusion/Instances/Out.luau +69 -69
  67. package/vendor/fusion/Instances/applyInstanceProps.luau +148 -148
  68. package/vendor/fusion/Instances/defaultProps.luau +194 -194
  69. package/vendor/fusion/LICENSE +21 -21
  70. package/vendor/fusion/Logging/formatError.luau +48 -48
  71. package/vendor/fusion/Logging/messages.luau +51 -51
  72. package/vendor/fusion/Logging/parseError.luau +24 -24
  73. package/vendor/fusion/Memory/checkLifetime.luau +133 -133
  74. package/vendor/fusion/Memory/deriveScope.luau +23 -23
  75. package/vendor/fusion/Memory/deriveScopeImpl.luau +44 -44
  76. package/vendor/fusion/Memory/doCleanup.luau +78 -78
  77. package/vendor/fusion/Memory/innerScope.luau +33 -33
  78. package/vendor/fusion/Memory/legacyCleanup.luau +17 -17
  79. package/vendor/fusion/Memory/needsDestruction.luau +16 -16
  80. package/vendor/fusion/Memory/poisonScope.luau +33 -33
  81. package/vendor/fusion/Memory/scopePool.luau +54 -54
  82. package/vendor/fusion/Memory/scoped.luau +26 -26
  83. package/vendor/fusion/Memory/whichLivesLonger.luau +74 -74
  84. package/vendor/fusion/RobloxExternal.luau +97 -97
  85. package/vendor/fusion/State/Computed.luau +138 -138
  86. package/vendor/fusion/State/For/Disassembly.luau +210 -210
  87. package/vendor/fusion/State/For/ForTypes.luau +30 -30
  88. package/vendor/fusion/State/For/init.luau +109 -109
  89. package/vendor/fusion/State/ForKeys.luau +93 -93
  90. package/vendor/fusion/State/ForPairs.luau +96 -96
  91. package/vendor/fusion/State/ForValues.luau +93 -93
  92. package/vendor/fusion/State/Value.luau +87 -87
  93. package/vendor/fusion/State/castToState.luau +25 -25
  94. package/vendor/fusion/State/peek.luau +30 -30
  95. package/vendor/fusion/Types.luau +314 -314
  96. package/vendor/fusion/Utility/Contextual.luau +90 -90
  97. package/vendor/fusion/Utility/Safe.luau +22 -22
  98. package/vendor/fusion/Utility/isSimilar.luau +29 -29
  99. package/vendor/fusion/Utility/merge.luau +35 -35
  100. package/vendor/fusion/Utility/nameOf.luau +34 -34
  101. package/vendor/fusion/Utility/never.luau +13 -13
  102. package/vendor/fusion/Utility/nicknames.luau +10 -10
  103. package/vendor/fusion/Utility/xtypeof.luau +26 -26
  104. package/vendor/fusion/init.luau +82 -82
  105. package/vendor/profilestore/init.luau +2242 -2242
  106. package/vendor/promise/init.luau +1982 -1982
  107. package/vendor/rbxutil/buffer-util/Buffer.test.luau +25 -25
  108. package/vendor/rbxutil/buffer-util/BufferReader.luau +228 -228
  109. package/vendor/rbxutil/buffer-util/BufferWriter.luau +269 -269
  110. package/vendor/rbxutil/buffer-util/DataTypeBuffer.luau +223 -223
  111. package/vendor/rbxutil/buffer-util/Types.luau +60 -60
  112. package/vendor/rbxutil/buffer-util/index.d.ts +153 -153
  113. package/vendor/rbxutil/buffer-util/init.luau +41 -41
  114. package/vendor/rbxutil/buffer-util/package.json +16 -16
  115. package/vendor/rbxutil/buffer-util/wally.toml +9 -9
  116. package/vendor/rbxutil/comm/Client/ClientComm.luau +232 -232
  117. package/vendor/rbxutil/comm/Client/ClientRemoteProperty.luau +156 -156
  118. package/vendor/rbxutil/comm/Client/ClientRemoteSignal.luau +109 -109
  119. package/vendor/rbxutil/comm/Client/init.luau +135 -135
  120. package/vendor/rbxutil/comm/Server/RemoteProperty.luau +295 -295
  121. package/vendor/rbxutil/comm/Server/RemoteSignal.luau +211 -211
  122. package/vendor/rbxutil/comm/Server/ServerComm.luau +211 -211
  123. package/vendor/rbxutil/comm/Server/init.luau +140 -140
  124. package/vendor/rbxutil/comm/Types.luau +18 -18
  125. package/vendor/rbxutil/comm/Util.luau +27 -27
  126. package/vendor/rbxutil/comm/init.luau +35 -35
  127. package/vendor/rbxutil/comm/wally.toml +13 -13
  128. package/vendor/rbxutil/component/init.luau +759 -759
  129. package/vendor/rbxutil/component/init.test.luau +311 -311
  130. package/vendor/rbxutil/component/wally.toml +14 -14
  131. package/vendor/rbxutil/concur/init.luau +542 -542
  132. package/vendor/rbxutil/concur/init.test.luau +364 -364
  133. package/vendor/rbxutil/concur/wally.toml +8 -8
  134. package/vendor/rbxutil/enum-list/init.luau +101 -101
  135. package/vendor/rbxutil/enum-list/init.test.luau +91 -91
  136. package/vendor/rbxutil/enum-list/wally.toml +8 -8
  137. package/vendor/rbxutil/find/index.d.ts +20 -20
  138. package/vendor/rbxutil/find/init.luau +44 -44
  139. package/vendor/rbxutil/find/package.json +17 -17
  140. package/vendor/rbxutil/find/wally.toml +8 -8
  141. package/vendor/rbxutil/input/Gamepad.luau +559 -559
  142. package/vendor/rbxutil/input/Keyboard.luau +124 -124
  143. package/vendor/rbxutil/input/Mouse.luau +278 -278
  144. package/vendor/rbxutil/input/PreferredInput.luau +91 -91
  145. package/vendor/rbxutil/input/Touch.luau +120 -120
  146. package/vendor/rbxutil/input/init.luau +33 -33
  147. package/vendor/rbxutil/input/wally.toml +12 -12
  148. package/vendor/rbxutil/loader/index.d.ts +15 -15
  149. package/vendor/rbxutil/loader/init.luau +137 -137
  150. package/vendor/rbxutil/loader/wally.toml +8 -8
  151. package/vendor/rbxutil/log/index.d.ts +38 -38
  152. package/vendor/rbxutil/log/init.luau +746 -746
  153. package/vendor/rbxutil/log/wally.toml +8 -8
  154. package/vendor/rbxutil/net/init.luau +190 -190
  155. package/vendor/rbxutil/net/wally.toml +8 -8
  156. package/vendor/rbxutil/option/index.d.ts +44 -44
  157. package/vendor/rbxutil/option/init.luau +489 -489
  158. package/vendor/rbxutil/option/init.test.luau +342 -342
  159. package/vendor/rbxutil/option/wally.toml +8 -8
  160. package/vendor/rbxutil/pid/index.d.ts +53 -53
  161. package/vendor/rbxutil/pid/init.luau +195 -195
  162. package/vendor/rbxutil/pid/package.json +16 -16
  163. package/vendor/rbxutil/pid/wally.toml +9 -9
  164. package/vendor/rbxutil/quaternion/index.d.ts +117 -117
  165. package/vendor/rbxutil/quaternion/init.luau +570 -570
  166. package/vendor/rbxutil/quaternion/package.json +16 -16
  167. package/vendor/rbxutil/quaternion/wally.toml +9 -9
  168. package/vendor/rbxutil/query/index.d.ts +43 -43
  169. package/vendor/rbxutil/query/init.luau +117 -117
  170. package/vendor/rbxutil/query/package.json +18 -18
  171. package/vendor/rbxutil/query/wally.toml +9 -9
  172. package/vendor/rbxutil/sequent/index.d.ts +28 -28
  173. package/vendor/rbxutil/sequent/init.luau +340 -340
  174. package/vendor/rbxutil/sequent/package.json +16 -16
  175. package/vendor/rbxutil/sequent/wally.toml +9 -9
  176. package/vendor/rbxutil/ser/init.luau +175 -175
  177. package/vendor/rbxutil/ser/init.test.luau +50 -50
  178. package/vendor/rbxutil/ser/wally.toml +11 -11
  179. package/vendor/rbxutil/shake/index.d.ts +36 -36
  180. package/vendor/rbxutil/shake/init.luau +532 -532
  181. package/vendor/rbxutil/shake/init.test.luau +267 -267
  182. package/vendor/rbxutil/shake/package.json +16 -16
  183. package/vendor/rbxutil/shake/wally.toml +9 -9
  184. package/vendor/rbxutil/signal/index.d.ts +100 -100
  185. package/vendor/rbxutil/signal/init.luau +432 -432
  186. package/vendor/rbxutil/signal/init.test.luau +190 -190
  187. package/vendor/rbxutil/signal/package.json +17 -17
  188. package/vendor/rbxutil/signal/wally.toml +9 -9
  189. package/vendor/rbxutil/silo/TableWatcher.luau +65 -65
  190. package/vendor/rbxutil/silo/Util.luau +55 -55
  191. package/vendor/rbxutil/silo/init.luau +338 -338
  192. package/vendor/rbxutil/silo/init.test.luau +215 -215
  193. package/vendor/rbxutil/silo/wally.toml +8 -8
  194. package/vendor/rbxutil/spring/index.d.ts +40 -40
  195. package/vendor/rbxutil/spring/init.luau +97 -97
  196. package/vendor/rbxutil/spring/package.json +17 -17
  197. package/vendor/rbxutil/spring/wally.toml +8 -8
  198. package/vendor/rbxutil/stream/index.d.ts +88 -88
  199. package/vendor/rbxutil/stream/init.luau +597 -597
  200. package/vendor/rbxutil/stream/package.json +18 -18
  201. package/vendor/rbxutil/stream/wally.toml +9 -9
  202. package/vendor/rbxutil/streamable/Streamable.luau +202 -202
  203. package/vendor/rbxutil/streamable/StreamableUtil.luau +80 -80
  204. package/vendor/rbxutil/streamable/init.luau +8 -8
  205. package/vendor/rbxutil/streamable/wally.toml +12 -12
  206. package/vendor/rbxutil/symbol/init.luau +56 -56
  207. package/vendor/rbxutil/symbol/init.test.luau +37 -37
  208. package/vendor/rbxutil/symbol/wally.toml +8 -8
  209. package/vendor/rbxutil/table-util/init.luau +938 -938
  210. package/vendor/rbxutil/table-util/init.test.luau +439 -439
  211. package/vendor/rbxutil/task-queue/index.d.ts +27 -27
  212. package/vendor/rbxutil/task-queue/init.luau +97 -97
  213. package/vendor/rbxutil/task-queue/wally.toml +8 -8
  214. package/vendor/rbxutil/timer/index.d.ts +81 -81
  215. package/vendor/rbxutil/timer/init.luau +249 -249
  216. package/vendor/rbxutil/timer/init.test.luau +73 -73
  217. package/vendor/rbxutil/timer/wally.toml +11 -11
  218. package/vendor/rbxutil/tree/index.d.ts +15 -15
  219. package/vendor/rbxutil/tree/init.luau +137 -137
  220. package/vendor/rbxutil/tree/wally.toml +8 -8
  221. package/vendor/rbxutil/trove/index.d.ts +46 -46
  222. package/vendor/rbxutil/trove/init.luau +787 -787
  223. package/vendor/rbxutil/trove/init.test.luau +203 -203
  224. package/vendor/rbxutil/trove/wally.toml +8 -8
  225. package/vendor/rbxutil/typed-remote/init.luau +196 -196
  226. package/vendor/rbxutil/typed-remote/wally.toml +8 -8
  227. package/vendor/rbxutil/wait-for/index.d.ts +17 -17
  228. package/vendor/rbxutil/wait-for/init.luau +257 -257
  229. package/vendor/rbxutil/wait-for/init.test.luau +182 -182
  230. package/vendor/rbxutil/wait-for/wally.toml +11 -11
  231. package/vendor/t/t.lua +1350 -1350
  232. package/vendor/testez/Context.lua +26 -26
  233. package/vendor/testez/Expectation.lua +311 -311
  234. package/vendor/testez/ExpectationContext.lua +38 -38
  235. package/vendor/testez/LifecycleHooks.lua +89 -89
  236. package/vendor/testez/Reporters/TeamCityReporter.lua +101 -101
  237. package/vendor/testez/Reporters/TextReporter.lua +105 -105
  238. package/vendor/testez/Reporters/TextReporterQuiet.lua +96 -96
  239. package/vendor/testez/TestBootstrap.lua +146 -146
  240. package/vendor/testez/TestEnum.lua +27 -27
  241. package/vendor/testez/TestPlan.lua +304 -304
  242. package/vendor/testez/TestPlanner.lua +39 -39
  243. package/vendor/testez/TestResults.lua +111 -111
  244. package/vendor/testez/TestRunner.lua +188 -188
  245. package/vendor/testez/TestSession.lua +243 -243
  246. package/vendor/testez/init.lua +39 -39
@@ -1,93 +1,93 @@
1
- # roblox-opencode Core Block
2
- # Written to AGENTS.md by /setup-game between version markers.
3
- # Budget: ~1.2k tokens. Every line must earn its place.
4
-
5
- ## 1. Sync vs MCP
6
-
7
- 1. Every session: try to read project .luau files at the expected synced paths.
8
- Found → Sync Mode. Not found → MCP-Only Mode.
9
- 2. Sync Mode: read/write/edit scripts via filesystem. Use MCP only for
10
- verification (run_code, execute_luau), playtest control, scene/instance ops.
11
- 3. Sync Mode: never read a script via MCP if its file exists on disk.
12
- 4. MCP-Only Mode: minimize file reads. Prefer run_code for inspection.
13
- Batch related edits behind ChangeHistoryService Recording.
14
- 5. MCP-Only Mode: note that MCP ops are slower and token-hungry. If a session
15
- will be heavy, recommend the user enable Sync.
16
- 6. MCP-Only Mode loses LSP diagnostics entirely (luau-check hooks filesystem
17
- writes only). Surface this when relevant.
18
-
19
- ## 2. Sharp Edges
20
-
21
- | Severity | Issue | Fix |
22
- |----------|-------|-----|
23
- | CRIT | DataStore data loss from no session lock | Use ProfileStore. Never raw SetAsync for player data. |
24
- | CRIT | Client-side currency manipulation | All currency math server-side. Client is display-only. |
25
- | CRIT | ProcessReceipt mishandling (duplicates/refunds) | Grant item THEN return PurchaseGranted. If grant fails, return NotProcessedYet. |
26
- | CRIT | Missing BindToClose | Always implement BindToClose to flush pending saves. |
27
- | HIGH | RemoteEvent flooding | Per-player rate limiting on all remotes. |
28
- | HIGH | Memory leaks from undisconnected events | Use Trove. Every :Connect() must have a corresponding :Disconnect(). |
29
- | HIGH | Assuming instances exist with StreamingEnabled | Check existence before access. Instances may not be loaded yet. |
30
- | MED | Instance.new(class, parent) race | Create first, parent second. Parenting in constructor causes replication race. |
31
- | LOW | :connect typo | It's :Connect() with capital C. |
32
-
33
- ## 3. Capabilities Boundary
34
-
35
- roblox-opencode handles: Luau code, scripts, modules, remotes, data, UI logic, game architecture.
36
- roblox-opencode does NOT handle: 3D model generation, mesh creation, animation authoring, terrain sculpting, pixel-perfect UI design. These are Studio's domain - use blockout Parts with descriptive names and let the user detail visually.
37
-
38
- ## 4. Skill Routing Corrections
39
-
40
- Only for ambiguous cases where two skills overlap:
41
- - streaming/workspace not loaded → roblox-runtime (not roblox-architecture)
42
- - gui/ui layout → roblox-gui (not roblox-architecture)
43
- - data persistence → roblox-data (not roblox-networking)
44
- - remote handler validation → roblox-networking (not roblox-architecture)
45
- - security hardening → roblox-networking (security is folded in)
46
-
47
- For everything else, load the skill whose description best matches the task.
48
- Load the Quick Reference section first. Only load the Full Reference if the task requires specific syntax examples or implementation details.
49
-
50
- ## 5. Asset Trust
51
-
52
- - Never suggest asset IDs. Never recommend free-model code (ModuleScripts, Scripts, LocalScripts).
53
- - Free models OK strictly for art assets (Mesh, Texture, Sound, Animation).
54
- - Before any LoadAsset: walk user through audit - inspect children, check for getfenv/loadstring/HttpService/suspicious RemoteEvents.
55
- - Vendored libraries (ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component) are the only pre-written code the agent may place.
56
-
57
- ## 6. Verification
58
-
59
- Silence means verified. Surface ⚠️ only when verification was NOT possible:
60
- "⚠️ not verified: [thing], [reason]"
61
- Do not prefix verified responses with "Verified: ..." - that noise trains users to stop reading.
62
-
63
- ## 7. Luau-LSP
64
-
65
- - Diagnostics are signal, not authority. On conflict with documented Roblox behavior, prefer documented behavior.
66
- - Never claim "done, test it" with unresolved diagnostics. Either fix them, justify them, or surface ⚠️.
67
- - Diagnostics fire async after each .luau write. The agent reconciles silently.
68
-
69
- ## 8. Tiered Library Policy
70
-
71
- **Vendored libraries** (auto-placed with mention): ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component.
72
- - Agent mentions the choice. User can revert or say "use my own."
73
- - Before auto-placing, query project index for existing equivalents. If found, skip auto-place and mention why.
74
- - Placement mechanic: copy from `.opencode/vendor/<path>` into the project's synced folder. Shared libs → ReplicatedStorage/Packages/. Server-only (ProfileStore) → ServerScriptService/Packages/. Infer sync folder from existing project structure.
75
-
76
- **Vendored tools** (recommended when relevant, not auto-placed): t (runtime type checking), TestEZ (testing).
77
- - Agent recommends when the task involves Remote validation, argument checking, or testing.
78
- - Agent does NOT auto-place - requires user buy-in.
79
-
80
- **Anything else**: full consent. Agent explains, asks via user prompts, places only on yes.
81
-
82
- ## 9. Skill & Command Routing
83
-
84
- When the user's task matches a command or skill, suggest it:
85
- - First-time project setup → /setup-game (command)
86
- - Sync feels broken → /sync-check (command)
87
- - Code review or audit → load roblox-code-review skill
88
- - Debugging → load roblox-debug skill
89
- - Pre-publish check → load roblox-publish-checklist skill
90
-
91
- ## Version
92
-
93
- roblox-opencode 1.0.0
1
+ # roblox-opencode Core Block
2
+ # Written to AGENTS.md by /setup-game between version markers.
3
+ # Budget: ~1.2k tokens. Every line must earn its place.
4
+
5
+ ## 1. Sync vs MCP
6
+
7
+ 1. Every session: try to read project .luau files at the expected synced paths.
8
+ Found → Sync Mode. Not found → MCP-Only Mode.
9
+ 2. Sync Mode: read/write/edit scripts via filesystem. Use MCP only for
10
+ verification (run_code, execute_luau), playtest control, scene/instance ops.
11
+ 3. Sync Mode: never read a script via MCP if its file exists on disk.
12
+ 4. MCP-Only Mode: minimize file reads. Prefer run_code for inspection.
13
+ Batch related edits behind ChangeHistoryService Recording.
14
+ 5. MCP-Only Mode: note that MCP ops are slower and token-hungry. If a session
15
+ will be heavy, recommend the user enable Sync.
16
+ 6. MCP-Only Mode loses LSP diagnostics entirely (luau-check hooks filesystem
17
+ writes only). Surface this when relevant.
18
+
19
+ ## 2. Sharp Edges
20
+
21
+ | Severity | Issue | Fix |
22
+ |----------|-------|-----|
23
+ | CRIT | DataStore data loss from no session lock | Use ProfileStore. Never raw SetAsync for player data. |
24
+ | CRIT | Client-side currency manipulation | All currency math server-side. Client is display-only. |
25
+ | CRIT | ProcessReceipt mishandling (duplicates/refunds) | Grant item THEN return PurchaseGranted. If grant fails, return NotProcessedYet. |
26
+ | CRIT | Missing BindToClose | Always implement BindToClose to flush pending saves. |
27
+ | HIGH | RemoteEvent flooding | Per-player rate limiting on all remotes. |
28
+ | HIGH | Memory leaks from undisconnected events | Use Trove. Every :Connect() must have a corresponding :Disconnect(). |
29
+ | HIGH | Assuming instances exist with StreamingEnabled | Check existence before access. Instances may not be loaded yet. |
30
+ | MED | Instance.new(class, parent) race | Create first, parent second. Parenting in constructor causes replication race. |
31
+ | LOW | :connect typo | It's :Connect() with capital C. |
32
+
33
+ ## 3. Capabilities Boundary
34
+
35
+ roblox-opencode handles: Luau code, scripts, modules, remotes, data, UI logic, game architecture.
36
+ roblox-opencode does NOT handle: 3D model generation, mesh creation, animation authoring, terrain sculpting, pixel-perfect UI design. These are Studio's domain - use blockout Parts with descriptive names and let the user detail visually.
37
+
38
+ ## 4. Skill Routing Corrections
39
+
40
+ Only for ambiguous cases where two skills overlap:
41
+ - streaming/workspace not loaded → roblox-runtime (not roblox-architecture)
42
+ - gui/ui layout → roblox-gui (not roblox-architecture)
43
+ - data persistence → roblox-data (not roblox-networking)
44
+ - remote handler validation → roblox-networking (not roblox-architecture)
45
+ - security hardening → roblox-networking (security is folded in)
46
+
47
+ For everything else, load the skill whose description best matches the task.
48
+ Load the Quick Reference section first. Only load the Full Reference if the task requires specific syntax examples or implementation details.
49
+
50
+ ## 5. Asset Trust
51
+
52
+ - Never suggest asset IDs. Never recommend free-model code (ModuleScripts, Scripts, LocalScripts).
53
+ - Free models OK strictly for art assets (Mesh, Texture, Sound, Animation).
54
+ - Before any LoadAsset: walk user through audit - inspect children, check for getfenv/loadstring/HttpService/suspicious RemoteEvents.
55
+ - Vendored libraries (ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component) are the only pre-written code the agent may place.
56
+
57
+ ## 6. Verification
58
+
59
+ Silence means verified. Surface ⚠️ only when verification was NOT possible:
60
+ "⚠️ not verified: [thing], [reason]"
61
+ Do not prefix verified responses with "Verified: ..." - that noise trains users to stop reading.
62
+
63
+ ## 7. Luau-LSP
64
+
65
+ - Diagnostics are signal, not authority. On conflict with documented Roblox behavior, prefer documented behavior.
66
+ - Never claim "done, test it" with unresolved diagnostics. Either fix them, justify them, or surface ⚠️.
67
+ - Diagnostics fire async after each .luau write. The agent reconciles silently.
68
+
69
+ ## 8. Tiered Library Policy
70
+
71
+ **Vendored libraries** (auto-placed with mention): ProfileStore, Trove, Signal (RbxUtil), Promise, Comm, Component.
72
+ - Agent mentions the choice. User can revert or say "use my own."
73
+ - Before auto-placing, query project index for existing equivalents. If found, skip auto-place and mention why.
74
+ - Placement mechanic: copy from `.opencode/vendor/<path>` into the project's synced folder. Shared libs → ReplicatedStorage/Packages/. Server-only (ProfileStore) → ServerScriptService/Packages/. Infer sync folder from existing project structure.
75
+
76
+ **Vendored tools** (recommended when relevant, not auto-placed): t (runtime type checking), TestEZ (testing).
77
+ - Agent recommends when the task involves Remote validation, argument checking, or testing.
78
+ - Agent does NOT auto-place - requires user buy-in.
79
+
80
+ **Anything else**: full consent. Agent explains, asks via user prompts, places only on yes.
81
+
82
+ ## 9. Skill & Command Routing
83
+
84
+ When the user's task matches a command or skill, suggest it:
85
+ - First-time project setup → /setup-game (command)
86
+ - Sync feels broken → /sync-check (command)
87
+ - Code review or audit → load roblox-code-review skill
88
+ - Debugging → load roblox-debug skill
89
+ - Pre-publish check → load roblox-publish-checklist skill
90
+
91
+ ## Version
92
+
93
+ roblox-opencode 1.0.0
package/dist/server.js CHANGED
@@ -1,167 +1,189 @@
1
- // src/index.ts
2
- import { tool } from "@opencode-ai/plugin";
3
- import { fileURLToPath } from "node:url";
4
- var VERSION = "1.0.0";
5
- var MARKER_BEGIN = `<!-- roblox-opencode ${VERSION} BEGIN - managed block, edits inside will be overwritten -->`;
6
- var MARKER_END = "<!-- roblox-opencode END -->";
7
- var RobloxOpenCode = async () => {
8
- try {
9
- const { existsSync, mkdirSync, readdirSync, copyFileSync } = await import("fs");
10
- const { join } = await import("path");
11
- const os = await import("os");
12
- const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
13
- const srcDir = join(pkgDir, "commands");
14
- const destDir = join(os.homedir(), ".config", "opencode", "commands");
15
- if (existsSync(srcDir)) {
16
- mkdirSync(destDir, { recursive: true });
17
- const files = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
18
- for (const file of files) {
19
- copyFileSync(join(srcDir, file), join(destDir, file));
20
- }
21
- }
22
- } catch {
23
- }
24
- return {
25
- tool: {
26
- roblox_setup: tool({
27
- description: "One-time project setup for roblox-opencode. Copies 17 skills and vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to the project, writes luau-lsp config to opencode.json, and writes the core Roblox agent instructions to AGENTS.md. Run this when first opening a Roblox project.",
28
- args: {},
29
- async execute(_args, context) {
30
- if (!context.directory) {
31
- return [{ step: "pre-check", status: "error", error: "No project directory. Open a project folder first." }];
32
- }
33
- return await runSetup(context.directory);
34
- }
35
- })
36
- }
37
- };
38
- };
39
- async function runSetup(directory) {
40
- const { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } = await import("fs");
41
- const { join } = await import("path");
42
- const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
43
- const projectDir = directory;
44
- const steps = [];
45
- steps.push({
46
- name: "Copy 17 skills to .opencode/skills/",
47
- fn: () => {
48
- const src = join(pkgDir, "skills");
49
- const dest = join(projectDir, ".opencode", "skills");
50
- if (!existsSync(src)) throw new Error(`skills/ not found in plugin at ${src}`);
51
- mkdirSync(dest, { recursive: true });
52
- cpSync(src, dest, { recursive: true, force: true });
53
- }
54
- });
55
- steps.push({
56
- name: "Copy vendor libraries to project",
57
- fn: () => {
58
- const src = join(pkgDir, "vendor");
59
- const dest = join(projectDir, ".opencode", "vendor");
60
- if (!existsSync(src)) throw new Error(`vendor/ not found in plugin at ${src}`);
61
- mkdirSync(dest, { recursive: true });
62
- cpSync(src, dest, { recursive: true, force: true });
63
- }
64
- });
65
- steps.push({
66
- name: "Write LSP config (luau-lsp)",
67
- fn: () => {
68
- const configPath = join(projectDir, "opencode.json");
69
- let config = {};
70
- if (existsSync(configPath)) {
71
- try {
72
- config = JSON.parse(readFileSync(configPath, "utf-8"));
73
- } catch {
74
- }
75
- }
76
- config.lsp = {
77
- ...config.lsp || {},
78
- luau: {
79
- command: ["luau-lsp", "lsp"],
80
- extensions: [".luau"]
81
- }
82
- };
83
- writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
84
- }
85
- });
86
- steps.push({
87
- name: "Write .luaurc (vendor path aliases)",
88
- fn: () => {
89
- const luaurcPath = join(projectDir, ".luaurc");
90
- let luaurc = {};
91
- if (existsSync(luaurcPath)) {
92
- try {
93
- luaurc = JSON.parse(readFileSync(luaurcPath, "utf-8"));
94
- } catch {
95
- }
96
- }
97
- const aliases = luaurc.aliases || {};
98
- aliases["Packages"] = ".opencode/vendor/rbxutil";
99
- aliases["Fusion"] = ".opencode/vendor/fusion";
100
- aliases["ProfileStore"] = ".opencode/vendor/profilestore";
101
- aliases["Promise"] = ".opencode/vendor/promise";
102
- aliases["TestEZ"] = ".opencode/vendor/testez";
103
- aliases["t"] = ".opencode/vendor/t";
104
- luaurc.aliases = aliases;
105
- luaurc.languageMode = luaurc.languageMode || "nonstrict";
106
- writeFileSync(luaurcPath, JSON.stringify(luaurc, null, 2) + "\n");
107
- }
108
- });
109
- steps.push({
110
- name: "Write core block to AGENTS.md",
111
- fn: () => {
112
- const agentsPath = join(projectDir, "AGENTS.md");
113
- const corePath = join(pkgDir, "core", "roblox-core.md");
114
- if (!existsSync(corePath)) throw new Error(`core/roblox-core.md not found in plugin at ${corePath}`);
115
- const coreContent = readFileSync(corePath, "utf-8");
116
- const block = `${MARKER_BEGIN}
117
- ${coreContent}
118
- ${MARKER_END}`;
119
- let agentsContent = "";
120
- if (existsSync(agentsPath)) {
121
- agentsContent = readFileSync(agentsPath, "utf-8");
122
- }
123
- const beginPattern = /<!-- roblox-opencode[^>]*BEGIN[^>]*-->/;
124
- const endPattern = /<!-- roblox-opencode END -->/;
125
- const oldBeginPattern = /<!-- roblox-pi[^>]*BEGIN[^>]*-->/;
126
- const oldEndPattern = /<!-- roblox-pi END -->/;
127
- let newContent;
128
- if (beginPattern.test(agentsContent) && endPattern.test(agentsContent)) {
129
- newContent = agentsContent.replace(
130
- new RegExp(`${beginPattern.source}[\\s\\S]*?${endPattern.source}`),
131
- block
132
- );
133
- } else if (oldBeginPattern.test(agentsContent) && oldEndPattern.test(agentsContent)) {
134
- newContent = agentsContent.replace(
135
- new RegExp(`${oldBeginPattern.source}[\\s\\S]*?${oldEndPattern.source}`),
136
- block
137
- );
138
- } else {
139
- newContent = agentsContent ? agentsContent.trimEnd() + "\n\n" + block + "\n" : block + "\n";
140
- }
141
- writeFileSync(agentsPath, newContent);
142
- }
143
- });
144
- const results = [];
145
- for (const step of steps) {
146
- try {
147
- step.fn();
148
- results.push({ step: step.name, status: "ok" });
149
- } catch (err) {
150
- results.push({
151
- step: step.name,
152
- status: "error",
153
- error: err instanceof Error ? err.message : String(err)
154
- });
155
- }
156
- }
157
- return results;
158
- }
159
- var index_default = {
160
- id: "roblox-opencode",
161
- server: RobloxOpenCode
162
- };
163
- export {
164
- RobloxOpenCode,
165
- index_default as default,
166
- runSetup
167
- };
1
+ // src/index.ts
2
+ import { tool } from "@opencode-ai/plugin";
3
+ import { fileURLToPath } from "node:url";
4
+ var VERSION = "1.0.1";
5
+ var MARKER_BEGIN = `<!-- roblox-opencode ${VERSION} BEGIN - managed block, edits inside will be overwritten -->`;
6
+ var MARKER_END = "<!-- roblox-opencode END -->";
7
+ var RobloxOpenCode = async (ctx) => {
8
+ const { existsSync, mkdirSync, readdirSync, copyFileSync, readFileSync, writeFileSync } = await import("fs");
9
+ const { join } = await import("path");
10
+ const os = await import("os");
11
+ const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
12
+ try {
13
+ const srcDir = join(pkgDir, "commands");
14
+ const destDir = join(os.homedir(), ".config", "opencode", "commands");
15
+ if (existsSync(srcDir)) {
16
+ mkdirSync(destDir, { recursive: true });
17
+ const files = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
18
+ for (const file of files) {
19
+ copyFileSync(join(srcDir, file), join(destDir, file));
20
+ }
21
+ }
22
+ } catch {
23
+ }
24
+ try {
25
+ const directory = ctx?.directory;
26
+ if (directory) {
27
+ const versionFile = join(directory, ".opencode", ".roblox-opencode-version");
28
+ let installedVersion = "";
29
+ if (existsSync(versionFile)) {
30
+ installedVersion = readFileSync(versionFile, "utf-8").trim();
31
+ }
32
+ if (installedVersion !== VERSION && existsSync(join(directory, ".opencode", "skills"))) {
33
+ await runSetup(directory);
34
+ mkdirSync(join(directory, ".opencode"), { recursive: true });
35
+ writeFileSync(versionFile, VERSION + "\n");
36
+ }
37
+ }
38
+ } catch {
39
+ }
40
+ return {
41
+ tool: {
42
+ roblox_setup: tool({
43
+ description: "One-time project setup for roblox-opencode. Copies 17 skills and vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to the project, writes luau-lsp config to opencode.json, and writes the core Roblox agent instructions to AGENTS.md. Run this when first opening a Roblox project.",
44
+ args: {},
45
+ async execute(_args, context) {
46
+ if (!context.directory) {
47
+ return [{ step: "pre-check", status: "error", error: "No project directory. Open a project folder first." }];
48
+ }
49
+ return await runSetup(context.directory);
50
+ }
51
+ })
52
+ }
53
+ };
54
+ };
55
+ async function runSetup(directory) {
56
+ const { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } = await import("fs");
57
+ const { join } = await import("path");
58
+ const pkgDir = join(import.meta.dirname ?? fileURLToPath(new URL(".", import.meta.url)), "..");
59
+ const projectDir = directory;
60
+ const steps = [];
61
+ steps.push({
62
+ name: "Copy 17 skills to .opencode/skills/",
63
+ fn: () => {
64
+ const src = join(pkgDir, "skills");
65
+ const dest = join(projectDir, ".opencode", "skills");
66
+ if (!existsSync(src)) throw new Error(`skills/ not found in plugin at ${src}`);
67
+ mkdirSync(dest, { recursive: true });
68
+ cpSync(src, dest, { recursive: true, force: true });
69
+ }
70
+ });
71
+ steps.push({
72
+ name: "Copy vendor libraries to project",
73
+ fn: () => {
74
+ const src = join(pkgDir, "vendor");
75
+ const dest = join(projectDir, ".opencode", "vendor");
76
+ if (!existsSync(src)) throw new Error(`vendor/ not found in plugin at ${src}`);
77
+ mkdirSync(dest, { recursive: true });
78
+ cpSync(src, dest, { recursive: true, force: true });
79
+ }
80
+ });
81
+ steps.push({
82
+ name: "Write LSP config (luau-lsp)",
83
+ fn: () => {
84
+ const configPath = join(projectDir, "opencode.json");
85
+ let config = {};
86
+ if (existsSync(configPath)) {
87
+ try {
88
+ config = JSON.parse(readFileSync(configPath, "utf-8"));
89
+ } catch {
90
+ }
91
+ }
92
+ config.lsp = {
93
+ ...config.lsp || {},
94
+ luau: {
95
+ command: ["luau-lsp", "lsp"],
96
+ extensions: [".luau"]
97
+ }
98
+ };
99
+ writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
100
+ }
101
+ });
102
+ steps.push({
103
+ name: "Write .luaurc (vendor path aliases)",
104
+ fn: () => {
105
+ const luaurcPath = join(projectDir, ".luaurc");
106
+ let luaurc = {};
107
+ if (existsSync(luaurcPath)) {
108
+ try {
109
+ luaurc = JSON.parse(readFileSync(luaurcPath, "utf-8"));
110
+ } catch {
111
+ }
112
+ }
113
+ const aliases = luaurc.aliases || {};
114
+ aliases["Packages"] = ".opencode/vendor/rbxutil";
115
+ aliases["Fusion"] = ".opencode/vendor/fusion";
116
+ aliases["ProfileStore"] = ".opencode/vendor/profilestore";
117
+ aliases["Promise"] = ".opencode/vendor/promise";
118
+ aliases["TestEZ"] = ".opencode/vendor/testez";
119
+ aliases["t"] = ".opencode/vendor/t";
120
+ luaurc.aliases = aliases;
121
+ luaurc.languageMode = luaurc.languageMode || "nonstrict";
122
+ writeFileSync(luaurcPath, JSON.stringify(luaurc, null, 2) + "\n");
123
+ }
124
+ });
125
+ steps.push({
126
+ name: "Write core block to AGENTS.md",
127
+ fn: () => {
128
+ const agentsPath = join(projectDir, "AGENTS.md");
129
+ const corePath = join(pkgDir, "core", "roblox-core.md");
130
+ if (!existsSync(corePath)) throw new Error(`core/roblox-core.md not found in plugin at ${corePath}`);
131
+ const coreContent = readFileSync(corePath, "utf-8");
132
+ const block = `${MARKER_BEGIN}
133
+ ${coreContent}
134
+ ${MARKER_END}`;
135
+ let agentsContent = "";
136
+ if (existsSync(agentsPath)) {
137
+ agentsContent = readFileSync(agentsPath, "utf-8");
138
+ }
139
+ const beginPattern = /<!-- roblox-opencode[^>]*BEGIN[^>]*-->/;
140
+ const endPattern = /<!-- roblox-opencode END -->/;
141
+ const oldBeginPattern = /<!-- roblox-pi[^>]*BEGIN[^>]*-->/;
142
+ const oldEndPattern = /<!-- roblox-pi END -->/;
143
+ let newContent;
144
+ if (beginPattern.test(agentsContent) && endPattern.test(agentsContent)) {
145
+ newContent = agentsContent.replace(
146
+ new RegExp(`${beginPattern.source}[\\s\\S]*?${endPattern.source}`),
147
+ block
148
+ );
149
+ } else if (oldBeginPattern.test(agentsContent) && oldEndPattern.test(agentsContent)) {
150
+ newContent = agentsContent.replace(
151
+ new RegExp(`${oldBeginPattern.source}[\\s\\S]*?${oldEndPattern.source}`),
152
+ block
153
+ );
154
+ } else {
155
+ newContent = agentsContent ? agentsContent.trimEnd() + "\n\n" + block + "\n" : block + "\n";
156
+ }
157
+ writeFileSync(agentsPath, newContent);
158
+ }
159
+ });
160
+ const results = [];
161
+ for (const step of steps) {
162
+ try {
163
+ step.fn();
164
+ results.push({ step: step.name, status: "ok" });
165
+ } catch (err) {
166
+ results.push({
167
+ step: step.name,
168
+ status: "error",
169
+ error: err instanceof Error ? err.message : String(err)
170
+ });
171
+ }
172
+ }
173
+ try {
174
+ const versionFile = join(projectDir, ".opencode", ".roblox-opencode-version");
175
+ mkdirSync(join(projectDir, ".opencode"), { recursive: true });
176
+ writeFileSync(versionFile, VERSION + "\n");
177
+ } catch {
178
+ }
179
+ return results;
180
+ }
181
+ var index_default = {
182
+ id: "roblox-opencode",
183
+ server: RobloxOpenCode
184
+ };
185
+ export {
186
+ RobloxOpenCode,
187
+ index_default as default,
188
+ runSetup
189
+ };
package/package.json CHANGED
@@ -1,35 +1,35 @@
1
- {
2
- "name": "roblox-opencode",
3
- "version": "1.0.0",
4
- "description": "OpenCode plugin for Roblox/Luau development: skills, commands, module libs, and config",
5
- "keywords": [
6
- "opencode-plugin",
7
- "roblox",
8
- "luau",
9
- "game-development"
10
- ],
11
- "license": "MIT",
12
- "author": "TabooHarmony",
13
- "type": "module",
14
- "main": "./dist/server.js",
15
- "exports": {
16
- "./server": {
17
- "import": "./dist/server.js"
18
- }
19
- },
20
- "repository": {
21
- "type": "git",
22
- "url": "https://github.com/TabooHarmony/roblox-opencode"
23
- },
24
- "scripts": {
25
- "build": "esbuild src/index.ts --bundle --outfile=dist/server.js --target=esnext --format=esm --platform=node --external:@opencode-ai/plugin",
26
- "prepare": "node -e \"\""
27
- },
28
- "files": [
29
- "dist/",
30
- "skills/",
31
- "commands/",
32
- "vendor/",
33
- "core/"
34
- ]
35
- }
1
+ {
2
+ "name": "roblox-opencode",
3
+ "version": "1.0.1",
4
+ "description": "OpenCode plugin for Roblox/Luau development - skills, commands, vendor libs, and config",
5
+ "keywords": [
6
+ "opencode-plugin",
7
+ "roblox",
8
+ "luau",
9
+ "game-development"
10
+ ],
11
+ "license": "MIT",
12
+ "author": "TabooHarmony",
13
+ "type": "module",
14
+ "main": "./dist/server.js",
15
+ "exports": {
16
+ "./server": {
17
+ "import": "./dist/server.js"
18
+ }
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "https://github.com/TabooHarmony/roblox-opencode"
23
+ },
24
+ "scripts": {
25
+ "build": "esbuild src/index.ts --bundle --outfile=dist/server.js --target=esnext --format=esm --platform=node --external:@opencode-ai/plugin",
26
+ "prepare": "node -e \"\""
27
+ },
28
+ "files": [
29
+ "dist/",
30
+ "skills/",
31
+ "commands/",
32
+ "vendor/",
33
+ "core/"
34
+ ]
35
+ }