💘C × SDL3 × OpenGL — Three Mysterious Forces, United as One! Bong~ Bongocat!!!
English • 简体中文 • 繁體中文 • Français • Deutsch • 日本語 • 한국어 • Português • Русский • Español • Bahasa Indonesia
- GitHub Releases
Download the latest release from [GitHub Releases](https://github.com/vladelaina/BongoCat/releases/latest).
## 🛠️ Build From Source
BongoCat uses CMake and requires a C11 compiler, a C++17 compiler, CMake 3.24
or newer, and desktop OpenGL development files. SDL3, yyjson, stb, miniaudio,
and Nuklear are downloaded at configure time by default, so the first
configuration needs network access.
Run the commands below from the project root (the directory containing
`CMakeLists.txt`).
### 📋 Platform Prerequisites
- **Windows:** Visual Studio 2022 with the Desktop C++ workload and CMake.
Use the MSVC generator; MinGW can build the diagnostic backend but is not
supported for the Cubism SDK.
- **macOS:** Xcode Command Line Tools, CMake, and Ninja. Select an architecture
with `CMAKE_OSX_ARCHITECTURES` when it differs from the host default.
- **Linux (Debian/Ubuntu):** GCC or Clang, Ninja, and the OpenGL/X11 headers:
```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build \
libgl1-mesa-dev libx11-dev libxi-dev libxfixes-dev libfontconfig1-dev fonts-noto-cjk
```
### 🔧 Configure and Build
On Linux and macOS, use a single-configuration generator such as Ninja:
```bash
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DBONGO_CAT_FETCH_DEPS=ON
cmake --build build --parallel
```
On Windows, run from a Visual Studio 2022 developer shell (or another shell
where MSVC is available):
```powershell
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
-DBONGO_CAT_FETCH_DEPS=ON
cmake --build build --config Release --parallel
```
The executable is written to `build/BongoCat` on Linux, to
`build/BongoCat.app/Contents/MacOS/BongoCat` on macOS, and to
`build/Release/BongoCat.exe` for Visual Studio builds.
### 🧪 Tests
CTest targets are enabled by default. Run them after building:
```bash
ctest --test-dir build --output-on-failure
```
For a multi-configuration generator such as Visual Studio, select the build
configuration explicitly:
```powershell
ctest --test-dir build -C Release --output-on-failure
```
### 🎭 Live2D / Cubism SDK (Optional)
If the Cubism SDK is not present, CMake emits a warning and builds the
diagnostic backend. This backend is intended for startup and platform
diagnostics; it does not provide Live2D model rendering. To build the full
runtime, install a compatible Cubism SDK for Native and either place it at
`vendor/CubismSdkForNative` or pass its location explicitly:
```bash
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DBONGO_CAT_CUBISM_SDK=/path/to/CubismSdkForNative \
-DBONGO_CAT_REQUIRE_CUBISM=ON
```
The SDK must contain its Core library, Framework sources, and the OpenGL GLEW
third-party tree in the layout expected by `cmake/Cubism.cmake`. Windows
Cubism builds require Visual Studio 2022. `BONGO_CAT_REQUIRE_CUBISM=ON` makes
configuration fail instead of silently selecting the diagnostic backend.
### ⚙️ CMake Options
| Option | Default | Description |
| --- | --- | --- |
| `BONGO_CAT_FETCH_DEPS` | `ON` | Download the pinned third-party dependencies with CMake `FetchContent`. Set `OFF` only when SDL3, yyjson, stb, miniaudio, and Nuklear are already available to CMake. |
| `BONGO_CAT_CUBISM_SDK` | `vendor/CubismSdkForNative` | Path to the Cubism SDK for Native. |
| `BONGO_CAT_REQUIRE_CUBISM` | `OFF` | Fail configuration when a usable Cubism SDK is unavailable. |
| `BONGO_CAT_WARNINGS_AS_ERRORS` | `OFF` | Treat native compiler warnings as errors. |
For an offline build with `BONGO_CAT_FETCH_DEPS=OFF`, provide CMake package
configurations for SDL3 (including `SDL3-static`) and yyjson, plus the include
directories for stb, Nuklear, and miniaudio when they are not discoverable:
```bash
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DBONGO_CAT_FETCH_DEPS=OFF \
-DBONGO_CAT_STB_INCLUDE_DIR=/path/to/stb \
-DBONGO_CAT_NUKLEAR_INCLUDE_DIR=/path/to/nuklear \
-DBONGO_CAT_MINIAUDIO_INCLUDE_DIR=/path/to/miniaudio
```
## 📌 Project Status
## 📜 License
The BongoCat source code and native runtime are licensed under
[AGPL-3.0-only](LICENSE).
The default built-in model mode (`standard`) remains MIT-licensed. The
bundled model assets in `resources/assets/models/standard`, `keyboard`, and
`gamepad` are covered by the separate [MIT license notice](resources/assets/LICENSE-MIT).
That MIT license applies to the model assets and their accompanying artwork
only; it does not relicense the BongoCat source code or native runtime.
## 🧭 Technical Architecture
> The current native version is built on C/C++, SDL3, and OpenGL. The diagram below focuses on the runtime data flow; build and packaging details live in CMake.
### 🔄 Runtime Ownership and Frame Scheduling
Each process owns one `BongoCatApp` and one main-thread event and render loop.
Platform listeners stop at the input boundary:
```text
Platform listeners
(keyboard / pointer)
|
v
C11 input state
(atomic edge queue + coalesced pointer position)
|
v
main-thread application <----- SDL3 events
|
v
model parameters, overlay, and UI state
|
v
model update -> OpenGL composition -> platform presentation
```
The Windows Raw Input receiver, macOS Quartz event tap, and Linux XInput2 listener
run outside the main loop. They publish timestamped key and mouse-button edges
to the bounded atomic queue and coalesce pointer motion separately, so frequent
motion cannot displace ordered key and button edges. Native SDL wake events
notify the main thread. Windows registers a message-only receiver for background
keyboard and mouse input with `RIDEV_INPUTSINK | RIDEV_DEVNOTIFY`, preserving legacy
window messages. Device motion drives the model when another application hides
or locks the cursor; SDL supplies the desktop cursor position. The receiver
tracks held inputs per device and clears them on device removal or desktop
switches. It does not install input hooks, use DirectInput, or send input to games.
SDL3 window, preferences, and gamepad events
are handled on the main thread, where gamepad events are normalized before they
reach model parameters or shortcuts. No platform listener calls Live2D,
overlay, or UI code directly.
`bongo_cat_app_run` handles update-shutdown and secondary-process arguments,
enforces single-instance ownership for the primary process, allocates the
application state, runs initialization, enters `bongo_cat_app_loop`, and then
flushes state and destroys resources in a defined order. Initialization loads
configuration and storage paths, locates assets, creates the SDL/OpenGL pet
window, initializes the platform backend, creates the Live2D, overlay, and
audio services, scans the built-in/installed/nearby model sources, and loads a
usable model. `BongoCatApp` owns settings, session state, model and behavior
catalogs, platform handles, and runtime service handles.
Installed model packages use Mver as the canonical format. The import workflow
resolves a selected file or directory, discovers and validates candidates,
fingerprints package identity, converts Tauri sources to Mver, applies image
patches, and commits the normalized package under `models_root`. It then
generates the runtime adapter and refreshes the catalogs. Nearby sources are
discovered without installing their source tree; their adapters and inspection
results are cached outside `models_root` under `cache_root`.
Each main-loop iteration waits for SDL/native wakeups or the earliest pending
frame, UI, animation, or pointer-hit deadline (with a maximum wait of 250 ms).
It dispatches queued SDL events, drains the atomic input queue and release
recovery, updates window and model-refresh state, and applies input-derived
parameters. With Cubism enabled, the model deadline follows
`settings.model.max_fps` (60 FPS by default); diagnostic builds use a 100 ms
fallback interval. The elapsed model time is capped at 250 ms and split into up
to eight substeps, targeting no more than 1/30 s per substep.
The normal pet path renders only when the window is visible, not minimized, and
marked dirty. A frame clears the background, draws the model, and composites
pointer, key, and effect overlays before calling the platform presenter.
Preview operations can request immediate renders, while capture renders may
skip presentation. macOS and Linux swap the SDL OpenGL window directly.
Windows swaps directly when layered presentation is inactive and otherwise
reads back the frame for `UpdateLayeredWindow`. The preferences UI owns a
separate SDL/OpenGL window and is rendered and presented independently from
the pet window.
The C runtime calls the ABI declared in `include/bongo_cat/model.h`. The Live2D
bridge and Cubism implementation live in `src/live2d` and use C++17 only when
the Cubism SDK is enabled; the rest of the native runtime uses C11. Cubism
types remain behind opaque C handles, while `src/live2d/live2d_stub.c` provides
the diagnostic backend when the SDK is unavailable.
```mermaid
flowchart TB
Input(["Keyboard / mouse / gamepad"])
BuiltIn(["Built-in model assets"])
Sources(["External model sources
|
Free code signing on Windows provided by SignPath.io, certificate by SignPath Foundation |