A decompiler and compiler for MES bytecode, the scripting format used by visual novel engines from Elf, Alice Soft, Silky's, Fairytale, and other software houses throughout the late 80s and into the 90s. Ported from tomyun's "juice" tool written in Racket. Yes, the title is a bad pun.

Juice converts MES binary scripts into human-readable RKT (Lisp-style S-expression) source files, and compiles them back. This enables translation, modding, and analysis of games built on these engines.

Not all engine commands have been identified yet. Unresolved commands appear in decompiled scripts as (cmd:N ...) with their raw opcode number. If you figure out what one does, contributions are welcome.

A companion tool, juice-img, handles the image formats used by the same games (GP4, GPC, GPA), converting them to and from PNG/GIF.

Six engine versions were used across these games. Functionally, they fall into three distinct families:

AI5WIN, a Windows port of AI5, also exists but is not currently supported by juice. It shares most of its bytecode format with AI5 but has some Windows-specific differences.

Decompile all MES scripts in a directory:

juice -d *.MES

This produces .rkt source files alongside the originals. Edit them as needed, then compile back:

juice -c *.rkt

For games that need specific settings, use a preset:

juice -d -p yuno *.MES

Settings from the preset are stored in the RKT file's (meta ...) block, so you only need to specify the preset when decompiling. Compilation reads the settings from the file automatically.

Charsets define the mapping between Shift-JIS byte pairs in the binary and Unicode characters in the RKT source. The default pc98 charset covers standard Japanese SJIS plus PC-98-exclusive characters. The other charsets extend this with mappings for translation projects targeting other languages (Korean syllables, European diacritics, etc.).

The dictionary base determines how many byte values are reserved for dictionary references vs. inline characters. Games like Isaku, YU-NO, Kakyuusei, Jack, and Mobius Roid use D0 instead of the default 80. If you see errors like "dict index >= dict size" during decompilation, try --dictbase D0.

The --extraop flag changes how certain opcodes are decoded. It's required for games like X-Girl and YU-NO that introduced slightly different instruction layouts for a few opcodes. Most later (1994+) ADV games require extraop. If decompilation produces empty or garbled output, this flag (possibly combined with --dictbase D0) is often the fix.

Many games use a (proc N) or (call VAR) instruction between text fragments to insert the protagonist's name. By default, these appear as separate instructions:

(text "【")
(proc 0)
(text "】Hello.")

With --protag 0, the decompiler fuses them into the text:

(text "【" 0 "】Hello.")

Values for --protag:

• none (default): no fusion
• all: fuse all proc/call instructions found between text
• A number (e.g. 0, 3, 51): fuse only the specified proc ID
• A letter (e.g. Z): fuse only the specified call variable
• A comma-separated list (e.g. 0,Z or 0,3): fuse multiple

When --auto-wrap is enabled, the compiler scans the script for (text-frame X1 Y1 X2 Y2) commands to determine the display width, then automatically inserts line breaks in (text "...") strings that would overflow. This is especially useful for translation projects to Western languages where the translated script is longer than the Japanese.

Presets bundle the correct engine, dictionary base, extraop, and protagonist settings for specific games. Use -P or --show-preset to list them. You only need the preset when decompiling; the settings are saved in the RKT file's metadata.

When compiling, juice reads settings from the (meta ...) block at the top of the RKT file. These override CLI defaults, so you generally don't need to repeat flags when compiling:

(meta (engine 'AI5) (charset "pc98") (extraop #t))

• Accepts multiple input files. Glob patterns (*, ?) are expanded automatically.
• Output filenames are generated by swapping the extension: .mes becomes .rkt (decompile), .rkt becomes .mes (compile).
• The -o flag overrides the output path but can only be used with a single input file.

• When decoding GPA files, if the animation has no embedded palette, juice-img searches for a GPC file with the same name in the parent directory tree. Use -p to specify one manually.
• If no palette is found at all, the resulting GIF will come out entirely black. If your decoded GPA looks all black, this is why.
• The last frame of a decoded GIF may contain metadata (original negative offsets) used for lossless re-encoding. Do not edit this frame if you plan to re-encode the GPA.

• CMake 3.16 or higher
• A C++17 compiler (Clang, GCC, or MSVC)
• iconv (optional, provides fallback for unmapped characters during SJIS conversion)
• Willingness to suffer and fight with cmake flags for hours on end.

mkdir build && cd build
cmake ..
cmake --build .

Assuming you have your system set up perfectly like mine, this produces two executables: juice and juice-img. If you don't, well - good luck.

• Windows (MinGW): The build statically links the C++ runtime so the executables can run standalone. If system iconv is not available, a vendored win-iconv is used automatically.
• Linux/macOS: iconv is typically provided by the system's libc. If CMake cannot find it, the build proceeds without it, but some uncommon character mappings may not be available.

The most common cause is using the wrong engine settings. Try these in order:

1. Use --auto-engine to let juice detect the engine type from the file.
2. Try a preset if one exists for your game (-P lists them all).
3. Try --extraop if you're working with a later AI5 or ADV game.
4. Try --dictbase D0 if you see dictionary index errors.

Use -f to force overwrite.

lime-juice formats its RKT script slightly differently, which may result in being unable to compile RKT files that were created by tomyun or dantecsm's juice.exe. Try re-decompiling the .MES from the original file, fixing any non-text differences, and then compiling your RKT script file again.

Make sure you're using the right charset (-C). The default pc98 is correct for most Japanese games, but English translations and other localizations need their specific charset.

The GPA file may not have an embedded palette. Either provide one with -p palette.gpc or place the matching GPC file in a sibling directory where juice-img can find it.

• MES Binary Format Specification
• AI5 Scripting Reference
• AI1 Scripting Reference
• ADV Scripting Reference
• GP4 Image Format
• GPC/GPA Image Format

lime-juice: C++ port of Tomyun's "Juice" de/recompiler for PC-98 games
Copyright (C) 2026 Fuzion

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Most of this project's files are licensed under the GNU Public License, version 3 or later (SPDX: GPL-3.0-or-later). For the full text of this license, see the included /LICENSE.md.

Exempt from this license are:

• all files in /docs/ (not code)
• the external projects included in /third_party/
  • iconv (win-iconv): Public Domain
  • lecram (gifenc & gifdec): Public Domain
  • lodepng (LodePNG): Zlib