Creating a VNDS Converter

Over the years I’ve created a number of converter programs for porting visual novels to VNDS format. While porting will never be an exact science, I’ve gradually hammered out an approach that works best for me.

1. Find an appropriate title to port

Not everything works well for porting. In particular, you’d need to take the limitations of VNDS into account — it doesn’t support any form of animation/movement and mini games are basically impossible to port due to the extremely limited scripting support. Some VNs may also be easier to port than others, older and more linear titles usually have a less complex script and are therefore easier to port. Which engine the VN is built in also matters, common and especially open source engines will have more documentation and tools available than obscure or proprietary engines.

Especially important is whether the scripts are stored in plain text or in bytecode. Rarely do tools exist to convert a bytecode script back to its textual form and text scripts are much easier to figure out and especially parse. The difference in understandability between SETIMG and 0x1F should be obvious. Always try to look at the scripts first before deciding what to port. You may need to extract them from an archive file first (see next paragraph).

2. Unpacking the resources

For most engines, resources (scripts, images, audio) are stored in a number of archive files. These take up the bulk of the VNs total size and often have names ending in .pak, .arc or something similar. These are usually in a simple to figure out, but engine-specific file format. What’s great is you very often don’t even have to figure out the file format because someone has already done it for you. For most mainstream VNs, CRASS is able to extract (and sometimes decode) the archive files. In the rare cases it doesn’t, there may be engine-specific tools. If it’s a translated game, the translation team’s hacker will probably have some tools.

3. Converting images/audio

Once you have the images extracted, you’ll still need to resize and convert them to a format VNDS understands (PNG/JPG for images, AAC audio for the DS, OGG-Vorbis audio for Android). If you’re lucky, the output of CRASS will be all in sensible file formats (32-bit BMP/PNG, audio files FFmpeg can read). In that case you can just batch convert the files. Keep in mind to rescale images by a fixed percentage, not to a target resolution (or you’ll accidentally make every sprite as tall as the screen).

Some engines (a disturbing number of them actually) use custom file formats for images and/or audio. They’re usually fairly simple formats like LZW-compressed paletted images or ADPCM-encoded audio with a custom header. Again, if it’s a translated VN, chances are the person(s) hacking it may have tools or info to help you out.

4. Converting scripts

This is the most time-consuming step, especially if you’re not a programmer. It can be done without programming knowledge, but I wouldn’t recommend it unless the script format is particularly simple.

If the script is in some kind of bytecode, you’ll have to decode it first. Even if there’s a translation, they most likely have only had to figure out a fraction of the commands. If you’re faced with a complex bytecode script format — my condolences.

Converting the script basically consists of writing a source-to-source compiler, automatically rewriting one scripting language to another one (in this case, the end result being VNDS code). Don’t try to convert everything in one step, it’s much easier to do things in small increments and write the intermediate results to a file between each step. Small steps are less confusing and it makes tracking down bugs so much easier. The VNDS script format is also horribly limited and this way you’ll only have to look at all the ugly workarounds for missing features (call/or/and) at the very end. All my converters are open-sourced — feel free to take a look through the source code and stare at the horrors.

5. Packaging

Packaging VNDS game is pretty easy, just put all the resources in the appropriate folders (backgrounds/foreground/script/sound). For better performance, you can then store the folders in an uncompressed ZIP file with names matching the folders (background.zip, etc). More documentation can be found on the VNDS wiki.

A: Character encoding

Character encodings are a gigantic pain in the ass. Almost all Japanese visual novel engines use Shift JIS/CP932 for encoding text. VNDS expects all text files, including scripts, to be in UTF-8 encoding.

Shift_JIS encoding in scripts isn’t usually an issue. The real problem lies in filenames using non-ASCII characters and the way those are handled in Windows. Short version: many programs can’t open files with names containing characters outside the current ‘codepage’. The reason so many Japanese games don’t work without AppLocale/NTLEA/etc. is because they use Japanese (non-ASCII) characters in filenames. It’s up to you whether to rename all files to ASCII-only filenames or to deal with the character encoding problem. You should only ever use non-ASCII filenames inside background.zip/sound.zip/etc. and never for unarchived resources. VNDS requires filenames to be stored in UTF-8 encoding inside the ZIP file.

B: Supporting multiple screen resolutions

In order to make it easier to create a high-res patch for existing ports, VNDS scripts always assume a resolution of 256x192. Basically, you just port the VN at 256x192, then provide higher-resolution versions of background.zip and foreground.zip. See also: Optimizing VNDS ports for Android

16 thoughts on “Creating a VNDS Converter

  1. It really shows how much effort and time goes into it. Makes me wish there was an easier way to port our favourite VNs to VNDS on Android since there are quite a few good ones I want to be able to take with me.

  2. Wow thanks, I’ve been wanting to port my favourite VNs to VNDS in my free time lately… So a question, how long does it take to completely port a medium length VN to VNDS?

    • For me, since I write a program to directly translate the scripts, length isn’t really an issue. The complexity of the script format is what determines how long it takes. The fastest port was Cross Channel (~10 hours), and ~40 hours for something of medium complexity with bytecode scripts (like say, Inganock).

      • How long time do you think making a converter for Rose Guns Days (same script language as Umineko) may take? May the Umineko parser work for it if I set it to ignore battle scripts?

        • Haven’t read it and haven’t looked at the specific scripts, so it’s hard to say anything definitive. NScripter stuff tends to get very messy. The Umineko parser can be a starting point, but it’s full of Umineko-specific hacks and you’ll probably need to create a new pile of hacks for Rose Guns Days.

          • Got it to work after some changes to the script. The only thing left is to edit the parser to set the sprites correctly :D
            Thanks for making this even possible.

  3. How about porting Reallive games? The text and the resources are kept seperate, manually porting it is near impossible for one person, and I do not see how you can automatically convert the scripts, even if the sounds and pictures are easy.
    Any Ideas? I’d really like to play kanon or Air on my android.

    • Scripts can always be automatically converted, some are just harder than others. I’ve delved abit into Reallive games and sucessfully created a VNDS converter for Kanon (well almost, tested 3 routes so far).
      I realize this thread is getting old, but thought I might as well comment :)

  4. Would someone be able to elaborate on how Crass/Crage actually works? I’ve tried to fiddle around with it, but not to an extent where it yet makes sense, and I’m not able to find any sensible documentation. It doesn’t give any output at all.

    • There are English readme/documentation files in the crass folder.

      “support_list.txt” is the list of supported games, and there’s some information about what’s supported for each engine inside “documentation”.

  5. So is it impossible to port games with animation/mini-games, or is just that you won’t be able to play/see those parts?

  6. Can we open up something similar to a repo where ppl can work together on a signle VN.
    I want to start converting Fate Hollow, it translation is finished and I just finished Fate stay on VNDS. it was my first VN and it was an amazing experience.
    I happen to be a developer so I can do the automation and hope to help out if possible … I dont work really like java but I can work in it too but my main domain is C# and .Net.
    I can play the Fate Hollow on my PC as I already have the game but playing it on my tablet on the go or playing while in bed are the options I miss. English is not my first language but I can manage a meaningful conversation.

Leave a comment

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>