Script Guide_8 In-game-script

define a block of scripts often used

you can write some script and use them as a macro. The script blocks should be write in script.txt in scenario directory. You can remove the file if you do not want to use this.

[iscript] - defined an in game script

Goes with the name of the script. you can use a [script scriptname] to call this block in other scenario files.

An in game script starts with [iscript] and ends with [endiscript].

[iscript ScriptName]

ScriptName: the name of the script block

[endiscript ScriptName]

write some script and use them as a macro. The script blocks should be write in script.txt in scenario directory. You can remove the file if you do not want to use this.

[script] - use an in game script

This script goes with the name of the script , use this to call a script block in script.txt.

At the end of the script block, the game goes back to the last scenario file and read the next line of script automatically.

[script ScriptName]

ScriptName: the name of the script block which is defined in script.txt

An in game script is also supported in [btn] and [ask] as a labelname.

[btn ,100,100,script:ScriptName,readnote.png]

Example: use an in game script

 in script.txt

[iscript nameA]

[dialog bunny, I am in an in-game-script]

[dialog bunny, I can talk and show some pictures]

[dialog bunny, use a return to go back to your scenario]

[endiscript nameA]

[iscript nameB]

[dialog bunny, I am in script nameB]

[if @V <2]

[dialog bunny, I will go back]

[return]

[end if]

[if @V <2]

[dialog bunny, I will go back]

[goto labelA]

[end if]

[endiscript nameB]

in another scenario file

[label labelA]

[dialog human, I will use an in-game-script]

[script somename]

[dialog human, now I am back]

[ask try in-game-script|300|100|script:nameB|imgask3.png]

[waitclick]

[dialog human, now I am back]

In this example, the human talked and the bunny talk. After the [endiscript], it go back to the human again. then it shows how to use in-game-script in buttons.

Scripts supported in an in-game-script

➽the following are scripts same as in a scenario file
[showtip]
[showcg] [getcg]
[text] [dialog] [dialogadd]
[img] [background]
[clearimg]
[clr] [msghide] [msgshow]
[if] [end] [eval]
[sound] [bgm] [bgmstop]
[setdurtime]
[waitclick]
[initsavefile]
[load]
[call]

➽the following are scripts able to use but have some difference with that in a scenario file

[goto]

go to a label in the scenario file. You cannot jump to a label in in-game-script while the script [label] is unusable.

[return]

jump out of the in-game-script and go back to the last scenario file and read the next line.

➽there some script which is not supported in in-game-script

[ask] [btn] [askdialog] [removebtn]

buttons are not supported

[label] [save]

no labels and you cannot save in an in-game-script

[wait]

you cannot wait but you can still use the parameter Time in [img].

[enablesave] [disablesave]

Now it 's an end of the script guide of sakusaku engine. we will keep on with some example game the next time

Script Guide_7 CG gallery,save and game initialize

CG garllery

[getcg] - collect a picture in gallery

Goes with the name of a picture as the one parameter, the name is defined in the cg.xml. This script will make one picture collected in gallery.

The state of the cg is updated in xml file ,and will not change when save and load.

Read the next line of script automatically.

[getcg CGname]

CGname: the name you defined in cg.xml.

[showcg]

[showcg] - show the gallery

Open the CG gallery.

Example:CG collection

in cg.xml

<CG1 name="A red picture" show="false" img="red.jpg"/>

in scenario file

[dialog bunny| show the CG gallery without a picture][getcg CG1][dialog bunny| the attribute show is true][dialog bunny| show the CG gallery][showcg]

When the gallery show the first time, you cannot open the picture CG1.After  [getcg] the picture is collected and you can open it in this example.

Save and Load

[enablesave] and [disablesave]-you can save here but cannot save there

These two script is used to set the statue of a game. When read the script [disablesave] , the save button in main menu will be gray and the game is unsaveable . Use [enablesave] to make it able to use.

IF you make a in-game menu, ask the player to choose New Game or Load a save file, you might not wish your play save here.

[enablesave]

[disablesave]

[autosave] - save point in game progress

Goes with no parameter, update the auto save file in document directory. this script would work when the game is unsaveable.

Read the next line of script automatically.

[load] - load a save file

The script [load] goes with one parameter, the path of a save file. After a load operation, the game will jump the point which stored in the save file. You will not be prompted after this script, it is different from use a load button in the main menu.

In this version ,you can use only two save file in one game.

[load Filename]

Filename: the filename of a save file. All the file can be found in the document directory.

Example: make a load menu

in init.xml

<imgsave  img="ui/btsave.png" x="65" y="15" file="save.xml"/>

<imgload  img="ui/btload.png" x="165" y="15" file="autosave.xml" txt="Do you  want to go &#xA; to the last checkpoint"/>

in a scenario file

[ask the save file|300|100|labelA|imgask3.png]

[ask the autosave file|300|200|labelB|imgask3.png]

[dialog bunny| Which file do you want?]

[label labelA]

[load save.xml]

[label labelB]

[load autosave.xml]

[initsavefile]-initialize all the save files and setting

This operation is dangerous that it will remove all your collection and setting in the game. The files in setting directory will copy to document directory and recover the cg.xml, staticvar.xml and the two save files. If the player want play a game at the very beginning, use [initsavefile].

You will not be prompted after this script, so write a confirm menu in the game before your players come to this script.

this script will read the next line of script, but not go to the first scenario  automatically.

Example: make a confirm menu before initialize

[label menu]

[ask New Game!|300|100|labelA|imgask3.png]

[ask Load|300|200|labelB|imgask3.png]

[ask Initialize|300|300|labelC|imgask3.png]

[waitclick]

[label labelC]

[ask Yes!|300|100|labelD|imgask3.png]

[ask I change my mind|300|200|menu|imgask3.png]

[dialog bunny| Do you really want to clean all your collection?]

[label labelD]

[initsavefile]

[dialog bunny| Now there is no picture in your gallery. ]

If a CG you defined in the cg.xml in setting directory is collected (show="true"), you can open it in the CG gallery of course.

Script Guide_6 the time in a game and write a warning tip

[wait] - pause the game for a second

The script [wait] goes with one parameter, the time you want the player to wait. The game will pause and wait for while, when the game is waiting, the play cannot click to read the next line.

[wait Time] 

Time: number in milliseconds. 

[waitclick] - click to continue

This script goes with no parameter, it only stops some script from reading the next line automatically.Most used at the end of an [ask] sequence. The game continues with a click.

[waiclick] 

Example: use wait to control a game

[img carrot.png|0|240|LayerA]

[wait 1000]

[img cabbage.png|0|240|LayerB]

[wait 1000]

[waitclick]

[dialog bunny| what should I eat for breakfast?]

This example shows the second picture after one second, and one second after the cabbage picture appears, players can click to read the dialog.

[setdurtime] - slow the menu down

It is a special script used to change the interval of time of the game setting. if the node <speed> exists in the staticvar.xml, this interval time of the game will be 

(the duration time in init)*(the speed in staticvar)/10

[setdurtime]

Example: change the fade in time

[dialog bunny|hi!]

[eval speed=1000]

[setdurtime]

[img ramen1.png|0|120|LayerA]

[dialog bunny|it takes 100 seconds to show a picture]

[eval speed=50]

[setdurtime]

[img ramen1.png|200|120|LayerB]

[dialog bunny|it takes 5 seconds to show a picture]

[eval speed=0]

[setdurtime]

[img ramen1.png|400|120|LayerC]

[dialog bunny|the picture shows directly]

Use a round number as the <speed>.

If the node <speed> does not exist, this script would not work. The [setdurtime] change global time so the speed of menu bar is slow down too.

[showtip] - show tips and warning

The script [showtip] shows some text on the left top of the game. It is usually used to show some tips when the game is played, also, it shows some information when the scenario has something wrong. The tips stay on the screen for a while and fade out, the time it stays is set in the init.xml.

  Goes with one parameter, the text you want show as a tip. Read the next line of script automatically.

[showtip Text]

Text: Some words you want to tell the players.

Example: write a Waring content

[showtip DO NOT COPY WHAT THE CHARACTERS DO IN YOUR REAL LIFE]

Script Guide_5 make your scenario with several files

It will be a nightmare to write all the content in a single file when the story is long, split it into episodes in other files.

[call] -  jump to another file

The script [call] goes with one or two parameters, the scenario file and the label you want to go to. You can use many files and jump between them in a game.  Use this script to read another scenario file.

[goto Filename| Labelname]

Filename: the filename of the scenario, all the file can be found in the scenario directory.

Labelname: the name a label in current scenario file. You can use variables in Labelname. It will read the first line  without this parameter.

Example: read a new file

[call anotherfile.txt]

This will lead the game to another file and read the first line of script.

[call anotherfile.txt|somelabel]

This will read the other file and jump to the line of that label.

[return] - go back to the last file

when you use [call] to jump to another scenario file, you can use the script [return] to go back to the last file and start at the next line of [call]. you can use it only once after a [call] in this version.

the last file will store in the savefile after a script [call] runs correctly if you saved. So the [return] is usable after you load a savefile.

Example: jump and go back

In the mainfile.txt

[dialog bunny| hello! I am bunny.]

[call anotherfile.txt]

[dialog bunny| It is me again!]

In the anotherfile.txt

[dialog cabbage| Hi, I am a cabbage.]

[return]

The bunny says hello and a cabbage come to say hi, and then the game goes back to the first scenario file, shows the bunny again.

Script Guide_4 variables and conditional statement

[if] - the conditional statement

The script [if] is used to check flag, point score or other variables you want to store, this script goes with some conditions (  logical IF statement).

Read the next line of script automatically if the result is true, or go to the next script [end if] line if the result is false.

[if (@variable Operator Value)]

[end if]

variable: the name of variable. Write the name after “@” and end with a space. You can also use some value here.

Operator: can use == as equality; != as  inequality ; > as greater than    ;    >= greater than or equal to;<    less than;<=  less than or equal to.

Value: the value you want to check can be a round number or string. You can also use variable here.

&&  logical AND  and    ||   logical OR   are supported in this script. Use a pair of bracket to split the statements.

[if (1>2)||(1<2)] obtains True

[if (1>2)&&(1<2)] obtains False

[if (1>2)||(1<2)||(1<3)] obtains True

You cannot use another [if] in a pair of [if] and [end if],use a [goto] instead.

Example: check a flag

[eval @food =carrot]

[eval @number =5]

[dialog bunny| what did I eat last night]

[if @food == carrot]

[dialog bunny|I had cabbage]

[goto labelC]

[end if]

[dialog bunny| the result is false if it is not carrot]

[goto somewhere]

[label labelC]

[if @number >3]

[dialog bunny| I ate too much]

[end if]

[label somewhere]

In this example, it will check the food type and the number. If the food type obtains false, the script will jump to another label and never check the number again.

[eval] -assignment statement

It usually need to store some value such flags and points in a game. The script [eval] is used to gave variables a value and store it. Read the next line of script automatically .

[eval @variable Operator Value]

variable: the name of variable. Write the name after “@” and end with a space.

Operator: can use + addition; - subtraction and = to evaluation.

Value:  can be a round number or string. You can also use variable here.

When you want to show a variable in dialog or some text, use a “@” and a space.

Example: evaluation a variable

[eval @food =carrots]

[eval @number =5]

[dialog bunny| I ate @number  @food  this morning. ]

[eval @number +1]

[dialog bunny| I ate @number  today. ]

the bunny will say “I ate 5 carrots this morning.” and”I ate 6 today.”

if you use [eval @number +another] after this, the result will be ”I ate 1another today.” Be careful to use number and string .A string does not support the subtraction operator.

All variables which defined in the init file will be stored in a save files. The variables in staticvar will write in file once their value are changed. If a variable has not been defined, you can still use it but it will not write in a save file.

Script Guide_3 make choice and jump to label

 Interactive novels alway have some branch of story, the script [goto] and [ask] can make this.

[goto] - jump to some other part

The script [goto] goes with one parameter, the label in current scenario file. Do nothing If cannot find the label. Jump to the line where the label was find, and Read the next line of script automatically.

[goto Labelname]

Labelname: the name a label in current scenario file.  The labels can be defined with the script [label].

You can use variables in Labelname.

[label]

The script [label] goes with one parameter, the name of this label. Read the next line of script automatically.

To ensure your game runs correctly, Each label should have its own name.

[label Labelname]

Labelname: The name this label in current scenario file. 

You cannot use variables here.

Example: jump to another section with goto and label

[goto Sec2]
[label Sec1]
[dialog Bunny| I like clover.]
[label Sec2]
[dialog Bunny| I like cabbage.]

you can also use in this example[eval somevariable= Sec2][goto @somevariable ]

[ask] - in game menu 

The script [ask] goes with 5 parameters, some text the players was asked,the position on of selection button, the label or some inscript and the gackground imagine of this button. Read the next line of script automatically till it comes to an [waitclick],[dialog],[text] or [askdialog] .

The game will stop when comes to a script [ask], the player should click one button to continue the game.

You can use a swf animation as the background imagine, but the action script will not work on IOS device.

[ask Text|posX|posY| Labelname|Filename]

Text: Some words the player was asked. (align center)

posX: the position where the imagine display horizontal.

posY: the position where the imagine display vertical .

Labelname: The name this label in current scenario file. You can use variables here. You can use a inscript as a label.

Filename: The filename of the imagine, all the file can be found in the ui directory.

Example: make some choice

[ask cabbige|300|100|labelA|imgask3.png]
[ask carrot|300|200|labelB|imgask3.png]
[ask nothing|300|300|labelC|imgask3.png]
[dialog bunny| what should I eat for breakfast?]

[label labelA]
[dialog Bunny| I like cabbage!]
[label labelB]
[dialog Bunny| Nahhhhh!]
[label labelC]
[dialog Bunny| all right.]

In this example, player should choose one of these selection to make the game continue.

[btn] - buttons in game 

Same as the script [ask], Read the next line of script automatically , but will not stop the game. You can use  [waitclick],[dialog] and [text] after a [btn]. The buttons will keep on the screen until the play click one of them.

When the player click a button All [btn] will be removed. Use a [removebtn] when you want to clean them up.

[btn Text|posX|posY| Labelname|Filename]

Example: make a button

[label labelA]
[btn STOP!!|300|70|labelB|imgask3.png]
[dialog bunny| what should I eat for breakfast?]
[dialog bunny| I like cabbage but I eat them last night]
[dialog bunny| I don't have any carrot. ]
[removebtn]
[dialog bunny| but I am hungry.]
[goto labelA]
[label labelC]
[dialog Bunny| I decide to have some cabbage!]

In this example, the bunny will ask itself again at [goto labelA], break the loop by clicking the button.

Script Guide_2 Image and sound

A  visual novel is too pale without pictures and musics. It should have some background pictures, music and a picture of your character.

[img] - avatar of a character

The script [img] goes with four or five parameters, read the next line of script automatically.

[img Filename| posX| posY| Layer| Time] 

Filename: The filename of the imagine, all the file can be found in the role directory. IF the filename parameter is empty or an “unload”, the layer will be cleaned

posX: the position where the imagine display horizontal. Change the position to make the layer move.

posY: the position where the imagine display vertical . Change the position to make the layer move.

Layer: the name of the layer where the imagine placed on.

Time: if you want the imagine fade in/out or move in some time longer. Not a necessary parameter.

Example: A Simple imagine show

[img avatar.png|0|240|LayerC]

[dialog Bunny |Hello there!]

[img avata2.png|50|240|LayerC|1000]

[dialog Bunny |I have <font  color="#ff0000">Red</font> eyes]

[img unload|100|240|LayerC]

[clearimg]

➽ The script [img] supports some swf files; you can show small animations with this.

[clearimg]-remove all imagine

The script [clearimg] will clean all the imagines in all layers. It is a faster way to remove all the imagines on the screen instead of unloading them one by one. Read the next line of script automatically.

[background]-show background picture

The script [background] goes with one parameter, the path of the background imagines. The background stays at the bottom of all layers.

read the next line of script automatically.

[background Filename]

Filename: the filename of the imagine, all the file can be found in the ui directory. IF the filename parameter is “clear”, the layer will be cleaned

Example: show a background picture

[background clear]

[background white.jpg]

this example remove the old picture and show a new imagine file.

[sound]-sound effects

The script [sound] goes with one parameter, the path of the mp3 file. The sound clip will be played once.

Read the next line of script automatically.

[sound Filename]

Filename: the filename of the sound file, only mp3 file. All the file can be found in the sound directory.

Example: play a sound effect

[sound bgm4.mp3]

[bgm]-a background music

The script [bgm] goes with one parameter, the path of the mp3 file. The music will loop until it go to a script [bgmstop].

Read the next line of script automatically.

[bgm Filename]

Filename: the filename of the sound file, only mp3 file. All the file can be found in the sound directory.

Example: have a background music

[bgm bgm4.mp3][bgmstop]

Script Guide_1 dialog and aside

All the scenario files can be found in the scenario directory, saved as txt file.

the scenario files usually saved as .txt file, while you can also save them with any extension.

It is highly recommended to Encode them in unicode

no matter which extension they have, edit them with text editors.

😃 try editplus or notpad++

you can place comment after  “//”

blank lines will not be read.

---------------------------

[text]--Subtitle or aside 

the script [text] goes with one five or six parameters , you need click to read the next line of script, or use an automation parameter to read the next line automatically .

[text Type| posX| posY| Width| Text| Automation ]

Type:

new: all the text exist will be clean and the new text will be placed at the beginning

add: new text will add after the old ones

clear:  clean all the text

posX: the position where the text field display horizontal 

posY: the position where the text field display vertical 

Width: the width of the text field

Text: some text you want to show in the screen

Automation :  write an “auto” to make the next line of text show itself automatically. Not a necessary parameter.

Example: A Simple text Game

[text new|0|20|100|Hello!]

[text new|0|20|200|welcome to sakusaku engine!|auto]

[text add|0|20|100|It is a very simple text game]

[text add|0|20|100|after this line, all the text will be removed]

[text clear]

[dialog]--the words what your character say 

The script [dialog] goes with two or three parameters , you need click to read the next line of script, or use an automation parameter to read the next line automatically .

[dialog Name | Text | Automation ]

Name: The name of the character who is talking.

Text: Some words the character says.

Automation: write an “auto” to make the next line of text show itself automatically. Not a necessary parameter.

[dialogadd Text]

The script [dialogadd] goes only one parameter, the Text you want to add a new line after the last words the character said.

Example: A Simple dialog

[dialog Bunny |Hello there!]

[dialogadd I am a cute animal in this forest!]

➤➤➤➤➤➤➤➤➤➤➤➤➤➤➤➤

The script [dialog] and [text] support some HTML tags.

<u>under line</u><br>line break

 The last example look the same as this

[dialog Bunny |Hello there! <br> I am a cute animal in this forest!]

The script [dialog] and [text] also support color tags and a herf tag.

[dialog Bunny |I have <font  color="#ff0000">Red</font> eyes]

[dialog Bunny |Click <A HREF="http://somehere.com">Here</A> to see my photo]

while the HTML tags can be used ,you need to write the angle brackets with &lt; and &gt;

➤➤➤➤➤➤➤➤➤➤➤➤➤➤➤➤

[clr]--clean and hide the dialog

The script [clr] hides the dialog frame and remove all the dialog text, 
click to read the next line of script.

[msghide]/[msgshow]--hide but not clean them

Different with the script [clr], just hide or show the dialog frame while do not r remove the dialog text, click to read the next line of script.

[msghide]: hide the dialog frame

[msgshow] :show the dialog frame

[img]--give the dialog a picture

A visual novel is not only a novel.Show pictures when your characters talking. 

The script [img] goes with four or five parameters, read the next line of script automatically.

[img Filename| posX| posY| Layer| Time] 

Filename: The filename of the imagine, all the file can be found in the role directory. IF the filename parameter is empty or an “unload”, the layer will be cleaned

posX: the position where the imagine display horizontal. Change the position to make the layer move.

posY: the position where the imagine display vertical . Change the position to make the layer move.

Layer: the name of the layer where the imagine placed on.

Time: if you want the imagine fade in/out or move in some time longer. Not a necessary parameter.

Example: A Simple imagine show

[img avatar.png|0|240|LayerC]

[dialog Bunny |Hello there!]

[img avata2.png|50|240|LayerC|1000]

[dialog Bunny |I have <font  color="#ff0000">Red</font> eyes]

[img unload|100|240|LayerC]

The script [img] supports some swf files; you can show small animations with this.

[clearimg]--clean all the layer

The script [clearimg] will clean all the imagines in all layers. It is a faster way to remove all the imagines on the screen instead of unloading them one by one. Read the next line of script automatically.

How to Make A Visual Novel_6 The save files

You can use two save point in a game, the auto save and quick save
the  two filename is defined in init.xml

save.xml autosave.xml

if you use [autosave] or click the save button in the game, you will find some file like this in document directory.
The filename is what you set in the init.xml. 

include the node <svar/> and <playingat>, which store the game variable and the scenario and line where you played.

How to Make A Visual Novel_5 some thing you no not want to change

staticvar.xml

while making a game, you might have some special variables which you want to make them static.Such as how long the time your player spend,how many times they finish your game.

Place the variables in the node <staticVar> </staticVar>.Then these variables won’t change when save and load.

Example:

<sv>
<staticVar>
<filecomplete1>0</filecomplete1>
<speed>1</speed>
<eDLmad>0</eDLmad>
<eBE/>
</staticVar>
</sv>

there are four nodes in the node <staticVar> of this example.

The node <speed></speed> should not be removed.( used to set ratio of the speed of imagine or background fade out, also set the speed of the menu bar hide and show ).

in this game you can use a filecomplete1 to keep a variable of the state of  episodes.

Evaluation the variable to 1 at the end of one episode. When the player load an earlier save point, the variable will not change back to 0.  

How to Make A Visual Novel_4 Make a CG Gallery

cg.xml

<name_of_CG  name="some text will display on the top the imagine" show= "true or false while true means the CG is collected"  img="path of the imagine file"/>

The path of the imagine file is under the ui directory. the attributes “show” will become “true” on the script [getCG], all the setting in cg.xml will not change with the save/load operation.

The CG gallery will display on the script [showCG], all the CG can be opened while the  attributes “show” is “true”.

The cg files you defined will show in the gallery ,8 pictures in one page. click the picture to open it, the name or some other information will show at the top left.

In the gallery , use the page up and down buttons to turn the page ,use the exit button to back to the game. 

the CG defined in the cg.xml will show up in the CG gallery.

The pictures with the attributes “show” is “true” can be click to see the detail.

the look of the buttons was defined in the init file.

see how to do a UI Customization

when click a collected CG in the gallery, the picture show up with some text on the top.click anywhere to close this picture. 

in the cg.xml file

<cg> <cgpanel>   <CG1 name="A red picture" show="true" img="red.jpg"/>   <CG2 name="A black picture" show="false" img="black.jpg"/>   <CG3 name="A white picture" show="false" img="white.jpg"/>   <CG4 name="The street" show="true" img="DMstreet1.jpg"/>   <CG5 name="A notebook" show="false" img="DLnote.jpg"/>   <CG6 name="Moon on the roof" show="false" img="DLroof.jpg"/> </cgpanel></cg>

these node with a false such as CG3 also in the gallery but can not be clicked.

in games, you can use a script [showCG] to open the CG gallery. 

Use a [getCG somename] to collect a CG file with the name you defined.

if the script [initsavefile] is used, the cg.xml and staticvar.xml will roll back to the first status.