Visual Novel Porting Guide - BASLQC/vnds GitHub Wiki
Porting Visual Novels to VNDS. Guide from Digital Haze Wiki tutorials.
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.
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.
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).
For example:
-->novel\Tsukihime\sound\
-->novel\Tsukihime\sound\BGM\
-->novel\Tsukihime\sound\Sound Effects\
-->novel\Tsukihime\sound\Voices\
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.
| 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 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
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 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 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.
The sound files encompass the music, sound effects, and voices when available.
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.
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.
| 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 |