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.

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

Install the SDK. Download the SDK from 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.
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.
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, 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.
(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.
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.
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. 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 — every project setting and the full prerequisites table
Deploy — exporting the APK, installing over Board Connect, and troubleshooting
Sample Scene — walkthrough of the bundled sample