Skip to content

Visual Novel Porting Guide

Léopold Couturier-Otis edited this page Feb 22, 2021 · 8 revisions

Porting Visual Novels to VNDS. Guide from Digital Haze Wiki tutorials.

- CXBlackCatXD

Table of Contents

Introduction

Porting a visual novel to VNDS is actually really simple, though time-consuming for the most part. Overall it requires a short list of items: the source files of the visual novel (background music, CGs, etc.), a text editor, an image editor, and most importantly, dedication towards your port. The better alternative, of course, requires some programming knowledge to create a converter to do all of the monotonous work for you.

Basics of the Basics

When you first get VNDS out of the box, there are a small number of files, but we are only interested in the files that will have to be placed in the "novels" folder as that is where all of the novels will be placed of course.

Folder Structure

Each novel is placed in a folder within the "novels" folder (generally named the title of the novel), and this folder in turn should contain 4 folders:

  • background
    • Contains all of the CGs and background images for the visual novel.
  • foreground
    • Contains the foreground images (like the character images).
  • script
    • Contains all of the script files (.scr format) and is the main part of your visual novel (that is where all of the text goes).
  • sound
    • Contains all sound files (music, sound effects, voices).
All of these folders can be split into subfolders for easier organization.

For example:

     -->novel\Tsukihime\sound\
     -->novel\Tsukihime\sound\BGM\
     -->novel\Tsukihime\sound\Sound Effects\
     -->novel\Tsukihime\sound\Voices\

Other Files

In addition to these folders, the following 4 files should be placed in the root (or 'home') folder of the novel:

  • default.ttf
    • The font used in your visual novel. Default font is used when not available.
  • info.txt
    • Contains the game title and consists of one line: title=<name></name>
  • icon.png (32x32px)
    • The icon shown next to the visual novel when selecting a visual novel.
  • thumbnail.png (100x75px)
    • A preview image of the visual novel.
  • img.ini
    • The resolution of the device that you wish to play the visual novel on.

Script Commands

Command Usage Example Notes
bgload bgload file [fadetime] bgload bg001.jpg 20 Default fadetime is 16
Draws background image.
setimg setimg file x y setimg yuki.png 85 0 X>0 shifts image right, Y>0 shifts image down, and vice versa.
Draws image at point (x,y) starting from upper left.
sound sound file N sound waves.aac 12
sound ~
-1 for infinite looping.
~ to stop any currently playing sound.
Loads sound into memory (don`t load anything over 1MB) and plays it N times.
music music file music bgm01.mp3
music ~
~ to stop any currently playing music.
Plays and loops music.
text text string text Life began anew
text @Life began anew
text ~
text !
text $variable
@ will show text and not require clicking to advance
~ will make a blank line and not require clicking to advance
! will make a blank line and require clicking to advance
variables can be shown by placing "$" in front of the variable name.
Displays text to the lower screen.
choice choice |option1|option2|etc... choice |Yes|No|$variable When a choice is clicked, the variable "selected" is set to the value of what was selected, starting at 1.
Variables can be shown by adding $ before the variable name
Use "if selected == 1", etc. to branch off what was selected.
Displays choices on the lower screen.
setvar setvar variable modifier value setvar YuAffection + 1
setvar ch01 = "Not Available"
modifier: =, +, -, >=, <=, >, <
Sets a variable into the local save memory, to be kept in normal save files for things like character flags (ie. Talk to <person></person> 7 times to get their ending).
gsetvar gsetvar variable modifier value gsetvar YuRoute = 1 modifier: =, +, -, >=, <=, >, <
Sets a variable into the global.sav, to be kept across games (ie. Cleared path flags, cleared game, etc.)
if/fi if x == 1
commands
fi
conditional jump
if YuAffection == 7
jump YuEnding.scr
fi
jump BadEnding.scr
The left operand "x" must be a variable, right may be either another variable, or a number.
If the initial condition is true, it keeps reading. If false, skip all between the "if x == 7" and "fi"
jump jump file.scr [label] jump endings.scr NiceEnd If label is specified, it jumps to that label within the .scr
Jumps to defined .scr and starts reading from there.
delay delay X delay 30 Audio still plays normally.
Pause actions for X frames.
random random var low high random dice 1 6 Includes the low and high numbers.
Sets variable "var" to a number between low and high.
label label name label start Can jump to label with the "goto" or "jump" commands.
Creates a label within the script that can be jumped to.
goto goto name goto start Only jumps to labels within the same .scr
Jumps to the label with the same name.
cleartext cleartext [type] cleartext
cleartext !
If no type is given, it`ll make enough blank lines (text ~) to fill the bottom screen.
If type is !, it`ll completely clear the text buffer (including history).
Clears text from the screen.
Start Colored Text \x1b[;1m |]\x1b[30;1m]Random text \x1b[0m |30--set]foreground color to black (actually greyish)
31--set foreground color to red
32--set foreground color to green
33--set foreground color to yellow
34--set foreground color to blue
35--set foreground color to magenta/purple
36--set foreground color to cyan
37--set foreground color to white
39--set foreground color to default (regular text)
Changes text color within a line until the end of the line.
Close Colored Text \x1b[0m |]\x1b[30;1m]Random text \x1b[0m |]This is not required for stopping colored text.
Stops text color changes before the end of the line.

Colored Text

Colored text may look hard to implement easily into a script, but there is a simple way to implement colors by setting some global variables for the colors you want to use.

Simple implementation:
gsetvar ccred = "\x1b[31;1m"
gsetvar]ccblue = "\x1b[34;1m"
gsetvar]cclose = "\x1b[0m"
text]This text is $ccred red $cclose and this is $ccblue blue

Images

The images are required to be one of two formats; .jpg and .png, though generally .png is for the characters due to alpha transparency. Alpha transparency is supported for the character sprites. To avoid colour banding, decrease the colour depth of the images to 5bits/pixel and use dithering (png doesn't support 5bits/pixel, so store them in 8bits/pixel instead). If you are having strange image size problems, check the img.ini to make sure that it has the correct resolution.

Background

Background images should try to keep to the main aspect ratios of 256x192, 320x240, 800x600, etc. of the target device. The .jpg format is generally ideal for quicker distribution, but .png can still be used if preferred.

Foreground

Foreground images can be any size that is not exceedingly big (e.g. 3200x2400), however you may find it easier if you also resize these to the resolution of the target device.

Sounds

The sound files encompass the music, sound effects, and voices when available.

Music

Sound FX

Voices

Scripts

Scripting is probably what most will spend their time on and is actually fairly easy to do. As in each programming language, there are certain commands that explain what VNDS is supposed to do. The full list of commands can be found here as well as on this page. The VNDS will ALWAYS begin a visual novel starting with the script file "main.scr" so you must always start with main.scr (you can place in whatever commands you want, but it will always start the visual novel). The Nintendo DS runs at 60 frames per second.

Day 1

Knowing everything above gets you all set for porting your very own visual novel and you can practically start from day one (provided you somehow got the source files for the visual novel). A great way to start is to just make an introductory screen and then start into the main story. Or just start by fixing up the images and sounds. There isn't really a set thing that you have to do to start with, but just keep in mind what commands you can use and kick off. Make sure you have fun as well.

Helpful Links

Resource Website Description Windows/Linux/Mac
Visual Novel Visual Novel DataBase Its a database of tons of visual novels and its the perfect place to search for a visual novel. Unfortunately, you have to find the actual visual novels by yourself by conventional and unconventional means (though I don't support piracy, its your decision) as well as how to take out the files from the visual novel (google is your friend here). Windows/Linux/Mac
Text Editor Geany One of the many text editors for linux, though I'm going to assume that if you are using linux, you can decide what text editor you want to use for yourself. Windows/Linux
Text Editor Notepad++ Probably the best free text editor around for Windows with lots of features (though most you won't need). Windows
Image Editor GIMP If you haven't really used an image editor before, then you might as well get used to this one, it's probably the best free one out there. Windows/Linux/Mac
Image Editor Paint.NET Another really amazing image editor, but it only supports Windows unfortunately. Windows
Image Converter Irfan View Really simple to use image viewer with batch conversion capabilities (quickly resizing all of your CGs & backgrounds to the correct size) Windows
Image Converter XnView A great image viewer right up there with Irfan View, with just about the same number of extra capabilites (give or take a couple). Windows/Linux/Mac
Media Converter SUPER Probably the most amazing media converter around. It can convert pretty much any file; audio, video, or image. Windows
aac Encoder VNDSaacEncoder A program by ShinseiTom used to add extra silence to the end of the sound files so they aren't clipped by VNDS. It requires faac.exe, ffmpeg.exe, and audacity to work. Windows
VNDS Tools VNDS Tools It's the standard package that comes with VNDS and has limited file support, but it is really user friendly and does the job. Windows/Linux/Mac
Automation NScript2VNDS A visual novel porter from NScripter/ONScripter to VNDS that does most of the boring tasks for you. Currently not released (developer vanished). Unknown
VNDS Digital-Haze VNDS The main website of VNDS. Windows/Linux/Mac/Nintendo DS
VNDS Reference Sheet VNDS Script Format The script format documentation. All
Script Checker VNDS Script Checker Checks VNDS scripts for mistakes. The download link for the latest version stopped working, so this is the beta version. Windows