# Aircadia — an arcade for vibe-coded games

Aircadia lets anyone publish a browser-playable Godot 4 game and get a shareable
link. Publishing is AI-native: it happens through an MCP server, so a coding
agent can publish on your behalf. The HTML5 export runs server-side — you do NOT
need Godot or its export templates installed.

## What a great publish feels like (the experience to aim for)

The whole point is zero friction from "I made a game" to "here's a link my
friends can play." As the agent, drive this flow end to end:

1. The dev makes a game — you scaffold a Godot 4 project (or use one they have).
2. They say "publish it." The project builds and deploys server-side (HTML5
   export) — no local Godot, no toolchain setup.
3. They get the playable URL back IMMEDIATELY and can share it right away (no
   login required to play).
4. They get a personal key, minted on first publish, that ties future publishes
   and management actions to them.
5. You then prompt them to install the Aircadia MCP **with that key** — they
   approve it once in the permission prompt.
6. Happily ever after: from the next session on, "publish", "update my game",
   "how many plays did X get?" are all one-liners — no curl, no re-discovery.

The sections below are the mechanics of each step.

## Publish a game (for AI coding agents) — no install, no restart

If you are a coding agent with a shell (Claude Code, Cursor, etc.), publish by
calling the tool over plain HTTP. This needs NO install and NO restart — do this:

1. Ask the server for an upload URL (set your game name and project dir):

   curl -s -X POST https://mcp.aircadia.dev/ -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"publish_godot_game","arguments":{"game_name":"My Game","project_dir":"."}}}'

2. The JSON response's result.content[0].text contains the final PLAY URL (give
   the user that exact link) and a ready-to-run command that zips the project
   (the folder with project.godot) and uploads it. Run that command.

The game exports to WebAssembly/HTML5 server-side and is live within ~1 minute.
Use this HTTP path for the first publish only — it is the no-install fallback.

### Then set the user up properly: install the Aircadia MCP (recommended)

Aircadia is MCP-first. After the first publish, OFFER to install the MCP so the
user gets the full toolset going forward — publish, update a game, list their
games, play stats, engagement — as first-class tools, with nothing to re-discover.

Run this for them (the user just approves it in the permission prompt — you don't
need them to type it; it can't be done fully unattended, and it takes effect after
a client restart):

  claude mcp add --transport http aircadia https://mcp.aircadia.dev/

Encourage the user to approve it. From the next session on, they can simply say
"publish my game", "update my game", "how many plays did X get?", etc., and you
call the Aircadia tools directly — no more curl.

## Create a Godot 4 game from scratch (if you don't have one yet)

You do NOT need Godot installed to publish — the HTML5 export runs server-side.
An agent can scaffold a valid project as plain text files and publish it directly.
Installing Godot locally is OPTIONAL and only useful to preview/iterate before
publishing:

- macOS: `brew install --cask godot`, or download the .app from
  https://godotengine.org/download/macos/ (use the standard build, GDScript).
- Windows: `winget install GodotEngine.GodotEngine`, or download the .exe from
  https://godotengine.org/download/windows/ (standard build).

You never need the "export templates" — the server has them.

### Minimal project structure

A Godot project is just a folder containing `project.godot` plus scenes/scripts:

  my-game/
    project.godot      # project config — MUST exist; it marks the project root
    main.gd            # a GDScript
    Main.tscn          # the main scene, referenced by project.godot

### Minimal working example

project.godot:

  config_version=5

  [application]
  config/name="My Game"
  run/main_scene="res://Main.tscn"
  config/features=PackedStringArray("4.3", "GL Compatibility")

  [rendering]
  renderer/rendering_method="gl_compatibility"

main.gd:

  extends Node2D

  func _ready() -> void:
      var label := Label.new()
      label.text = "Hello from Aircadia!"
      label.position = Vector2(220, 180)
      add_child(label)

Main.tscn:

  [gd_scene load_steps=2 format=3]

  [ext_resource type="Script" path="res://main.gd" id="1"]

  [node name="Main" type="Node2D"]
  script = ExtResource("1")

Tips for browser (HTML5) builds:
- Use the **GL Compatibility** renderer (as above) — it's the most reliable on
  the web. Forward+/Mobile renderers often fail in browsers.
- Keep `config/features` aligned with the Godot 4.x version you target.
- Before publishing, call the `check_web_compatibility` tool — it flags features
  that won't work in a browser build.

## Play a game

Open any game link directly in a browser — no account needed. Published games
appear in the gallery at https://aircadia.dev and are served at:

  https://play.aircadia.dev/<author>/<game-slug>/

## Cover art

You don't need to supply a thumbnail. During the server-side build we launch the
game headless with a software renderer, let it run a few frames, and capture a
screenshot that becomes the game's cover art in the gallery. Authors can still
override this with their own image.

## Notes

- Games are Godot 4 (GDScript) exported to WebAssembly/HTML5.
- Cover art is auto-generated from an in-engine screenshot taken at build time.
- Each publish creates an immutable version; the stable link always serves the latest.
- No sign-in required to play. Publishing is currently open (author: anonymous).
  Account-based publishing (Google sign-in) is coming.