Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HarbourMasters/Starship/llms.txt

Use this file to discover all available pages before exploring further.

Building Starship on Windows requires Visual Studio 2022 with the C++ workload, CMake, and at least 8 GB of RAM. The steps below walk you through cloning the repository, generating asset archives, and producing a distributable ZIP.
Machines with only 4 GB of RAM have seen compiler failures. 8 GB is the minimum recommended amount.

​
Prerequisites

Install each of the following before proceeding:
RequirementNotes
RAM8 GB minimum
Visual Studio 2022 CommunityFree edition is sufficient — select the Desktop development with C++ workload during installation
Windows SDK 10.0.19041.0Included automatically when you select the C++ workload
MSVC v143 toolsetCheck MSVC v143 – VS 2022 C++ x64/x86 build tools in the VS Installer details panel
Python 3Install standalone from python.org for best results
GitInstall standalone from git-scm.com for best results
CMakeInstall via cmake.org or Chocolatey (choco install cmake)
It is recommended that you install Python and Git as standalone applications rather than through the Visual Studio Installer — the VS Installer path has caused issues for some users in the past.

​
Visual Studio workload selection

When running the VS 2022 installer, check Desktop development with C++. This automatically selects a compatible Windows SDK. Then, in the Installation details panel on the right, verify that the MSVC v143 – VS 2022 C++ build tools component is also checked (it usually is by default).

​
Building Starship

You must clone the repository with --recursive, or run git submodule update --init after cloning, to pull in the libultraship submodule. The build will fail without it.
Open PowerShell and follow these steps:
1

Clone the repository

git clone https://github.com/HarbourMasters/starship.git --recursive
cd starship
If you already cloned without --recursive, initialise submodules now:
git submodule update --init
2

Configure CMake

Generate the Visual Studio 2022 project files targeting the x64 architecture:
& 'C:\Program Files\CMake\bin\cmake.exe' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64
Add -DCMAKE_BUILD_TYPE:STRING=Release to this command if you intend to create a distributable package.
3

Generate sf64.o2r

Extract game assets from your ROM to produce the sf64.o2r archive:
& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 --target ExtractAssets
4

Generate starship.o2r

Package the port-specific assets into starship.o2r:
& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64 --target GeneratePortO2R
5

Compile the project

Build the final Starship executable:
& 'C:\Program Files\CMake\bin\cmake.exe' --build .\build\x64
Add --config Release to the command above when packaging.The compiled executable will be located inside .\build\x64.

​
Development Workflows

​
Visual Studio

If you prefer to work inside Visual Studio, generate the solution file with the same CMake command used in Step 2 and then open build/x64/Starship.sln: 
# Generates Starship.sln inside build/x64 for Visual Studio 2022
& 'C:\Program Files\CMake\bin\cmake.exe' -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64

​
Visual Studio Code

Open the cloned repository folder directly in VS Code. The CMake Tools extension provides one-click build and debug support.
You can also substitute Ninja as the build system instead of MSVC for potentially better incremental build performance.

​
Generating a Distributable

After a successful build, package everything into a ZIP archive: 
cd "build/x64"
& 'C:\Program Files\CMake\bin\cpack.exe' -G ZIP

​
Additional CMake Targets

​
Clean

Remove all build artefacts and force a full rebuild on the next run: 
& 'C:\Program Files\CMake\bin\cmake.exe' --build build-cmake --target clean

​
CI Setup for Forks

Starship’s CI pipeline uses GitHub Actions. The Extract Assets step requires a self-hosted runner because it needs access to your ROM file. To configure this on your own fork:
  1. Go to Settings → Actions → Runners in your GitHub repository.
  2. Add a new self-hosted runner and assign it the asset-builder tag.
  3. Follow GitHub’s documentation to configure the runner as a service.
On Windows runners you must allow unsigned scripts in PowerShell before the CI agent can execute build scripts. Open PowerShell as Administrator and run:
Set-ExecutionPolicy RemoteSigned
You will also need 7-Zip installed and available on PATH (e.g. via choco install 7zip).

Build docs developers (and LLMs) love

Get started for freeTalk to us