# Setup Reference

The reference you come back to when something isn’t working. For a faster on-ramp, see [Quick Start](https://docs.dev.board.fun/godot/getting-started/quick-start).

## Developer Access

The Board Godot SDK is available from the developer portal at [dev.board.fun](https://dev.board.fun/). See [board.fun](/content/site-root.html) for developer-program details, Piece Set availability in your region, and how to request a Board if you don’t already have one.

## Prerequisites

| Tool | Version | Install |
| --- | --- | --- |
| **Godot** | 4.6.x stable | `brew install --cask godot` or godotengine.org |
| **JDK 17** | OpenJDK 17 | Temurin / Microsoft / Oracle |
| **Android SDK** | platform-tools, `build-tools;35.0.1`, `ndk;28.1.13356709` | `sdkmanager` |
| **Android export templates** | Matches your Godot version | Godot Editor: Manage Export Templates |
| **board-connect** | Latest stable | `curl -fsSL https://dev.board.fun/downloads/board-connect/install.sh \| bash` |

> **Warning**: JDK 11 will not work. Godot 4.6 emits class-file version 61 (Java 17) bytecode and AGP rejects it when the JDK target is 11.

## Install the SDK

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

```
mkdir -p path/to/your-project/addons
cp -R path/to/board-godot-sdk/addon/addons/board_sdk path/to/your-project/addons/
```

The compiled `board.aar` ships inside the addon at `addons/board_sdk/android/bin/debug/board.aar` — no separate build step.

Open the project in Godot. Under **Project > Project Settings > Plugins**, tick **Enabled** next to `board_sdk`. That registers the `Board` autoload (verify under **Project > Project Settings > Autoload**) and activates the `EditorExportPlugin` that bundles `board.aar` into every Android export.

## Install onto a Board

You install over Board Connect, the Board’s built-in HTTP service — no USB cable. The Board shows its address under **Settings > System**. Board Connect requires BoardOS 1.10.0 or later.

**From a browser (human):** open the Board Connect web UI at the Board’s address and drag your `.apk` onto it. The app then appears in the Library.

**From an agent:** use the [`board-connect`](https://docs.dev.board.fun/godot/getting-started/deploy) CLI (the agent-facing Board Connect client — no ADB, no scripts; install it from [dev.board.fun/connect/install](https://dev.board.fun/connect/install)). Pair once with `board-connect pair <host>` (the user taps **Approve** on the device), which saves that Board as the default so later commands need no address. Then drive installs with `board-connect install <apk> --launch`, `board-connect launch <package>`, `board-connect logs <package>` (add `--follow` to stream live), and `board-connect screenshot --out shot.png`. Pairing is a one-time step.

## Project Settings

The Board hardware is a fixed-target device: 1920x1080 landscape, no rotation, GL Compatibility renderer.

```
[application]
config/name="Your Game"
run/main_scene="res://main.tscn"

[autoload]
Board="*res://addons/board_sdk/board.gd"

[display]
window/size/viewport_width=1920
window/size/viewport_height=1080
window/handheld/orientation=0

[rendering]
renderer/rendering_method="gl_compatibility"
renderer/rendering_method.mobile="gl_compatibility"
textures/vram_compression/import_etc2_astc=true
```

| Setting | Why |
| --- | --- |
| `viewport_width=1920`, `viewport_height=1080` | Board’s native resolution. |
| `window/handheld/orientation=0` | Landscape sensor. |
| `rendering_method="gl_compatibility"` | The only renderer validated for the MediaTek Genio 700. |
| `textures/vram_compression/import_etc2_astc=true` | Required for Android export — Godot gates the Android target on ETC2/ASTC texture compression. Without it, **Export Project** is disabled. |

## Export Preset

Open **Project > Export…** and add an **Android** preset.

| Field | Value |
| --- | --- |
| `gradle_build/use_gradle_build` | `true` |
| `gradle_build/min_sdk` | `29` |
| `gradle_build/target_sdk` | `33` |
| `architectures/arm64-v8a` | `true` (all others `false`) |
| `package/unique_name` | reverse-DNS (e.g. `fun.mystudio.your_game`) |
| `package/name` | display string shown in BoardOS Settings |
| `screen/immersive_mode` | `true` |

## Install the Custom Android Build Template

Open the project in Godot and run **Project > Install Android Build Template**. This produces the `<project>/android/build/` directory. Check the template files into git so teammates don’t have to repeat the install.

This is also a one-time setup step. After installing the template, open `android/build/build.gradle` and add `noCompress "pck", "sparsepck"` to the `aaptOptions` block, right after the `ignoreAssetsPattern` line:

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

Godot’s stock template doesn’t set this. Without it, the PCK is stored deflated inside the APK and cold boot takes about two minutes instead of a few seconds. Commit this edit with the rest of the template.

## Piece Set Models

A Piece Set Model is a TensorFlow Lite `.tflite` file that the touch sensor’s inference loop consumes to classify Glyph patterns. Models are distributed from `https://dev.board.fun/downloads/models/manifest.json`.

```
./scripts/install_models.sh --list              # see what's available
./scripts/install_models.sh --name board-arcade # download one
./scripts/install_models.sh --all               # download everything
```

**No terminal?** Open the manifest at [dev.board.fun/downloads/models/manifest.json](https://dev.board.fun/downloads/models/manifest.json) in a browser, pick a Piece Set, and download its `.tflite` (the entry’s `url`). Create an `assets/models/` folder in your project (the SDK ships none — Piece Sets are game-specific) and put the file there. Godot won’t _list_ the `.tflite` in its FileSystem dock (no importer, so no thumbnail and no `.import` file — that’s expected, not an error); the file is present regardless and the export `include_filter` (`assets/models/*.tflite`) bundles it into the APK.

Models land in `assets/models/` and get bundled into the PCK by Godot’s export (the export `include_filter` is `assets/models/*.tflite`). The model loads from the PCK at runtime, so a vanilla export Just Works — no separate asset-staging step. Reference models by their asset-relative path:

```
Board.input.activate("models/arcade_v1.3.7.tflite")
```

## Scene Setup

The Godot SDK works through a single autoload — no per-scene wiring. Once `board_sdk` is enabled, every scene has `Board` available. The autoload guards itself off-device, so editor previews and desktop builds run without throwing.

```
func _ready() -> void:
    if not Board.is_on_device:
        return
    Board.initialize(APP_ID)
    Board.input.activate("models/arcade_v1.3.7.tflite")
    Board.input.subscribe()
```

## Build the APK

No build script is required. Build the APK with Godot’s own export, which 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.

**From the editor:** **Project > Export Project… > Android**, then choose an output path.

**Headless / CI:**

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

For the Gradle build to run (and for `board.aar` to be bundled), the Android export preset must have `gradle_build/use_gradle_build=true` — see [Export Preset](https://docs.dev.board.fun/godot/getting-started/setup-reference#export-preset).

## Project Checklist

- [ ] `addons/board_sdk/android/bin/debug/board.aar` exists
- [ ] **Plugins** shows `board_sdk` as Enabled
- [ ] **Autoload** shows `Board` at `res://addons/board_sdk/board.gd`
- [ ] `project.godot` matches the resolution, orientation, and renderer settings above
- [ ] `export_presets.cfg` has the Android preset with `arm64-v8a` only and `use_gradle_build=true`
- [ ] `android/build/` exists, with `noCompress "pck", "sparsepck"` added to its `aaptOptions` block
- [ ] At least one `.tflite` model is at `assets/models/`
- [ ] A debug keystore is available at `~/Library/Application Support/Godot/keystores/debug.keystore`

If all pass, **Project > Export Project… > Android** (or `godot --headless --export-debug "Android" <out>.apk`) produces a signed, ready-to-install APK. Install it onto a Board over Board Connect — drag the `.apk` onto the Board Connect web UI, or use the `board-connect` CLI from an agent.

## Next Steps

- [Quick Start](https://docs.dev.board.fun/godot/getting-started/quick-start) — the fastest path
- [Deploy](https://docs.dev.board.fun/godot/getting-started/deploy) — build with export, then install over Board Connect
- [Upgrading](https://docs.dev.board.fun/godot/getting-started/upgrading) — moving between SDK versions