Guide to VNS release one-dot-zero

 

 

Introduction. 2

New in version 1.1. 2

Graphics. 4

Sound. 5

VNS definition file. 6

Configuration keywords. 6

STORYTITLE=title of story. 6

STORYDIR=directory containing resources for story. 6

ZIP=name of zip file containing resources. 6

TITLESCREEN=BMP file. 6

TEXTCOLOR=palette index number7

TEXTSHADOW=palette index number7

BARCOLOR=palette index number7

SOUNDFREQ=GP32 supported sample frequency. 7

SOUNDBITS=GP32 supported sample frequency. 7

GRAPHICBITS=colordepth. 8

Scene keywords. 9

[SCENENAME]9

PREVIOUS=ERASE/CONTINUE. 9

TRANSITION=transition effect.9

BGM=SEF file / MOD file. 9

SFX=SEF file. 10

BGP=Valid BMP file. 10

TEXTOWNER=Valid BMP file, transparency colour10

SPRITE1=Valid BMP file, Screen location, transparency colour10

SPRITE2, SPRITE3, SPRITE4b. 10

TEXTWRAP=Line of text10

TEXT1=Line of text11

TEXT2, TEXT3, TEXT4, TEXT5, TEXT6, TEXT7, TEXT8, TEXT9. 11

CHOICE1=Scenename,Text11

CHOICE2, CHOICE3, CHOICE4. 11

TIMEOUT=seconds,choice. 11

PUSHSCENE=Scenename. 11

POPSCENE. 11

HOTSPOT1=SCENENAME,X,Y,WIDTH,HEIGHT. 12

HOTSPOT2, HOTSPOT3, HOTSPOT4. 12

STORYEND.. 12

The variable system.. 13

SETVAR=<varname>,<value>. 13

CHOICEVAR=<varname>. 13

IFEQUAL=<variable>,<value>. 13

IFNOTEQUAL=<variable>,<value>. 14

IFGREATER=<variable>,<value>. 14

IFSMALLER=<variable>,<value>. 14

System variables. 15

To do / wish list:16

Legalities. 17


Introduction

 

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.
17


New in version 1.1

 

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.



Installation and usage

 

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.

 


Graphics

 

The following rules/limitations apply to the graphics used in VNS:

 

(See VNS definition file description).

 


Sound

 

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.

 

 


VNS definition file

 

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.

 

 

Configuration keywords

 

First a list of the configuration keywords. These keywords can only be used ones at the top of the VNS definition file.

STORYTITLE=title of story

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

 

STORYDIR=directory containing resources for story

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

 

ZIP=name of zip file containing resources

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

 

TITLESCREEN=BMP file

Defines the bitmap used as a title screen for this story. <BMP file> must be a 320x240 bitmap.

 

Example: TITLESCREEN=title.bmp

 

TEXTCOLOR=palette index number

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

 

TEXTSHADOW=palette index number

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

 

BARCOLOR=palette index number

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

 

SOUNDFREQ=GP32 supported sample frequency

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

 

SOUNDBITS=GP32 supported sample frequency

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

 

GRAPHICBITS=colordepth

Defines the colordepth used for the graphics.

Valid values are:

·         8 – 8 bits colordepth

·         16 – 16 bits colordepth

 

Example: GRAPHICBITS=16

 


Scene keywords

 

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.

 

[SCENENAME]

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]

 

PREVIOUS=ERASE/CONTINUE

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

 

TRANSITION=transition effect.

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

 

BGM=SEF file / MOD file

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

SFX=SEF file

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

 

BGP=Valid BMP file

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

 

TEXTOWNER=Valid BMP file, transparency colour

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

 

SPRITE1=Valid BMP file, Screen location, transparency colour

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

 

SPRITE2, SPRITE3, SPRITE4

See SPRITE1

 

TEXTWRAP=Line of text

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.

 

TEXT1=Line of text

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 .

 

TEXT2, TEXT3, TEXT4, TEXT5, TEXT6, TEXT7, TEXT8, TEXT9

See TEXT1

 

CHOICE1=Scenename,Text

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

 

CHOICE2, CHOICE3, CHOICE4

See CHOICE1

 

TIMEOUT=seconds,choice

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.

 

PUSHSCENE=Scenename

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.

 

POPSCENE

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.

 

HOTSPOT1=SCENENAME,X,Y,WIDTH,HEIGHT

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

 

HOTSPOT2, HOTSPOT3, HOTSPOT4

See HOTSPOT1

 

STORYEND

The story file must always end with the keyword STORYEND. If not found the file is scanned until the last (virtual) line (line 9999).

 


The variable system

 

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.

 

SETVAR=<varname>,<value>

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

 

CHOICEVAR=<varname>

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

 

IFEQUAL=<variable>,<value>

 

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.

IFNOTEQUAL=<variable>,<value>

If <variable> does not equals <value> all keywords between IFNOTEQUAL and ENDIF are processed. If not, all keywords between IFNOTEQUAL and ENDIF are ignored.

 

IFGREATER=<variable>,<value>

If <variable> is greater then <value> all keywords between IFGREATER and ENDIF are processed. If not, all keywords between IFGREATER and ENDIF are ignored.

 

IFSMALLER=<variable>,<value>

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

 

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)


To do / wish list:

WAV loader

BMP loader fix

Panoramic images

Windows Story Builder

Remove clicking when SEF file restarts

Free sprite placement

Free text placement


Legalities

 

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.