本文へ移動
Fizor LogoFizor/

FIZOR DOCUMENTATION

Loader API

Loader APIは、Roblox Lua側から公開済みScript releaseを取得するためのAPIです。

互換APIとして/api/loader/executeを残しています。新規LoaderではLua SDKの/loader/:scriptId.lua、/api/loader/check、/api/loader/loadを使います。

入口の選び方

Use caseRecommended entry point
最短のKey Loader/api/library.lua
固定URLでrelease配信/loader/<script-id>.lua
独自UIとsession制御/api/loader/check + /api/loader/load

/api/library.luaとStable Loaderはshared secretを必要としません。秘密情報はLuaへ配置しないでください。

基本フロー

POST /api/loader/checkはkeyとidentifierを検証し、sourceを含まない短命sessionを返します。

json
{
  "project": "main",
  "script": "hub",
  "script_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
  "identifier": "client-hwid-1"
}

POST /api/loader/loadはsessionを一度だけ消費し、配信直前にProject、Script、License、User、期限、HWID bindingを再検証してから最新版sourceを返します。

json
{
  "session": "fizor_session_v1...",
  "execution_id": "run_20260621_0001"
}

改変tokenはSESSION_INVALID、期限切れはSESSION_EXPIRED、再利用はSESSION_REPLAYED、check後に認可状態が変わった場合はSESSION_NOT_ACTIVEを返します。

実行中の再検証

Heartbeatを有効にしたScriptではload応答にheartbeat（session id、bearer token、interval、grace）が含まれます。SDKはPOST /api/loader/heartbeatをintervalごとに呼び、単調増加sequenceとserver clockに対して最大60秒のclient clock skewを検証します。同一sequenceはHEARTBEAT_REPLAYEDです。

各heartbeatはProject停止、Script停止、emergency stop、key ban/expiry、User状態、HWIDをDBから再検証します。DB障害はHEARTBEAT_UNAVAILABLE（503）でfail-closedとなり、SDKはgrace deadlineまで指数backoffで再試行し、超過時にcleanupとon_revoked callbackを呼びます。heartbeat無効時はruntime sessionを作らず、SDKからheartbeat通信も発生しません。interval/grace変更時は既存sessionをrevokeし、次回loadから新設定を適用します。

load応答のchecksumはsourceのSHA-256、signatureはScript ID・version・checksumを束縛するHMAC-SHA256です。signatureはserver側監査用で、clientへ秘密鍵は配布しません。

http
POST /api/loader/execute
Content-Type: application/json

互換APIのRequest

互換リクエストではscript_key / identifierを推奨します。

json
{
  "project": "main",
  "script": "hub",
  "script_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
  "identifier": "client-hwid-1",
  "executor": "manual-test"
}

互換用に既存のkey / hwidも受け付けます。

実行履歴の重複防止

retryする可能性がある場合は、論理実行ごとに一意な8〜128文字のexecution_idを指定します。x-execution-id headerも利用でき、headerが優先されます。

json
{
  "project": "main",
  "script": "hub",
  "script_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
  "identifier": "client-hwid-1",
  "execution_id": "run_20260621_0001"
}

同一Project・Script・execution_idのretryは一度だけ集計されます。同じexecution_idを別の実行で使い回すと、telemetryはretryとして扱います。key、identifier、IPの平文はtelemetryへ保存されません。

成功Response

json
{
  "ok": true,
  "script": "print('loaded')",
  "version": "1.0.0",
  "checksum": "sha256"
}

拒否Response

json
{
  "ok": false,
  "code": "IDENTIFIER_MISMATCH",
  "message": "Identifier does not match this key."
}

Rate limit

Loader APIはIP + key単位で120 requests/minに制限されます。keyなしのfree for all scriptではIP + project + script単位で制限します。

制限に達すると429とRATE_LIMITEDを返します。

次に読む