<div align="center">
  <img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/logo-mid.png" alt="Suika3 Logo" width="480" hspace="20">
  <h1 align="center" style="border-bottom: none">
    <a href="https://suika3.vn">Suika3</a>:<br>
    Standard Universal Infrastructure<br>
    for Kinetic Arts<br>
    The Third Generation
  </h1>
  <p>
    Suika3 is a modern, ultra-portable, full-stack<br>
    Infrastructure on Compiler / Virtual Machine / HAL<br>
    for interactive entertainment.<br>
    It's a next-generation open-source game OS or runtime at low-level.<br>
    In a nutshell, it's like Unity with the 3D and editor removed,<br>
    and visual novel added by default.<br>
  </p>
  <p>
    We've brought Suika3 to life<br>
    with a deep love for mobile devices —<br>
    the platforms that major 3D engines left behind.<br>
    <br>
    It's a powerful, production-ready game runtime<br>
    for Visual Novels and all kinds of 2D games,<br>
    designed to run beautifully on any platform you choose.
  </p>
  <a href="https://discord.gg/YZsq9u9Mgr"><img src="https://img.shields.io/badge/suika3.vn-Discord-orange"></a>
  <img src="https://img.shields.io/badge/License-ZLib-orange.svg">
  <img src="https://img.shields.io/github/stars/awemorris/suika3.svg?style=flat&logo=github&colorB=orange&label=stars">
  <img src="https://img.shields.io/github/forks/awemorris/suika3.svg">
  <p>
    <a href="https://github.com/awemorris/suika3/blob/main/README.zh-CN.md">简体中文</a>&nbsp;|&nbsp;
    <a href="https://github.com/awemorris/suika3/blob/main/README.ja.md">日本語</a>
  </p>
</div>

---

## TL;DR

- **What's This:** An open-source equivalent to Unity's IL2CPP
- **Target:** Mobile-first, yet cross-platform by design
- **High-Performance:** Native, core written in 100%-pure ANSI C (C89)
- **Hybrid Scripting:** JIT VM with AOT fallback for App Store compliance
- **Broad Platforms:**
    - **Desktop:** Windows, macOS, Linux, ChromeOS, Raspberry Pi
    - **Mobile:** iOS, Android, HarmonyOS NEXT
    - **Web:** WebAssembly
    - **Console:** Xbox (GDK), PS5/Switch/Xbox via Unity Integration \[DevKit required\]
    - **Exotic:** FreeBSD, NetBSD, OpenBSD, Solaris, Haiku, MS-DOS, PC98
- **Users:** Professional creators, indie studios, enterprise teams.

---

<div align="center">
  <p>
    Our custom JIT/AOT scripting infrastructure<br>
    allows you to publish the exact same game<br>
    across both Steam and the App Store,<br>
    eliminating traditional porting headaches!
  </p>
  <img src="https://img.shields.io/badge/Desktop-Windows%20%2F%20macOS%20%2F%20Linux%20%2F%20Chromebook%20%2F%20Raspberry%20Pi-blue"><br>
  <img src="https://img.shields.io/badge/Mobile-iOS%20%2F%20Android%20%2F%20HarmonyOS%20NEXT-blue"><br>
  <img src="https://img.shields.io/badge/Console-Switch%20%2F%20PS5%20%2F%20Xbox-blue"><br>
  <img src="https://img.shields.io/badge/Web-Emscripten-blue"><br>
  <img src="https://img.shields.io/badge/Exotic-FreeBSD%20%2F%20NetBSD%20%2F%20OpenBSD%20%2F%20Solaris%20%2F%20Haiku-blue"><br>
  <img src="https://img.shields.io/badge/Store-App%20Store%20%2F%20Play%20Store%20%2F%20Microsoft%20Store%20%2F%20Steam%20%2F%20itch%2eio%20%2F%20App%20Gallery-green"><br>
  <br>
</div>

---

<!-- SCREENSHOT -->
<div align="center">
  <a href="https://noctvm.io/test/">
    Click to play on the browser!<br>
    <img src="https://github.com/awemorris/suika3/blob/main/docs/img/screenshot-20260406.webp" alt="Suika3 Sample Game Screenshot">
  </a>
  <br>
  <br>
  Suika3 now has a nice launcher written in and self-hosted by Suika3!<br>
  <img src="https://github.com/awemorris/suika3/blob/main/docs/img/screenshot-20260429.webp" alt="Suika3 Launcher Screenshot">
  <br>
  <br>
  Windows 11<br>
  <img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/screenshot-win11.webp" alt="Suika3 on Windows 11" width="480">
  <br>
  <br>
  iOS<br>
  <img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/screenshot-ios.webp" alt="Suika3 on iOS" width="480">
  <br>
  <br>
  Android<br>
  <img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/screenshot-android.webp" alt="Suika3 on Android" width="480">
  <br>
  <br>
  Suika3 on NEC PC-9801<br>
  <img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/screenshot-pc98.png" alt="Suika3 on NEC PC-9801" width="480"><br>
  We've returned where VN was born...<br>
  Requires: 80386/16MB RAM/MS-DOS 6.2/OpenWatcom/DOS4GW<br>
  Crazy thing is, our Sun-Ray JIT VM works on a real PC98 machine!<br>
  <br>
</div>

---

## Installation

### Downloading Full SDK

[Download Suika3-SDK-Full.zip](https://github.com/awemorris/suika3/releases/latest/download/Suika3-SDK-Full.zip)

Please refer to [Getting Started](docs/mkdocs-en/docs/getting-started.md).

### Package Managers

Linux (Flathub):
```
flatpak install --user flathub vn.suika3.engine
flatpak run vn.suika3.engine
```

macOS (Homebrew):
```
brew tap awemorris/suika3
brew install suika3
```

FreeBSD (Ports):
```
pkg install suika3
```

### Building from Source

Please refer to [build.md](docs/mkdocs-en/docs/build.md) for platform-specific instructions.

```
# Clone the repo.
git clone https://github.com/awemorris/suika3.git
cd suika3

# Make a build directory.
mkdir build && cd build

# Build and install.
cmake .. && cmake --build . --parallel && sudo cmake --install .

# Run the sample.
cd ../game
suika3
```

---

## Syntax Highlighting on Visual Studio Code

There is an awesome VS Code extension by `@lalalll-lalalll` to support
syntax highlighting for Suika3, including `NovelML`, `Ray`, `GUI`, and `Anime` files.

Check it out: [NovelML-Helper](https://github.com/lalalll-lalalll/NovelML-Helper)

To install this extension, visit the repository and download the .vsix file from the
[Releases page](https://github.com/lalalll-lalalll/NovelML-Highlighter/releases),
then install it on VS Code.

<img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/syntax-highlighter-3.png" alt="Install highlighter 1" width="320" hspace="20">

---

## VS Code Integration

### Copilot Completion

You can write `NovelML` and `Ray` using Copilot Chat and/or Completion
because the SDK contains the full documentation inside the project and
Copilot can refer it.

### Desktop Execution

Open the extracted folder by `Visual Studio Code`.

- Click the command bar, `Run Task --> Suika3: Run` (or just press `Ctrl-Shift-B`)
- Suika3 will launch immediately!

<img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/vscode-2.webp" alt="VSCode 2" width="640" hspace="20">

- Any script errors will appear in the `PROBLEMS` tab.
- You can click an error to jump directly to the corresponding line in the source code.

<img src="https://raw.githubusercontent.com/awemorris/suika3/refs/heads/main/docs/img/vscode-3.webp" alt="VSCode 3" width="640" hspace="20">

### iOS and Android Execution

Ever dreamed of becoming an iOS/Android developer in just a minute?
With Suika3, it's that simple.

- One-Click:
    - By selecting the `Suika3: Build iOS IPA` or `Suika3: Build Android APK`
      task, Suika3 will automatically build the app and install it
      onto your USB-connected smartphone.
- For Android:
    - Turn on `Developer Mode` and `USB Debugging` on the phone
    - No manual setup required on the Suika3 side
    - No Android Studio required, of course
    - No paid license required
    - JDK and Android SDK will be downloaded automatically during the build process
- For iOS:
    - Xcode 15+ required (free)
    - No paid license required for testing on iPhone simulators
    - `Apple Developer Program` required for testing on real iPhone/iPad ($99/year)

We truly believe Suika3 is one of the most streamlined tools in the
world for creating and publishing iPhone, iPad, and Android apps to
the stores!

Even if you aren't ready to publish just yet, imagine the look on your
friends' faces when they see your game running smoothly on an iPhone.
You'll be the star of the day.

And if you're looking for a publisher to back your project, having a
playable, high-quality mobile demo is your ultimate weapon. It speaks
louder than any pitch deck ever could!

---

## Introduction

Suika3 is a production-grade visual novel & 2D game runtime
specifically engineered for commercial mobile app development,
developed by the Suika3 Project, led by Awe Morris.

Games made with Suika3 are powered by `NovelML` and the `Ray`
scripting platform. It runs swiftly, but it's not a lightweight
technology.

- **NovelML** ("演戲標記"): A tag-based, human-readable, extensible
  DSL designed specifically for visual novels. It features concise,
  declarative tags for seamless dialogue and scene control. Developers
  can add custom tags using `Ray`.

- **Ray** ("光陰腳本"): The robust scripting language for Suika3. It
  utilizes a high-speed JIT compiler on desktop platforms (Sun-Ray JIT
  VM; codename "諏訪武叡") and can be compiled into native binaries
  (Lunar-Ray AOT Compiler; codename "少彥智叡") for production or
  mobile environments, alongside the interpreter (Ubi-Ray Interpreter;
  codename "天滿梅貴"). Our native technology, Ray, enables you to
  make not only VN but also generic 2D games.
  (Ray codename: "神威/和光全球之天媛")

Although Suika3 is designed as a professional tool, you are absolutely
welcome to use it just for fun — after all, fun is the driving force
behind every great community.

> [!TIP]
> Suika3 is ambitious software born from over 25 years of independent
> R&D, and we are still shaping its future together with early
> adopters.

---

## Key Features

Suika3 is engineered with modern techniques, and delivers:

- **High Performance**: Powered by Sun-Ray JIT, it delivers 2.5-4.5x
  faster execution speed compared to our interpreter backend in
  synthetic benchmarks.

- **Optimized**: Engineered to run smoothly at 60 fps even on
  low-spec hardware such as Raspberry Pi in developing regions.

- **True Portability**: Designed with a "port anywhere" strategy,
  ensuring compatibility with almost every modern platform.

- **Extensible**: NovelML can be seamlessly extended using the Ray
  language. Developers can implement custom tags simply by writing a
  Ray function named `Tag_*()`.

- **Sophisticated**: Our `Story-View-Logic Architecture` streamlines
  game development. `NovelML` manages the timeline and flow of the
  game, `GUI` and `Anime` drive the UI/UX, and `Ray` encapsulates
  complex implementation details.

- **Reliable**: We follow a structured `Quality Assurance` process
  to deliver reliable software.

- **Mobile UI/UX:** The default UX is mobile-first with a hamburger
  menu. Desktop-style tiny buttons on message windows are not a
  primary target due to mobile usability and store review risks.

- **Battery-Friendly:** With only 1% CPU usage on Core Ultra 5 228V,
  8% on Apple M5, and 20% on Apple A15 Bionic during 60 fps gameplay,
  it's perfect for extended play on the go! It prevents your phone or
  laptop from overheating—pretty "cool," isn't it?

- **Long-Term Support:** Built with a highly portable codebase, our
  software is designed to support future platforms through the 2030s,
  2040s, and beyond. LTS versions include a minimum of 10 years of
  bug-fix support.

---

## Index

- [Kanban](#kanban-status)
- [Getting Started Guide](#getting-started-guide)
- [Quick Look](#quick-look)
- [Examples](#examples)
- [Why Ray?](#why-ray)
- [Technical Overview](#technical-overview)
- [Garbage Collection](#garbage-collection)
- [Compatibility List](#compatibility-list)
- [Documentation](#documentation)
- [Internationalization](#internationalization)
- [Third-party Libraries](#third-party-libraries)
- [CMake Presets](#cmake-presets)
- [Codebase & Maturity](#codebase--maturity)
- [Quality Assurance](#quality-assurance)
- [Adoption Status](#adoption-status)
- [Repository Structure](#repository-structure)
- [Asset File Formats](#asset-file-formats)
- [Game Packaging & Distribution](#game-packaging-distribution)
- [Engine Feature List](#engine-feature-list)
- [Versioning Policy](#versioning-policy)
- [License](#license)
- [Support & Contact](#support--contact)
- [Community](#community)
- [Contribution](#contribution)
- [Lineage: The Grand Journey](#lineage-the-grand-journey)
- [Why Suika3?: Our Philosophy](#why-suika3-our-philosophy)
- [FAQ](#faq)

---

## Kanban (Status)

**The current version is `26.05.x`:**

- Quality is improving daily, and `26.05.x` is now considered stable.
- We are currently in the `Quality Stabilization Period` (April 1 - June 30, 2026)
  in preparation for the upcoming `Suika3 26.07 LTS` release (scheduled for July 1, 2026).
- While some minor bugs may remain, they will be fully resolved by the LTS release.
- A detailed list of all issues can be found in [BUGS.md](BUGS.md).
- See [Quality Assurance](#quality-assurance) for more details.

**Our current status is:**

- ✅ Cleaning up the Suika2 codebase. (OpenNovel) (June 2024 - November 2024)
- ✅ Implementing the scripting language. (NoctLang) (December 2024 - March 2025)
- ✅ Implementing the 2D game runtime. (Playfield Engine) (March 2025 - October 2025)
- ✅ Implementing the tag execution engine. (Suika3) (January 2026 - February 2026)
- ✅ Refactoring all C functions into a stable "C API". (January 2026 - February 2026)
- ✅ Implementing all tags in C. (January 2026 - February 2026)
- ✅ Wrapping "C API" for Ray. (February 2026 - March 2026)
- ✅ API Freeze (March 7, 2026)
- ✅ GUI Animation Implementation (March 10, 2026)
- ✅ Code Freeze (March 12, 2026)
- ✅ Milestone: `Suika3 26.04 (=LTS RC1)` (April 1, 2026)
- ✅ Milestone: `Suika3 26.05 (=LTS RC2)` (May 1, 2026)
- Milestone: `Suika3 26.06 (=LTS RC3/GM)` (June 1, 2026)
- Goal: `Suika3 26.07 LTS` Public Release (July 1, 2026)

**Remaining Tasks:**
- Document: `SRS: System Requirement Specification`
- Document: `SDS: System Design Specification`

---

## Getting Started Guide

See also [Getting Started Guid](docs/mkdocs-en/getting-started.md)

This guide will help you jump-start your very first visual novel
project in just a few easy steps.

### Installation

Let's get Suika3 running so you can see the magic happen!

**Windows:**
- **Download & Extract**
    - Download [Suika3-full.zip](https://github.com/awemorris/suika3/releases/latest/download/Suika3-full.zip) and extract it to your preferred folder.
- **Launch**
    - Open the folder and run `suika3.exe` to start to the sample game!

**macOS:**
- **Download & Extract**
    - Download Suika3-SDK-Full.zip and extract it to your preferred folder.
- **Mount the Disk Image**
    - Navigate to `SDK/macos/` and open `Suika3.dmg`.
- **Setup the App Bundle**
    - Copy the `Suika3` app from the DMG into the same folder where `suika3.exe` (and the data folder) is located.
    - Note: The app bundle must reside alongside your game data to function correctly.
- **Launch**
    - Double-click the `Suika3` app to start the sample game!

**Linux:**
- **Download & Extract**
    - Download Suika3-full.zip and extract it to your preferred directory.
- **Install the Flatpak Package**
    - Navigate to `SDK/linux/` and open `Suika3.flatpak` (or run `flatpak install --user Suika3.flatpak`).
    - This associates `.novel` and `.ray` files with the Suika3.
- **Launch**
    - Open the extracted folder, then double-click `start.novel` to launch the sample game!

### Personalize Your Story (`start.novel`)

Now, let's make the game say exactly what you want.

- **Open:**
    - Find the `start.novel` file in your project folder and open it with your favorite text editor.
- **Edit:**
    - Add the following tag at the beginning of the file:
    ```
    [text text="Hello, world! This is my first game."]
    ```
- **Test:**
    - Save the file and run Suika3 again.
    - You should see your new message on the screen!

- **Edit:** Replace the existing text with the following command:
```
[text text="Hello, world! This is my first game."]
```
- **Test:** Save the file and run `suika3.exe` again. You should see your new message on the screen!

### Under the Hood (Advanced Tips)

You can easily change the screen size of your game.

- **Locate:** Open the `main.ray` file in your editor.
- **Modify:** Look for the `func setup()` section. You can change the resolution and the title of your window here:
```
// Called when the window is opened.
func setup() {
    return {
        width:      1280,            // The width of your game
        height:     720,             // The height of your game
        title:      "My First Game", // Your game's title
        fullscreen: false            // Set to true for full-screen mode
    };
}
```

The bottom part of your `main.ray` file contains the core game logic
in `Ray`. It's best to leave these functions as they are unless you
are doing advanced customization:

- `func start()`: This is called once when your game launches.
- `func update()`: This runs every single frame to handle game logic.
- `func render()`: This draws everything on the screen after the update is done.

```
// Called before the game starts.
func start() {
    // Load plugins here.
    // Suika.loadPlugin("testplugin");

    // Do not delete the following line.
    Suika.start();
}

// Called before a frame rendering.
func update() {
    // Do not delete the following line.
    Suika.update();
}

// Called every frame rendering.
func render() {
    // Do not delete the following line.
    Suika.render();
}
```

> [!TIP]
> These functions are the core mechanism of the `Playfield Engine` that
> powers Suika3. Suika.start(), Suika.update(), and Suika.render() must
> remain in place for the game to function properly.

---

## Quick Look

### NovelML

`start.novel` file looks like:

```
# Show a background image.
[bg file="bg/coast.png" time="0.5"]

# Show a character image.
[ch center="ch/midori-normal.png" time="0.5" fade="normal"]

# Show a question text.
[text text="Choose a name."]

# Show options.
[choose
    name="choose_result"
    text1="March"
    text2="April"
    text3="May"
]

# Branch by the choose's result.
[if lhs="${choose_result}" op="==" rhs="March"]
    [set name="name" value="March"]
[elseif lhs="${choose_result}" op="==" rhs="April"]
    [set name="name" value="April"]
[else]
    [set name="name" value="May"]
[endif]

# Show a text.
[text name="${name}" text="Hello! My name is ${name}."]
```

---

## Examples

[A sample game](game) is included in the release zip.

See the `game/` folder for:
- Demo project
- Sample assets
- NovelML usage
- Ray usage

---

## Why Ray?

- **Instant Iteration:** No compile cycles, no waiting. The built-in
  JIT compiler runs your scripts immediately after editing, so you can
  tweak gameplay and see results in real-time.

- **True Native Performance:** Run extensions at full speed on iOS,
  Android, and consoles. Even on platforms where JIT is restricted,
  you never have to sacrifice performance thanks to AOT. Ray is a
  native technology.

- **Sandbox Model:** Scripts cannot access arbitrary files/network.
  Only game assets and save data are accessible via engine-managed
  APIs.

- **Smooth Store Approval:** Dramatically lower the risk of
  rejection. Since final builds consist of native code via AOT, you'll
  breeze through App Store and console certifications.

- **Easy to Learn, Powerful to Use:** The JavaScript-inspired syntax
  is friendly for beginners, yet offers the deep flexibility
  experienced developers expect for complex systems.

- **Long-term Stability:** Because we develop the language in-house,
  you're shielded from breaking changes in upstream projects. We own
  and control the full stack, so your scripts stay compatible forever.

In short, since we couldn't find a practical, free language that
integrated JIT, AOT, and an interpreter into a single project, we
created one ourselves.

---

## Technical Overview

If these specifications excite you, you're probably in the right
place.

Suika3 is not merely an SDL wrapper with scripting. It features its
own rendering and audio backends, and its own scripting language,
positioning it as a fully independent game runtime.

### Core Architecture

Suika3 is based on `PlayField Engine`, a comprehensive 2D game runtime.
This means that Suika3 is fully extensible using the Playfield API.

Playfield Engine was originally developed specifically for Suika3.
The name "Playfield" was inspired by PlayStation during Awe's time at
the SIE PlayStation firmware team.

```
+------------------------------+
|        NovelML (Tags)        | --> Will be expanded to other game genres.
+------------------------------+
|     Plugin Tags (by Ray)     | --> Ray can be compiled into a native binary!
+------------------------------+
|       Base Tags (by C)       |
+------------------------------+
|       Ray Wrapper API        |
+------------------------------+
|         Suika3 C API         |
+------------------------------+
|       Playfield C API        |
+---------------+--------------+
|   StratoHAL   |   NoctLang   |
+---------------+--------------+
|       Operating System       |
+------------------------------+
```

- **Scripting**: Integrates
  [NoctLang](https://github.com/awemorris/NoctLang), a tiny yet mighty
  language designed for game scripting.

* **Rendering**: Supports native DirectX 9/11/12, Metal, OpenGL,
  OpenGL ES, and WebGL for wide compatibility.

* **Audio**: Provides audio output support through native
  DirectSound or XAudio2 (Windows), Audio Unit (macOS/iOS), ALSA
  (Linux), OSS (BSD), and other APIs.

### StratoHAL

StratoHAL originated as the codebase of a 2D game runtime developed
since 2001, and has been Zlib-licensed with a proven record of
exceptional stability.

Evolving over a quarter century from the Windows 9x era, StratoHAL has
grown to support macOS, Linux, iOS, Android, WebAssembly, and Unity.
It has been running reliably on smartphones for more than a decade.

While SDL3 already exists as a popular free/libre software
alternative, StratoHAL covers:

- The same major platforms as SDL3.

- Uniquely provides console support through Unity Integration without
  relying on any NDA-restricted code on the source tree.

- Software 3D rendering for older platforms.

### Platform Support and Components

|Platform Type  |OS / Platform       |Graphics                 |Sound                  |SDK                  |
|---------------|--------------------|-------------------------|-----------------------|---------------------|
|Desktop        |Windows             |DirectX 12/11/9          |DirectSound            |Win32 API            |
|               |macOS               |Metal                    |Audio Unit             |AppKit (Objective-C) |
|               |ChromeOS            |WebGL 2                  |OpenAL (Emscripten)    |Emscripten (C)       |
|               |Linux               |OpenGL 3                 |ALSA                   |C, X11 or Wayland    |
|               |*BSD                |OpenGL 3                 |/dev/dsp \| /dev/audio |C, X11               |
|               |Solaris 11          |Software                 |/dev/dsp               |C, X11               |
|               |Solaris 10          |Software                 |/dev/audio             |C, X11               |
|               |Qt                  |OpenGL 3                 |Qt Sound               |Qt                   |
|Mobile         |iOS                 |Metal                    |Audio Unit             |UIKit (Objective-C)  |
|               |Android             |OpenGL ES 2              |OpenSL ES              |Android NDK          |
|               |HarmonyOS NEXT      |OpenGL ES 2              |OpenSL ES              |OpenHarmony SDK      |
|Web            |WebAssembly (Wasm)  |WebGL 2                  |OpenAL (Emscripten)    |Emscripten (C)       |
|Console        |Unity               |Unity                    |Unity                  |Unity Native Plugin  |
|               |Xbox Series X\|S    |DirectX 12               |XAudio2                |Microsoft GDK        |

### Console Unity Plugin Notice

Playfield Engine provides Unity Plugin binaries for platforms
including Windows 64-bit and game consoles.  These binaries are built
entirely with the official version of LLVM/Clang toolchain (no
proprietary SDKs).

For Xbox series, you can use the native Microsoft GDK port directly, not via Unity.

### NoctLang

```
Ray = NoctLang + Suika3 API + Playfield API
```

**NoctLang** is a scripting language designed for in-app sandboxed
scripting.  With a game-oriented syntax, it emphasizes clarity,
instant startup, and tight integration with the game runtime.

The built-in JIT compiler supports a wide range of CPU architectures
to cover most gaming consoles and smartphones, including:

- ✅ Intel x86 (Xbox) [jit-x86.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-x86.c)
- ✅ AMD64/x86_64 (PS4/PS5/Xbox One/Xbox series X|S) [jit-x86_64.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-x86_64.c)
- ✅ ARMv5-ARMv7 (Nintendo DS/PS Vita) [jit-arm32.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-arm32.c)
- ✅ Arm64 (Switch/Switch2) [jit-arm64.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-arm64.c)
- ✅ PowerPC 32 (Wii/GameCube) [jit-ppc32.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-ppc32.c)
- ✅ PowerPC 64 (PS3/Xbox 360) [jit-ppc64.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-ppc64.c)
- ✅ MIPS32 (PS1/PSP) [jit-mips32.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-mips32.c)
- ✅ MIPS64 (N64/PS2) [jit-mips64.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-mips64.c)
- ✅ RISC-V 32 (for future devices) [jit-riscv32.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-riscv32.c)
- ✅ RISC-V 64 (for future devices) [jit-riscv64.c](https://github.com/awemorris/suika3/blob/main/external/PlayfieldEngine/external/NoctLang/src/core/jit-riscv64.c)

These architectures are well-supported, we can say at least they all pass [the test suite](external/PlayfieldEngine/external/NoctLang/tests/run-syntax.sh).

However, the following are not supported yet (interpreter-only) because of the lack of development machines:

- ❌ SH-4 (Dreamcast) (Runs interpreter)
- ❌ Sun SPARC (Runs interpreter)
- ❌ HP PA-RISC (Runs interpreter)
- ❌ Motorola 68000 (Runs interpreter)
- ❌ Loongson (Runs interpreter)
- ❌ IBM Z (Runs interpreter)
- **Challenge:** If you have one, please provide a ssh access to the development environment for 3 days. We can port there ;-)

### AOT Compilation

For platforms where JIT is restricted (such as mobile or consoles),
NoctLang can fall back to at least interpreter mode, and modern AOT
(ahead-of-time) compilation using a C source backend — ensuring full
compatibility even in tightly controlled environments.

Please see [AOT](docs/mkdocs-en/docs/aot.md) for more details.

### Script Execution Mode

|Platform          |Mode               |
|------------------|-------------------|
|Windows x86       |JIT                |
|Windows x64       |JIT                |
|Windows arm64     |JIT                |
|macOS x86_64      |JIT                |
|macOS arm64       |JIT                |
|Linux x86         |JIT                |
|Linux x86_64      |JIT                |
|Linux armv7       |JIT                |
|Linux arm64       |JIT                |
|iOS               |Interpreter or AOT |
|Android           |Interpreter or AOT |
|HarmonyOS NEXT    |Interpreter or AOT |
|WebAssembly       |Interpreter or AOT |
|Unity Plugin      |Interpreter or AOT |
|Xbox              |Interpreter or AOT |
|FreeBSD           |JIT                |
|NetBSD            |JIT                |
|OpenBSD           |Interpreter or AOT |
|Solaris 11 x86_64 |JIT                |
|Solaris 11 Sparc  |Interpreter or AOT |

### Runtime Footprint

The footprint of Suika3 is very small.

| OS           | Binary Size  | Memory Usage                |
|--------------|--------------|-----------------------------|
| Windows 11   | 2 MB         | 300 MB in the task manager  |
| Windows 2000 | 3 MB         | 8 MB in the task manager    |

> [!TIP]
> Due to the modern graphics architecture, game applications using
> DirectX 12 typically consume at least 300 MB of memory even before
> loading any game assets. The runtime itself consumes only 8 MB on
> Windows 2000.

### JIT Pipeline

NoctLang uses a dual-IR architecture where HIR handles analysis and
LIR unifies execution across interpreter, JIT, and AOT backends:

- **HIR (High-level Intermediate Representation)**
    - Structured control flow graph (CFG) for program analysis.
    - Expression DAG for algebraic simplification.
    - Basis for future advanced optimizations.

```
CFG for "func foo(a) { if (a > 0) { return a; } else { return -a; } }"

  +---------------+
  | 0: Func Block |         -- pred: none, succ: 1
  +---------------+
     +-------------+
     | 1: IF Block |        -- pred: 0, succ: 2 (true), 3 (false)
     +-------------+
        +----------------+
        | 2: Basic Block |  -- pred 1, succ 5
        +----------------+
     +---------------+
     | 3: Else Block |      -- pred 1, succ 4
     +---------------+
        +----------------+
        | 4: Basic Block |  -- pred 3, succ 5
        +----------------+
  +--------------+
  | 5: End Block |          -- pred 2, 4
  +--------------+
                                 (pred = predecessor, succ = successor)
     
```

- **LIR (Low-level Intermediate Representation)**
    - VM bytecode, serving as the primary format for both interpretation and JIT codegen input.
    - High abstraction level to achieve fast, portable interpretation.
    - Compact enough for efficient machine code lowering in the JIT.

```
  LIR for "a = 1 + 2"

    ICONST       %0, 1               ; Load constant 1
    ICONST       %1, 2               ; Load constant 2
    ADD          %2, %0, %1          ; Compute sum
    STORESYMBOL  "a", %2             ; Store result into global variable "a"
```

Compilation stages are as below.

```
 +-----+     +-----+     +-----+     +-----+
 | SRC | --> | AST | --> | HIR | --> | LIR | -----> [Interpreter Backend]
 +-----+     +-----+     +-----+     +-----+   |
                                               +--> [JIT Backend]
                                               |
                                               +--> [C Backend]
```

The separation of HIR and LIR enables:

- **Robust JIT pipeline**: minimal overhead from analysis to code generation.
- **Clarity in architecture**: each stage has a well-defined role, simplifying maintenance.
- **Portability**: the same LIR can be interpreted directly or lowered into optimized machine code.

As shown above, HIR expresses structure, while LIR expresses
execution. This split allows NoctLang to keep the JIT pipeline
organized without sacrificing optimization opportunities.

Because all JIT backends translate from the same LIR, portability
across architectures comes naturally.  This unified approach is what
makes NoctLang both portable and maintainable.

### Unified Execution Model

NoctLang preserves strict bytecode semantics across its JIT, AOT, and
interpreter execution models. Each NoctLang bytecode instruction maps
directly to a corresponding runtime C function. In the NoctLang JIT—a
method-level baseline JIT—every bytecode instruction is translated
into a runtime function call. The same mechanism applies to both AOT
and interpreter execution. Consequently, all three execution models
leverage a unified infrastructure, ensuring full semantic equivalence.

This streamlined, unified execution model represents the core novelty
of NoctLang. To the best of our knowledge, NoctLang is the first
practical language to unify JIT, AOT, and interpreter execution while
maintaining rigorous semantic consistency across all execution modes.

---

## Garbage Collection

`Ray` features a high-performance generational garbage collector,
inspired by the architecture of the Java HotSpot VM. This design
ensures that developers can focus on creation without being
interrupted by the dreaded "GC spikes" or frame drops.

Objects in scripts (strings, dictionaries) are managed by GC,
while large assets such as textures are managed by native code.

### Core Mechanism: Generational GC

The system categorizes objects into two groups to optimize memory
management:

* Young Generation: Most objects die young. Suika3 handles these using
  a high-speed Copying Algorithm (Semi-space Copy GC), which clears
  out temporary data in a flash. (typically < 0.1ms)

* Old Generation: Long-lived objects are moved here. This area uses a
  Mark-Sweep-Compact GC algorithm, which periodically reorganizes
  memory to prevent fragmentation. (typically 10-300ms)

For more detailed implementation, please check
[gc.h](external/PlayfieldEngine/external/NoctLang/src/core/gc.h) and
[gc.c](external/PlayfieldEngine/external/NoctLang/src/core/gc.c).

### Frame-Synchronized Latency Hiding

The real "magic" of Ray lies in its timing. By executing the
Young-generation Copy GC every single frame, the system effectively
hides the GC processing time within the natural frame interval.

Thanks to this generational strategy, the heavier Old-generation
Mark-and-Sweep is rarely triggered, maintaining a constant 60 fps
experience for the player.

---

## Compatibility List

### Platform Availability at a Glance

`Supported` means the upstream (`Playfield Engine`) fully supports it.

| Category    | OS / Environment   | Status       | Last Checked | Checked On                       |
|-------------|--------------------|--------------|--------------|----------------------------------|
| **Desktop** | Windows            | ✅ Supported | 3 April 2026 | Windows 11 (x64/Arm64)           |
|             | macOS              | ✅ Supported | 3 April 2026 | macOS 26 Tahoe (Apple Silicon)   |
|             | Linux              | ✅ Supported | 3 April 2026 | Ubuntu 24.04 LTS (x86_64)        |
| **Mobile**  | iOS                | ✅ Supported | 3 April 2026 | iOS 18                           |
|             | Android            | ✅ Supported | 3 April 2026 | Android 15                       |
|             | HarmonyOS NEXT     | ✅ Supported | -            | API 10+                          |
| **BSD**     | FreeBSD            | ✅ Supported | 5 April 2026 | 15.0-RELEASE amd64               |
|             | NetBSD             | ✅ Supported | 5 April 2026 | 10.0 amd64, aarch64, armv7       |
|             | OpenBSD            | ✅ Supported | 5 April 2026 | 7.8 amd64, aarch64, armv7        |
| **Web**     | WebAssembly (Wasm) | ✅ Supported | 3 April 2026 | Chrome, Edge, Safari             |
|             | Chromebook         | ✅ Supported | -            | Chrome Browser / Linux Container |
| **Other**   | Unity Integration  | ✅ Supported | -            | Unity 6.2 (Windows x86_64)       |

### 64-bit Windows Binary Compatibility List

The official recommended binary is the 64-bit version.

| OS      | Version                     | Patch | CPU    | Runtimes                              | 64-bit Binary | Direct3D |
|---------|-----------------------------|-------|--------|---------------------------------------|---------------|----------|
| Windows | 11                          |       | x64    | (None required)                       | ✅            | 12.0     |
| Windows | 11                          |       | arm64  | (None required)                       | ✅            | 12.0     |
| Windows | 10                          |       | x64    | (None required)                       | ✅            | 12.0     |
| Windows | 10                          |       | arm64  | (None required)                       | ✅            | 12.0     |
| Windows | 8.1                         |       | x64    | (None required)                       | ✅            | 11.0     |
| Windows | 8                           |       | x64    | (None required)                       | ✅            | 11.0     |
| Windows | 7                           | SP1   | x64    | (None required)                       | ✅            | 11.0     |
| Windows | 7                           |       | x64    | UCRT Update (KB2999226)               | ✅            | 11.0     |
| Windows | Vista                       | SP2   | x64    | Platform Update                       | ✅            | 11.0     |
| Windows | Vista                       | SP1   | x64    | DirectX End-User Runtimes (June 2010) | ✅            | 9.0      |
| Windows | Vista                       |       | x64    | DirectX End-User Runtimes (June 2010) | ✅            | 9.0      |
| Windows | XP Professional x64 Edition | SP2   | x64    | DirectX End-User Runtimes (June 2010) | ✅            | 9.0      |
| Windows | XP Professional x64 Edition | SP1   | x64    | DirectX End-User Runtimes (June 2010) | ✅            | 9.0      |
| Windows | XP Professional x64 Edition |       | x64    | DirectX End-User Runtimes (June 2010) | ✅            | 9.0      |

### 32-bit Windows Compatibility List

Suika3 provides the 32-bit binary `suika3-32.exe` for backward compatibility,
supporting legacy systems through older runtimes.

| OS      | Version                     | Patch | CPU    | Runtimes                               | 32-bit Binary | Direct3D               |
|---------|-----------------------------|-------|--------|----------------------------------------|---------------|------------------------|
| Windows | 11                          |       | x64    | (None required)                        | ✅            | 12.0                   |
| Windows | 11                          |       | arm64  | (None required)                        | ✅            | 12.0                   |
| Windows | 10                          |       | x86    | (None required)                        | ✅            | 12.0                   |
| Windows | 10                          |       | x64    | (None required)                        | ✅            | 12.0                   |
| Windows | 10                          |       | arm64  | (None required)                        | ✅            | 12.0                   |
| Windows | 8.1                         |       | x86    | (None required)                        | ✅            | 11.0                   |
| Windows | 8.1                         |       | x64    | (None required)                        | ✅            | 11.0                   |
| Windows | 8                           |       | x86    | (None required)                        | ✅            | 11.0                   |
| Windows | 8                           |       | x64    | (None required)                        | ✅            | 11.0                   |
| Windows | 7                           | SP1   | x86    | (None required)                        | ✅            | 11.0                   |
| Windows | 7                           |       | x86    | (None required)                        | ✅            | 11.0                   |
| Windows | 7                           | SP1   | x64    | (None required)                        | ✅            | 11.0                   |
| Windows | 7                           |       | x64    | (None required)                        | ✅            | 11.0                   |
| Windows | Vista                       | SP2   | x86    | DirectX 11 Platform Update             | ✅            | 11.0                   |
| Windows | Vista                       | SP1   | x86    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | Vista                       |       | x86    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | Vista                       | SP2   | x64    | DirectX 11 Platform Update             | ✅            | 11.0                   |
| Windows | Vista                       | SP1   | x64    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | Vista                       |       | x64    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | XP                          | SP3   | x86    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | XP                          | SP2   | x86    |                                        | -->           | Need VS2008            |
| Windows | XP                          | SP1   | x86    |                                        | -->           | Need VS2008            |
| Windows | XP                          |       | x86    | DirectX 9.0b Runtime                   | ✅            | 9.0                    |
| Windows | XP Professional x64 Edition | SP2   | x64    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | XP Professional x64 Edition | SP1   | x64    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | XP Professional x64 Edition |       | x64    | DirectX End-User Runtimes (June 2010)  | ✅            | 9.0                    |
| Windows | 2000                        | SP4   | x86    | DirectX End-User Runtimes (June 2010)  | -->           | Need VS2008            |
| Windows | 2000                        | SP3   | x86    | DirectX End-User Runtimes (June 2010)  | -->           | Need VS2008            |
| Windows | 2000                        | SP2   | x86    | DirectX End-User Runtimes (June 2010)  | -->           | Need VS2008            |
| Windows | 2000                        | SP1   | x86    | DirectX End-User Runtimes (June 2010)  | -->           | Need VS2008            |
| Windows | 2000                        |       | x86    | DirectX End-User Runtimes (June 2010)  | -->           | Need VS2008            |
| Windows | Me                          |       | x86    |                                        | -->           | Need VC++ 6.0          |
| Windows | 98                          |       | x86    |                                        | -->           | Need VC++ 6.0          |
| Windows | 95                          |       | x86    |                                        | -->           | Need VC++ 6.0          |
| Windows | NT 4.0                      |       | x86    |                                        | -->           | Need VC++ 6.0          |
| Windows | NT 3.51                     |       | x86    |                                        | ❌            | Insufficient Win32 API |

### macOS Compatibility List

| OS                     | Version | Mac CPU              | Status                       |
|------------------------|---------|----------------------|------------------------------|
| macOS Tahoe            | 26.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Sequoia          | 15.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Sonoma           | 14.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Ventura          | 13.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Monterey         | 12.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Big Sur          | 11.0    | arm64 / x86_64       | ✅ OK                        |
| macOS Catalina         | 10.15   | x86_64               | ✅ OK                        |
| macOS Mojave           | 10.14   | x86_64               | ✅ OK                        |
| macOS High Sierra      | 10.13   | x86_64               | ✅ OK                        |
| macOS Sierra           | 10.12   | x86_64               | ✅ OK                        |
| OS X El Capitan        | 10.11   | x86_64               | ✅ OK                        |
| OS X Yosemite          | 10.10   | x86_64               | ❌ No Metal                  |
| OS X Mavericks         | 10.9    | x86_64               | ❌ No Metal                  |
| OS X Mountain Lion     | 10.8    | x86_64               | ❌ No Metal                  |
| Mac OS X Lion          | 10.7    | x86_64               | ❌ No Metal                  |
| Mac OS X Snow Leopard  | 10.6    | i386 / x86_64        | ❌ No Metal, No AVFoundation |
| Mac OS X Leopard       | 10.5    | ppc / ppc64 / i386   | ❌ No Metal, No AVFoundation |
| Mac OS X Tiger         | 10.4    | ppc / ppc64 / i386   | ❌ No Metal, No AVFoundation |
| Mac OS X Panther       | 10.3    | ppc                  | ❌ No Metal, No AVFoundation |
| Mac OS X Jaguar        | 10.2    | ppc                  | ❌ No Metal, No AVFoundation |
| Mac OS X Puma          | 10.1    | ppc                  | ❌ No Metal, No AVFoundation |
| Mac OS X Cheetah       | 10.0    | ppc                  | ❌ No Metal, No AVFoundation |

### Linux Compatibility List

| Distribution      | Version               | CPU             | Status | Graphics                                |
|-------------------|-----------------------|-----------------|--------|-----------------------------------------|
| Debian            | 13 / 12               | x86_64, arm64   | ✅     | X11 + OpenGL 3 or Wayland + OpenGL ES 3 |
| Raspberry Pi OS   | Debian 13             | arm64, armv7    | ✅     | X11 + OpenGL ES                         |
| Ubuntu            | 24.04 / 22.04 / 20.04 | x86_64, arm64   | ✅     | X11 + OpenGL 3 or Wayland + OpenGL ES 3 |
| Kubuntu           | 25.04                 | x86_64, arm64   | ✅     | X11 + OpenGL 3 or Wayland + OpenGL ES 3 |
| Linux Mint        | 22.3                  | x86_64          | ✅     | X11 + OpenGL 3 or Wayland + OpenGL ES 3 |
| Fedora            | 43                    | x86_64          | ✅     | X11 + OpenGL 3 or Wayland + OpenGL ES 3 |
| Odroid Variants   |                       | arm64           | ✅     | GBM + DRM + EGL + OpenGL ES             |

### iOS Compatibility List

| OS     | Status   |
|--------|----------|
| iOS 26 | ✅       |
| iOS 18 | ✅       |
| iOS 17 | ✅       |
| iOS 16 | ✅       |
| iOS 15 | ✅       |
| iOS 14 | ✅       |
| iOS 13 | ✅       |
| iOS 12 | ✅       |
| iOS 11 | ✅       |
| iOS 10 | ✅       |
| iOS 9  | ✅       |
| iOS 8  | ✅       |
| iOS 7  | No Metal |

### Android Compatibility List

| OS          | Status |
|-------------|--------|
| Android 16  | ✅     |
| Android 15  | ✅     |
| Android 14  | ✅     |
| Android 13  | ✅     |
| Android 12  | ✅     |
| Android 11  | ✅     |
| Android 10  | ✅     |
| Android 9   | ✅     |
| Android 8   | ✅     |
| Android 7   | ✅     |
| Android 6   | ✅     |
| Android 5   | ✅     |
| Android 4.4 | ✅     |

### HarmonyOS / OpenHarmony Compatibility List

| OS         | Status |
|------------|--------|
| API 20     | ✅     |
| API 12     | ✅     |

### FreeBSD

| OS         | Status      |
|------------|-------------|
| FreeBSD 15 | ✅          |
| FreeBSD 14 | ✅          |

### NetBSD

| OS         | Status      |
|------------|-------------|
| NetBSD 10  | ✅          |
| NetBSD 9   | ✅          |
| NetBSD 8   | ✅          |

### OpeBSD

| OS           | Status      |
|--------------|-------------|
| OpenBSD 7.8  | ✅          |

### Solaris

| OS         | Status      |
|------------|-------------|
| Solaris 11 | ✅          |
| Solaris 10 | ✅          |
| Solaris 9  | Not Checked |
| Solaris 8  | Not Checked |
| Solaris 7  | Not Checked |

---

## Documentation

Documentation is available at the Website:
- [English](https://suika3.vn/en/docs/)
- [Spanish](https://suika3.vn/es/docs/)
- [French](https://suika3.vn/fr/docs/)
- [German](https://suika3.vn/de/docs/)
- Italian (now translating)
- [Russian](https://suika3.vn/ru/docs/)
- Greek (now translating)
- [簡体中文](https://suika3.vn/zh-Hans/docs/)
- [繁体中文](https://suika3.vn/zh-Hant/docs/)
- [日本語](https://suika3.vn/ja/docs/)

---

## Internationalization

Suika3 supports the following languages.

| Language               | Our Code    | Translation Type         | Scope of Translation             | Progress      |
|------------------------|-------------|--------------------------|----------------------------------|---------------|
| English (Fallback)     | `en`        | Original                 | UI / Docs / Samples              | Baseline      |
| English (America)      | `en-us`     | None                     | UI                               | -             |
| English (British)      | `en-gb`     | None                     | UI                               | -             |
| Spanish (Fallback)     | `es`        | Machine Translation      | UI                               | Done          |
| Spanish (Spain)        | `es-es`     | None                     | UI                               | -             |
| Spanish (Latin America)| `es-la`     | None                     | UI                               | -             |
| French (Fallback)      | `fr`        | Machine Translation      | UI                               | Done          |
| French (France)        | `fr-fr`     | None                     | UI                               | -             |
| French (Canada)        | `fr-ca`     | None                     | UI                               | -             |
| Italian                | `it`        | Machine Translation      | UI                               | -             |
| German                 | `de`        | Machine Translation      | UI                               | Done          |
| Greek                  | `el`        | Machine Translation      | UI                               | Done          |
| Russian                | `ru`        | Machine Translation      | UI                               | Done          |
| Simplified Chinese     | `zh-cn`     | Machine Translation      | UI                               | Done          |
| Traditional Chinese    | `zh-tw`     | Machine Translation      | UI                               | Done          |
| Japanese               | `ja`        | Native Translation       | UI                               | Done          |

### How To Switch Languages

Suika3 uses the system locale. To switch languages, set your system
locale.

In addition, the sample game has language switching buttons in the
config screen.

### Contributing Translations

We welcome community contributions to improve our translations!
If you want to help us reach more developers, here is how you can contribute:

0.  Do `grep -r _TR() .` and detect original messages.
1.  **Locate the Files**: Translation assets are managed across three core directories:
    - `resources/i18n/message.txt` (Suika3 part, `S3_TR()`)
    - `external/PlayfieldEngine/resources/i18n/message.txt` (Playfield Engine part, `PF_TR()`)
    - `external/PlayfieldEngine/external/NoctLang/i18n/message.txt` (NoctLang part, `N_TR()`)
    - `external/PlayfieldEngine/external/StratoHAL/i18n/message.txt` (StratoHAL part, `HAL_TR()`)
2.  **Submit Your Changes**: 
    - Found a typo or a weird machine translation? Feel free to open a **Pull Request**.
    - Want to add a new language? Please open an **Issue** first so we can coordinate!

> [!TIP]
> Manual/Professional translations are prioritized over
> machine-generated content. Your human touch makes a huge difference!

---

## Third-Party Libraries

Our software is built upon several free/libre software libraries. To
ensure build reproducibility and long-term maintainability, all
necessary source code tarballs and patches are bundled within this
repository under the
`external/PlayfieldEngine/external/StratoHAL/lib/` directory.

### Core Libraries

| Library          | Purpose             | Key Feature                                            |
|------------------|---------------------|--------------------------------------------------------|
| Playfield Engine | 2D Game Runtime     | Our base game runtime. (in-house)                      |
| NoctLang         | Scripting Language  | Our scripting language. (in-house)                     |
| zlib             | Compression         | Deflate algorithm for general data compression.        |
| libpng           | Image               | Reference library for supporting PNG images.           |
| JPEG9            | Image               | Industry-standard JPEG image decompression.            |
| libwebp          | Image               | Modern, high-efficiency image format support.          |
| FreeType2        | Font                | High-quality font rendering and glyph processing.      |
| libogg           | Audio Container     | Bitstream handling for Ogg multimedia files.           |
| libvorbis        | Audio Codec         | Lossy audio compression used for BGM and SE.           |
| brotli           | Compression         | High-ratio compression for web and data assets. (WOFF) |
| bzip2            | Compression         | High-quality data compressor for archives.             |

### License Compliance

Each library is used according to its respective free/libre software
license. Please refer to the `NOTICE` file in this repository for the
full text of each license and copyright notice.

---

## CMake Presets

Suika3 ships with CMake presets covering various platforms and build
configurations.

| Preset                      | Platform              | Compiler   | Type           |
|-----------------------------|-----------------------|------------|----------------|
| windows-vs2022-x86          | Windows               | MSVC       | Executable     |
| windows-vs2026-x86          | Windows               | MSVC       | Executable     |
| windows-vs2022-x64          | Windows               | MSVC       | Executable     |
| windows-vs2026-x64          | Windows               | MSVC       | Executable     |
| windows-vs2022-x64-console  | Windows               | MSVC       | Executable     |
| windows-vs2026-x64-console  | Windows               | MSVC       | Executable     |
| windows-vs2022-arm64        | Windows               | MSVC       | Executable     |
| windows-vs2026-arm64        | Windows               | MSVC       | Executable     |
| windows-mingw-x86           | Windows               | MinGW-GCC  | Executable     |
| windows-mingw-x86_64        | Windows               | MinGW-GCC  | Executable     |
| windows-mingw-arm64         | Windows               | MinGW-LLVM | Executable     |
| windows-mingw-win95         | Windows 9x            | MinGW-GCC  | Executable     |
| macos                       | macOS                 | Clang      | App Bundle     |
| macos-lib                   | macOS (lib)           | Clang      | Library        |
| macos-cli                   | macOS (CLI)           | Clang      | Executable     |
| linux                       | Linux (Wayland/X11)   | GCC        | Executable     |
| linux-debug                 | Linux Debug           | GCC        | Executable     |
| linux-wayland               | Linux (Wayland)       | GCC        | Executable     |
| linux-x11                   | Linux (X11)           | GCC        | Executable     |
| linux-dri                   | Linux (DRI)           | GCC        | Executable     |
| linux-dri-rot90             | Linux (DRI)           | GCC        | Executable     |
| linux-fbdev                 | Linux (fbdev)         | GCC        | Executable     |
| linux-x11soft               | Linux                 | GCC        | Executable     |
| freebsd                     | FreeBSD               | Clang      | Executable     |
| freebsd-wayland             | FreeBSD               | Clang      | Executable     |
| freebsd-x11                 | FreeBSD               | Clang      | Executable     |
| freebsd-x11soft             | FreeBSD               | Clang      | Executable     |
| netbsd                      | NetBSD                | GCC        | Executable     |
| netbsd-x11soft              | NetBSD                | GCC        | Executable     |
| openbsd                     | OpenBSD (OpenGL)      | Clang      | Executable     |
| openbsd-x11soft             | OpenBSD (Soft3D)      | Clang      | Executable     |
| solaris11                   | Solaris11             | SunCC      | Executable     |
| solaris10                   | Solaris10             | SunCC      | Executable     |
| haiku                       | Haiku OS              | GCC        | Executable     |
| wasm                        | WebAssembly           | Emscripten | HTML + Wasm    |
| wasm-local                  | Chromebook            | Emscripten | HTML + Wasm    |
| ios-device                  | iOS Device            | Clang      | Static Library |
| ios-simulator               | iOS Simulator         | Clang      | Static Library |
| android-x86                 | Android x86           | Clang      | Shared Library |
| android-x86_64              | Android x86_64        | Clang      | Shared Library |
| android-armv7               | Android armv7         | Clang      | Shared Library |
| android-arm64               | Android arm64         | Clang      | Shared Library |
| android-riscv64             | Android riscv64       | Clang      | Shared Library |
| openharmony-arm64           | HarmonyOS NEXT arm64  | Clang      | Static Library |
| openharmony-armv7           | HarmonyOS NEXT armv7  | Clang      | Static Library |
| openharmony-x86_64          | HarmonyOS NEXT x86_64 | Clang      | Static Library |
| unity-win64                 | Unity Plugin          | Clang-CL   | DLL Plugin     |
| unity-switch                | Unity Plugin          | Clang      | Static Library |
| unity-ps5                   | Unity Plugin          | Clang      | Static Library |
| unity-xbox                  | Unity Plugin          | Clang      | Static Library |
| windows-vs2022-gdk-desktop  | Windows               | MSVC       | Executable     |
| windows-vs2022-gdk-xbox-xs  | Windows               | MSVC       | Executable     |
| windows-vs2026-gdk-desktop  | Windows               | MSVC       | Executable     |
| windows-vs2026-gdk-xbox-xs  | Windows               | MSVC       | Executable     |
| pc98                        | MS-DOS NEC PC-9801    | OpenWatcom | Executable     |
| pcat                        | MS-DOS IBM PC/AT      | OpenWatcom | Executable     |

---

## Codebase & Maturity

Suika3 is a robust 2D game runtime with over 100k lines of code (LoC).
This is not a weekend project but a mature codebase evolved over 25+ years.

- **Proven Stability:** Includes core modules refined since 2001.

- **Modern Architecture:** Features a clean HAL (Hardware Abstraction
  Layer) separated in 2016 and high-performance GPU rendering
  implemented in 2022.

- **Native Multi-Platform:** Built mostly with C, and the platform
  native languages, including C++ (DirectX), Swift (macOS/iOS),
  Objective-C (macOS/iOS), C# (Unity) and Shaders (HLSL/GLSL/Metal).

---

## Quality Assurance

In **Software Engineering**, reliability is fundamentally a function
of time. As Suika3 has been newly released in April 2026, the engine
is currently in its early lifecycle stage regarding field-tested
uptime. Consequently, formal quality metrics are not yet fully
applicable.

However, the architecture inherits over two decades of development
expertise, ensuring a solid foundation for the QA process leading
toward our first LTS (Long-Term Support).

### Our Path to Stability

We are committed to delivering a production-grade engine. Our QA
roadmap is as follows:

1. **Bug Tracking**: We maintain a comprehensive log of all
  identified issues. See [BUGS.md](BUGS.md)

2. **Data-Driven Hardening**: We analyze root causes and resolution
  rates to quantify and improve software stability.

3. **Commercial-Grade Standards**: Our ultimate goal is to achieve
  a level of robustness that meets the rigorous requirements of
  commercial app production.

---

## Adoption Status

We aim to create a new market for "Mobile Visual Novels" and have not
yet established a track record.

If you are interested in helping shape this new market as an **Early
Adopter**, we warmly invite you to join our community.

If you prefer to adopt tools with an established track record, you may
wish to revisit the project once Suika3 has matured further.

---

## Repository Structure

```
include/                           # Public headers
src/                               # Source code
resources/                         # Assets and resources
  projects/                          # Official project base for iOS, Android, etc.
cmake/                             # CMake configuration files and presets
docs/                              # Documentation source files (MkDocs)
external/                          # Third-party libraries and dependencies
  PlayfieldEngine/                   # The core 2D game runtime
    external/                          # Sub-dependencies of Playfield Engine
      NoctLang/                          # Scripting language used by the engine
        include/                           # Public headers for NoctLang
        src/                               # Source code for NoctLang
          core/                              # Core implementation of NoctLang
      StratoHAL/                         # Hardware Abstraction Layer for cross-platform support
        include/                           # Public headers for StratoHAL
        src/                               # Source code for StratoHAL
```

---

## Asset File Formats

- Images:
    - Supported formats: PNG, JPEG, WebP.

- Audio:
    - Supported formats: Ogg Vorbis, 44100Hz, Stereo or Mono.

- Fonts:
    - Supported formats: TrueType (TTF), OpenType (OTF)

---

## Game Packaging & Distribution

| OS                 | Assets                                                                                                                         |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Windows            | Assets should be stored into a file name `assets.arc`.                                                                         |
| macOS              | Assets should be stored into `Contents/Resources/assets.arc` inside the app bundle.                                            |
| Linux              | Assets should be stored into a file name `assets.arc`.                                                                         |
| iOS                | Assets should be stored into `Contents/Resources/assets.arc` inside the app bundle.                                            |
| Android            | Assets must not be packed. Please add your assets to the `app/src/main/assets/` folder directly as normal files.               |
| HarmonyOS NEXT     | Assets must not be packed. Please add your assets to the `entry/src/main/resources/rawfiles/` folder directly as normal files. |
| WebAssembly (Wasm) | Assets should be stored into `assets.arc` and placed alongside `index.html`.                                                   |
| Unity              | Assets must not be packed. Please add your assets to the `Assets/Resources/StreamingAssets/` folder directly as normal files.  |

To generate `assets.arc` from your game assets, please use the
`suika3-pack` tool. The `suika3-pack` tool creates an obfuscated
archive of your assets that can be efficiently loaded by the
runtime. (The obfuscation algorithm is a key rotating XOR, and it is
not intended for strong security. It can help prevent casual
tampering. The obfuscation key can be changed in "key.h".)

On Windows, macOS, and Linux, you can use a predefined task on Visual
Studio Code.

- Click the search bar
- Click `Run Task`
- Click `Suika3: Create a package file`

---

## Engine Feature List

**2D Game Support:**
- Texture from:
    - Color
    - Image
    - Font
- Render:
    - Pixel-wise
    - Scaling
    - 3D Transform
- Audio Playback (Vorbis)
- Asset File Access
- Save Data Access

**Visual Novel Out-of-box Support:**
- Message Display
- Option Selection
- Background and Character Display / Transition
- Sound Playback
- Movie Playback
- Layered Raster Image Animation (Shift, Scale, Rotate)
- UI/UX Construction
- Save / Load
- Skip Mode
- Auto Mode
- Skip Seen Messages
- Message History Display and Voice Replay
- CG Gallery
- Localization
- Simulation Parameter Display

**Future  Work:**
- 2D RPG Map Walk
- 3D Character Model
- Network Play

---

## Roadmap

- Visual Novels (Done)
- Other 2D games that have story parts

---

## Versioning Policy

`Year.Month.Patch-Level`

| Version  | Level                              | Release Date        | Support Period     |
|----------|------------------------------------|---------------------|--------------------|
| 26.04    | Feature Rollup / LTS RC1           | April 2026          | - codename "北辰天歸" |
| 26.05    | Feature Rollup / LTS RC2           | May 2026            | -                  |
| 26.06    | Feature Rollup / LTS RC3           | June 2026           | -                  |
| 26.07    | Long Term Support                  | July 2026           | 10 years (minimum) |
| 26.08    | Feature Rollup                     | August 2026         | -                  |
| 26.09    | Feature Rollup                     | September 2026      | -                  |
| 26.10    | Feature Rollup                     | October 2026        | -                  |
| 26.11    | Feature Rollup                     | November 2026       | -                  |
| 26.12    | Feature Rollup                     | December 2026       | -                  |
| 27.01    | Feature Rollup                     | January 2027        | -                  |
| 27.02    | Feature Rollup                     | February 2027       | -                  |
| 27.03    | Feature Rollup                     | March 2027          | -                  |
| 27.04    | Feature Rollup / LTS RC1           | April 2027          | -                  |
| 27.05    | Feature Rollup / LTS RC2           | May 2027            | -                  |
| 27.06    | Feature Rollup / LTS RC3           | June 2027           | -                  |
| 27.07    | Long Term Support                  | July 2027           | 10 years (minimum) |
| 27.08    | Feature Rollup                     | August 2027         | -                  |
| 27.09    | Feature Rollup                     | September 2027      | -                  |
| 27.10    | Feature Rollup                     | October 2027        | -                  |
| 27.11    | Feature Rollup                     | November 2027       | -                  |
| 27.12    | Feature Rollup                     | December 2027       | -                  |
| 28.01    | Feature Rollup                     | January 2028        | -                  |
| 28.02    | Feature Rollup                     | February 2028       | -                  |
| 28.03    | Feature Rollup                     | March 2028          | -                  |
| 28.04    | Feature Rollup / LTS RC1           | April 2028          | -                  |
| 28.05    | Feature Rollup / LTS RC2           | May 2028            | -                  |
| 28.06    | Feature Rollup / LTS RC3           | June 2028           | -                  |
| 28.07    | Long Term Support                  | July 2028           | 10 years (minimum) |

---

## License

Suika3 is a permissive
[free/libre software](https://www.gnu.org/philosophy/free-sw.en.html),
released under the permissive `ZLib License`.

* You can use Suika3 for commercial games.
* You do not need to open-source your game code.
* You may modify and redistribute the software.
* Attribution is appreciated but not required.

```
Suika3
Copyright (c) 2026 Awe Morris / SCHOLA SUIKAE
```

The full license is available at [LICENSE](LICENSE) and [NOTICE](NOTICE).

---

## Support & Contact

For general inquiries, bug reports, and technical assistance:

- **GitHub Issues**: Preferred for formal bug tracking and feature
  requests.

- **[Discord Server](https://discord.gg/YZsq9u9Mgr)**: The best place
  for real-time discussions and quick questions.

We strive to provide timely support and help creators bring their
stories to life.

### Professional & Enterprise Support

While the **community** provides active support through GitHub and
Discord, we understand that commercial productions often require
dedicated support or guaranteed response times.

For studios and developers requiring **formal maintenance contracts,
priority bug fixes, or private consultations**, please contact us
directly via email. We are committed to helping ensure your project's
success in a high-stakes production environment.

- **Contact**: Awe Morris <awe@suika3.vn>

**Not looking for a formal contract? No problem.** If you are an indie
developer or hobbyist and prefer to keep things casual, just ping us
on GitHub Issue or Discord with any questions. We're always happy to
chat, and we'll do our best to respond or push a fix as soon as
possible! ;-)

---

## Community

### Discord

[Discord Server](https://discord.gg/YZsq9u9Mgr)

Our server does not tolerate any form of discrimination. It is an
inclusive space that embraces all human differences, including, but
not limited to, race, gender, skill levels, and neurodiversity.

### Recruiting

We are currently looking for contributors in the following areas:

* Documentation editors
* Software Engineer in Testing
* HarmonyOS NEXT testers

### Our Commitment to Inclusivity

We are committed to providing a welcoming and safe environment for
everyone. Any form of discrimination is strictly prohibited.

Our community warmly welcomes developers of all backgrounds, including
but not limited to:

- **Identity & Expression:** Race, ethnicity, nationality, language,
  gender identity and expression, sexual orientation, and sex
  characteristics.

- **Personal Attributes:** Age, body size, personal appearance,
  illness, and neurodiversity.

- **Life Context:** Faiths, beliefs, disability (e.g. visibility, but
  not limited), level of experience, education, and socio-economic
  status.

- **Justice & Inclusion:** We explicitly welcome individuals with past
  criminal records, firmly believing in the power of second chances
  and the inherent value of every contributor who participates
  respectfully.

### Governance

Suika3 provides a clean upstream codebase intended to serve as a
reliable foundation for downstream customizations. Users are
encouraged to maintain private forks tailored to their own needs.
Creating your own rebranded version is a natural and fully supported
use of the project.

Because of this philosophy, Suika3 does not employ a formal governance
structure. Instead, the project is guided by its lead maintainer in
close collaboration with community users.

---

## Contribution

We welcome contributions from everyone! Whether you are fixing a bug,
improving documentation, or proposing new features, your help is what
drives **Suika3** forward.

---

## Lineage: The Grand Journey

Suika3 represents the culmination of over two decades of relentless innovation and development:

- **Suika Studio (2001–2004)**: The origin of our codebase, featuring
  our first GUI-based editors. [Archive](https://github.com/awemorris/suika-studio-2002)

- **Unfruitiful (2005–2015)**: A decade of R&D focused on establishing
  a robust portability layer for cross-platform support.

- **Suika2 (2016–2024)**: The cornerstone of our current architecture
  and the fruit of a decade of dedicated R&D. It delivers a full
  visual novel experience with extensive platform compatibility.
  Several games with Suika3 were sold on App Store. [Archive](https://github.com/awemorris/suika2)

- **Playfield Engine (2025–)**: A versatile 2D runtime derived from the
  core portability layer of the Suika series. [Repo](https://github.com/awemorris/PlayfieldEngine)

- **Suika3 (2026–)**: By synthesizing these legacies and introducing
  `NovelML` and `Ray`, Suika3 delivers the stability of its
  predecessors alongside the flexibility of modern technology.

---

## Why Suika3?: Our Philosophy

We are not looking at the existing VN market. We aim to pioneer a
mobile VN market that does not yet exist.

Creators with different goals may also find excellent resources in
other runtimes like Ren'Py, Unity, or Godot.

### Mission: Building a Sustainable Ecosystem

Our dedication to the commercial success of visual novels is a
strategic response to the long-term health of the medium. We believe
that for visual novels to flourish in the 2030s, they must transcend
hobbyist boundaries and re-establish themselves as a thriving creative
industry.

Since the 2010s, the visual novel market has faced significant growth
challenges. One critical bottleneck has been the **lack of
high-performance software engines** capable of delivering a seamless
**native experience on iOS and Android**. While developers typically
work on PCs, for most people today, the primary personal computer is a
smartphone.

Without accessible, professional-grade tools for modern mobile
platforms, many creators have been restricted to limited distribution
channels. As a result, the medium has struggled to reach a global,
mobile-first audience, slowing its overall expansion.

While free and hobbyist projects are culturally valuable and
indispensable, they alone may not always sustain a large creative
industry. A truly healthy ecosystem may require:

- **Commercially Viable Games** — Titles that reach players on their
  primary devices and generate the economic activity necessary for
  creators to build long-term careers.

- **Economic Independence** — Empowering talent, particularly in Asia
  and the Global South, to overcome economic barriers through
  storytelling.

- **A Living Industry** — Transforming the medium from a niche
  interest into a sustainable market where creativity can lead to
  self-reliance.

In our view, it is a natural professional expectation for commercial
success.

Please note that this philosophy does not reject hobbyist or
experimental projects. We simply focus on a different problem space:
sustainability at scale.

### Our Vision: Catalyst for Growth

We do not aim to provide just another tool. Our goal is to provide a
**catalyst for growth**.

By offering a "port-anywhere" engine that delivers native performance
without the overhead of heavy frameworks, we enable developers to
focus on what matters most: **telling stories that endure.**

Because we love visual novels, we are committed to pushing the medium
forward and ensuring it remains a vibrant and economically viable art
form for decades to come.

### Our Values: Empowering Talents for Sustainable Careers

Our value is to empower talent—particularly in Asia and the Global
South—to build sustainable careers through their storytelling. We
believe that with the right tools, creativity can overcome economic
barriers.

Our commitment to the permissive license is for those people who
publish and sell original visual novels on the App Store and Google
Play, regardless of their software, hardware, and budget limitations.

---

## FAQ

- [What's this?](#whats-this)
- [Is this a competitor to existing engines such as Ren'Py, Unity, or Godot?](#is-this-a-competitor-to-existing-engines-such-as-renpy-unity-or-godot)
- [Is this okay to use for now?](#is-this-okay-to-use-for-now)
- [Doesn't "over 25 years of maturity" contradict "zero operational use"?](#doesnt-over-25-years-of-maturity-contradict-zero-operational-use)
- [Oh it's bus factor 1, isn't it?](#oh-its-bus-factor-1-isnt-it)
- [Can companies maintain their own forks?](#can-companies-maintain-their-own-forks)
- [Who makes the decisions?](#who-makes-the-decisions)
- [Is Suika3 open source software? Can it be used commercially?](#is-suika3-open-source-software-can-it-be-used-commercially)
- [What about the license for third-party libraries?](#what-about-the-license-for-third-party-libraries)
- [JIT is disabled on iOS/console, so what should I do?](#jit-is-disabled-on-iosconsole-so-what-should-i-do)
- [Are scripts safe? Can they access files or the network?](#are-scripts-safe-can-they-access-files-or-the-network)
- [Is it easy to pass the store review?](#is-it-easy-to-pass-the-store-review)
- [Is "Supports all modern platforms" really true?](#is-supports-all-modern-platforms-really-true)
- [What does "via Unity" mean for console support?](#what-does-via-unity-mean-for-console-support)
- [To what extent is HarmonyOS NEXT supported?](#to-what-extent-is-harmonyos-next-supported)
- [Can you reproduce "2.5-4.5x times faster"? What are the measurement conditions?](#can-you-reproduce-25-45x-times-faster-what-are-the-measurement-conditions)
- [Old GC takes 10 to 300ms, but does it cause frame drops?](#old-gc-takes-10-to-300ms-but-does-it-cause-frame-drops)
- [How do I start making games? Any samples?](#how-do-i-start-making-games-any-samples)
- [How do I go about developing plugins?](#how-do-i-go-about-developing-plugins)
- [Can I migrate from existing assets (like Ren'Py or Unity)?](#can-i-migrate-from-existing-assets-like-renpy-or-unity)
- [Where's the document? Is it the latest version?](#wheres-the-document-is-it-the-latest-version)
- [Is Japanese/Chinese/... supported?](#is-japanesechinese-supported)
- [Where should I go if I'm in trouble?](#where-should-i-go-if-im-in-trouble)
- [What about SLAs and maintenance contracts for businesses?](#what-about-slas-and-maintenance-contracts-for-businesses)
- [What are the minimum requirements?](#what-are-the-minimum-requirements)
- [What does "Supported" mean?](#what-does-supported-mean)
- [Will there be breaking changes? What is the compatibility policy?](#will-there-be-breaking-changes-what-is-the-compatibility-policy)
- [Does it support DLC or in-app purchases?](#does-it-support-dlc-or-in-app-purchases)
- [Why the deep devotion to Apple and iPhone?](#why-the-deep-devotion-to-apple-and-iphone)
- [Why Using Python on iOS is Challenging?](#why-using-python-on-ios-is-challenging)

### What's this?

Suika3 is a next-generation 2D game and visual novel runtime designed
with professional studios and commercial app development in mind. It
aims for high performance, long-term maintainability, and broad
platform support through native implementations (primarily in C).

### Is this a competitor to existing engines such as Ren'Py, Unity, or Godot?

Rather than being competitors, we target different problem
areas. Suika3 clearly states its direction as "creating a
mobile-centric VN market that can withstand commercial use," and
respects existing engines as viable options.

By the way, Suika3 might seem like a competitor to Ren'Py if you
compare them by VN genre. However, Suika3 is actually a competitor to
Unity when you compare them by technology because Ray scripting can be
considered an open-source equivalent to Unity's IL2CPP.

### Is this okay to use for now?

Stabilization for the first LTS release is progressing smoothly, and
quality metrics are showing steady improvement. The 26.05 series is
already stable enough for general use.

While the user base is currently small, giving you the choice to adopt
early or wait for further maturity, GitHub issues are typically
resolved within a day. This ensures a high level of community support
for all users.

### Doesn't "over 25 years of maturity" contradict "zero operational use"?

Suika3 itself is a new integration, but it builds upon a long lineage
including Suika2 and StratoHAL. In other words, it's a "new package
with an old foundation."

### Oh it's bus factor 1, isn't it?

The policy explicitly states "encouraging forks and rebrands" and
"maintaining a clean upstream without formal governance," fostering an
approach that makes downstream maintenance easier.

### Can companies maintain their own forks?

With both "Software Requirement Specification" (SRS) and "Software
Design Specification" (SDS) provided, it is ideal for enterprise
maintenance. Furthermore, "professional/enterprise support" is
available, enabling the transfer of necessary know-how to the adopting
organization.

### Who makes the decisions?

The lead developers make the decisions. We do not maintain a formal
governance structure for the community.

### Is Suika3 open source software? Can it be used commercially?

Suika3 is released under the zlib license and qualifies as Open Source
Software (OSS) under the FOSS definition. It can be used freely in
commercial projects.

However, its positioning differs slightly from many projects typically
found on GitHub. While many OSS projects thrive by building upon large
existing ecosystems, Suika3 is designed around core components
developed almost entirely from scratch, with external dependencies
kept to an absolute minimum.

While we have deep respect for the philosophy of GNU/Linux and the
broader open-source community, our goal has always been to deliver
"commercial-grade quality" that meets our own rigorous
standards. Because of this strong independence, Suika3 may feel closer
to "commercial software provided as OSS" than to a typical
community-driven OSS project.

Accordingly, we actively welcome closed-source forks and downstream
commercial products built on top of this project.

### What about the license for third-party libraries?

See [NOTICE](NOTICE) for the full text of each license and copyright
notice for the third-party libraries used in Suika3.

### JIT is disabled on iOS/console, so what should I do?

The official binaries use an interpreter in those environments. While
we believe our interpreter is sufficiently fast, if you require speed
or if even the interpreter poses a problem for a store review, please
use [AOT](docs/mkdocs-en/aot.md). This is a perfect solution boasting
2.5-4.5x the speed compared to the interpreter.

### Are scripts safe? Can they access files or the network?

No, scripts run in a sandboxed environment and cannot access files
outside the resource bundle or the network. It can access only the
APIs exposed by the engine, which are designed to be safe for game
logic.

### Is it easy to pass the store review?

We believe that using AOT compilation dramatically lowers the hurdle
for store reviews, as it essentially becomes a native app simply
executing tags, not running a generic-purpose scripting. However, we
cannot guarantee the outcome of store reviews, as they can be up to
the game quality including graphical design, user experience, and
content.

### Is "Supports all modern platforms" really true?

It's understandable that you find this hard to believe, but everything
is working according to our checks. However, when you ship it as a
product, please perform QA/QC at your own responsibility.

### What does "via Unity" mean for console support?

Even if we port Suika3 to consoles, we cannot disclose its source code
due to the NDA. However, dedicated versions of Unity are available for
consoles. Therefore, we ported Suika3 into a Unity plugin. Using this
plugin allows you to run Suika3 within Unity. In other words, if you
have the console version of Unity and a "devkit" machine, you can run
Suika3 on consoles as well.

Please understand that the console has UI/UX requirements, so you will
need to implement them additionally.

### To what extent is HarmonyOS NEXT supported?

All of the core developer resides outside China and does not possess
the actual hardware sold in China. Consequently, functionality has
only been verified using an emulator.

### Can you reproduce "2.5-4.5x times faster"? What are the measurement conditions?

This is a synthetic benchmark designed to measure the performance difference.

Measurement code:
```
func main() {
    var sum = 0;
    for(i in 0..10000) {
        for(j in 0..100000) {
            sum = sum + 1;
        }
    }
}
```

| Machine                 | JIT (s)      | Interpreter (s)       | Scaling (JIT vs Interpreter) |
|-------------------------|--------------|-----------------------|------------------------------|
| Intel Core i9 12900H    | 3.32         | 13.2s                 | 4.0x                         |
| Intel Core Ultra 5 228V | 5.78s        | 15.6                  | 2.7x                         |
| Intel Xeon Silver 4114  | 8.08         | 36.4s                 | 4.5x                         |
| Apple M5                | 2.77         | 10.6s                 | 3.8x                         |
| IBM POWER8              | 43.719       | 117.8s                | 2.7x                         |

In a real game app, the performance difference may vary depending on
the your logic and the amount of script execution. However, we have
observed that in typical visual novel scenarios, the performance
improvement can be significant, often around 5x faster when using AOT
compared to the interpreter.

### Old GC takes 10 to 300ms, but does it cause frame drops?

The Old GC is rarely invoked. Large buffers like images are managed by
C and are properly freed manually. The targets for GC are strings and
dictionary objects in scripts, and the Old GC is not invoked unless
something unusual occurs.

### How do I start making games? Any samples?

Please see the
[Getting Started Guide](docs/mkdocs-en/docs/getting-started.md)
for a step-by-step guide to creating your first game with Suika3.
We also provide sample games in the `game/` directory of this
repository, which you can use as references or starting points for
your own projects.

### How do I go about developing plugins?

Please see the [Plugin Development Guide](docs/mkdocs-en/docs/plugin.md)
for detailed instructions on how to create plugins for Suika3.

### Can I migrate from existing assets (like Ren'Py or Unity)?

Only consider migration when targeting mobile is necessary and your
existing engine makes it difficult. Otherwise, migration may not be
worth the effort.

Images and audio can be migrated by batch converting their formats,
but the UI requires manual porting. Scenarios also need manual
porting, though AI could enable some degree of automated conversion.

### Where's the document? Is it the latest version?

See [Documentation](docs/mkdocs-en/docs/index.md) for the latest
documentation.

### Is Japanese/Chinese/... supported?

Games are Unicode compliant, so you can use any language that does not
use Unicode composition in your game content. The engine itself is
internationalized, and error messages are shown in local languages.

For Japanese and CJK games, Suika3 supports:
* Kinsoku characters including line breaking rules
* Ruby annotations
* Vertical writing

Note that Right-To-Left writing system is currently not implemented
yet because of the lack of the speakers in the development
team. Please contact the developers if you can help implementing it.

### Where should I go if I'm in trouble?

Please ask questions on GitHub or Discord. If you're unfamiliar with
GitHub and don't like Discord, email is fine too ;-)

### What about SLAs and maintenance contracts for businesses?

Please request the service level you require. For a contract covering
only bug fixes, the cost is typically around 100 USD per month. For a
comprehensive contract including feature additions, it is
approximately 5000 USD per game title. If you are based in an emerging
country and cannot cover these costs, please reach out to discuss
options.

### What are the minimum requirements?

Please see the [Compatibility List](#compatibility-list) for detailed
information on supported platforms and their requirements.

- Official Configuration
    - Display: 640x480 24bpp
    - CPU: 1GHz
    - RAM: 512MB
    - GPU: DirectX 9 / OpenGL 3.0 / OpenGL ES 2.0 / Metal 1.0
    - Disk: 2MB + assets

- Minimum Configuration for Embedded Devices
    - Display: Any size, 24bpp required
    - CPU: 200MHz
    - RAM: 32MB
    - GPU: Not required
    - Disk: 2MB + assets

### What does "Supported" mean?

This indicates that the sample game has passed the verification
process to ensure it runs on either the actual hardware or an
emulator.

It just means we have a working codebase for the platform, and you
need a final QA for your game.

### Will there be breaking changes? What is the compatibility policy?

No backward-breaking changes to API specification will be made to past
releases. Existing API functions will not be changed, and new APIs
will be added instead. If behavior must be altered, a flag will be
provided to configure the behavior mode. Note that save data
specifications may not be compatible across releases. For a single
product, please fix and lock the major release version to be used.

### Does it support DLC or in-app purchases?

No, it doesn't, and there are no plans to support them.

Instead, please assume a subscription-based distribution model, like
Apple Arcade. In this model, a visual novel becomes a work that is
read for a long time—much like a book—and is monetized through
continuous viewing and playtime, similar to YouTube videos.

The visual novel market on mobile cannot survive unless it adapts to
this long-tail distribution.

Even if the project is supported by a small number of core fans, I
recommend selling merchandise rather than relying on DLC. Additional
content should be provided as free app updates rather than being split
into paid segments; the work should always remain a single, unified
experience.

At present, this remains a forward-looking perspective. However,
in-app monetization models—particularly those resembling gambling
mechanics—may face increasing regulatory restrictions depending on
regional policies. It is possible that such regulations could expand
and become a broader global standard over time.

For this reason, building a business model that does not rely on
in-app purchases is not only a risk mitigation strategy, but also a
path toward more sustainable revenue. More importantly, it allows each
work to remain available, discoverable, and continuously
played—enabling it to be appreciated and loved over the long term.

Furthermore, platform holders are the core of distribution and
essential business partners. On mobile and consoles, it’s necessary
to design projects based not only on "what you want to create" but
also on "what kind of experience the platformer expects." This might
seem like a different dimension from pure artistic creation. However,
as a professional creator, this is an indispensable process for
delivering your work sustainably.

Game subscription services are still an emerging and evolving
market. By contributing to its growth at this stage, creators are well
positioned to build strong relationships with platform holders and
benefit from increased visibility and support. Early participation in
shaping the ecosystem is likely to be rewarded as the market matures.

This is the core strategy of the Suika3 project.

### Why the deep devotion to Apple and iPhone?

Apple products may not always be the most affordable or universally accessible.  
Yet for over four decades, Apple has continually redefined the landscape of computing.

We are proud to support their platforms, and our commitment remains unwavering —  
from the iPhone all the way to Vision Pro.

### Why Using Python on iOS is Challenging?

On the App Store, Apple enforces a de facto strict limitation on
"Virtual Machines (VMs) for compatibility" that involve dynamic code
execution. Rather than being explicitly detailed in the written
guidelines, this is widely recognized among developers as an "implicit
rule" of the review process. A prime example is the near-total absence
of general-purpose apps bundled with a Java runtime.

In contrast, languages like `Lua`, frequently used in game
development, are relatively well-accepted. This is because Lua is easy
to "sandbox," making it suitable for a restricted scripting
environment isolated from the app’s core functionality. In other
words, it allows for a structure where the core OS features and the
fundamental behavior of the app cannot be arbitrarily altered after
the review process.

`Python`, however, is a different story. It lacks a robust, built-in
sandboxing mechanism by default, and depending on the design, scripts
can gain broad access to iOS functionalities. From Apple’s
perspective, this is often viewed as a "difficult-to-control VM" that
allows significant behavioral changes post-review, making it a
frequent target for rejection.

You might wonder, "Then why are there Ren'Py games on the App Store?"
This is the crux of the matter. In reality, Apple's review process
involves a degree of discretionary operation. If a project comes from
a major publisher or is a high-quality work that Apple deems "adds
value to the overall store ecosystem," it may pass even if it is
Python-based.

Essentially, if you challenge the store with Ren'Py, you need an
overwhelming level of polish to convince the reviewer. However, visual
novels are a genre that relies heavily on artistic sensibility; it is
no simple task to instantly convey that value to a reviewer whose
primary focus is technical compliance.

This is where Suika3 comes in.

Suika3 utilizes a design that either converts scripts into native code
beforehand via AOT (Ahead-of-Time compilation) or executes them within
a strictly managed sandbox VM. This approach significantly reduces the
technical risks associated with the App Store review process.

By removing these technical barriers upfront, Suika3 empowers
developers to compete solely on the "quality of their work."
