# Quick Start

Get a Board game running on real hardware in roughly five minutes. For a deeper tour of every project setting, see [Setup Reference](https://docs.dev.board.fun/godot/getting-started/setup-reference).

## Prerequisites

- **Godot 4.6.x stable** with Android export templates installed
- **JDK 17** (Godot 4.6 ships Java 17 bytecode — JDK 11 fails at AGP class-version validation)
- **Android SDK** with `build-tools;35.0.1` and `ndk;28.1.13356709`
- **A Board** running BoardOS 1.10.0 or later, reachable on your network for Board Connect

> **Note**: This SDK only deploys to Board hardware. Every `Board.*` call no-ops when `Board.is_on_device` is `false`, so editor previews and desktop builds don’t crash.

## Steps

1. **Install the SDK.** Download the SDK from [https://dev.board.fun/](https://dev.board.fun/) and copy the addon into your Godot project.

```
    # after downloading and unpacking the SDK to ~/Developer/board-godot-sdk
    mkdir -p path/to/your-project/addons
    cp -R ~/Developer/board-godot-sdk/addon/addons/board_sdk path/to/your-project/addons/
```

Open the project in Godot and enable `board_sdk` under **Project > Project Settings > Plugins**. That registers the `Board` autoload and wires the AAR into Android exports.

2. **Install the Custom Android Build Template.** Open the project in Godot and run **Project > Install Android Build Template**. This drops a copy of Godot’s Android template into `android/build/`, which Godot’s exporter builds against. The compiled `board.aar` ships pre-built in the addon, so there’s no separate build step.

Then make a one-time edit to `android/build/build.gradle`: in the `aaptOptions` block, add a `noCompress` line right after `ignoreAssetsPattern`:

```
    aaptOptions {
        ignoreAssetsPattern "..."
        noCompress "pck", "sparsepck"
    }
```

Godot’s stock template doesn’t set this. Without it the PCK is deflated inside the APK and cold boot takes ~2 minutes instead of a few seconds.

3. **Install a Piece Set Model.** Pieces are recognized by an on-device TFLite model, one per Piece Set. The SDK ships no model (the right one depends on your game’s Piece Set), so fetch one — with the helper, or by hand.

```
    ./scripts/install_models.sh --list             # see what's available
    ./scripts/install_models.sh --all              # download everything (~8 MB)
```

**No terminal?** Open the manifest at [dev.board.fun/downloads/models/manifest.json](https://dev.board.fun/downloads/models/manifest.json), pick a Piece Set, and download its `.tflite` (the entry’s `url`). Put the file in your project’s `assets/models/` folder (create it if it isn’t there). Godot won’t _list_ the `.tflite` in its FileSystem dock — it has no importer for that type, so there’s no thumbnail and no `.import` file (expected, not an error) — but the file is there, and a normal export bundles it into the PCK. The model loads from the PCK at runtime, so once it’s in your project a vanilla export Just Works — no asset staging.

4. **(Optional) Run the sample.** The bundled `sample/` project exercises every domain — input, session, save, avatar, pause. Open `sample/project.godot` in Godot to poke at it before wiring up your own scene.

5. **Build the APK.** Use Godot’s own Android export — no build scripts required. In the editor, run **Project > Export Project… > Android**, or build headless:

```
    godot --headless --export-debug "Android" build/your-game.apk
```

With `gradle_build/use_gradle_build=true` in the Android export preset, this runs the Gradle build, bundles the addon’s `board.aar` (so `libboard.so` is present for the install gate) and the Piece Set Model into the PCK, and signs with the debug keystore.

6. **Install and launch.** Board games install over Board Connect, the Board’s built-in HTTP API — no USB cable.

**From a browser (human):** Open the Board Connect web UI (the Board shows its address under **Settings > System**) and drag the `.apk` onto it. Then launch your game from the Library.

**From an agent (Claude Code):** Use the `board-connect` CLI — the agent-facing Board Connect client, no ADB and no scripts. Install it from [dev.board.fun/connect/install](https://dev.board.fun/connect/install). Pair once (tap **Approve** on the device), then install, launch, and tail logs:

```
    board-connect pair <host>
    board-connect install <apk> --launch
    board-connect launch <package>
    board-connect logs <package>
    board-connect screenshot --out shot.png
```

Only `pair` takes the Board’s address (the one-time approval step also saves it as the default). Every later command resolves the target from that saved default, so they need no address. Use `board-connect logs <package> --follow` to stream logs live while debugging.

> **Note**: The Board’s install gate rejects any APK that doesn’t contain `lib/arm64-v8a/libboard.so` (“this APK is not built with Board SDK”). The bundled `board.aar` includes it, so a standard export passes the gate automatically.

> **Note**: For greenfield projects, the bundled `bootstrap-board-godot-game` Claude Code skill scaffolds a complete project (autoload registered, sample input handler, export preset pre-configured). Install it from the SDK’s bundled skills directory into `~/.claude/skills/`, then open Claude Code and run `/bootstrap-board-godot-game`.

## Next Steps

- [Setup Reference](https://docs.dev.board.fun/godot/getting-started/setup-reference) — every project setting and the full prerequisites table
- [Deploy](https://docs.dev.board.fun/godot/getting-started/deploy) — exporting the APK, installing over Board Connect, and troubleshooting
- [Sample Scene](https://docs.dev.board.fun/godot/getting-started/sample) — walkthrough of the bundled sample