How To Write Your First Script

Introduction:

In this page of the wiki, you will be taught how to implement and write your first VNScript, and play it through VNBase.

Important

Please keep in mind that VNBase is currently in active development. This means that syntax might change in the future.

How to create a script

In order to add a script for VNBase to use, navigate to your s&box project files, navigate to your game's assets folder, and add whatever .vnscript you've written into the "Scripts" folder. If no Scripts folder exist, shrimply create one.

Your files should look something like this:

Adding your script to your S&box scene

In your game scene, ensure you have at least one gameobject (preferably fresh with no components) and a camera. Apply the VN Script Player component to the object, the rest of the necessary components will be added automatically. Add a screen panel to the object as well (component hierarchy doesn't matter). By default, the background will be whatever the camera that you have in your scene looking at.

Now, all you need to do is write your visual novel sections into the .vnscript file!

How to write a .vnscript

Below is an example of what 90% of the code used in your .vnscript file will look like, which is called a "label". A label represents a cutscene in a visual novel where you can change it's background, add new text or options, conditions, etc.

(label example-rocks
    (dialogue "You see some tasty rocks. Eat them?")
    (choice "Yes please")
    (choice "No, thank you" jump game-over)
    (bg "cave.jpg")
    (after load /Scripts/RockBuffet.vnscript)
)

Required Keywords

label

The label is the "name" of the section the player will view while playing the game. This is important when you want a choice to jump back to a specific section in your visual novel (which is explained in the jump description below). The name is treated as one singular word internally, so make sure to use dashes in place of spaces!

start

Tells the game what section to start at using the label name. The position in the file does not matter, but it is recommended to add at the bottom or top of the file.

Example:

(start example-rocks)

General Keywords

dialogue

Represents a line of dialogue.

jump

This will cause the game to jump to the label with the name provided. You can only jump to a label that can be found in the current script.

choice

Anything typed in here - within quotation marks - will be generated along with a clickable button in the center of the screen. You can add as many choices as you like within a label.

bg

Will load a specified picture asset to use as a background. To add a background, simply go your scene's files and navigate to Assets/Materials/Scripts/Backgrounds directory and put your image file in there. If you do not have these folders, shrimply add them. If there is no background provided in a section, the scene will use whatever the camera's view is as the background. Supports any image file, including .gif files.

sound

Plays the specified sound event by name.

after

Specifies certain commands to be run after the section has been completed, such as: jump, load-script, set.

load

Will load a new .vnscript specified via it's file address.

Example:

(label game-over
    (dialogue "You're awful at this game")
    (after load /Scripts/loser.vnscript)
)

input

Displays an input box where the player can type whatever they want in there to store as a variable value, which can be utilized in text in other sections.

Example:

(label who-are-you
    (dialogue "Oh, hey. Nice to meet you. What's your name?")
    (input name)
    (after jump oh-wow)
)

(label oh-wow
    (dialogue "Oh wow. Your name is {name}? You're weird. And stinky.")
    (after jump goodbye)
)

cond

Checks to see if the player fulfills a certain conditional for a choice.

Example:

(label doorway
    (dialogue "Unlock the door?")
    (choice "Yea sure why not." cond (= bronze-key true) jump opened-doorway)
    (choice "I'll blow a hole threw the door." cond (= $dynamite rope fuse-cord true) jump exploded-doorway) 
    (choice "Nah im good" jump hallway)
)

set

the 'set' keyword allows you to define and set variables. Variable names must be one word, case sensitive.

Variables with the prefix $ are global variables and will persist between script environments.

Example:

// Variable initialization.
(set bronze-key false)

(label drawer
    (dialogue "You found a key in the drawer!)
    (after (set bronze-key true) jump hallway)
)

(label chest
    (dialogue "You found a sword that permanently stays in your inventory!")
    (after (set $sword true) jump hallway)
)