AI Tools

Alpha Version: This is the v2 engine documentation. Features and APIs may change.

How It Works

Floaty's AI tools let you use coding assistants like Claude Code, Cursor, and GitHub Copilot to build and edit games directly from your IDE. No copy-paste between browser and editor.

Generate a token on your profile — one token per playground or plugin
Install a skillset for your AI agent
Give the agent your token and start building

Tokens are short-lived (12, 24, or 48 hours) and scoped to a single resource. A playground token lets the agent read and write scripts for that playground. A plugin token lets the agent read and write plugin drafts and mint versions.

Getting a Token

Log in and go to your profile
Scroll to API Tokens and click New Token
Select Playground or Plugin and pick your resource (or create a new one)
Choose an expiry (12h, 24h, or 48h) and click Generate Token
Copy the token — you can copy it again anytime from the token list

Each token is tied to one resource. If you need to edit both a playground and a plugin, you'll need two tokens.

API Reference

Base URL: https://floaty.dev/api/v1

All requests require these headers: Authorization: Bearer <token>, Content-Type: application/json, and Accept: application/json.

Playground Endpoints

Method	Path	Description	Access
GET	`/api/v1/playground`	Read script, metadata, plugins	Owner + collaborators
PUT	`/api/v1/playground`	Write script	Owner + collaborators
PUT	`/api/v1/playground/meta`	Update title, background, visibility	Owner only
PUT	`/api/v1/playground/plugins`	Update plugin associations	Owner only
GET	`/api/v1/playground/plugins/{uuid}`	Read attached plugin script + releases	Owner + collaborators
GET	`/api/v1/playground/plugins/{uuid}/releases/{releaseUuid}`	Read specific release of attached plugin	Owner + collaborators

Plugin Endpoints

Method	Path	Description	Access
GET	`/api/v1/plugin`	Read draft script, metadata, latest release	Owner only
PUT	`/api/v1/plugin`	Write draft script	Owner only
PUT	`/api/v1/plugin/meta`	Update title, description, visibility	Owner only
POST	`/api/v1/plugin/release`	Create new version from current draft	Owner only
GET	`/api/v1/plugin/releases`	List all releases	Owner only
GET	`/api/v1/plugin/releases/{uuid}`	Read a specific release script	Owner only

Error Codes

Code	Meaning
401	Token expired or invalid — regenerate on your profile
403	Wrong token type or insufficient permissions
422	Validation error (missing field, script larger than 1MB)
429	Rate limited (60 requests/minute on write endpoints) — wait and retry

Installing the Skillset

Claude Code

BASE=https://raw.githubusercontent.com/floaty-dev/agent-skills/main/claude-code/floaty
for f in SKILL.md api-reference.md engine-reference.md; do
  curl -sL "$BASE/$f" --create-dirs -o ".claude/skills/floaty/$f"
done

Then use /floaty in Claude Code to start a session.

Cursor

curl -sL https://raw.githubusercontent.com/floaty-dev/agent-skills/main/cursor/.cursor/rules/floaty.mdc \
  --create-dirs -o .cursor/rules/floaty.mdc

GitHub Copilot

curl -sL https://raw.githubusercontent.com/floaty-dev/agent-skills/main/copilot/.github/instructions/floaty.instructions.md \
  --create-dirs -o .github/instructions/floaty.instructions.md

Prompting Your Agent

Once the skillset is installed and you've given the agent your token, try prompts like:

"Read the current playground script and explain what it does"
"Add keyboard controls to move the player with arrow keys"
"Create a simple platformer with gravity and jumping"
"Read the plugin script and add a health bar helper"

The agent will use the API to read the current script, make changes, and write it back. You can preview the result in your browser at https://floaty.dev/en/playground/{uuid}.

Tip: The playground editor is not multi-user. If you have the editor open while an agent writes to the same playground via the API, clicking Run will save the version you see in the editor — overwriting whatever the agent has changed since you opened it. Use the full-screen preview URL instead when working with an agent.

Editor: https://floaty.dev/en/playground/{uuid}
Preview (full screen): https://floaty.dev/en/playground/{uuid}/preview

You can ask your agent for the UUID — it's included in the API response when reading a playground.

Checking for Skill Updates

Each skill file checks for updates at the start of every session by comparing the local file against the latest version in the skills repository . If an update is available, the agent will ask before making changes.

To manually update, re-run the install command for your agent.