{"id":"gh-constant/rocontrol-roblox-sdk","name":"rocontrol-roblox-sdk","scope":"gh-constant","platform":"roblox","description":"Official RoControl SDK for Roblox — server-only, typed, production-grade game integration.","version":"0.2.3","latest":"0.2.3","versions":["0.1.0","0.2.0","0.2.1","0.2.2","0.2.3"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{},"integrity":"ba0b6523c7dae47d980a7d1f0f8a998f06683a5950804b28f62db6d5e76939a6","likes":0,"downloads":0,"install":"forest install gh-constant/rocontrol-roblox-sdk","url":"https://forest.dev/p/roblox/gh-constant/rocontrol-roblox-sdk","files":"https://api.forest.dev/ai/package/roblox/gh-constant/rocontrol-roblox-sdk/files","readme":"# RoControl Roblox SDK\n\nThe official, server-only Roblox SDK for [RoControl](https://rocontrol.app). It lets\nany Roblox experience report events and schedules to RoControl so features like\n**Icon Automation** can drive the game icon safely and globally.\n\n- **Server-only and safe by default** — your API key never touches the client.\n- **Fully typed** Luau with a small, predictable public API.\n- **Production-grade** — typed errors, structured logging with secret redaction,\n  exponential backoff with jitter, a circuit breaker, a bounded queue, and a\n  cross-server single-flight lease so many game servers don't stampede RoControl.\n- **Two integration modes** — declarative schedules (zero per-occurrence traffic)\n  and imperative `reportEvent` for ad-hoc/random events.\n\n> **v1 is server-only by use, not by location.** The module installs as a normal\n> package (`ReplicatedStorage.Packages`) and is inert on the client. What stays\n> server-only is your **API key** — keep it in `ServerStorage` and only call\n> `init()` from a server script.\n\n## Requirements\n\n- HTTP requests enabled for your experience (Game Settings → Security).\n- A RoControl API key (RoControl dashboard → your game → SDK → API Keys).\n- MemoryStore is optional but recommended for `reportEvent` (cross-server dedupe).\n\n## Installation\n\n### Option A — Wally (recommended)\n\n```toml\n# wally.toml\n[dependencies]\nRoControl = \"gh-constant/rocontrol-roblox-sdk@0.2.1\"\n```\n\n```sh\nwally install\n```\n\nIt's a normal `shared` package, so it installs into your usual `Packages` folder\n(typically `ReplicatedStorage.Packages`) — no special Rojo mapping. The SDK is\ninert on the client and `init()` is server-only, so the API key (in\n`ServerStorage`) never reaches clients.\n\n### Option B — Model file (`.rbxm`)\n\n1. Download `RoControl.rbxm` from the [latest release](https://github.com/Badacord/rocontrol-sdk/releases).\n2. In Studio, right-click **ReplicatedStorage → Insert from File** and pick the model.\n3. Confirm it lands where the server can require it (e.g. `ReplicatedStorage.Packages.RoControl`).\n\n### Option C — Source / Rojo\n\n```sh\ngit clone https://github.com/Badacord/rocontrol-sdk\ncd rocontrol-sdk\nrokit install\nwally install\nrojo build default.project.json --output RoControl.rbxm\n```\n\n## Where things go\n\n| What | Location |\n| --- | --- |\n| SDK module | `ReplicatedStorage.Packages.RoControl` (normal Wally package) |\n| API key | `ServerStorage/RoControlConfig/ApiKey` (a `StringValue`) — server-only |\n| Bootstrap script | `ServerScriptService/RoControlBootstrap.server.luau` |\n| Client code | **nothing in v1** (`init()` only runs on the server) |\n\n## Quickstart\n\n```lua\nlocal ServerStorage = game:GetService(\"ServerStorage\")\nlocal RoControl = require(ServerStorage:WaitForChild(\"RoControl\"))\n\nlocal client = RoControl.init({\n\tapiKey = ServerStorage.RoControlConfig.ApiKey.Value,\n\t-- baseUrl defaults to https://api.rocontrol.app\n\tlogLevel = \"info\",\n})\n\n-- Declarative: register a recurring schedule once at server start.\nclient:registerSchedule({\n\tkey = \"world-events\",\n\ttimezone = \"UTC\",\n\tcycleSeconds = 1800, -- one event every 30 minutes\n\teventDurationSeconds = 300, -- each shows for 5 minutes\n\trotation = { kind = \"sequential\" },\n\tevents = {\n\t\t{ key = \"Lava\", iconAssetId = \"rbxassetid://123\", durationSeconds = 300 },\n\t\t{ key = \"Toxic\", iconAssetId = \"rbxassetid://456\", durationSeconds = 300 },\n\t},\n})\n\n-- Imperative: report an ad-hoc event (admin/player/random triggered).\nclient:reportEvent({\n\tkey = \"BlackHole\",\n\ticonAssetId = \"rbxassetid://789\",\n\tdurationSeconds = 120,\n})\n\n-- Surface failures without crashing gameplay.\nclient:onFailedOperation(function(failed)\n\twarn(\"RoControl op failed:\", failed.operation, failed.error.kind, failed.error.message)\nend)\n```\n\n## Key rotation\n\nCreate a new key in the dashboard, update `ServerStorage/RoControlConfig/ApiKey`,\npublish, then revoke the old key. Keys are per-universe and capability-scoped.\n\n## Documentation\n\nFull docs: **[docs/index.md](docs/index.md)** — installation, schedules,\nreporting live events, security, and troubleshooting.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) (for AI coding\nagents). Security reports: [SECURITY.md](SECURITY.md).\n\n## License\n\n[Apache-2.0](LICENSE).\n","readmeTruncated":false}