@jstn-sdk/rcs 0.1.0 → 0.1.6

package/prompts/writer.md

@@ -1,10 +1,14 @@
 ---
-description: "Technical documentation writer for README, API docs, and comments"
+description: "Technical documentation writer for creator docs, remote contracts, README files, and comments"
 argument-hint: "task description"
+surface-class: "internal"
+domain: "creator-runtime"
+audience: "internal"
+artifact-type: "prompt"
 ---
 <identity>
 You are Writer. Your mission is to create clear, accurate technical documentation that developers want to read.
-You are responsible for README files, API documentation, architecture docs, user guides, and code comments.
+You are responsible for README files, creator guides, remote contract docs, architecture docs, user guides, and code comments.
 You are not responsible for implementing features, reviewing code quality, or making architectural decisions.
 
 Inaccurate documentation is worse than no documentation -- it actively misleads. These rules exist because documentation with untested code examples causes frustration, and documentation that doesn't match reality wastes developer time. Every example must work, every command must be verified.
@@ -89,8 +93,8 @@ VERIFICATION:
 </anti_patterns>
 
 <scenario_handling>
-**Good:** Task: "Document the auth API." Writer reads the actual auth code, writes API docs with tested curl examples that return real responses, includes error codes from actual error handling, and verifies the installation command works.
-**Bad:** Task: "Document the auth API." Writer guesses at endpoint paths, invents response formats, includes untested curl examples, and copies parameter names from memory instead of reading the code.
+**Good:** Task: "Document the trading remote contract." Writer reads the actual `RemoteEvent` / `RemoteFunction` usage, documents payload fields and server validation rules, includes Studio/Luau examples that match the code, and verifies any referenced RCS commands actually run.
+**Bad:** Task: "Document the trading remote contract." Writer guesses payload shapes, invents server responses, includes untested pseudo-network examples, and copies field names from memory instead of reading the code.
 
 **Good:** The user says `continue` after you already have a partial writing recommendation. Keep gathering the missing evidence instead of restarting the work or restating the same partial result.
 
@@ -107,3 +111,6 @@ VERIFICATION:
 - Did I stay within the requested scope?
 </final_checklist>
 </style>
+surface-class: "internal"
+domain: "creator-runtime"
+audience: "internal"

package/skills/.agents/skills/roblox-animations/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: roblox-animations
+description: Use when working with Roblox animation systems including playing, stopping, or blending animations on Humanoid characters or non-Humanoid models, handling AnimationTrack events, replacing default character animations, or debugging animation priority and blending issues.
+---
+
+# Roblox Animations Reference
+
+## Core Objects
+
+| Object | Purpose |
+|---|---|
+| `Animation` | Asset reference — holds `AnimationId` |
+| `Animator` | Lives inside Humanoid or AnimationController; loads and drives tracks |
+| `AnimationController` | Replaces Humanoid for non-character rigs |
+| `AnimationTrack` | Returned by `LoadAnimation`; controls playback |
+
+---
+
+## Where to Run Animation Code
+
+| Scenario | Script Type | Location |
+|---|---|---|
+| Local player character | `LocalScript` | `StarterCharacterScripts` |
+| NPC / server-owned model | `Script` | Inside model or `ServerScriptService` |
+
+> Never play player character animations from a `Script` — they will not replicate correctly to the local client.
+
+---
+
+## Loading and Playing Animations
+
+```lua
+-- LocalScript in StarterCharacterScripts
+local character = script.Parent
+local animator = character:WaitForChild("Humanoid"):WaitForChild("Animator")
+
+local animation = Instance.new("Animation")
+animation.AnimationId = "rbxassetid://1234567890"
+
+local track = animator:LoadAnimation(animation)
+
+track:Play()                      -- default fade-in (0.1s), weight 1, speed 1
+track:Play(0.1, 1, 0.5)          -- fadeTime, weight, speed
+
+track:AdjustSpeed(1.5)           -- change speed while playing
+track:AdjustWeight(0.5, 0.2)     -- weight 0.5, fade over 0.2s
+
+track:Stop()                      -- default fade-out (0.1s)
+track:Stop(0.5)                   -- fade out over 0.5s
+```
+
+---
+
+## AnimationTrack Events
+
+```lua
+-- Fires after fade-out completes
+track.Stopped:Connect(function()
+    print("Animation finished")
+end)
+
+-- Use :Once for one-shot cleanup
+track.Stopped:Once(function()
+    cleanup()
+end)
+
+-- Fires when a named keyframe marker is reached
+-- Marker names are set in the Roblox Animation Editor
+track:GetMarkerReachedSignal("FootStep"):Connect(function(paramString)
+    playFootstepSound()
+end)
+```
+
+---
+
+## Looped vs One-Shot
+
+| Property | Looped | One-Shot |
+|---|---|---|
+| `track.Looped` | `true` | `false` |
+| Set in | Animation Editor (loop toggle) | Animation Editor |
+| Override at runtime | `track.Looped = false` | `track.Looped = true` |
+| Stops automatically | No — must call `track:Stop()` | Yes — after one cycle |
+
+```lua
+-- Force a looped animation to play once
+track.Looped = false
+track:Play()
+track.Stopped:Once(function() print("Done") end)
+```
+
+---
+
+## Animation Priority and Blending
+
+Priority controls which tracks win on contested joints. Higher priority overrides lower.
+
+```
+Idle < Movement < Action < Action2 < Action3 < Action4 < Core
+```
+
+```lua
+idleTrack.Priority   = Enum.AnimationPriority.Idle
+runTrack.Priority    = Enum.AnimationPriority.Movement
+attackTrack.Priority = Enum.AnimationPriority.Action
+
+idleTrack:Play()
+runTrack:Play()     -- overrides idle on shared joints
+attackTrack:Play()  -- blends on top for joints it owns
+```
+
+Weight adjusts influence when two tracks share the same priority:
+
+```lua
+trackA:Play(0, 0.6)  -- weight 0.6
+trackB:Play(0, 0.4)  -- weight 0.4 — blended on shared joints
+```
+
+---
+
+## Humanoid vs AnimationController
+
+### Humanoid (characters and humanoid NPCs)
+
+```lua
+local animator = character:FindFirstChildOfClass("Humanoid"):FindFirstChildOfClass("Animator")
+local track = animator:LoadAnimation(animation)
+track:Play()
+```
+
+### AnimationController (props, vehicles, creatures)
+
+```lua
+local controller = model:FindFirstChildOfClass("AnimationController")
+local animator = controller:FindFirstChildOfClass("Animator")
+if not animator then
+    animator = Instance.new("Animator")
+    animator.Parent = controller
+end
+local track = animator:LoadAnimation(animation)
+track:Play()
+```
+
+---
+
+## Replacing Default Character Animations
+
+The `Animate` LocalScript in the character holds animation references. Modify its `AnimationId` values on CharacterAdded.
+
+```lua
+-- LocalScript in StarterCharacterScripts
+local animate = script.Parent:WaitForChild("Animate")
+
+local function replaceAnim(slotName, newId)
+    local slot = animate:FindFirstChild(slotName)
+    if slot then
+        local animObj = slot:FindFirstChildOfClass("Animation")
+        if animObj then animObj.AnimationId = newId end
+    end
+end
+
+replaceAnim("idle",  "rbxassetid://111111111")
+replaceAnim("run",   "rbxassetid://222222222")
+replaceAnim("jump",  "rbxassetid://333333333")
+replaceAnim("fall",  "rbxassetid://444444444")
+replaceAnim("climb", "rbxassetid://555555555")
+```
+
+Available slots: `idle`, `walk`, `run`, `jump`, `fall`, `climb`, `swim`, `swimidle`, `toolnone`, `toolslash`, `toollunge`.
+
+---
+
+## Stop All Playing Animations
+
+```lua
+local function stopAll(animator, fadeTime)
+    for _, track in animator:GetPlayingAnimationTracks() do
+        track:Stop(fadeTime or 0.1)
+    end
+end
+```
+
+---
+
+## Quick Playback Reference
+
+```lua
+track:Play(fadeTime, weight, speed)
+-- fadeTime  default 0.1   — blend-in seconds
+-- weight    default 1.0   — joint influence (0–1)
+-- speed     default 1.0   — playback rate
+
+track.TimePosition   -- current position in seconds (read/write)
+track.Length         -- total duration in seconds
+track.IsPlaying      -- bool
+track.Looped         -- bool (override allowed at runtime)
+track.Priority       -- Enum.AnimationPriority
+track.WeightCurrent  -- actual blended weight right now
+track.WeightTarget   -- target weight after fade
+```
+
+---
+
+## Upper-Body Only Animations
+
+Priority blending affects **all joints** an animation touches. To play a wave only on the arms while legs animate from run/idle, the animation itself must be authored to only key upper-body bones (leave lower-body joints unkeyed in the Animation Editor). There is no runtime API to mask joints — the solution is in the animation asset, not the script.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Playing character animations in a `Script` | Use `LocalScript` in `StarterCharacterScripts` |
+| `LoadAnimation` called on `Humanoid` (deprecated) | Call on `Animator` instead |
+| Two animations fighting on same joints | Assign different `Priority` values |
+| `Stopped` fires immediately | Animation has zero length or wrong `Looped` setting |
+| `GetMarkerReachedSignal` never fires | Marker name misspelled, or animation not re-uploaded after adding markers |
+| NPC animation not visible to other clients | Play from a `Script` (server), not `LocalScript` |
+| `AnimationController` track won't play | Missing `Animator` child inside `AnimationController` |

package/skills/.agents/skills/roblox-datastores/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: roblox-datastores
+description: "Use when implementing player data persistence in Roblox, saving/loading player stats or inventory, building leaderboards with ordered datastores, handling data migration between versions, diagnosing data loss issues, or adding auto-save and shutdown-safe data handling with DataStoreService."
+---
+
+# roblox-datastores
+
+Reference for Roblox `DataStoreService` — saving, loading, and managing player data on the server.
+
+## Quick Reference
+
+| Method | Signature | Notes |
+|---|---|---|
+| `GetDataStore` | `DSS:GetDataStore(name, scope?)` | Returns a `GlobalDataStore` |
+| `GetOrderedDataStore` | `DSS:GetOrderedDataStore(name, scope?)` | For leaderboards |
+| `GetAsync` | `store:GetAsync(key)` | Returns value or nil |
+| `SetAsync` | `store:SetAsync(key, value)` | No return value needed |
+| `UpdateAsync` | `store:UpdateAsync(key, fn)` | Atomic read-modify-write |
+| `RemoveAsync` | `store:RemoveAsync(key)` | Deletes key, returns old value |
+| `GetSortedAsync` | `orderedStore:GetSortedAsync(asc, pageSize)` | Returns `DataStorePages` |
+
+---
+
+## Basic Setup
+
+```lua
+-- Server Script (ServerScriptService)
+local DataStoreService = game:GetService("DataStoreService")
+local Players = game:GetService("Players")
+
+local playerStore = DataStoreService:GetDataStore("PlayerData_v1")
+
+local DEFAULT_DATA = {
+    coins = 0,
+    level = 1,
+    xp = 0,
+}
+```
+
+---
+
+## Loading Data (GetAsync + pcall)
+
+Always wrap datastore calls in `pcall`. They can fail due to network issues or rate limits.
+
+```lua
+local function loadData(player)
+    local key = "player_" .. player.UserId
+    local success, data = pcall(function()
+        return playerStore:GetAsync(key)
+    end)
+
+    if success then
+        local result = {}
+        for k, v in pairs(DEFAULT_DATA) do result[k] = v end
+        if data then
+            for k, v in pairs(data) do result[k] = v end
+        end
+        return result
+    else
+        warn("Failed to load data for", player.Name, ":", data)
+        return nil -- signal failure; do not give default data silently
+    end
+end
+```
+
+---
+
+## Saving Data (SetAsync vs UpdateAsync)
+
+Use `SetAsync` for simple overwrites. Use `UpdateAsync` when the value must be based on the current stored value (e.g., incrementing a counter safely across servers).
+
+```lua
+-- Simple save
+local function saveData(player, data)
+    local key = "player_" .. player.UserId
+    local success, err = pcall(function()
+        playerStore:SetAsync(key, data)
+    end)
+    if not success then
+        warn("Failed to save data for", player.Name, ":", err)
+    end
+end
+
+-- Atomic increment with UpdateAsync
+local function addCoinsAtomic(userId, amount)
+    local key = "player_" .. userId
+    pcall(function()
+        playerStore:UpdateAsync(key, function(current)
+            current = current or { coins = 0 }
+            current.coins = current.coins + amount
+            return current
+        end)
+    end)
+end
+```
+
+---
+
+## Retry Logic
+
+```lua
+local MAX_RETRIES = 3
+local RETRY_DELAY = 2
+
+local function safeGet(store, key)
+    for attempt = 1, MAX_RETRIES do
+        local success, result = pcall(function()
+            return store:GetAsync(key)
+        end)
+        if success then return true, result end
+        warn(string.format("GetAsync attempt %d/%d failed: %s", attempt, MAX_RETRIES, result))
+        if attempt < MAX_RETRIES then task.wait(RETRY_DELAY) end
+    end
+    return false, nil
+end
+```
+
+---
+
+## Auto-Save: PlayerRemoving + BindToClose
+
+Server shutdown without `BindToClose` silently discards unsaved data.
+
+```lua
+local sessionData = {} -- [userId] = data table
+
+Players.PlayerAdded:Connect(function(player)
+    local data = loadData(player)
+    if data then
+        sessionData[player.UserId] = data
+    else
+        player:Kick("Could not load your data. Please rejoin.")
+    end
+end)
+
+Players.PlayerRemoving:Connect(function(player)
+    local data = sessionData[player.UserId]
+    if data then
+        saveData(player, data)
+        sessionData[player.UserId] = nil
+    end
+end)
+
+-- Flush all sessions on server shutdown
+game:BindToClose(function()
+    for userId, data in pairs(sessionData) do
+        local key = "player_" .. userId
+        pcall(function()
+            playerStore:SetAsync(key, data)
+        end)
+    end
+end)
+```
+
+---
+
+## Ordered DataStores (Leaderboards)
+
+Values must be positive integers.
+
+```lua
+local coinsLeaderboard = DataStoreService:GetOrderedDataStore("Coins_v1")
+
+local function setLeaderboardScore(userId, coins)
+    pcall(function()
+        coinsLeaderboard:SetAsync("player_" .. userId, math.floor(coins))
+    end)
+end
+
+local function getTopPlayers(count)
+    local success, pages = pcall(function()
+        return coinsLeaderboard:GetSortedAsync(false, count) -- false = descending
+    end)
+    if not success then return {} end
+
+    local results = {}
+    for rank, entry in ipairs(pages:GetCurrentPage()) do
+        table.insert(results, { rank = rank, userId = entry.key, score = entry.value })
+    end
+    return results
+end
+```
+
+---
+
+## Data Versioning / Migration
+
+Include a `_version` field and migrate in the load path.
+
+```lua
+local CURRENT_VERSION = 2
+
+local function migrateData(data)
+    local version = data._version or 1
+    if version < 2 then
+        data.coins = data.gold or 0  -- renamed field
+        data.gold = nil
+        data._version = 2
+    end
+    return data
+end
+```
+
+Use a versioned datastore name (`PlayerData_v2`) for breaking schema changes.
+
+---
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---|---|---|
+| No `pcall` around datastore calls | Unhandled error crashes the script | Always wrap in `pcall` |
+| Saving on every `Changed` event | Hits rate limits (60 + numPlayers×10 writes/min) | Throttle; save on remove + periodic interval |
+| No `BindToClose` handler | Data lost on server shutdown | Always flush all sessions in `BindToClose` |
+| Giving default data on load failure | Player silently loses progress | Return `nil` on failure; kick or retry |
+| `SetAsync` for atomic counters | Race condition across servers | Use `UpdateAsync` for read-modify-write |
+| Storing Instances or functions | Data silently drops | Store only strings, numbers, booleans, plain tables |
+| Reusing datastore name after schema change | Old shape clashes with new code | Append `_v2`, `_v3` to name on breaking changes |

package/skills/.agents/skills/roblox-gui/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: roblox-gui
+description: "Use when building, animating, or debugging Roblox GUI elements including HUDs, menus, world-space UI, and player labels. Triggers on: ScreenGui setup, SurfaceGui or BillboardGui placement, UDim2 sizing questions, TweenService UI animations, responsive scaling, LocalScript GUI logic, ResetOnSpawn issues, or any Frame/TextLabel/ImageButton layout work."
+---
+
+# Roblox GUI Reference
+
+## GUI Container Types
+
+| Container | Parent | Use Case |
+|---|---|---|
+| `ScreenGui` | `PlayerGui` | HUDs, menus, overlays — always faces screen |
+| `SurfaceGui` | `BasePart` | World-space UI on a part surface (signs, screens) |
+| `BillboardGui` | `BasePart` or `Model` | Floats above a part in 3D space (name tags, health bars) |
+
+### ScreenGui
+
+```lua
+-- LocalScript in StarterGui or StarterPlayerScripts
+local player = game:GetService("Players").LocalPlayer
+local playerGui = player:WaitForChild("PlayerGui")
+
+local screenGui = Instance.new("ScreenGui")
+screenGui.Name = "HUD"
+screenGui.ResetOnSpawn = false   -- keep GUI across respawns
+screenGui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
+screenGui.Parent = playerGui
+```
+
+### SurfaceGui
+
+```lua
+local surfaceGui = Instance.new("SurfaceGui")
+surfaceGui.Face = Enum.NormalId.Front
+surfaceGui.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
+surfaceGui.PixelsPerStud = 50
+surfaceGui.Parent = workspace.ScreenPart
+
+local label = Instance.new("TextLabel")
+label.Size = UDim2.fromScale(1, 1)
+label.Text = "Hello World"
+label.Parent = surfaceGui
+```
+
+### BillboardGui
+
+```lua
+local billboard = Instance.new("BillboardGui")
+billboard.Size = UDim2.fromOffset(200, 50)
+billboard.StudsOffset = Vector3.new(0, 2.5, 0)  -- float above head
+billboard.AlwaysOnTop = false
+billboard.Parent = character:WaitForChild("Head")
+
+local nameLabel = Instance.new("TextLabel")
+nameLabel.Size = UDim2.fromScale(1, 1)
+nameLabel.BackgroundTransparency = 1
+nameLabel.Text = player.DisplayName
+nameLabel.Parent = billboard
+```
+
+---
+
+## UDim2 Sizing and Positioning
+
+`UDim2.new(xScale, xOffset, yScale, yOffset)` — scale is 0–1 relative to parent, offset is pixels.
+
+```lua
+frame.Size     = UDim2.new(1, 0, 0, 50)       -- full width, 50px tall
+frame.Position = UDim2.new(0, 0, 0, 0)         -- top-left corner
+
+frame.Size     = UDim2.fromScale(0.6, 0.4)     -- 60% wide, 40% tall
+frame.Position = UDim2.new(0.2, 0, 0.3, 0)    -- centered (0.2 = (1-0.6)/2)
+
+UDim2.fromScale(0.5, 0.5)    -- scale only
+UDim2.fromOffset(300, 150)   -- pixels only
+```
+
+**AnchorPoint** shifts the element's pivot (0–1 on each axis):
+
+```lua
+frame.AnchorPoint = Vector2.new(0.5, 0.5)   -- pivot at center
+frame.Position    = UDim2.fromScale(0.5, 0.5)  -- truly centered on screen
+```
+
+---
+
+## Responsive Design
+
+Prefer scale over offset so UI adapts to all screen sizes.
+
+```lua
+button.Size     = UDim2.fromScale(0.2, 0.07)
+button.Position = UDim2.new(0.4, 0, 0.85, 0)
+
+-- Prevent distortion with UIAspectRatioConstraint
+local arc = Instance.new("UIAspectRatioConstraint")
+arc.AspectRatio = 4   -- width:height = 4:1
+arc.Parent = button
+```
+
+---
+
+## TweenService Animations
+
+```lua
+local TweenService = game:GetService("TweenService")
+local tweenInfo = TweenInfo.new(0.3, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)
+
+local menuFrame = script.Parent
+
+local function openMenu()
+    TweenService:Create(menuFrame, tweenInfo, {
+        Position = UDim2.new(0.05, 0, 0.1, 0)
+    }):Play()
+end
+
+local function closeMenu()
+    TweenService:Create(menuFrame, tweenInfo, {
+        Position = UDim2.new(-0.5, 0, 0.1, 0)
+    }):Play()
+end
+
+-- Animated progress bar
+local function setProgress(bar, pct)
+    TweenService:Create(bar, TweenInfo.new(0.2), {
+        Size = UDim2.new(pct, 0, 1, 0)
+    }):Play()
+end
+```
+
+---
+
+## LocalScript Placement
+
+| Location | Notes |
+|---|---|
+| `StarterGui` | Cloned into `PlayerGui` on join; use `ResetOnSpawn = false` to persist |
+| `StarterPlayerScripts` | Runs once, not reset on respawn; good for persistent managers |
+| `StarterCharacterScripts` | Re-runs each spawn; suited for character-dependent UI |
+
+```lua
+-- Safe pattern: wait for character
+local player = game:GetService("Players").LocalPlayer
+local character = player.Character or player.CharacterAdded:Wait()
+local humanoid = character:WaitForChild("Humanoid")
+
+humanoid.HealthChanged:Connect(function(health)
+    -- update health bar
+end)
+```
+
+---
+
+## ResetOnSpawn
+
+```lua
+screenGui.ResetOnSpawn = false  -- persist across respawns (inventory, settings)
+screenGui.ResetOnSpawn = true   -- re-create on respawn (respawn timer) — default
+```
+
+---
+
+## Common Patterns Quick Reference
+
+| Pattern | Key Setup |
+|---|---|
+| Full-screen overlay | `Size = UDim2.fromScale(1,1)`, `Position = UDim2.fromScale(0,0)` |
+| Bottom-center HUD bar | `AnchorPoint = (0.5,1)`, `Position = UDim2.new(0.5,0,1,-10)` |
+| Padded list | `UIPadding` + `UIListLayout` inside a Frame |
+| Scrollable list | `ScrollingFrame` + `UIListLayout`; set `CanvasSize` from `UIListLayout.AbsoluteContentSize` |
+| Rounded corners | `UICorner` with `CornerRadius = UDim.new(0, 8)` |
+| Scaled text | `TextScaled = true` on TextLabel/TextButton so font grows with container |
+| Dynamic frame height | `AutomaticSize = Enum.AutomaticSize.Y` so frame expands to fit children |
+| Health bar | Nested frames: outer = background, inner tweened by `Size.X.Scale` |
+| Name tag | `BillboardGui` on Head, `StudsOffset = Vector3.new(0, 2.5, 0)` |
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| GUI disappears on respawn | Set `ResetOnSpawn = false` or use `StarterPlayerScripts` |
+| UI looks wrong on mobile | Use `UDim2.fromScale` + `UIAspectRatioConstraint` |
+| Script can't find `PlayerGui` | Use `player:WaitForChild("PlayerGui")` |
+| Tween doesn't run | Ensure the property is tweenable; `Text` is not, `Position` and `Size` are |
+| BillboardGui visible through walls | Verify `AlwaysOnTop = false` |
+| `AbsoluteSize` is zero on first frame | Read it inside `task.defer` or after first render step |
+| Clicks pass through overlapping frames | Add a transparent input-blocking Frame or set `Modal = true` |
+| SurfaceGui flickers | Set `LightInfluence = 0`; ensure part isn't too thin |
+| Text tiny on mobile | Set `TextScaled = true` — fixed `TextSize` doesn't adapt to screen size |
+| UI hard to test on mobile | Use Studio's **Device Emulator** (Test tab → Device) to preview layouts |