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. 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.

    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 — 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 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 — start fresh with the latest SDK
  • Setup Reference — full project configuration
  • Deploy — build with Godot’s export and install via Board Connect