@jstn-sdk/rcs 0.1.0 → 0.1.1

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

@@ -0,0 +1,208 @@
+---
+name: roblox-monetization
+description: Use when developing Roblox games or experiences and need to earn Robux through Game Passes, Developer Products, UGC avatar items, or Premium Payouts — covers both Studio scripting and Creator Hub dashboard setup.
+---
+
+# Roblox Monetization
+
+## Overview
+
+End-to-end guide for earning Robux legitimately through Roblox's monetization systems. Covers dashboard configuration and Lua scripting for both developers and designers.
+
+## Quick Reference
+
+| System | Use For | Repeatable? | Min Price |
+|--------|---------|-------------|-----------|
+| Game Pass | Permanent perks/access | No (one-time) | 1 Robux |
+| Developer Product | Consumables, currency, boosts | Yes (unlimited) | 1 Robux |
+| UGC Item | Avatar marketplace sales | N/A | 1 Robux |
+| Premium Payout | Passive playtime income | Automatic | No setup |
+
+---
+
+## 1. Game Passes
+
+One-time purchases granting permanent perks. Player pays once per game per pass.
+
+### Dashboard Setup
+1. [create.roblox.com](https://create.roblox.com) → select experience → **Monetization → Passes**
+2. **Create a Pass** → upload 512×512 PNG icon, set name, description, price
+3. Save → note the **Pass ID**
+
+### Server Script
+```lua
+local MarketplaceService = game:GetService("MarketplaceService")
+local Players = game:GetService("Players")
+
+local PASS_ID = 000000 -- your Pass ID
+
+-- Check ownership on join
+Players.PlayerAdded:Connect(function(player)
+    local success, hasPass = pcall(function()
+        return MarketplaceService:UserOwnsGamePassAsync(player.UserId, PASS_ID)
+    end)
+    if success and hasPass then
+        -- grant perk
+    end
+end)
+
+-- Prompt purchase (call from server)
+local function promptPass(player)
+    MarketplaceService:PromptGamePassPurchase(player, PASS_ID)
+end
+
+-- Grant immediately after purchase
+MarketplaceService.PromptGamePassPurchaseFinished:Connect(function(player, passId, purchased)
+    if purchased and passId == PASS_ID then
+        -- grant perk
+    end
+end)
+```
+
+> **Always run on server (Script), never LocalScript** — client-side ownership checks can be spoofed.
+
+---
+
+## 2. Developer Products
+
+Repeatable purchases — players can buy unlimited times. Use for coins, potions, boosts, in-game currency.
+
+### Dashboard Setup
+1. Creator Hub → experience → **Monetization → Developer Products**
+2. **Create a Developer Product** → set name, description, icon, price
+3. Note the **Product ID**
+
+### Server Script
+```lua
+local MarketplaceService = game:GetService("MarketplaceService")
+local DataStoreService = game:GetService("DataStoreService")
+local Players = game:GetService("Players")
+
+local PRODUCT_ID = 000000 -- your Product ID
+local coinStore = DataStoreService:GetDataStore("PlayerCoins")
+
+local function processReceipt(receiptInfo)
+    local player = Players:GetPlayerByUserId(receiptInfo.PlayerId)
+    if not player then
+        return Enum.ProductPurchaseDecision.NotProcessedYet
+    end
+
+    if receiptInfo.ProductId == PRODUCT_ID then
+        -- Persist to DataStore FIRST — if server crashes after this line, coins are safe
+        local ok, err = pcall(function()
+            coinStore:UpdateAsync(tostring(player.UserId), function(current)
+                return (current or 0) + 100
+            end)
+        end)
+        if not ok then
+            warn("DataStore failed:", err)
+            return Enum.ProductPurchaseDecision.NotProcessedYet -- Roblox will retry
+        end
+        -- Now safe to update in-memory value (leaderstats, etc.)
+    end
+
+    return Enum.ProductPurchaseDecision.PurchaseGranted
+end
+
+MarketplaceService.ProcessReceipt = processReceipt
+
+-- Prompt purchase
+local function promptProduct(player)
+    MarketplaceService:PromptProductPurchase(player, PRODUCT_ID)
+end
+```
+
+> **Critical rules for `ProcessReceipt`:**
+> - Must return `PurchaseGranted` or `NotProcessedYet` — never error silently
+> - Persist to DataStore **before** returning — crashes can cause loss
+> - Return `NotProcessedYet` on DataStore failure so Roblox retries the receipt
+> - Only one `ProcessReceipt` handler allowed per server; combine all product IDs inside it
+> - Roblox may call `ProcessReceipt` more than once for the same purchase — use `receiptInfo.PurchaseId` as a dedup key if double-granting is a concern
+
+---
+
+## 3. UGC / Avatar Items
+
+Sell clothing, accessories, and bundles in the Roblox Marketplace.
+
+### Requirements
+- UGC Program access — apply at [roblox.com/create/ugc](https://www.roblox.com/create/ugc)
+- ID verification completed on your account
+- Roblox Studio or Blender for 3D mesh items
+
+### Workflow
+1. Design item (follow [Roblox mesh/texture specs](https://create.roblox.com/docs/art/accessories/specifications))
+2. Creator Hub → **Avatar Items → Create** → upload, set category, tags, price
+3. Submit for moderation (typically 1–3 business days)
+4. Item goes live and appears in Marketplace
+
+### Earning Rates
+
+| Item Type | Creator Cut |
+|-----------|-------------|
+| Clothing (t-shirts, shirts, pants) | 70% of sale |
+| UGC Accessories | 30% (40% with Premium subscription) |
+| Limited UGC with resale | Up to 70% |
+
+---
+
+## 4. Communicating Purchase State to the Client
+
+After granting a product server-side, notify the client via a `RemoteEvent` so the UI can update (show a boost timer, unlock a button, etc.):
+
+```lua
+-- Inside ProcessReceipt, after DataStore save succeeds
+local NotifyClient = game:GetService("ReplicatedStorage").Remotes.PurchaseGranted
+local player = Players:GetPlayerByUserId(receiptInfo.PlayerId)
+if player then
+    NotifyClient:FireClient(player, { productId = receiptInfo.ProductId })
+end
+```
+
+---
+
+## 5. Premium Payouts
+
+Passive Robux from Roblox Premium subscribers spending time in your game. **No setup required.**
+
+- Roblox tracks Premium member engagement automatically
+- You receive a share of the Premium Payout Pool monthly, proportional to Premium playtime
+- View earnings: Creator Hub → **Analytics → Monetization → Premium Payouts**
+
+### Maximize Premium Payouts
+- Build longer session loops (progression, story, replayability)
+- Add Premium-exclusive cosmetics or bonuses to attract Premium players
+
+---
+
+## DevEx: Robux → Real Money
+
+**Eligibility requirements:**
+- 30,000+ Robux earned (purchased Robux do not count)
+- Age 13 or older
+- Verified email address on your Roblox account
+- No active account violations
+- Roblox Premium subscription
+
+**Steps:**
+1. Creator Hub → **DevEx (Developer Exchange)**
+2. Submit exchange request
+3. Roblox reviews request (typically 1–2 weeks)
+4. Paid via **Tipalti** at approximately **$0.0035 per Robux** (~$122 per 35,000 Robux)
+
+> **Tipalti:** You must create and verify a Tipalti account separately before your first payout. Set this up early to avoid delays.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Ownership check in LocalScript | Move to server Script — client checks can be exploited |
+| `ProcessReceipt` throws an error | Wrap logic in `pcall`; always return a decision enum |
+| Not saving purchase to DataStore | Player loses item on crash — persist before returning `PurchaseGranted` |
+| Multiple `ProcessReceipt` handlers | Only one allowed per server — combine all product logic in one function |
+| Double-granting on receipt retry | Use `receiptInfo.PurchaseId` as a DataStore key to detect already-processed receipts |
+| Selling UGC without program access | Apply to UGC program first; uploads will be rejected otherwise |
+| Price below platform minimum | Minimum is 1 Robux for most item types |
+| DevEx blocked despite enough Robux | Check all eligibility: age 13+, verified email, no violations, Premium subscription, earned (not purchased) Robux |

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

@@ -0,0 +1,230 @@
+---
+name: roblox-performance
+description: Use when optimizing a Roblox game for better frame rates, reducing lag, improving server or client performance, diagnosing FPS drops, handling large worlds, or when asked about streaming, draw calls, object pooling, LOD, MicroProfiler, or expensive loop operations.
+---
+
+# Roblox Performance Optimization
+
+## Quick Reference
+
+| Technique | Impact | When to Use |
+|---|---|---|
+| StreamingEnabled | High | Large open worlds |
+| Object pooling | High | Frequent spawn/destroy |
+| Cache references outside loops | High | Heartbeat/RenderStepped |
+| `task.wait()` over `wait()` | Medium | All scripts |
+| MeshParts over Unions | Medium | Many unique shapes |
+| LOD (hide at distance) | Medium | Complex models |
+| Anchor static parts | Medium | Reduce physics budget |
+| Limit PointLights | High | Any scene with many lights |
+
+---
+
+## StreamingEnabled
+
+Enable for large worlds — engine sends only nearby parts to the client.
+
+```lua
+-- Studio: Workspace > StreamingEnabled = true
+workspace.StreamingEnabled = true
+workspace.StreamingMinRadius = 64
+workspace.StreamingTargetRadius = 128
+```
+
+- Parts outside the radius are `nil` on the client — always guard with `if part then`.
+- Set `Model.LevelOfDetail = Disabled` on models that must always be present.
+- Pre-stream an area before a cutscene or teleport:
+
+```lua
+workspace:RequestStreamAroundAsync(targetPosition, 5) -- 5s timeout
+```
+
+---
+
+## Hot-Path Loop Optimization
+
+`RunService.Heartbeat` and `RenderStepped` fire every frame (~60×/sec). Keep them lean.
+
+### Bad — searching the hierarchy every frame
+
+```lua
+RunService.Heartbeat:Connect(function()
+    local char = workspace:FindFirstChild(player.Name)
+    local humanoid = char and char:FindFirstChild("Humanoid")
+    if humanoid then humanoid.WalkSpeed = 16 end
+end)
+```
+
+### Good — cache references once, do work only when needed
+
+```lua
+local humanoid = nil
+
+Players.LocalPlayer.CharacterAdded:Connect(function(char)
+    humanoid = char:WaitForChild("Humanoid")
+end)
+
+RunService.Heartbeat:Connect(function(dt)
+    if not humanoid then return end
+    humanoid.WalkSpeed = 16  -- cached reference, no search
+end)
+```
+
+**Rules:**
+- Cache `game:GetService()` and part references outside the loop.
+- Never call `FindFirstChild`, `GetChildren`, or `GetDescendants` inside Heartbeat.
+- Throttle work that doesn't need every frame:
+
+```lua
+local TICK_INTERVAL = 0.5
+local elapsed = 0
+
+RunService.Heartbeat:Connect(function(dt)
+    elapsed += dt
+    if elapsed < TICK_INTERVAL then return end
+    elapsed = 0
+    -- expensive work here, runs 2×/sec instead of 60×/sec
+end)
+```
+
+---
+
+## task Library vs Legacy Scheduler
+
+Always use `task` — `wait()` and `spawn()` throttle under load and are deprecated.
+
+| Legacy | Modern |
+|---|---|
+| `wait(n)` | `task.wait(n)` |
+| `spawn(fn)` | `task.spawn(fn)` |
+| `delay(n, fn)` | `task.delay(n, fn)` |
+| `coroutine.wrap(fn)()` | `task.spawn(fn)` |
+
+---
+
+## Object Pooling
+
+Reuse instances instead of creating and destroying them every frame.
+
+```lua
+-- ObjectPool ModuleScript
+local ObjectPool = {}
+ObjectPool.__index = ObjectPool
+
+function ObjectPool.new(template, initialSize)
+    local self = setmetatable({ _template = template, _available = {} }, ObjectPool)
+    for i = 1, initialSize do
+        local obj = template:Clone()
+        obj.Parent = nil
+        table.insert(self._available, obj)
+    end
+    return self
+end
+
+function ObjectPool:Get(parent)
+    local obj = table.remove(self._available) or self._template:Clone()
+    obj.Parent = parent
+    return obj
+end
+
+function ObjectPool:Return(obj)
+    obj.Parent = nil
+    table.insert(self._available, obj)
+end
+
+return ObjectPool
+```
+
+```lua
+-- Usage
+local pool = ObjectPool.new(ReplicatedStorage.Bullet, 20)
+
+local function fireBullet(origin)
+    local bullet = pool:Get(workspace)
+    bullet.CFrame = CFrame.new(origin)
+    task.delay(3, function() pool:Return(bullet) end)
+end
+```
+
+---
+
+## Level of Detail (LOD)
+
+**Built-in:** Set `Model.LevelOfDetail = Automatic` — engine merges distant parts into an imposter mesh automatically.
+
+**Manual distance-based LOD:**
+
+```lua
+-- LocalScript
+local INTERVAL = 0.2
+local LOD_DISTANCE = 150
+local elapsed = 0
+
+RunService.Heartbeat:Connect(function(dt)
+    elapsed += dt
+    if elapsed < INTERVAL then return end
+    elapsed = 0
+
+    local dist = (workspace.CurrentCamera.CFrame.Position - model.PrimaryPart.Position).Magnitude
+    local visible = dist < LOD_DISTANCE
+    for _, v in model:GetDescendants() do
+        if v:IsA("BasePart") then
+            v.LocalTransparencyModifier = visible and 0 or 1
+        end
+    end
+end)
+```
+
+---
+
+## Reducing Draw Calls
+
+- Merge parts that share a material into one MeshPart (export from Blender as `.fbx`).
+- **MeshParts** batch better than CSG Unions (Unions re-triangulate at runtime).
+- Reuse materials — 10 parts sharing `SmoothPlastic` costs far less than 10 unique textures.
+- Use `TextureId` on a single MeshPart instead of stacking Decals on many parts.
+
+---
+
+## Profiling with MicroProfiler
+
+1. Press `Ctrl+F6` in-game to open MicroProfiler.
+2. Press `Ctrl+P` to pause and inspect a single frame.
+3. Look for wide bars in `heartbeatSignal` (Lua), `physicsStepped` (physics), or `render` (GPU).
+4. Label your own code:
+
+```lua
+RunService.Heartbeat:Connect(function()
+    debug.profilebegin("MySystem")
+    -- your code
+    debug.profileend()
+end)
+```
+
+---
+
+## Common FPS Killers
+
+| Cause | Fix |
+|---|---|
+| Thousands of individual parts | Merge into MeshParts |
+| Unanchored static geometry | `Anchored = true` on anything that never moves |
+| Many `PointLight` / `SpotLight` instances | Limit to ~10–20 dynamic lights per area |
+| High-rate ParticleEmitters | Lower `Rate` and `Lifetime`; disable when off-screen |
+| `wait()` under heavy load | Replace with `task.wait()` |
+| `FindFirstChild` chains inside Heartbeat | Cache on load |
+| StreamingEnabled off on large maps | Enable it |
+| `Model.LevelOfDetail = Disabled` everywhere | Use `Automatic` where safe |
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| `workspace:FindFirstChild` every frame | Cache reference on character/model load |
+| Destroying and re-creating bullets/effects | Use an object pool |
+| `wait()` in tight loops | `task.wait()` |
+| All parts with unique materials | Standardize to a small set of shared materials |
+| ParticleEmitters enabled off-screen | Disable `Enabled` when particle source is not visible |
+| Physics on decorative parts | `Anchored = true` |

package/skills/.agents/skills/roblox-remote-events/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: roblox-remote-events
+description: Use when implementing client-server communication in Roblox, firing events between LocalScripts and Scripts, passing data across the network boundary, syncing game state, or defending against exploits that abuse RemoteEvents or RemoteFunctions.
+---
+
+# Roblox Remote Events & Functions
+
+## RemoteEvent vs RemoteFunction
+
+| Type | Direction | Returns value? | Use when |
+|---|---|---|---|
+| `RemoteEvent` | Any direction | No (fire-and-forget) | Notifying server of player action, broadcasting state |
+| `RemoteFunction` | Client→Server | Yes (yields caller) | Client needs a result back (e.g. fetch inventory) |
+| `UnreliableRemoteEvent` | Any direction | No | High-frequency updates where dropped packets are fine |
+
+**Default to RemoteEvent.** Avoid server→client `RemoteFunction` — an exploiter's frozen callback stalls your server thread indefinitely.
+
+---
+
+## Where to Put Remotes
+
+Always store Remotes in `ReplicatedStorage`. Create them from a server Script that runs before any LocalScript.
+
+```
+ReplicatedStorage/
+  Remotes/
+    DealDamage        (RemoteEvent)
+    GetInventory      (RemoteFunction)
+    SyncPosition      (UnreliableRemoteEvent)
+```
+
+```lua
+-- Script in ServerScriptService
+local folder = Instance.new("Folder")
+folder.Name = "Remotes"
+folder.Parent = game:GetService("ReplicatedStorage")
+
+local function make(class, name)
+    local r = Instance.new(class)
+    r.Name = name
+    r.Parent = folder
+    return r
+end
+
+make("RemoteEvent",           "DealDamage")
+make("RemoteFunction",        "GetInventory")
+make("UnreliableRemoteEvent", "SyncPosition")
+```
+
+---
+
+## Firing Patterns
+
+### Client → Server (FireServer)
+
+```lua
+-- LocalScript
+local DealDamage = game:GetService("ReplicatedStorage").Remotes:WaitForChild("DealDamage")
+DealDamage:FireServer({ targetId = 12345, amount = 50 })
+-- First arg on server is always the firing Player (injected automatically, cannot be spoofed)
+```
+
+```lua
+-- Script (server) — VALIDATE everything in the payload
+DealDamage.OnServerEvent:Connect(function(player, data)
+    -- player identity is trustworthy; data contents are not
+end)
+```
+
+### Server → One Client
+
+```lua
+local Notify = game:GetService("ReplicatedStorage").Remotes:WaitForChild("Notify")
+Notify:FireClient(player, { message = "Welcome!" })
+```
+
+```lua
+-- LocalScript
+Notify.OnClientEvent:Connect(function(data)
+    print(data.message)
+end)
+```
+
+### Server → All Clients
+
+```lua
+AnnounceEvent:FireAllClients({ text = "Game starting in 10 seconds!" })
+```
+
+### RemoteFunction (Client Calls, Server Returns)
+
+```lua
+-- Script (server)
+GetInventory.OnServerInvoke = function(player)
+    return getPlayerInventory(player.UserId)
+end
+```
+
+```lua
+-- LocalScript
+local inventory = GetInventory:InvokeServer()  -- yields until server returns
+```
+
+### UnreliableRemoteEvent (High-Frequency Sync)
+
+```lua
+-- LocalScript
+RunService.Heartbeat:Connect(function()
+    SyncPosition:FireServer(character.HumanoidRootPart.CFrame)
+end)
+```
+
+```lua
+-- Script (server) — still validate
+SyncPosition.OnServerEvent:Connect(function(player, cframe)
+    if typeof(cframe) ~= "CFrame" then return end
+    -- apply with sanity bounds check
+end)
+```
+
+---
+
+## CRITICAL: Server-Side Security
+
+**The client is hostile. Treat every argument as untrusted input.**
+
+```lua
+local MAX_DAMAGE = 100
+local COOLDOWNS = {}
+local COOLDOWN_SECONDS = 0.5
+
+DealDamage.OnServerEvent:Connect(function(player, data)
+    -- 1. Rate limit
+    local now = tick()
+    if COOLDOWNS[player.UserId] and now - COOLDOWNS[player.UserId] < COOLDOWN_SECONDS then
+        return
+    end
+    COOLDOWNS[player.UserId] = now
+
+    -- 2. Type checks
+    if type(data) ~= "table" then return end
+    if type(data.targetId) ~= "number" then return end
+    if type(data.amount) ~= "number" then return end
+
+    -- 3. Range clamp
+    local amount = math.clamp(data.amount, 0, MAX_DAMAGE)
+
+    -- 4. Server-side weapon lookup — never trust client-provided Instance
+    local weapon = getEquippedWeapon(player)
+    if not weapon then return end
+
+    -- 5. Server-side target lookup
+    local target = getPlayerByUserId(data.targetId)
+    if not target then return end
+
+    applyDamage(target, amount, player)
+end)
+```
+
+---
+
+## Exploit Patterns & Defenses
+
+| Exploit | What the attacker does | Defense |
+|---|---|---|
+| Argument injection | Sends unexpected types to crash handler | Type-check all arguments |
+| Damage amplification | Sends `amount = math.huge` | Clamp to sane maximum |
+| Remote spam | Fires thousands of times per second | Per-player cooldown |
+| Spoofed target | Sends another player's UserId | Server resolves from its own state |
+| Infinite yield | Never returns from `OnClientEvent` callback | Avoid server→client RemoteFunction |
+| Duplicate action | Replays a valid fire to buy twice | Check state / consume token before acting |
+
+---
+
+## Quick Reference
+
+```
+FireServer(args)            LocalScript → server
+FireClient(player, args)    server → one client
+FireAllClients(args)        server → every client
+InvokeServer(args)          LocalScript → server, waits for return
+OnServerEvent               server-side listener for FireServer
+OnClientEvent               client-side listener for FireClient/FireAllClients
+OnServerInvoke              server-side function assigned for InvokeServer
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| `OnServerEvent` in a LocalScript | Use `OnClientEvent` on client; `OnServerEvent` is server-only |
+| Remotes in ServerStorage | Move to ReplicatedStorage |
+| Trusting payload beyond player identity | Validate every field in the payload |
+| Server→client RemoteFunction | Use RemoteEvent; frozen client stalls server thread |
+| No `WaitForChild` in LocalScript | Remotes may not exist yet; always use `WaitForChild` |
+| Multiple `OnServerInvoke` assignments | Only the last assignment wins; keep it in one place |
+| Firing inside tight loop without throttle | Use `UnreliableRemoteEvent` or accumulate delta time |