OpenStarbound Mobile

A mobile-focused port of OpenStarbound for Android and iOS devices.

You must own a copy of Starbound. Base game assets are not provided for very obvious reasons.

The code is worked on whenever I have the spare time. Contributions and issues are welcome!

Installation

Download the latest release.

The latest stable release is recommended, as the nightly build can have bugs.

At the moment, you must have a copy of the game assets (packed.pak) to upload to the app.

Usage

Setting up

All you have to do is download your packed.pak from your game files. Find the root of your Starbound installation, and under the assets/ folder, you will find packed.pak. Send that to your phone through any method, and then you can select that in the launcher by clicking "Pick packed.pak". After selecting it once, you will never have to select it again (unless you delete your data).

Using/configuring controls

There are many features that oSBM has that you should know about.

• Direct screen touch gestures
• Gyro Aiming
• Aim joystick
• D-Pad
• Gamepad controls and remapping
• etc. in the Controls manager.

Controls Manager

The Controls manager is a menu in the oSBM launcher that can be accessed by clicking the Controls button in the main menu. Opening it up, you will be presented with many options.

There are touch control settings directly in the Controls manager, and a Gamepad Controls button that opens gamepad-specific settings. For touch controls, there are two sections to the manager: the general toggles at the top, and the configurable buttons/joysticks below. In the top section, you can enable/disable various options about the touch controls.

• Enable touch overlay: this toggles the actual usage of all touch controls.
• Enable direct screen touch gestures: this toggles if the user can touch the screen anywhere to act as a left click at that location (the virtual mouse is placed at the place of the tap, and a left click occurs). Holding down with one finger where you want to aim, and then tapping or holding down with a second finger on the screen will initiate a right click/hold, occurring at the aimed location of the first finger.
• Invert gyro X/Y axis: inverts the axis of the gyro if preferred.

Custom Buttons

You can add more custom buttons with some sort of interaction, such Tech, Codex, Chat, Interact, etc. Many of the essential functionalities are already created as buttons in the long list of options, though not all enabled by default. By clicking on the name of a button, it will open up details about it. In general, there will be the Displayed text, which you can change to change the name of the button and what is displayed on it in-game, the size which is self explanatory, the position, which can be adjusted visually with the Preview / Adjust Layout button at the top, the Interaction that occurs when the button is interacted with, and button behavior, which is Single press, Rapid fire/repeat, Hold, and Toggle. Single press runs the interaction once when the button is tapped. Rapid fire repeatedly runs the interaction while the button is held, hold will send the signal that the interaction should be held (typically the one you want), and toggle which is hold but instead of canceling when released it is canceled when it is tapped for the second time.

Macros

Macros let one touch button press multiple keyboard keys at the same time. They are useful for shortcuts that normally require a modifier key, such as emotes, menu shortcuts, or any custom keybinds you have set up in Starbound.

To make a macro, open a button in the Controls manager and use the Custom keys field under its interaction. Enter each key name separated by +, spaces, commas, or semicolons, then press Apply. If you enter one valid key, the button becomes a normal single-key action. If you enter multiple valid keys, the button becomes a macro.

Examples:

• LShift+F1
• LCtrl,LShift,Up
• LAlt E
• 1 for action bar slot 1

Key names should match the names used by the game, such as A, Space, Return, Esc, LShift, LCtrl, LAlt, Up, Down, F1, or 1. Invalid key names are ignored, so if a macro does not work, double-check the spelling and capitalization.

The selected button behavior applies to the whole macro:

• Single press: briefly presses all keys in the macro once.
• Rapid fire / repeat: repeatedly sends that same brief macro press while held.
• Hold: holds all keys in the macro down until you release the touch button.
• Toggle: holds all keys in the macro down until you tap the touch button again.

Macros are simultaneous key presses, not ordered scripts. For example, LCtrl+LShift+Up is treated like holding those three keys together, not pressing them one after another.

How to play

Just click Launch once the packed.pak has been selected! As long as Enable touch overlay is on, touch controls will show up in-game.

Building

Android (ARM64 APK)

Requirements

• CMake 3.23+
• Ninja
• Java 17
• Android SDK with:
  • platform-tools
  • platforms;android-35
  • build-tools;35.0.0
  • ndk;26.3.11579264
• vcpkg (set VCPKG_ROOT)

Environment variables

Set these before configuring:

export VCPKG_ROOT=/absolute/path/to/vcpkg
export ANDROID_SDK_ROOT=/absolute/path/to/android-sdk
export ANDROID_NDK_HOME="$ANDROID_SDK_ROOT/ndk/26.3.11579264"

Configure and build

From the repository source/ directory:

cmake --preset android-arm64-release
cmake --build --preset android-arm64-release --target android_apk --parallel

Debug build:

cmake --preset android-arm64-debug
cmake --build --preset android-arm64-debug --target android_apk --parallel

Build outputs

• Release APK: source/application/mobile/android/host/app/build/outputs/apk/release/app-release.apk
• Debug APK: source/application/mobile/android/host/app/build/outputs/apk/debug/app-debug.apk

iOS (ARM64)

Requirements

• macOS (Xcode 15+ recommended)
• Xcode command line tools
• CMake 3.23+
• vcpkg (set VCPKG_ROOT)

Option A: compile-only check (preset)

From source/:

cmake --preset ios-arm64-debug
cmake --build --preset ios-arm64-debug --target starbound --parallel

Option B: build unsigned .ipa locally (matches CI workflow)

From repository root:

cmake -S source -B build/ios-arm64-ipa \
  -G Xcode \
  -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_OVERLAY_TRIPLETS="$PWD/triplets" \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_SYSROOT=iphoneos \
  -DCMAKE_OSX_ARCHITECTURES=arm64 \
  -DCMAKE_BUILD_TYPE=Release \
  -DVCPKG_TARGET_TRIPLET=arm64-ios-mixed \
  -DSTAR_ENABLE_STEAM_INTEGRATION=OFF \
  -DSTAR_ENABLE_DISCORD_INTEGRATION=OFF \
  -DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED=NO \
  -DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_REQUIRED=NO \
  -DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_IDENTITY=""

Build and package the unsigned .ipa in one step using the ipa CMake target:

cmake --build build/ios-arm64-ipa --config Release --parallel --target ipa

The ipa target:

1. Builds starbound (and all dependencies) if out of date
2. Deletes any previous ipa/Payload/ directory and unsigned .ipa
3. Copies the full current app bundle (binary + assets + Info.plist) into ipa/Payload/OpenStarbound.app/
4. Zips the result into the final .ipa

Do not package a manually staged Payload directory. Re-run the ipa target whenever you need a fresh installable build; it is the only step that writes the final IPA payload.

Resulting file:

• build/ios-arm64-ipa/ipa/OpenStarbound-iOS-Release-unsigned.ipa

CI (manual workflows)

If you prefer GitHub Actions artifacts instead of local packaging:

• Android manual workflow: .github/workflows/android-manual.yml
• iOS manual workflow: .github/workflows/ios-manual.yml