libultraship (LUS) is a library meant to provide reimplementations of libultra (n64 sdk) functions that run on modern hardware.
LUS uses an asset loading system where data is stored separately from the executable in an archive file ending in .otr or .o2r. .otr files are .mpq compatible files. .o2r files are .zip compatible files. This separation of data from executable follows modern design practices which are more mod friendly. All one needs to do is supply a patch .otr or .o2r and the system will automatically replace the data.
| Page | Description |
|---|---|
| Porting Guide | How to port an N64 game to PC using LUS. |
| Scripting | Writing and packaging C mods for the scripting system. |
| Fast3D Renderer | Overview of the Fast3D display-list renderer. |
| Contributing | How to contribute code, formatting guidelines, and CI troubleshooting. |
| Code of Conduct | Community standards for contributors. |
| Versioning | Epoch semantic versioning policy and epoch maintenance strategy. |
| API Reference | Doxygen-generated documentation for all public classes and functions. |
| Epoch 2 Migration Plan | Migration checklist and architecture notes for upgrading ports to epoch 2. |
LUS accepts any and all contributions. You can interact with the project via PRs, issues, email ([email protected]), or Discord. Please see the Contributing page for more information.
We use epoch semantic versioning. For the new epoch, versioning scope includes everything that is public within the Ship namespace.
This replaces the previous epoch rule that treated every C linkage function, variable, struct, class, public class method, or enum included from libultraship.h as part of the versioned API.
See Versioning for details.
Install system dependencies before building.
Linux (Debian/Ubuntu):
sudo apt-get install $(cat .github/workflows/apt-deps.txt)
macOS:
brew install $(cat .github/workflows/brew-deps.txt)
Then install the required Python packages (needed to generate asset keys):
pip install -r requirements.txt
cmake -H. -Bbuild
cmake --build build
On Windows, LUS uses vcpkg to manage C++ dependencies. Pass -DUSE_AUTO_VCPKG=ON to have CMake download and bootstrap vcpkg automatically. Alternatively, install the required ports manually with an existing vcpkg installation and pass -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake instead.
& 'C:\Program Files\CMake\bin\cmake' -DUSE_AUTO_VCPKG=ON -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64
& 'C:\Program Files\CMake\bin\cmake' --build .\build\x64
Requires Xcode on macOS. Set CMAKE_OSX_DEPLOYMENT_TARGET to the minimum iOS version you wish to support.
cmake -H. -Bbuild -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0
cmake --build build --config Release
Requires the Android NDK. Set ANDROID_NDK_HOME to the path of the extracted NDK directory.
cmake -S . -Bbuild-android -GNinja \
-DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
-DANDROID_NDK=$ANDROID_NDK_HOME \
-DANDROID_ABI=arm64-v8a \
-DANDROID_PLATFORM=latest \
-DANDROID_STL=c++_static \
-DCMAKE_BUILD_TYPE=Release
cmake --build build-android
Thank you to JetBrains for providing their IDE CLion to me for free!
LUS is licensed under the MIT license.
LUS makes use of the following third party libraries and resources:
.mpq compatible archive files.
.zip compatible archives.