OnscripterYuri: an ONScripter engine ported to the web, Android and every desktop

A fork of ONScripter-Jh whose real feature is the build matrix

OnscripterYuri describes itself as an enhancement ONScripter project porting to many platforms, especially web. The base is ONScripter-Jh by jh10001, which is itself built on SDL2, and the repository topics list the platforms it now covers: android, arm, arm64, emscripten, linux, web, x64 and x86, alongside galgame and onscripter.

The platform list in the README is the substance of the project. Windows is covered for x86 and x64, built locally or cross compiled with mingw and statically linked, and for amd64 and arm64 built locally with msvc and vcpkg. Linux covers x86 and x64 built locally with static or dynamic linking, and arm and aarch64 cross compiled with an SDL2 build from Raspberry Pi, statically linked, plus a RetroArch target contributed by iyzsong. macOS covers x64 and arm64 through a local compile contributed by yujincheng08. Android and the PlayStation Vita are supported as well, with the Vita build living in a separate repository, psv-OnscripterJH.

The web build is the one that has no equivalent in the original. It is produced by Emscripten, and the README lists what that required: a filesystem layer in IndexedDB to hold saves, export and import of saves as a zip file since v0.7.5beta5, lazy loading by async fetch rather than BrowserFS or a worker so the audio is not blocked, and a mobile web build with touch and a web UI menu.

The development notes are equally concrete: a cleaned up project structure, documentation for development and usage, scripts that compile or cross compile without pain, VS Code and Android Studio projects, CI in GitHub Actions, and Docker used to build for all platforms. The repository root matches that description, with a CMakeLists.txt, a docker/ directory, a vcpkg.json, an asset/ directory, a script/ directory and a src/ directory.

The command line is the entire configuration surface

Everything is driven from one executable called onsyuri, and options can also be placed in an ons_args file. The usage section opens with four invocations that show the shape of it:

./onsyuri --help
./onsyuri --root /path/to/game --save-dir /path/to/save --font /path/default.ttf --enc:sjis
./onsyuri --width 1280 --height 720 --sharpness=3.1
./onsyuri --fullscreen2 # fullscreen1 alt+f, fullscreen2 f10 (toggle stretch)

The first group of options covers loading:

Usage: onsyuri [option ...]
  -h, --help            show this help and exit
  -v, --version         show the version information and exit

 load options:
  -f, --font file       set a TTF font file
  -r, --root path       set the root path to the archives
      --save-dir        set save dir
      --debug:1         print debug info
      --enc:[gbk|sjis|utf8]  change encoding of the script, default is gbk

The render group is where the portability work shows up, since arbitrary resolution and stretch are how the same engine runs on a phone, a stretched television and a browser canvas:

 render options:
      --window          start in windowed mode
      --width 1280      force window width
      --height 720      force window height
      --fullscreen      start in fullscreen mode (alt+f or alt+enter)
      --fullscreen2     start in fullscreen mode with stretch (f10 to toggle stretch)
      --sharpness 3.1    use gles to make image sharp
      --no-video        do not decode video
      --no-vsync        turn off vsync

The remaining switches handle CD audio, a registry file, an external DLL, wheel-to-advance text, disabling image rescaling, forcing button shortcuts, rendering a font outline instead of a shadow, online modification of the volume and variables when z is pressed, an external key table in a .EXE file, and font caching. That last group is inherited behaviour from the ONScripter family, and it is the part that makes this a drop-in for existing game archives rather than a new format.

Script encoding is the setting you will get wrong first

The README leads with the encoding change because it is the first thing that bites. The original Onscripter only supports sjis or gbk encodings, and this fork adds utf8 script support with the option --enc:utf8, which the feature list dates to v0.7.6. The enc option accepts gbk, sjis or utf8, and the default is gbk.

If your archive was written in Shift-JIS and you leave the default, the text will render as mojibake, and the natural reaction is to assume the port is broken. The fix is either the right --enc value or a conversion, and the README gives the conversion command in the form of an iconv invocation that rewrites a script file from gbk to utf8 in place.

The engine also reads nt2 and nt3 script encryption, which the README marks as an exclusive format of the author's own, and supports English half-width text since v0.7.4. Lua scripting and animation are supported, and the changelog records a fix for a Lua animation problem.

Two more script level details are worth noting because they change how the engine feels in use. A long click or touch invokes the menu, which is the standard mobile gesture mapped onto a mouse-driven engine, and forcing an exit can damage the save, with the README advising that you remove the environment data to play again.

That last warning is the kind of thing that only appears in a mature fork. It tells you the save format and the shutdown path are shared with the upstream project and that the fork has not made them crash safe.

The browser build keeps saves in IndexedDB and exports them as a zip

A visual novel engine in a browser has one problem that a desktop port does not, which is where the save system and the filesystem are. OnscripterYuri's answer is a filesystem layer in IndexedDB, plus export and import of saves by zip file since v0.7.5beta5.

The lazy loading strategy is the second browser specific decision. The README records it as lazy load by async fetch to avoid blocking the audio, with BrowserFS or a worker struck through, so the earlier approaches were tried and replaced. In a visual novel, audio playback is the thing a user notices immediately when it stutters, and a synchronous or worker-based filesystem emulation was interfering with it.

The third piece is the mobile web build, with touch support and a web UI menu, which matters because the same web bundle is what a phone browser loads.

The distribution side is equally deliberate. There is a set of online demos hosted on Netlify, including a lazy load example, and the Android build is on Google Play under the com.yuri.onscripter package. The desktop builds come out of GitHub Actions releases, with separate workflows for web, Android, Windows in both mingw and msvc flavours, Linux and Darwin. Every badge at the top of the README is one of those workflows, so the visible status of the project is a build matrix rather than a test suite.

Docker, vcpkg and a CMake build for nine targets

The build tooling is what makes the platform spread maintainable rather than aspirational. The README's develop checklist lists scripts to compile or cross compile without pain, continuous integration in GitHub Actions that builds automatically, and the use of Docker to build for all platforms, and the repository root carries the docker/ directory and CMakeLists.txt that go with that.

The Windows arm64 support is the clearest example of the approach paying off. The README credits ryank231231 with a pull request that provides amd64 and arm64 builds on local msvc using vcpkg, and vcpkg.json sits at the root of the repository to declare the C++ dependencies. Doing that once in a build script means every contributor and every CI run gets the same result, which is the only way a nine target matrix stays honest.

The Android target has its own set of constraints that the checklist makes explicit: SDK level above 21, which is Android 5.1 Lollipop; external SD card access through SAF, the Storage Access Framework, with a separate android-SafFile repository, plus scoped storage; non-English characters in paths; and video playback by the system player. Those are the four problems that make a desktop engine fail on a phone, and each has a named answer.

The RetroArch target and the PlayStation Vita build are community contributions rather than first party work, and the Vita build lives in its own repository, which keeps the console specific parts out of the main tree.

Where OnscripterYuri is the wrong tool

The first and most important point is what this project is not. OnscripterYuri is an engine and a porting effort. It plays archives that you already have, and it ships no games, no scripts and no copyrighted assets. Anyone reading this to find a source of visual novels is looking in the wrong place, and the licence reinforces the point: the project is under GPL-2.0 with the LICENSE file at the root of the repository, which is the normal arrangement for an engine that others distribute alongside their own data.

The second limitation is upstream coupling. This is a fork of ONScripter-Jh, and the bulk of the option surface, the registry file handling, the key table in a .EXE, the online modification mode when z is pressed, are inherited. If you are debugging a behavioural difference against the upstream engine, the fork is not the place to look, and the project has fixed a specific set of origin bugs, including one where 00.txt could not be read, which tells you the fork has already diverged in places.

The third is the save durability point mentioned above. Force exit can damage the save, and recovery means removing the environment data. For a long game on a phone, where the operating system kills background applications without warning, that is a real risk rather than a footnote.

The fourth is that the browser build is not a desktop build in a tab. It is a specific set of compromises: IndexedDB for saves, zip export and import, async fetch loading, and a web UI menu. If you need the full option set, or a fixed resolution, or the system video player, you want the desktop build.

Editorial conclusion

OnscripterYuri fits someone who already has game archives and wants the ONScripter engine on a platform the original never covered, especially the browser, where saves live in IndexedDB and can be exported as a zip. It does not fit someone looking for a way to obtain the games themselves, and it does not fit a project that needs the upstream ONScripter-Jh behaviour unchanged. Before committing, run the binary against one of your own archives with an explicit --enc value, since the default script encoding is gbk and a mismatch will look like a rendering fault rather than a configuration error.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. YuriSizuku/OnscripterYuri on GitHub