Aether

A Godot-hosted, extensible multi-runtime platform for visual novels.
English · 简体中文

Overview

Aether runs multiple visual-novel engines inside one Godot 4.7 app. A single AetherRuntimePlayer hosts the native runtimes behind a versioned provider ABI, while Godot owns the product surface: UI, final-frame presentation, input, settings, export presets, and platform packaging. The runtime dispatcher selects the engine from each game's markers and capabilities.

Godot App Shell
  ├─ AetherFlashPlayer ─────── Ruffle (Flash)
  ├─ AetherTyranoPlayer ────── WebKit / Android WebView (TyranoScript)
  ├─ AetherRenpyNativePlayer ─ Native Ren’Py SDK (embedded view / Surface)
  └─ AetherRuntimePlayer
       └─ Runtime Dispatcher
            ├─ KiriRuntime ──────── KiriKiri2 core / plugins
            ├─ OnsRuntime ───────── OnscripterYuri
            ├─ SiglusRuntime ────── siglus_rs
            ├─ Artemis Runtime ──── Artemis (private package)
            ├─ CatSystem2 Runtime ─ CatSystem2 (private package)
            ├─ BGI Runtime ──────── BGI / Ethornell (private package)
            └─ SoftPal Runtime ──── SoftPal (private package)

The default product renderer is Godot Native: engine frames are rendered through Godot-owned RenderingDevice resources. GPU Bridge is an optional compatibility and comparison backend for external native GPU render targets, and Debug CPU is a diagnostic fallback only.

Highlights

• One stable AetherRuntimePlayer with a versioned provider ABI for current and future runtimes.
• C++17 KiriKiri2 engine core (visual, audio, storage, VM, plugins) as the AetherKrkr submodule.
• OnscripterYuri integration with Godot pointer/touch/keyboard input mapped back to ONS events.
• Export presets for macOS, iOS/iPadOS, Android, Web, and Linux.
• A separate Flash library powered by native Ruffle, with sound, keyboard, mouse, touch, and the visual-novel virtual controls.
• Experimental TyranoScript browser-project playback from the visual-novel library on macOS, iOS/iPadOS and Android, with isolated saves and virtual keys. See the prototype scope and tests.
• Runtime-selectable render backend with persisted settings.
• Native Ren’Py 8 playback on macOS, iOS/iPadOS, Android and Linux, inside the existing Aether window, with isolated saves and optional virtual keys. See the native host and validation.
• Bundled multilingual KAG3 demo, playable from the library and deletable by the player.
• Smoke, render, interaction, performance, and manual-repro probe scripts.
• Manual compatibility notes for tested titles in doc/verified_games.md.

In iOS and macOS Release distribution builds, Minori, SoftPal, and the WHITE ALBUM2 (Leaf TtT / WA2) runtime require an active 30-day coffee entitlement. ONScripterYuri, Artemis, and CatSystem2 are generally available. Debug builds and Android/Linux releases do not enforce this coffee requirement.

Flash Library

Import .swf files or folders from the Flash category on macOS, Linux, and Android. Folders retain their hierarchy, and search can find nested SWFs. On iOS, copy files or folders into Files → On My iPhone/iPad → Aether → Flash, then refresh the Flash library. Local relative assets are resolved beside the SWF; SharedObject saves persist between sessions. Playback fills the available area. Back and Refresh appear only while the menu options are open; showing virtual keys hides the header again. The player uses the same virtual keyboard and pointer controls as visual novels, with arrow keys on the virtual joystick.

Playback compatibility follows Ruffle. This native integration currently loads local content; browser scripting, remote downloads, and Web exports are not supported by the Flash player.

Platform Support

Platform	Minimum	Product package
macOS	macOS 13.0 (Ventura)	App Store (Apple Silicon)
iOS / iPadOS	iOS / iPadOS 16.0, arm64	App Store; simulator builds for development
Android	Android 8.0 (API 26), arm64-v8a	GitHub Release APK
Web	Browser with wasm SIMD + threads, SharedArrayBuffer, COOP/COEP	Self-hosted static export
Linux	x86_64 or arm64	GitHub Release archive; build from source via ./build.sh linux release
Windows	Build from source	Native targets compile locally

Repository Layout

Area	Path	Purpose
Product	apps/godot_app/	Godot project: scenes, settings UI, library, export presets.
ABI	abi/	Stable C ABI the host uses to drive the C++ engines.
Glue	bridge/godot_extension/	GDExtension host entry points.
	bridge/krkr2_runtime/	KiriKiri2 integration glue (legacy engine implementation, host hooks).
	bridge/onscripter_runtime/	Headless OnscripterYuri host, frame capture, input bridge.
	bridge/siglus_runtime/	Siglus provider plus the build-time overlay applied to pristine siglus_rs.
	bridge/flash_runtime/	Ruffle static library and native playback/input/audio bridge.
Engines	packages/AetherKrkr/	KiriKiri2 engine runtime submodule.
	packages/OnscripterYuri/	Public OnscripterYuri submodule.
	packages/AetherSiglus/	Public siglus_rs submodule (kept pristine).
	packages/ruffle/	Pinned upstream Flash runtime submodule (kept pristine).
	packages/AetherInternal/	Optional private E-mote package; public builds work without it.
	packages/AetherSoftPal/	Optional private native SoftPal runtime submodule.
Support	demos/aetherkiri-kag3/	Source of the built-in KAG3 demo.
	tests/	Unit tests, fixtures, and portable probe profiles.
	tools/	Developer and compatibility tools (xp3 archive tools).
Docs	doc/	Development guide, diagnostics, plugin notes, verified games, release guide.

Getting Started

Prerequisites

Tool	Needed for	Notes
CMake 3.28+, Ninja	All builds
NASM	Native FFmpeg
vcpkg	All builds	.devtools/vcpkg or VCPKG_ROOT
Godot 4.7	Exports	/Applications/Godot.app or GODOT_BIN=/path/to/Godot
Current stable Rust (rustup)	Flash, Siglus, Minori	rustup update stable; use RUSTUP_TOOLCHAIN=stable consistently for all native runtimes
Java 17+	Flash player builtins	java on PATH; on macOS, e.g. brew install openjdk@17 and add its bin directory to PATH
Xcode	macOS / iOS	Tagged iOS releases need the iOS 26 SDK
Android SDK/NDK	Android	NDK 28.1.13356709; ANDROID_HOME or $HOME/Library/Android/sdk
Emscripten (emsdk)	Web	emcc/em++/emar on PATH; Godot dlink templates (web_dlink_*.zip)
Node.js + npm	Web dev server	TypeScript/Vite
E-mote SDK	Private E-mote builds	packages/AetherInternal/tools/install_emote_sdk.sh

Build

git submodule update --init \
  packages/AetherKrkr packages/OnscripterYuri packages/psdfile \
  packages/AetherSiglus packages/AetherMinori packages/ruffle
./build.sh macos debug        # or: macos release / ios debug --simulator /
                               # ios release / android debug --abi=arm64-v8a /
                               / web debug / linux release

These six public runtime submodules are the minimum for a default build (the engine repository is a hard configure requirement; Siglus and Minori degrade gracefully without a Rust toolchain, but the checkouts must be present; Flash requires current stable Rust and Java). Set AETHERKIRI_ENABLE_FLASH=OFF to build without Flash playback. AetherInternal, AetherSoftPal, tjs2Decompiler, and rfvp are optional — see Optional Components. AetherKrkr, psdfile, and AetherMinori are recorded with SSH URLs in .gitmodules; without SSH credentials, map them to HTTPS once, the same rewrite GitHub-hosted runners apply automatically:

git config --global url."https://github.com/".insteadOf git@github.com:

The scripts build the native engine and Godot host library, stage them under apps/godot_app/bin/, and run the matching Godot export preset when Godot is available. Linux exports bundle the required vcpkg shared libraries beside the executable. The four native platform build scripts also prepare and bundle the pinned Ren’Py runtime; their first build requires downloading the upstream SDK inputs.

Optional Components

• Private package — maintainers with access to the complete E-mote and native Live2D implementations can enable them before building:

  git submodule update --init packages/AetherInternal
  packages/AetherInternal/tools/install_emote_sdk.sh

  CMake enables the package automatically when present; a package/API mismatch stops configuration instead of building an incompatible combination. Trusted runs of the Build workflow use the AETHERSECRET read-only SSH key; fork and Dependabot runs use the public fallback. Use -DAETHERKIRI_ENABLE_INTERNAL=OFF to test the public fallback explicitly.

• SoftPal runtime — maintainers with access to the private provider can initialize its pinned submodule before a native build:

  git submodule update --init packages/AetherSoftPal

  build.sh enables it when checked out; an explicit AETHERKIRI_ENABLE_SOFTPAL_RUNTIME=OFF tests the build without it. Trusted CI checks out the pinned commit with the read-only AETHER_SOFTPAL_DEPLOY_KEY secret and builds the provider, while fork and Dependabot builds leave it disabled.

• Runtime checkout overrides — each submodule accepts a local checkout path for engine-side hot iteration without committing a gitlink bump: AETHERKIRI_KRKR_DIR, AETHERKIRI_ONSCRIPTERYURI_DIR, AETHERKIRI_SIGLUS_DIR, AETHERKIRI_MINORI_DIR, AETHERKIRI_RFVP_DIR, AETHERKIRI_INTERNAL_DIR, and AETHERKIRI_SOFTPAL_DIR.

• TJS2 analysis helper — git submodule update --init packages/tjs2Decompiler (see development.md).

• Linux bootstrap — the Linux environment is project-local and keeps all tool downloads in .aetherkiri-cache/ (override with AETHERKIRI_CACHE_DIR):

  ./tools/setup_linux.sh

Run

macOS

./build.sh macos release
open out/godot/macos/release/Aether.app

Run the debug build from a terminal to inspect logs, or pass a local test game for the current run only:

AETHERKIRI_GAME_PATH="/path/to/game" \
  out/godot/macos/debug/Aether.app/Contents/MacOS/Aether

iOS / iPadOS

./build.sh ios debug --simulator     # simulator
./build.sh ios release               # device (Xcode project in out/godot/ios/release/)

Install the device build with Xcode, or from the command line:

xcodebuild -project out/godot/ios/release/Aether.xcodeproj \
  -scheme Aether -configuration Release \
  -destination 'generic/platform=iOS' -allowProvisioningUpdates build
xcrun devicectl device install app --device <id> <path>/Aether.app

Copy games through the Files app into On My iPhone/iPad → Aether → Games, then tap refresh in the app.

Android

./build.sh android debug --abi=arm64-v8a
adb install -r out/godot/android/debug/Aether-debug.apk
adb shell monkey -p org.github.krkr2.aetherkiri -c android.intent.category.LAUNCHER 1

The release APK (out/godot/android/release/Aether-release.apk) is unsigned until a release keystore is configured — sign it with apksigner before distributing.

Web

source /path/to/emsdk/emsdk_env.sh
./build.sh web debug
npm install && npm run web:dev:debug   # serves with the required COOP/COEP headers

The export lands in out/godot/web/<debug|release>/index.html. Cloud deployments import games through the browser's file/directory picker and mount the authorized files with on-demand Range reads; saves persist to the site's IndexedDB-backed /userfs. For local development only, Vite can expose a read-only test game root via AETHERKIRI_GAME_ROOT (see development.md).

Render Backends

Backend	Role
Godot Native	Default product path — Godot-owned GPU rendering.
GPU Bridge	Optional backend for external GPU render targets (compatibility, comparison).
Debug CPU	RGBA readback/upload fallback, diagnostics only.

The settings UI persists the selection and warns when switching during a game session, because render resources must be recreated.

Runtime Notes

• ONScripter games are detected by their markers (0.txt, 00.txt, nscript.dat, nscr_sec.dat, nscript.___, onscript.nt2, onscript.nt3). Saves are written to the game's savedata/ directory so they survive app updates; the default script encoding matches upstream (GBK) and can be overridden with AETHERKIRI_ONS_ENCODING=gbk|sjis|utf8. ONS mpegplay/avi/movie commands share Aether's FFmpeg media pipeline. Integration permission and licensing are recorded in upstream issue #75.
• Built-in demo — the multilingual Aether KAG3 demo ships inside the app package and is staged into the library on first launch, using the same flow as an imported game. Deleting it removes the staged copy and its saves. Source: demos/aetherkiri-kag3/.

Testing & Probes

AETHERKIRI_SMOKE_GAME="/path/to/game" \
  /Applications/Godot.app/Contents/MacOS/Godot --headless \
  --path apps/godot_app --script res://scripts/smoke_test.gd

Probe configuration (AETHERKIRI_TEST_CONFIG), render/interaction/performance probes, profile fields, and the validation checklist are documented in development.md. The repository also ships a minimal ONS fixture (tests/fixtures/onscripter_smoke) and an ONScripter movie-command fixture (tests/fixtures/onscripter_movie_smoke/video.avi).

Releases

Tagged releases (SemVer) drive the Release workflow: App Store signing, upload to App Store Connect, and the GitHub Release. See doc/release.md for the required repository secrets and the store packaging flow.

Documentation

Document	Contents
doc/development.md	Developer guide: architecture, file roles, build, testing, probes, debugging.
doc/diagnostics.md	In-app debugger, one-command collection, evidence-first investigation.
doc/krkr2_plugins.md	KiriKiri2 plugin notes.
doc/verified_games.md	Manually smoke-tested games.
doc/release.md	Tagged release and App Store signing guide.
tools/README.md	Tools.

License

Aether is distributed under GPL-3.0-or-later (LICENSE); third-party notices are preserved in THIRD_PARTY_LICENSES.md. For Apple App Store distribution, COPYING.iOS records the limited additional permission granted by approving copyright holders solely for the official Aether iOS or macOS release, or a distributor they authorize in writing; third-party forks and derivative apps may not rely on that permission, which neither grants rights in upstream or third-party material on behalf of other copyright holders nor revokes rights already granted by the GPL.