 | TotoyeVN EngineA visual novel engine or library since June 26th, 2020. |
TotoyeVN 2.2 API Documentation
Quickstart
The TotoyeVN API is a JavaScript library used to make visual novel games with simple syntaxes. With the TotoyeVN 2, the structure of the engine has changed, looking more like a book structure to make it easier to understand. A basic in JavaScript language is necessary to use this library at its full potential.
Classes
- Screen
- Panel (NEW)
- Character
- Reader
- Book
- button
- image
- Key
- Audio
- Timer (NEW)
- Progressbar (NEW)
- Label (NEW)
- ItemList (NEW)
- HTTPRequest (NEW)
- LineInput (NEW)
Screen
The API uses a layer structure also in order to create easily "main menu layer", "game layer", "credits layer" and other without the needs of creating two or more files for each page. The Screen class manages these layers and displays them as needed.
Instance:
var scene = new TotoyeVN.Screen();Methods
A) createLayer(name)
Use this method to create a new layer inside the screen. Each layer is given a name in order to handle them easily later. The parameter is a String object.
B) addToLayer(layer_name, object)
After creating your layer, you'll want to add something to it. The layer name has to be given as the first parameter(String object). The second parameter, object, can only be from the following classes: button, image, Audio, Reader, Panel, Progressbar, Label, ItemList, and LineInput which are TotoyeVN classes.
C) addLayerView(layer_name, url)
Add a beautiful image as your layer's background. The layer name has to be given as the first parameter(String object) and the URL of the image has to be given as the second(String Object).
D) open()
The Screen doesn't display the layers by default. You need to call this method beforhand and it will start with the first layer created.
E) changeView(layer_name)
The Screen class displays one layer at the time starting with the first layer created. In order to change to another one, use this method by giving the new layer name as parameter.
F) setPageIcon(icon_url)
Same as the gameIcon class in versions 1.0 and 2.0. This method allows you to set a icon to your web page. This method has replaced the gameIcon class.
G) closeWindow()
Close the Web page window.
Panel
You can create panels inside a Screen's Layer. They can be use to isolate the menu buttons on one side of the main menu page or to show the Setting options on another side of the screen.
Instance:
var panel1 = new TotoyeVN.Panel(width, height);Methods
A) setWidth(value:float)
Change the width of the Panel instance by using this function. The value is ranged from 0.0 to 100.0
B) setHeight(value:float)
Change the height of the Panel instance by using this function. The value is ranged from 0.0 to 100.0
C) setPosition(x:float, y:float)
Change the position of the Panel instance by using this function. Both x and y values are ranged from 0.0 to 100.0
D) setBackground(r:int, g:int, b:int, a:float)
Change the background color of the Panel instance by using this function. The parameters r,g, and b which are for red, green, and blue values, are ranged from 0.0 to 255 while the parameter a which is for alpha value, is ranged from 0.0 to 1.0
E) addChild(object:variant)
Add an object instance to the panel like a button, image or text.
F) removeChild(object:variant)
Remove an added object instance to the panel like a button, image or text.
G) setBorder(color:String, size:float)
Add a border to the panel.
G) removeBorder()
Remove the border from the panel.
Character
The Character class is used to create a character for the game by setting a specific color for hir or her text in the name box. The parameters are String objects used to set the name and color for the character and both are not mandatory which means you can create a empty character for your scene.
Instance:
var Mike = new TotoyeVN.Character(name, color);Reader
The API uses a book structure to get more familiar with the visual novel type. A Book instance only cannot do anything, that's why we need to Reader to play the story that is inside the Book. The Reader class takes one parameter which is the Book instance, however the parameter is not mandatory to create the instance since it has a method by which you can set the Book instance to the Reader.
Instance:
var Mike = new TotoyeVN.Reader(book);Methods
A) setBook(Book_instance)
The method is used to set a Book instance to read by the Reader class. Know that without a Book, the Reader does nothing.
B) startAt(chapter_name)
In order for the Reader to start reading, it must know in which chapter the story begins. Use this method to set the chapter at which start the script inside the Book instance. The parameter(the chapter name) is a String object.
C) read()
Each time you want to start the story, use that method. Can be used for "Play" button.
D) close()
This method does the opposite of the read() method. It ends the mechanics that handle the story reading and can well be used in the endChapter's parameter function to end the story.
E) roundedNameBox(degree)
Method that is used to set a border radius to the name box inside the scene. The parameter is a Number object that is between 0 to 10. The default parameter is 0.
F) roundedDialogBox(degree)
Used to set a border radius to the dialog box by giving a number between 0 to 10 as parameter.
G) setTextColor(r,g,b)
Creating a character object only gives you possibility to give a character, a specific color for his or her text name. But you can only custom the text color in the dialog box by using this method. It takes three numbers parameters based on the RGB codes of colors.
H) setBoxColor(r,g,b)
You can change the boxes colors by using this method. It takes three numbers parameters based on the RGB codes.
I) saveJSON()
If you want to save the current level of your game, use this method that will return a JSON String that contains the necesary data for the scene.
J) loadJSON(json)
If you want to load a game state like a scene that you were in and has saved by getting the JSON String using the saveJSON() method, you can set the same String as a parameter to this method.
Book
The Book class is used to create a complete script for your game.
Instance:
var book = new TotoyeVN.Book();Methods
A) addDialog(character, text)
This method is called each time a new dialog(text) with character is added to the script of the game. It takes two(2) parameters: A character and the text read by the character. The text is a String object(text between quotes like "my name is Mike.") and the character object can be both a Character instance or a String(The name of the Character). This method is called at first when declaring a page in the Book instance which means that showing a character, play audio or showing background for the current page come after adding the text of the character(using addDialog).
B) addChoice(arrayOfChoices)
Method used to add choices to the script. It takes one argument which is an array with the form of [{menu: "I'm the first choice", jump: "chapter_name"},{menu: "I'm the second choice", jump: "chapter_name2},...]. As you can see the array contains objects. Each object or associative array inside the main one is a choice with menu being the text and jump being the name of the chapter to go after the player takes a choice. Four choices is the maximum that can be used for your script at a time.
C) background(image, effect)
This method is used to change the background of the scene. By default, the background is a black scene and can only be change by using this method. Only uses the method if you want to change the current background. It takes two parameters: image and effect. Image is a String Object which is the url of the image you want to set as the background(like "images/bluesea.png") and effect is how you want the background to appear when the player changes scene. It can only be "normal" or "dissolve". The second parameter(effect) is not mandatory and as the default value of "normal". You can also set a black background by putting the String "black" as the URL(the image parameter).
D) show(character_url, effect)
This methow is called to show a character on the screen during a scene. It takes two parameters: the character_url("images/mike_happy.png") and effect which can be "normal" or "dissolve". Both parameters are String object and only the first one(character_url) is mandatory to show a character. The effect parameter has a default value of "normal".
E) hide()
This method is used when you want to hide the current character. As the show method replace a character image by another, the hide method just hides the character present on the screen.
F) play(audio_url)
The method play() is used to play some music in the background of the scene. It takes one parameter(String object) which is the url of the audio file("sounds/techno.mp3").
G) pause()
If you want to pause the current audio playing in the background, you can use this function.
G) resume()
If you want to continue to play the current audio after you have paused it before, you can use this function.
H) stop()
Used to stop the current audio playing in the background without replacing it.
I) volume(magnitude)
To set or to change the volume of the current audio playing in the scene, set a magnitude bu using this method. The parameter is a Number object between 0 to 100.
J) startChapter(name)
Before writting a story in your book instance. You must set the chapter in which the scenes are happening. To start a chapter uses this method before adding any dialogs or sounds to it. The method takes one parameter(String object) which is a the name of the chapter. The names are used so that you can create a lot of chapters and jump to them using choices(with addChoice method).
K) endChapter(event)
After starting a chapter and add elements to it, you must tell the Book where it ends before creating another one. End your chapter with this method. The parameter(a function) is not mandatory, it's a function that you might want to run at the end of a chapter. Called a event function, it is usually used at the last chapter of the Book if you want the player to go to the credits scene or the main menu.
L) setLetterByLetterDisplay(bool, elapse)
This function is available since the version 2.1 of the API. You can use it if you don't want the word to appear all together in the dialog box of the scene. It takes two parameters: bool which is a boolean value(true or false) to activate the feature and elapse that is the size of second by which you want each letter to appear on the screen. the elapse parameter is a number greater than 0 and less or equal to one(1) second.
M) addBlackScreen(text)
This method works just like addChoice or addDialog. Instead of adding a next scene in the script, it adds a black transition screen. The argument text is a String object which is a text that you might want to appear at the center of the black screen like "Chapter One" or "At Vanessa's house".
button
The button Class is used to create a simple button in your Screen layers. The parameter is not mandatory as the text can be given through a method of the class.
Instance:
var mybutton = new TotoyeVN.button(title);Methods
A) setTitle(text)
Set which text should appear on your button. The parameter can be String or Number object.
B) setBackground(style:String)
Customize the background of the button by changing its color or by replacing it with an image instead. The style parameter is a String object that can be a color or the link to a image file.
C) setFont(color, size, style)
You can customize the button more by changing the font. A color, String object that be a color name, a hexadecimal code or RGB codes; the font size of the text with is a number between 0 and 100; and finally the font style which can be "bold", "italic" or "normal".
D) setFontColor(color)
Change the font color of the button.
E) setFontSize(size)
Change the font size of the button. The size is between 0.0 and 100.0.
F) setFontStyle(style)
Change the font style of the button by setting it "normal", "italic" or "bold".
G) setBorder(width, color, type)
This method allows its user to change the border features of the button. The width parameter is a number object that tells how many pixels wide is the border. The color parameter is a String object that sets the color of the border. And finally, the type of the border(a String object) that can be "dotted", "dashed", "solid", "double", "groove", "ridge", or "none".
H) setBorderWidth(width)
Change the width of the current border of the button. The width is a number object that represents the number of pixels used for the border's width.
I) setBorderColor(color)
Change the color of the current border of the button.
J) setBorderStyle(type)
Change the type of the current border of the button. It can be "dotted", "dashed", "solid", "double", "groove", "ridge", or "none".
K) roundedBorder(radius)
Set the border radius of the button to make the corners appears more round. The radius parameter is a number object that has value between 0 and 100.
L) setWidth(size)
Change the current width of the button by giving it a new value. The size is a number between 0.0 and 100.0.
M) setHeight(size)
Change the current height of the button by giving it a new value. The size is a number between 0.0 and 100.0.
N) alignX(x)
Set a x-alignment to the button. The x parameter is a String object which can only be three values: "left", "center", or "right".
O) alignY(y)
Set a y-alignment to the button. The y parameter is a String object which can only be three values: "top", "center", or "bottom".
P) setPosition(x:float, y:float)
You can change the x and y position of the button in the screen by giving it new ones as parameters. The x and y parameters are ranged from 0.0 to 100.0.
Q) getWidth()
Return the current width of the button.
R) getHeight()
Return the current height of the button.
S) getPosition()
Return the current position of the button as an object like {x: 1.0, y: 1.0}.
T) disabled(value:boolean)
Defines the state of the button. It's false bu default.
U) eventListener(event, method)
Set an event listener to the button(which tells it what to do for each action). The event parameter is a String object that tells the name of the event("click", "mouseover", "mousedown", "mouseout", or "mouseup") to take into account. The method, as its name tells, is the function to run when the event occurs.
image
The image Class is used to create a image object in your Screen layers. The parameter is not mandatory as the source file can be given through a method of the class.
Instance:
var myimage = new TotoyeVN.image(src);Methods
A) src(file_url:String)
To create a image object you need to give it a image file to use. This method is used to set the link of the image to the instance like "images/characters/Mike.png"
B) setWidth(size:float)
Change the current width of the image by giving it a new one. The size is a number between 0.0 to 100.0.
C) setHeight(size:float)
Change the current height of the image by giving it a new one. The size is a number between 0.0 to 100.0.
D) alignX(x:String)
Align the image on the x-axis of the Screen. The x parameter is a String object which can only be three values: "left", "center", or "right".
E) alignY(y:String)
Align the image on the y-axis of the Screen. The y parameter is a String object which can only be three values: "top", "center", or "bottom".
F) setPosition(x:float, y:float)
You can change the x and y position of the image in the screen by giving it new ones as parameters. The x and y parameters are ranged from 0.0 to 100.0.
G) getPosition()
Return the current position of the button as an object like {x: 1.0, y: 1.0}.
Key
The engine gives you the option to create events using Key input.
Instance:
var mykey = new TotoyeVN.Key();Methods
A) eventListener(key, type, method)
Set an event listener by giving three parameters: the key, the type of event, and the method, a function to run when the event occurs. The type is a boolean value where true is when the key is pressed and false when the key is released(After being pressed). The key parameter is a value that comes from the Key class.
B) mykey.A, mykey.B, ...., mykey.Z
Using the Key instance with the letter needed, we will get the key value of letter from "A" to "Z"(on keyboard).
C) mykey.CTRL
Return the key value of the Control key.
D) mykey.SHIFT
Return the key value of the Shift key.
E) mykey.LEFT
Return the key value of the Left Arrow key.
F) mykey.RIGHT
Return the key value of the Right Arrow key.
G) mykey.UP
Return the key value of the Up Arrow key.
H) mykey.DOWN
Return the key value of the Down Arrow key.
I) mykey.SPACE
Return the key value of the Space key.
J) mykey.ENTER
Return the key value of the Enter key.
Example:
var mykey = new TotoyeVN.Key();
mykey.eventListener(mykey.A, true, function(){
console.log("Display this text when the key A is pressed.");
});
Audio
The Audio class is used to create sound object for your game. It is used to set soundtrack for your Screen layers. The parameter is the url of the audio file which is not mandatory during the instance creation.
Instance:
var audio = new TotoyeVN.Audio(url);Methods
A) src(url:String)
Set the url(String object) of the audio file to the Audio instance. It will need it to play the sound.
B) play()
Set the Audio object to the play state.
C) pause()
Set the Audio object to the pause state.
D) stop()
Set the Audio object to the stop state.
E) loop()
Set the Audio object to play as a loop in the background.
F) setTime(second:float)
Set the time position of the music(our audio) to a certain amount of second. The parameter is a Number object.
G) volume(magnitude)
Set the volume of the Audio object from 0 to 100 percent.
Timer
Create a timer inside your game using this class. While creating the instance, three parameters are given: sec which is the number of seconds for the timer to reach its end; once, a true or false statement that specifies if the Timer has to run once or infinitely; and finally, callback which is the function that will run each time the Timer ends.
Instance:
var myTimer = new TotoyeVN.Timer(sec:float, once:boolean , callback: function);Methods
A) stop()
Use this method to stop or clear the timer.
Progressbar
You can add a progress bar to your game as a loading screen or anything else. Both parameters aren't mandatory for the progress bar instance. The default max value is 100.0 and the default value is 0.0
Instance:
var bar = new TotoyeVN.Progressbar(max:float, value:float);Methods
A) setValue(v:float)
Set a new value to the progress bar.
B) setMax(v:float)
Set a new maximum to the progress bar.
C) setBackgroundColor(r,g,b)
Change the background color of the progress bar by giving a red value(parameter r), a green value(parameter g), and a blue value(parameter b). Those three parameters are ranged from 0 to 255.
D) setForegroundColor(r,g,b)
Change the foreground color of the progress bar by giving a red value(parameter r), a green value(parameter g), and a blue value(parameter b). Those three parameters are ranged from 0 to 255.
E) setLabel(text:String)
Set a text as label to the progress bar.
F) setFontColor(r,g,b)
Change the text color of the progress bar's label by giving a red value(parameter r), a green value(parameter g), and a blue value(parameter b). Those three parameters are ranged from 0 to 255.
G) setSize(width:float, height:float)
Change the size of the progress bar by setting a width value and a height value. Both parameters are ranged from 0.0 to 100.0.
H) setPosition(x:float, y:float)
Change the position of the progress bar by setting its x and y values. Both parameters are ranged from 0.0 to 100.0.
I) getPosition()
Return the current position of the progress bar as an object like {x:1.0, y:1.0}.
Label
You can add a Label element to your game's screen. Maybe like the title of your game.
Instance:
var mygametitle = new TotoyeVN.Label(text:String);Methods
A) setText(text:String)
Change the Label's text.
B) uppercase(value:boolean)
Set a true/false value to define if the label's text is uppercase or not.
C) textAlign(type:String)
Change the Label's type. The type parameter can be left, right, center, justify.
D) setColor(r,g,b)
Change the text color of the label by setting the red, green and blue values.
E) setFontSize(size:float)
Change the size of the text. The size parameter is ranged from 0.0 to 25.0.
F) setStyle(style:String)
Change the text's style. The style parameter can be normal, italic, bold, bold-italic.
G) setBorder(size, color:String, side:String)
Add a border to the label. The side parameter can be left, right, top, bottom and it's not mandatory. You can skip the side parameter to add color and size to the four sides at once.
H) setSize(width:float, height:float)
Change the size of the Label by setting a width value and a height value. Both parameters are ranged from 0.0 to 100.0.
I) getSize()
Return the current position of the Label as an object like {x:1.0, y:1.0}.
J) setPosition(x:float, y:float)
Change the position of the Label by setting its x and y values. Both parameters are ranged from 0.0 to 100.0.
K) getPosition()
Return the current position of the Label as an object like {x:1.0, y:1.0}.
ItemList
You can add a list to your game's screen using this class. You can set the ordered parameter as true or false to define the type of list you want to create. The list is unordered by default.
Instance:
var characterList = new TotoyeVN.ItemList(ordered:boolean);Methods
A) addItem(text:String)
Add an item to the list.
B) setItem(text:String, position:int)
Add an item at a specific position inside the list.
C) remove(position:int)
Remove an item at a specific position inside the list.
D) setColor(r,g,b)
Change the text color of the list.
E) setFontSize(size:float)
Change the text size. The size parameter is ranged from 0.0 to 25.0.
F) setStyle(style:String)
Change the text style. The style parameter can be normal, italic, bold, bold-italic.
G) clear()
Clear the list.
H) setPosition(x:float, y:float)
Change the position of the ItemList in the screen. Both parameters x and y are ranged from 0.0 to 100.0.
I) getPosition()
Return the current position of the ItemList.
HTTPRequest
You can send or receive data from your server using this class
Instance:
var http = new TotoyeVN.HTTPRequest();Methods
A) request(url:String, action:String, value)
Send a request to the server. The url parameter is the address you send the request to, like "data.json" or "http://mywebsite.com/data.json". The action parameter can be whether GET to get data or POST to send data. And finally, the value parameter is the data you want to send which means it's not mandatory when receiving data.
B) cancel()
End or cancel the current request.
C) onerror(method)
The method parameter is a function to run when an error occurred after starting a request.
D) onprogress(method)
The method parameter is a function to run when the request is progressing. The function to run, must also has a parameter which is the percentage of the progress.
Example:
http.onprogress(function(per){console.log("Loading: "+per+"%");});
E) getResult(method)
The method parameter is a function to run when the GET request is done. The function to run, must also has a parameter which is the JSON data received.
LineInput
Use this function to create a text input element.
Instance:
var username = new TotoyeVN.LineInput();Methods
A) maxLength(value:int)
Set a maximum number of character for the text input element.
B) placeholder(text:String)
Set a text as placeholder.
C) text(value:String)
Set a text value inside for the input element.
D) readOnly(value:boolean)
Set a true or false value to specify if the user can write inside the LineInput or not.
E) setFont(color:String, size:int, style:String)
Change the color, size and style of the text inside the LineInput element. The size parameter is ranged from 0.0 to 25.0. The style can be normal, italic, bold, bold-italic.
F) setBackground(value:String)
Change the current background of the LineInput. The parameter can be a color or an image url.
G) setBorder(size:int, color:String, side:String)
Set a border to the LineInput. The size parameter is ranged from 0.0 to 10.0. The side parameter can be left, right, top, bottom.
H) setPosition(x:float, y:float)
Change the LineInput position using this function. Both parameters x and y are ranged from 0.0 to 100.0.
I) getPosition()
Return the current position of the LineInput as an object like {x:1.0, y:1.0}.