Guide to VNS release one-dot-zero
STORYDIR=directory containing resources for story
ZIP=name of zip file containing resources
TEXTCOLOR=palette index number
TEXTSHADOW=palette index number
SOUNDFREQ=GP32 supported sample frequency
SOUNDBITS=GP32 supported sample frequency
TEXTOWNER=Valid BMP file, transparency colour
SPRITE1=Valid BMP file, Screen location, transparency colour
TEXT2, TEXT3, TEXT4, TEXT5, TEXT6, TEXT7, TEXT8, TEXT9
HOTSPOT1=SCENENAME,X,Y,WIDTH,HEIGHT
Welcome to VNS.
VNS (Virtua Novel System) started out as a Visual Novel creation system. Along the way more and more options were added so now it can also be used to build simple games or adventure games.
My main two reasons for building VNS were the following:
My first reason is that I am really into Japanese pop culture and I like the idea of Visual Novels. Unfortunately most,if not all, Visual Novels are published in Japanese, Korean, Chinese or some other eastern language I don’t master. Almost no stories are published in English. So if I wanted to read English Visual Novels I had to either write them myself or facilitate others with an easy tool to write Visual Novels.
My second reason is that on the GP32 boards (gp32x.com) I saw a lot of people that wanted to get creative on the GP32 but didn’t know how to program in C (yet). With VNS I will try to give them something where they can be creative and visualize their ideas with the help of graphics, sound and a (branching) story without knowing how to program. In this respect VNS can be considered a very basic “game creation tool”.
Furthermore I would like to thank (in no particular order)
· Rico for his beta testing and his many suggestions and tips. NiN^_^NiN for his beta testing and story building (thanks for the exclusive ;).
· Hando for setting up one of the best console sites/boards.
· Generalnmx for giving me that last push I needed to finish the first public release of VNS.
For bugs, suggestions, tips, new features, code sharing,
story ideas etc. contact me at VirtuaLeech@jpopmail.com
or through the GP32X board.
VNS (Virtua Novel System) version 1.1 containes the following new features, enhancements and bugfixes.
Most of the above new features and enhancements are shown in the demo story DEMOV11.VNS.
Unzip the files from the ZIP file VNS.ZIP to gp:\gpmm leaving the directory structure of the ZIP file intact. This means that there should be a directory VNS under gpmm containing demo1.vns and demo2.vns. There should also be a directory demo1 and demo2 under VNS both containing resources like BMP,SEF and MOD files.
When the program is started press B to see the credits or press A to load a story. After pressing A you are presented with a story selector. Press Up or Down to scroll through the stories and press A to select your story.
When in a story press START to get to the menu. The menu has the following options:
Continue – Continue with the story
MOD playing – Switch between MOD playing in Mono or Stereo
Save – Save your story progress. Only one save per story can exist.
Load – Continue story from last save
Restart current story – Restarts current story
Another story – Stop current story and return to Story load menu
Reset GP32 – Quits VNS and resets GP32
When in a story press SELECT to switch between graphics mode and text mode. This option is mainly for testing when developing a story.
The following rules/limitations apply to the graphics used in VNS:
(See VNS definition file description).
VNS uses sound for two types of events: background music and sound effects. Background music can be either SEF files or MOD files. For now sound effects must always be in the GP32 default SEF format. SEF files can be create from WAV files with the GP32Converter tool from Edorul which can be found at http://www.ifrance.com/edorul/gp32/
VNS on the GP32 uses the 8.3 files system. Therefore all files (graphic, sound, zip and story) must be in the 8.3 format.
BUG ALERT: At the moment if you stream SEF files (automatically done when you use a SEF file as background music) from a ZIP file VNS crashes if you try to read another file from the ZIP at the same time. I have no idea (yet) why this happens. For now if you use SEF files (instead of MOD files) for background files you must leave them out of the ZIP file.
The GP32 requires all sounds that are played simultaneously to be of the same frequency and resolution. Therefore the sound effects and background music used in a one story must all be of the same frequency and bit rate. MOD files are a bit more flexible. So any MOD file can be used, and is automatically scaled down/up by VNS using the settings given in the keywords SOUNDFREQ and SOUNDBITS
For playing MOD files the CHN mod library is used. For now this library only plays 4 channel MOD files. When CHN releases his new version of the library, with support for more tracker formats, I will try to incorporate this new library .
The keywords SOUNDFREQ and SOUNDBITS set the frequency and bit rate you are using for your SEF files.
SOUNDFREQ can have the following values:
· M11 – Mono 11 KHz.
· S11 – Stereo 11 KHz.
· M22 – Mono 22 KHz.
· S22 - Stereo 22 KHz.
· M44 - Mono 44 KHz.
· S44 - Stereo 44 KHz.
SOUNDBITS can have the following values:
· 8 – 8 bit
· 16 – 16 bit
Background music can be continued across several scenes. (See VNS definition file description).
A WAV loader is on the wish list to make Windows based story building easier. WAV also has the advantage of having the sample frequency and bit rate available in the header information.
First keywords in the definition file MUST ALWAYS BE STORYTITLE and STORYDIR (STORYDIR is no longer mandatory from VNS version 1.1 if all resources are in a zip file).
First scene must always be called STORYSTART. Other scenes can have any name (as far as I have tested) as long as they are between brackets. For example [MYSCENE]
After the last scene there must always be the keyword STORYEND. If you omit this VNS will scan until the maximum numbers of lines (9999) has been reached. All lines after STORYEND are ignored.
Lines starting with // are considered comment and are ignored
What follows below is a description of the format of the VNS definition file. It is also recommended to look at the demos provided in the VNS distribution ZIP file.
First a list of the configuration keywords. These keywords can only be used ones at the top of the VNS definition file.
The title of the story to display by the loader. The user sees this description when loading a story.
Example: STORYTITLE=VNS demo story 2
The directory where the loose file resources (BMP, SEF and MOD files) are for this story. This directory must be a subdirectory of VNS. If all your resources are in a ZIP file the STORYDIR keyword is no longer mandatory.
Example: STORYDIR=DEMO2
The name of the zip file that contains the resources of the story. The zip file must reside in the \gpmm\vns directory. When the story loads a file (graphic, sound or music) the system first checks to see if this file exists as a loose file in the STORYDIR directory. If the file doesn’t exist there then the file is searched within the ZIP file.
Example: ZIP=demo2.zip
Defines the bitmap used as a title screen for this story. <BMP file> must be a 320x240 bitmap.
Example: TITLESCREEN=title.bmp
Defines the colour used for text. The value corresponds to a palette entry. In 8bit mode the palette used is the palette from the background image in STORYSTART.
Example: TEXTCOLOR=12
Defines the colour used for the text shadow. This colour is also used for the raster beneath the text and as background for error messages. The value corresponds to a palette entry. In 8bit mode the palette used is the palette from the background image in STORYSTART.
Example: TEXTSHADOW=0
Defines the colour used for the bar that appears beneath the choices. The value corresponds to a palette entry. In 8bit mode the palette used is the palette from the background image in STORYSTART.
Example: BARCOLOR=244
Defines the sample frequencies used for the background music and sound effects. All music and sound effects used within a story must be of the same frequency. MOD files are a bit more flexible. So any MOD file can be used and is automatically scaled down/up by VNS using the SOUNDFREQ setting.
Valid values are:
· M11 – Mono 11 KHz.
· S11 – Stereo 11 KHz.
· M22 – Mono 22 KHz.
· S22 - Stereo 22 KHz.
· M44 - Mono 44 KHz.
· S44 - Stereo 44 KHz.
Example: SOUNDFREQ=M11
Defines the resolution used for the background music and sound effects. All music and sound effects used within a story must be of the same resolution. Again this does not apply to the MOD files used.
Valid values are:
· 8 – 8 bits resolution
· 16 – 16 bits resolution.
Example: SOUNDBITS=8
Defines the colordepth used for the graphics.
Valid values are:
· 8 – 8 bits colordepth
· 16 – 16 bits colordepth
Example: GRAPHICBITS=16
The following keywords can be used in each scene. If you use the same keyword more then one time the last setting will be used.
Scene identifier. Must always be between brackets. The VNS definition file must always include at least [STORYSTART] (the first scene of the story) and [STORYEND] (after the last scene). Other scene names can be self-defined.
Valid scene names are [SCENE003], [AtTheBeach], [at my house]. Do not use a comma (,) in the scene name. This will cause a “SCENE not found” error.
Example: [STORYSTART]
Defines what happens with information from the previous scene.
ERASE completely erases all settings of the previous scene.
CONTINUE erases the scene except for the settings of BGM, BGP, SPRITE1, SPRITE2, SPRITE3, SPRITE4, TEXTOWNER.
When this option is omitted CONTINUE is the default setting.
Valid values are ERASE, CONTINUE
Example: PREVIOUS=CONTINUE
Defines the transition effects between two scenes.
If this option is omitted the default setting NORMAL is used.
The speed with which the transition operates can be changed with the system variable _transdelay
Valid values are: FADE, WIPR, WIPEL, WIPEU, WIPED, BLINDSR, BLINDSL, BLINDSU, BLINDSD, CLOSEH, CLOSEV, OPENH, OPENV, PIXELREPLACE, NORMAL.
Example: TRANSITION=CLOSEV
Defines the SEF or MOD file used for background music. The SEF files must be in the frequency and bit rate as specified with SOUNDBIT and SOUNDFREQ. The background music is streamed from disk; so large files should not be a problem. When this option is omitted the background music from the previous scene will keep playing (unless PREVIOUS=ERASE is issued). When the option BGM= is used without a SEF or MOD file behind the = symbol the current background music stops playing. MODs are played using CHNs mod library.
Example: BGM=BACK01.SEF
Example: BGM=AMIGA.MOD
Defines the SEF file used as a sound effect. The SEF files must be in the frequency and bit rate as specified with SOUNDBIT and SOUNDFREQ. The sound effect is played only once at the beginning of the scene. IF a new scene begins and the sound effect is still playing the sound effect is stopped. If you are using MOD files as background music please watch that the resolution of the SEF file (8 or 16 bits) is the same as the MOD file playing when the sound effect is used.
Example: SFX=PHONE.SEF
Defines the BMP file used as background image. The BMP file must be of dimension 320x240. The BMP file can be RGB of RLE encoded. In 8bit mode the palette used for all images (sprites and background) is taken from the BGP at STORYSTART.
When this option is omitted the background from the previous scene will be used (unless PREVIOUS=ERASE is issued).
Example: BGP=BACK01.BMP
Defines the BMP file to be used for displaying a picture in the topleft of the textbox to indetify the talking character. Due to a bug in the BMP loading routine BMP dimensions must be a multiple of 20 (ex. 20x120). When the transparency colour is omitted the first colour of the palette (colour 0) will be used as transparent colour.
Location of the textowner picture is 8 pixels from the left side of the screen while the bottom of the picture is placed 10 pixels below the top of the textbox. the picture is overlayed over the textbox but under the text.
Example TEXTOWNER=LUM01.BMP,65343
Defines the BMP file to be used as sprite and it’s location on the screen. Due to a bug in the BMP loading routine BMP dimensions must be a multiple of 20 (ex. 20x120). When the transparency colour is omitted the first colour of the palette (colour 0) will be used as transparent colour.
Location can be L,M or R representing Left, Middle or right. Left means the centre of the sprite is at pixel 60, right means the centre of the sprite is at pixel 180. When a sprites width exceeds 120 pixels and is placed at the left or right, the spirte is aligned to the left or right side of the screen to prevent parts of the sprite falling of the screen. The bottom of the sprite is always aligned with the bottom of the screen. When this option is omitted the sprite from the previous scene will be used (unless PREVIOUS=ERASE is issued). When the option SPRITE1= is used without a sprite file behind the = symbol the sprite is erased from the scene.
To have more control over the sprite placement you can also set the system variables _spriteleft, _spriteright and _spritemiddle. These variables hold the default value for the middle left and right placement of the sprite.
Example SPRITE1=LUM01.BMP,M
See SPRITE1
Defines a line of text (maximum 300 characters) that is displayed on the screen. This text is automatically word wrapped over a maximum of nine lines. This way you can put all the text for the scene in one line. If you want to have more control over your text placement you can use TEXT1, TEXT2, TEXT3 etc. See also below.
New in version 1.1 is the ability to display the value of a variable in a textline the format for this is ~~variable . So if you have defined a variable called goldpieces you can display the value of this variable by putting ~~goldpieces in your text. Make sure you always put a space after the variable name. For now only one variable per textline can be displayed. So if you want to display more than one variable in a scene you have to use TEXT1, TEXT2, TEXT3 etc. instead of TEXTWRAP to display your text with variables.
Example TEXTWRAP=Hi, I am Lum. And I like to introduce myself to you with this long line of text. My age is ~~currentage years.
Defines a line of text displayed on the screen. A maximum of 9 lines of text of approximately 40 characters each can be displayed in one scene. Each line of text can display one variable. For more info on using variables in text see the TEXTWRAP keyword.
Example
TEXT1=Hi, I am Lum.
TEXT2=And I like to introduce myself to you.
TEXT3=My age is ~~currentage years.
TEXT4=and my shoesize is ~~shoesize .
See TEXT1
Defines the choices displayed on screen. The choices represented here decide which way the story continues. Up to 4 choices can be displayed in one scene. It there is only one choice the text is ignored and the user is presented with a picture of the A button in the lower right corner as a reminder to push the A button to go to the next scene. When no choice is defined VNS continues with the next scene in the definition file after the A button is pushed.
SCENENAME must be a valid scene name defined in the VNS definition file WITHOUT brackets. If a non-valid scene name is used a “Scene not found” error follows.
TEXT is the text displayed to the user in the choice menu.
Example(s):
CHOICE1=SCENE004
or
CHOICE1=SCENE006,Go to the left
CHOICE2=SCENE007,Go to the right
See CHOICE1
Used to timeout a scene. If the number of seconds defined in seconds have elapsed, the program will continue automatically as if the A button has been pressed. The second parameter (choice) is for use in conjuction with the CHOICE1..4 keywords. When the user can make more then one choice the choice parameter contains the default choice that is selected when timeout occurs.
Example:
Timeout=5
Timeout=10,2
CHOICE1=GOLEFT,Go to the left
CHOICE2=GORIGHT, Go to the right.
In this example when the timout occurs after 10 seconds the story continues with scene GORIGHT.
The keyword PUSHSCENE (together with POPSCENE) can be used
to create something resembling procedures in VNS stories. With PUSHSCENE you push
the current scene onto a stack (incl. scene name, BGM, BGP, sprites etc.) after this
the story continues with the scene specified in Scenename. When the POPSCENE
keyword is then found the story continues with the scene that contained the PUSHSCENE.
It is important to remember that the scene contaning the PUSHSCENE keyword is not
displayed until a POPSCENE keyword is found. For an example of the PUSHSCENE and POPSCENE
keywords see the DEMOV11.VNS demo story file.
For now the stack can only contains one scene.
If another PUSHSCENE is issued before a POPSCENE is issued only the last scene will remain
on the stack.
These keywords can be used to create things like battle scenes or status displays.
Example:
[MyScene]
PUSHSCENE=YourScene
TEXTWRAP=This is you.
[YOURSCENE]
TEXTWRAP=Now in YourScene
[YOURSCENE-END]
POPSCENE
In the above example when MyScene is read control is immediatly handed over to YourScene (the name specified after PUSHSCENE) the text in TEXTWRAP is not displayed until a POPSCENE is found and control is handed back to MyScene.
Used in conjuction with PUSHSCENE. When a POPSCENE is found control is immedialty returned to the scene that issued the PUSHSCENE command. All other commands in the same scene as the POPSCENE keyword are ignored. So it is a good idea to have only the POPSCENE keyword in the last scene of your PUSHSCENE procedure. For more info see the PUSHSCENE keyword above.
Defines a hotspot on screen from coordinates X,Y to X+WIDTH,Y+HEIGHT. When the user clicks inside this region (using the joypad and the A button) VNS continues with the scene specified in SCENENAME
Example:
HOTSPOT1=FACE,100,10,20,40
See HOTSPOT1
The story file must always end with the keyword STORYEND. If not found the file is scanned until the last (virtual) line (line 9999).
VNS supports a simple variable system. With this system you can set and change variables and make decisions based on the value of the variables.
In this version of VNS only numeric variables can be used.
For more information about the variable system check out demo5.vns.
The following keywords can be used within the VNS definition file.
Assigns <value> to <varname>. If <varname> does not exist <varname> is created. Special values for <value> are:
· +, increases <varname> with 1
· -, decreases <varname> with 1
· RANDOM, assign a random value between 1 and 100 to <varname>
· <varname2>, Assigns the value of <varname2> to <varname>
SETVAR can also be used to change the values of system variables.
Examples
SETVAR=A,3
SETVAR=A,+
SETVAR=A,-
SETVAR=B,RANDOM
SETVAR=A,B
Assigns the value of the choice the user makes to a variable names <varname>. This is usefull when you want to store the choice a user makes.
Example:
CHOICEVAR=PickedUp
CHOICE1=LAMP,Pick up the lamp
CHOICE2=KEY,Pick up the key
If <variable> equals <value> all keywords between IFEQUAL and ENDIF are processed. If not, all keywords between IFEQUAL and ENDIF are ignored. All IF statements (IFEQUAL, IFNOTEQUAL, IFGREATER, IFSMALLER) can be nested as deep as you like. The end of all IF statements must be terminated with an ENDIF (see example).
Example:
SETVAR=A,1
IFEQUAL=A,2
BGP=BACK01.BMP
ENDIF
IFNOTEQUAL=A,2
BGP=BACK02.BMP
ENDIF
The result of the above example is that back02.bmp will be used as background picture since variable A hast the value 1.
If <variable> does not equals <value> all keywords between IFNOTEQUAL and ENDIF are processed. If not, all keywords between IFNOTEQUAL and ENDIF are ignored.
If <variable> is greater then <value> all keywords between IFGREATER and ENDIF are processed. If not, all keywords between IFGREATER and ENDIF are ignored.
If <variable> is smaller then <value> all keywords between IFSMALLER and ENDIF are processed. If not, all keywords between IFSMALLER and ENDIF are ignored.
System variables can be used and set just as regular variables. Within VNS the following system variables exists:
_version – the version of VNS. Can be used to check if the right version is used for your story
_spriteleft – the default horizontal position for left placed sprites.
_spritemiddle – the default horizontal position for left placed sprites.
_spriteright – the default horizontal position for left placed sprites.
_transdelay – Transition delay. A smaller value means transitions will appear faster
_modinstereo – Returns 1 if the current mod is played in stereo.
_seconds – Returns the number of seconds elapsed since this story was started.
__availablemem – Returns the number of available free bytes.
__darkencolor – Set the transparacy color for the textbox in 16bit graphics mode. This way you can use the color of the textbox to, for example, display the mood of the talking person. Red for angry, green for peacfull etc. The value given to _darkencolor is a 15bit GP32 color number.
Examples of _darkencolor values:
very red 63687
very blue 6399
very green 8135
red-ish 64743
blue-ish 40191
green-ish 40935
neutral 40167 (default when no darkencolor specified)
WAV loader
BMP loader fix
Panoramic images
Windows Story Builder
Remove clicking when SEF file restarts
Free sprite placement
Free text placement
VNS on the GP32 is freeware. You are however not allowed to sell VNS. You can however sell your story, and give away VNS for free. Also I would like to note that I, the author of VNS, am in no way responsible for the content of the stories made with/for VNS. These stories and there content, as well as the used graphics, sound and storyline, are the responsibility of the author of the story.