libultraship

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.

Documentation

Full Documentation | API Reference

• Porting Guide - How to port an N64 game to PC using LUS
• Scripting Guide - Writing and packaging C mods
• Fast3D Renderer - Overview of the display-list renderer
• API Reference - Doxygen-generated API documentation

Contributing

LUS accepts any and all contributions. You can interact with the project via PRs, issues, email (kenixwhisperwind@gmail.com), or Discord. Please see CONTRIBUTING.md file for more information.

Versioning

We use epoch semantic versioning. Please see our versioning page for more information..

Building

Prerequisites

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

Linux / macOS

cmake -H. -Bbuild
cmake --build build

Windows

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.

Generating a Visual Studio solution (x64)

& 'C:\Program Files\CMake\bin\cmake' -DUSE_AUTO_VCPKG=ON -S . -B "build/x64" -G "Visual Studio 17 2022" -T v143 -A x64

Building

& 'C:\Program Files\CMake\bin\cmake' --build .\build\x64

iOS

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

Android

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

License

LUS is licensed under the MIT license.

LUS makes use of the following third party libraries and resources:

• Fast3D (MIT) render display lists.
• prism-processor (MIT) shader preprocessor.
• ImGui (MIT) display UI.
  • SDL3 (zlib) windowing and input backend.
  • glew (modified BSD-3-Clause and MIT) OpenGL extension loading backend (Windows/macOS).
  • metal-cpp (Apache 2.0) Apple Metal rendering backend (macOS/iOS).
• StormLib (MIT) create and read .mpq compatible archive files.
  • zlib (zlib) compression.
  • bzip2 (bzip2) compression.
• libzip (BSD-3-Clause) create and read .zip compatible archives.
  • zlib (zlib) compression.
• StrHash64 (MIT, zlib, BSD-3-Clause) provide crc64 implementation.
• nlohmann-json (MIT) json parsing and saving.
• spdlog (MIT) logging.
  • {fmt} (MIT) text formatting (bundled).
• stb (MIT) image conversion.
• thread-pool (MIT) thread pool for the resource manager.
• tinyxml2 (zlib) parse XML files for resource loaders.
• SDL3 (zlib) window manager, controllers, and audio player.
• glob_match (Dual MIT/GPL) Glob pattern matching.
• libgfxd (MIT) display list disassembler.
• libtcc (LGPL-2.1) C compiler used for the script system.
• monocypher (CC-0) cryptography library used for the modding system.