Creator & agents

Use the SDK to build the game itself. Use Creator Portal as your account workspace to review games and connect an agent. You do not need to configure CI in your game's repository to use Creator.

Surface	What you do there	Sign-in
Developer docs	Learn the SDK, run an example, integrate a host and test your game	None
Creator Portal	Review game details, version status and publication; create or revoke API keys	Your Fah Google or Apple account
Creator skill	Give an agent instructions for game operations through the Backend API	Public to read; an API key is needed to act

Connect an agent

Choose your environment before creating a key. Production and staging have separate accounts, games, publication state and credentials; a staging key cannot manage production games.

Environment	Documentation	Creator Portal	FAH_CREATOR_ORIGIN
Production	Production docs	Production Creator	https://fah.portal-interactive.com
Staging	Staging docs	Staging Creator	https://staging.fah.portal-interactive.com

1. Open Creator Portal in your chosen environment. Sign in with the same Google or Apple account you use in that Fah environment.
2. Choose Connect your agent and create a named key. The default includes games you already manage and future games, so you do not need to choose game IDs in advance. Use advanced access to narrow the selection. Enable release permissions if you want the agent to publish, roll back or unpublish.
3. Save the one-time key in your agent's local environment or secret manager as FAH_CREATOR_API_KEY. Set FAH_CREATOR_ORIGIN to the matching origin in the table. Keep the key out of chat, source files and commits.
4. Copy the agent instructions from Creator, or give the agent the matching public Creator skill: production or staging. The Backend serves this Markdown directly and links to its Python client; GitHub access is not needed to read the skill.
5. Tell the agent what to build or change. Return to Creator to review game details, versions and release status.

Use staging for integration testing and production for published games. A key's access follows your current game roles. Revoke unused keys in API keys; signing out of the browser does not revoke agent access.

Build and manage a game

Start with Getting started, then adapt the example and follow the game requirements. The SDK handles runtime behavior such as lifecycle, input, audio and graphics; it does not provide an account session or Creator API key.

Today, an agent uses the Creator API to create game records, edit draft metadata, register versions and change publication. The Portal's game views are read-only; the human controls agent access. The public skill describes the current API, permissions, conditional updates and recovery rules. Use it as the reference for those operations instead of treating SDK runtime methods as publishing commands.

Package a release

Build and test the game locally using the SDK checks. Your repository does not need publishing CI, cloud credentials or a Fah service account. An agent uploads using your scoped Creator key.

A ZIP release contains the game, the approved SDK and any shared libraries:

g/my-game/index.html
g/my-game/game.json
g/my-game/assets/...
g/my-game/preview/poster.webp
g/my-game/preview/loop.mp4
kit/portal-kit.js
lib/...

Include the game manifest and license notices. Use relative imports such as ../../kit/portal-kit.js and ../../lib/three/three.module.min.js from the game entry. The platform serves the complete ZIP under an immutable /releases/{versionId}/ prefix; root-relative /kit/ URLs will fail.

Use the unmodified portal-kit 0.3.0 browser bundle. Its approved SHA-256 is f464105465a3dc5a8fb7f3af188cecca89817af15e177d5091280be50a3e8a03. A matching version label alone does not approve a different bundle. Keep SDK and third-party notices with the release. For campaign games, use session: "long"; publishing does not impose a timer or reset player progress. See managed saves for checkpoint and compatibility requirements.

The ZIP is limited to 16 MiB compressed, 64 MiB expanded and 1,000 regular files. Up to 128 MiB may be queued per uploader. Paths use ASCII letters, numbers, _, -, ., and /; hidden files, dot segments, duplicate entries, symlinks, encryption and directory-only entries are rejected. Use stored or deflated compression. Include files only under your game's g/{id}/, kit/ and lib/ directories.

Upload, review and publish

1. Ask your agent to create a game record using a permanent game ID and your card metadata.
2. Register a new UUID v4 version. Hash the exact ZIP bytes for artifactDigest and the exact packaged game.json bytes for manifestDigest. Record the full source commit and SDK version. The manifest's ID, SDK version, source commit and card metadata must agree with the version record.
3. Upload that ZIP to the registered version. The matching environment's Creator skill linked above provides the prepare-upload and send commands, permission details and safe retry rules.
4. Check the version in Creator. Upload acceptance means the bytes entered quarantine. The trusted worker verifies hashes, archive paths, metadata, approved SDK bytes and immutable delivery. Wait for validation ready before publishing. Rejected versions need a corrected package and a new UUID; the status detail explains the failed check. Temporary storage outages remain pending and retry.
5. After your game tests pass, ask the agent to publish the ready version. Publication uses the current publication ETag, so another person's change cannot be overwritten silently.
6. Open the production feed or staging feed for the environment you published to, optionally with ?g=my-game to open that game. The feed reads the published catalogue; it does not need a Web rebuild. Allow up to 15 seconds for catalogue caches, then refresh an existing tab.

The Portal keeps game and release views read-only; your agent performs uploads and release actions. The human controls access through Connect your agent and API keys. No upload or publish form is required in the Portal to complete this workflow.

Ready confirms bundle integrity and delivery, not gameplay quality or save compatibility. Exercise start, pause/resume, input, audio and save/load before publication. Test a signed-in player and a fresh browser session when the game uses cloud saves. Temporary validation failures do not expose your quarantined ZIP; after delivery, immutable asset URLs remain accessible even if the game is unpublished.

Update or roll back

Build an update as a new version; never overwrite an existing release. Publishing changes the catalogue pointer, and fresh page loads use the new version. A running game may continue its existing version. Saves belong to the player and permanent game ID, so they survive version changes. Keep snapshot migration and backwards compatibility in your game before selecting an older ready version to roll back. Unpublishing removes discovery; it does not erase player saves or invalidate already delivered URLs.

Continue from here

• Run your first game for the local development loop.
• SDK API for runtime calls and game callbacks.
• Host integration for embedding games in a feed or native app.
• Creator Portal in production or staging for the matching account workspace.