---

---

---

TL;DR

• Target: Mobile-first, yet runs anywhere
• High-Performance: Native, written in C
• Hybrid Scripting: JIT VM with AOT fallback for App Store compliance
• Broad Platforms:
  • Desktop: Windows, macOS, Linux, Chromebook, Raspberry Pi
  • Mobile: iOS, Android, HarmonyOS NEXT
  • Web: WebAssembly
  • Console: Xbox (GDK), PS5/Switch/Xbox via Unity Integration [DevKit required]
  • More: FreeBSD, NetBSD, OpenBSD, Solaris, Haiku
• Users: Professional creators, indie studios, enterprise teams.

---

Installation

Downloading Full SDK

Download Suika3-SDK-Full.zip

Please refer to Getting Started.

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 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

To install this extension, visit the repository and download the .vsix file from the Releases page, then install it on VS Code.

---

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!

• 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.

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 engine 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.

• 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 an ambitious engine 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 Ray JIT, it delivers 2.5-4.5x faster execution speed compared to our interpreter backend in synthetic benchmarks.

• Lightweight: 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 engine 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
• Getting Started Guide
• Building Locally
• Quick Look
• Packages
• Examples
• Why Ray?
• Technical Overview
• Garbage Collection
• Compatibility List
• Documentation
• Internationalization
• Third-party Libraries
• CMake Presets
• Codebase & Maturity
• Quality Assurance
• Adoption Status
• Repository Structure
• Asset File Formats
• Game Packaging & Distribution
• Engine Feature List
• Screenshots
• Versioning Policy
• License
• Support & Contact
• Community
• Contribution
• Lineage: The Grand Journey
• Why Suika3?: Our Philosophy
• 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.
• See 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 engine. (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 alsp Getting Started Guid

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

Installation

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

Windows:

• Download & Extract
  • 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 engine.
• 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 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 engine.

Core Architecture

Suika3 is based on PlayField Engine, a comprehensive 2D game engine. 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, 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 lightweight audio 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 engine 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

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 lightweight scripting language designed for in-app scripting. With a game-oriented syntax, it emphasizes clarity, instant startup, and tight integration with the engine.

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
• ✅ AMD64/x86_64 (PS4/PS5/Xbox One/Xbox series X|S) jit-x86_64.c
• ✅ ARMv5-ARMv7 (Nintendo DS/PS Vita) jit-arm32.c
• ✅ Arm64 (Switch/Switch2) jit-arm64.c
• ✅ PowerPC 32 (Wii/GameCube) jit-ppc32.c
• ✅ PowerPC 64 (PS3/Xbox 360) jit-ppc64.c
• ✅ MIPS32 (PS1/PSP) jit-mips32.c
• ✅ MIPS64 (N64/PS2) jit-mips64.c
• ✅ RISC-V 32 (for future devices) jit-riscv32.c
• ✅ RISC-V 64 (for future devices) jit-riscv64.c

These architectures are well-supported, we can say at least they all pass the test suite.

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 for more details.

Script Execution Mode

Runtime Footprint

The footprint of Suika3 is very small.

[!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 engine 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:

• A lightweight 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 lightweight 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 and 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.

64-bit Windows Binary Compatibility List

The official recommended binary is the 64-bit version.

32-bit Windows Compatibility List

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

macOS Compatibility List

Linux Compatibility List

iOS Compatibility List

Android Compatibility List

HarmonyOS / OpenHarmony Compatibility List

FreeBSD

NetBSD

OpeBSD

Solaris

---

Documentation

Documentation is available at the Website:

• English
• Spanish
• French
• German
• Italian (now translating)
• Russian
• Greek (now translating)
• 簡体中文
• 繁体中文
• 日本語

---

Internationalization

Suika3 supports the following languages.

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:

1. Do grep -r _TR() . and detect original messages.
2. 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())
3. 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 engine 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

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.

---

Codebase & Maturity

Suika3 is a robust visual novel engine 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

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/                               # Engine source code
resources/                         # Assets and resources for the engine
  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 engine
    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

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 engine. (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

---

Screenshots

---

Versioning Policy

Year.Month.Patch-Level

---

License

Suika3 is a permissive free/libre software, 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 engine.
• Attribution is appreciated but not required.

Suika3
Copyright (c) 2026 Awe Morris / SCHOLA SUIKAE

The full license is available at LICENSE and NOTICE.

---

Support & Contact

For general inquiries, bug reports, and technical assistance:

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

• Discord Server: 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

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

• 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

• Playfield Engine (2025–): A versatile 2D engine derived from the core portability layer of the Suika series. Repo

• 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 engines 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?
• Is this a competitor to existing engines such as Ren'Py, Unity, or Godot?
• Is this okay to use for now?
• Doesn't "over 25 years of maturity" contradict "zero operational use"?
• Oh it's bus factor 1, isn't it?
• Can companies maintain their own forks?
• Who makes the decisions?
• Is Suika3 open source software? Can it be used commercially?
• What about the license for third-party libraries?
• JIT is disabled on iOS/console, so what should I do?
• Are scripts safe? Can they access files or the network?
• Is it easy to pass the store review?
• Is "Supports all modern platforms" really true?
• What does "via Unity" mean for console support?
• To what extent is HarmonyOS NEXT supported?
• Can you reproduce "2.5-4.5x times faster"? What are the measurement conditions?
• Old GC takes 10 to 300ms, but does it cause frame drops?
• How do I start making games? Any samples?
• How do I go about developing plugins?
• Can I migrate from existing assets (like Ren'Py or Unity)?
• Where's the document? Is it the latest version?
• Is Japanese/Chinese/... supported?
• Where should I go if I'm in trouble?
• What about SLAs and maintenance contracts for businesses?
• What are the minimum requirements?
• What does "Supported" mean?
• Will there be breaking changes? What is the compatibility policy?
• Does it support DLC or in-app purchases?
• Why the deep devotion to Apple and iPhone?
• Why Using Python on iOS is Challenging?

What's this?

Suika3 is a next-generation visual novel engine 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.

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 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. 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;
        }
    }
}

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 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 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 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 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."