# Upgrading

How to move an existing Board Godot SDK install to the latest version. The SDK is a Godot addon under `addons/board_sdk/` backed by a separately-built native AAR — both need to upgrade together.

## Steps

1. **Review the [Changelog](https://docs.dev.board.fun/godot/changelog).** Read the entries between your current version and the latest. Pay attention to **Changed** and **Removed** — those are the places code-level migration is needed.

2. **Download the latest SDK.** Get the latest release from the [download page](https://dev.board.fun/).

Then replace the in-project addon:
   
   
   ```
       rm -rf path/to/your-project/addons/board_sdk
       cp -R path/to/downloaded-sdk/addon/addons/board_sdk path/to/your-project/addons/
   ```

3. **Reload the project.** Open the project in Godot. If the plugin reports compile errors after the upgrade, **Project > Reload Current Project** forces a re-import of the addon.

4. **Rebuild and reinstall.** Export the project again with Godot’s own Android export — the new `board.aar` ships inside the addon, so a fresh export picks it up automatically. In the editor: **Project > Export Project… > Android**. 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. The model loads straight from the PCK, so a vanilla export Just Works — no asset staging.

Then install the new APK over Board Connect (HTTP on the LAN, port 8843 — no USB cable). **Human:** open the Board Connect web UI in a browser (the Board shows its address under **Settings > System**) and drag the `.apk` onto it, then launch from the Library. **Agent:** use the [`board-connect` CLI](https://dev.board.fun/connect/install) — `board-connect pair <host>` once (tap **Approve** on the device, which also saves that Board as the default), then `board-connect install <apk> --launch`, and `board-connect logs <package>` / `board-connect screenshot --out shot.png` to confirm. Every command after `pair` resolves the target from the saved default, so no address is repeated.

> **Note**: The compiled `board.aar` is bundled with the addon — replacing the `addons/board_sdk` directory updates the AAR and the GDScript together. No separate AAR build step.
>
> **One-time setup carries over.** If you set up this project before, the Custom Android Build Template and the `noCompress "pck", "sparsepck"` line in `android/build/build.gradle`’s `aaptOptions` block are already in place and don’t need to be redone on upgrade. If you’re moving to the Gradle export for the first time, see [Deploy](https://docs.dev.board.fun/godot/getting-started/deploy) for that one-time step (without it the PCK is deflated inside the APK and cold boot takes ~2 minutes instead of a few seconds).

## Troubleshooting

- **Plugin loads but signals never fire.** The addon copy is stale. Re-copy the addon directory and reload the project.
- **Compile errors after upgrade.** Same fix: re-copy the addon into your project (`cp -R path/to/downloaded-sdk/addon/addons/board_sdk path/to/your-project/addons/`) and reload the project.

## Next Steps

- [Quick Start](https://docs.dev.board.fun/godot/getting-started/quick-start) — start fresh with the latest SDK
- [Setup Reference](https://docs.dev.board.fun/godot/getting-started/setup-reference) — full project configuration
- [Deploy](https://docs.dev.board.fun/godot/getting-started/deploy) — build with Godot’s export and install via Board Connect