API Reference

All types are exported from the root module (RoControl.<Type>).

`RoControl.init(config)` → `RoControlClient`

Creates a client. Raises a clear Config error on invalid input. Server-only: calling from the client errors.

Field	Type	Default	Notes
`apiKey`	`string`	—	Required. Per-universe key from the dashboard.
`baseUrl`	`string?`	`https://api.rocontrol.app`	Must be http(s).
`logger`	`Logger?`	built-in	Custom structured sink.
`logLevel`	`LogLevel?`	`"info"`	`silent \| error \| warn \| info \| debug`.
`metrics`	`MetricsSink?`	none	Optional metrics hook.
`httpTimeoutSeconds`	`number?`	`10`	1–60.
`maxRetries`	`number?`	`3`	0–10.
`retryBaseDelaySeconds`	`number?`	`0.5`	0–30.
`retryMaxDelaySeconds`	`number?`	`10`	0–120, `>= base`.
`circuitBreakerFailureThreshold`	`number?`	`5`	1–100.
`circuitBreakerCooldownSeconds`	`number?`	`60`	1–3600.
`enableMemoryStoreLease`	`boolean?`	`true`	Cross-server single-flight for `reportEvent`.
`studioMode`	`boolean?`	`false`	Friendlier logs in Studio.

`RoControlClient` methods

Method	Returns	Description
`registerSchedule(descriptor)`	`OperationResult`	Declarative schedule registration. Validates, normalizes, content-hashes, and coalesces identical schedules.
`reportEvent(input)`	`OperationResult`	Imperative event report (cross-server single-flight).
`buildScheduleFromRegistry(config)`	`RoControlSchedule`	Build a descriptor by scanning a `Folder` of event instances.
`onFailedOperation(cb)`	`RBXScriptConnection`	Fires on dispatch/network failure.
`retryFailedOperation(failed)`	`OperationResult`	Re-dispatch a failed operation.
`getHealth()`	`HealthStatus`	Circuit state, pending count, last success/failure.
`flush()`	`()`	Bounded wait until pending work drains (use in `BindToClose`).
`destroy()`	`()`	Stop accepting work, flush, release resources.

Schedule descriptor


type RoControlSchedule = {
	key: string,
	timezone: "UTC",
	cycleSeconds: number,        -- length of one cycle
	eventDurationSeconds: number, -- how long each event is "live"
	startsAtUnix: number?,       -- optional anchor (defaults to epoch-aligned)
	rotation: { kind: "sequential" }
		| { kind: "weighted", algorithm: "mulberry32-fnv1a32" },
	events: {
		{
			key: string,
			iconAssetId: string?, -- 123, "123", or "rbxassetid://123"
			durationSeconds: number?,
			priority: number?,    -- lower wins; advanced
			weight: number?,      -- weighted rotation only
		}
	},
}

Rotation defaults to sequential. Use weighted only if you need it — it uses the portable mulberry32-fnv1a32 algorithm the backend reproduces exactly; never rely on Roblox Random.new for the icon to match in-game. See Icon Automation Events.

Report input


type ReportEventInput = {
	key: string,
	label: string?,
	iconAssetId: string?,
	startedAt: number?,    -- unix seconds; defaults to now
	durationSeconds: number?,
	priority: number?,
	occurrenceId: string?, -- defaults to "<normalizedKey>:<startedAt>"
	metadata: { [string]: any }?,
}

Errors — `RoControlError`


{ kind: ErrorKind, message: string, retryable: boolean,
  statusCode: number?, requestId: string?, cause: any? }

Retry policy: Auth/Validation/Config never retry; RateLimit (honors Retry-After), Server, Timeout, and Transport retry idempotent operations with exponential backoff + jitter, guarded by a circuit breaker.

Metrics

If you pass a MetricsSink, the SDK emits rocontrol.sdk.* counters/timings: init, schedule.register.{attempt,success,failure}, event.report.{attempt,success,failure}, http.retry, lease.{win,loss,error}, circuit.{open,close}, queue.{enqueued,dropped}, and moderation.{pending,approved,rejected,failed} when the backend returns moderation state.

The full source lives at github.com/Badacord/rocontrol-sdk .