v 44d67cc: Module: Visual Novel
v1.0.0+ up to v 44d67cc
Note: Even though this module can be used for both Visual Novels and Kinetic Novels, we'll use the term Visual Novel throughout.
Visual Novel files have the extension "vn". You can change the criteria for Visual Novel files by adjusting FILE_DATA_GET_MODULES in showpony/settings.php.
The resources folder goes into the story's primary folder, along with the language and subtitles folders.
- resources/
- audio/
- music.mp3
- ...
- images/
- image.jpg
- ...
- characters/
- name/
- excited.png
- happy.png
- upset.png
- ...
- ...
- name/
- audio/
This module has a unique programming language. It's not Ren'Py-like- it's got HTML mixed with a more concise setup. It's made to be extremely simple to read and feel powerful in your hands. We'll talk about it below!
Note: make sure you use tabs in your files!
I stopped and stared, wondering why the baseball was getting bigger.
Then it hit me.
Write a tab and then the text you want to display!
Punctuation will automatically create pauses in the text, so you don't need to worry about adding any of that in manually.
Mario::It's-a me, Mario!
Luigi::Woo-hoo!
Peach::Yeah!
Toad::It's my turn!
Put the character's name plus :: to show their name in the name tag while the text all goes in the textbox!
Guard::I'm sorry, I'm going to have to ask you to leave->
Fangirl::No! I came to see Sparkling Angel->
Guard::...before things get ugly.
Put a > at the end of a line to automatically proceed to the next one!
Brian::See... I wanted to... I wanted to tell you...
Stephanie::Yes, Brian?!
Brian::I... I love...
Stephanie::Yes, yes?!?!
Brian::I
+ love
+ you
+r sister.
Add a + at the beginning of a line of text to append it to the current textbox, rather than replacing the existing text. It'll still require clicking through to continue (unless the previous line ends with >).
You can use this to add commands in the middle of text:
mech focused
Mechanic::Give me a moment...>
wait 1s
mech happy
+ There we go!>
mech thumbs-up
+ Good as new!
You can use any HTML tags! <span>, <img>, etc.
<shout></shout> makes the text appear large and return to normal size.
<shake></shake> makes the text shake.
<sing></sing> makes the text move up and down in a wave, like singing.
<fade></fade> makes the text slowly fade in.
<speed rate="1" constant></speed> adjusts the text's speed.
rate is the relative rate of text display- the regular speed is multiplied by it. 0 means text appears instantly; 2 means letters appear in 2x the time; .5 means letters appear in 1/2 the time.
constant means punctuation won't affect the text's speed.
basetime is also supported and sets the time a regular letter will take to appear in seconds: <speed basetime=".01"> means a letter will take .01 seconds to appear, and punctuation will be calculated based off that. You can also set basetime="default", which will set it back to normal.
These tags can be nested, so if you have speed tags inside of speed tags, take care that you're getting the speed you want!
If you want to write a character in that normally would perform a special function, use \.
For example, < will always read as the beginning of an HTML tag. If you want to write out the literal character <, you can use \ like:
Student::The professor said something about a "\<p>" tag. Ever heard of it?
Characters that may need to be escaped: [ ] < > + \
If your text doesn't end up looking right, try using \ to escape some of the letters!
An \ at the end of the line will display normally.
You don't have to use HTML entities or funky code for special letters or characters; you can just write them directly in! They'll be translated correctly. So don't worry about that! (you might have to set <meta charset="UTF-8"> in your webpage, but Showpony shouldn't have a problem from there)
name excited
name upset
If you want to have multiple images, you can comma-separate them. This allows you to use layers!
name pose-01,eyes/excited,mouth/happy
If you don't specify a file extension, it'll assume png.
name excited.svg
filename
That's it!
Images will default to moving behind the characters, but using .style you can move it in front of characters for CGs and other uses instead.
Assumes jpg extension.
If you want multiple elements to use the same files, you can add info with #. This would let you have multiple characters use the same images, for example:
fan#1 excited
fan#2 upset
filename.play
You must include an audio command for Showpony to know it's audio! Assumes mp3 extension.
All objects are called the same way, and most have the same options. Commands are called this way:
object.command-name
Most of the above are actually calling a command!
When a command isn't specified, the assumed command is content. content can be used to specify different file types for audio and images:
audio.content song.wav
image.content image.svg
content is used to write text to a textbox, adjust character images, and so on, but again- since it's assumed as the default command, you never have to specify it.
The "style" command adjusts CSS for an object. The following would start a character off the left side of the screen:
object.style left:-100%;
time is a special type of style only usable through object.style. This command would move the element to the center of the screen over the course of 1 second:
object.style time:1s;left:0%;
You can use any CSS styles you want! In order to animate a style though, you'll have to have set it previously. Just add "time:Xs" in order to have it animate in a way that Showpony can pause effectively!
You can also run this on engine!
Set a class on an element.
object.class className
You can also run this on engine!
Remove an object. This can helpful if you have a lot of objects in your file, and you want to begin removing them because things are slowing down. You probably don't have to worry about this in general, though.
object.remove
You can also run this on engine! ...because, um, I don't know.
Audio has special commands:
audio.play
audio.pause
audio.stop
audio.loop
audio.time 0
audio.speed 1
audio.volume 1
If you don't specify an object, the assumed object will be "engine". engine is a special object with special commands:
wait will force users to click to continue. You can also set an amount of time to wait before automatically proceeding (skippable by clicking).
engine.wait
engine.wait 5s
engine doesn't have to be specified for wait:
wait
wait 1s
engine.go //Go here
go can be written alone, and will take you to the specified line:
go //Go here
Let's skip this line of text!
//Go here
We're skipping to here!
You can create multiline comments with /* and */. These will be parsed out of the file at runtime.
/*
This is great! I can hide this part for now or just add a bunch of info here:
Lalala, comments are great!~
*/
You can create singleline comments with //. These will remain, because they can be used with engine.go to send you to a specific spot!
engine.go //Excited
//Excited
I am WAY too pumped about this date.
You can set and adjust variables by stating a variable name and following it up with an = sign, with tabs after the =:
variable= Hello!
Then you can call it in a textbox this way:
"[variable]" Bobby greeted Susie cheerfully.
You can even nest variables!
variable= [one] and [two]
one= ONE!
two= TWO!
Come on, let's go! [variable] and THREE! and FOUR!
You can include HTML tags and even commands in variables!
shouting= <shout>YES I DID, AND I'M SOOOO EXCITED!!!!</shout>
Did you know you can use variables for text?
[shouting]
But did you?
[shouting]
I'm not quite sure if you get it...
[shouting]
commonCommand= character pose-excited,eyes/excited,mouth/excited
[commonCommand]
You can adjust values with operations as well:
variable= 1
variable+= 1
variable-= 1
In order to get user input, use any HTML element in your text. When an element is present, the user won't be able to click through to the next section without selecting an option; so if you have an element, make sure you also have an element present too!
In order to state what variable to adjust, set a data-var attribute to your input. When the user adjusts the variables, it will be set to the value present.
What's your name? <input type="text" data-var="name"> <input type="submit" value="Continue">
If you want to have buttons with different values, you can also use the data-val attribute, which is only relevant for button inputs. Regular value just adjusts the button text, as normal.
Do you like me? <input type="button" data-var="like" data-val="1" value="Yes"> <input type="button" data-var="like" data-val="0" value="No">
You don't need a continue button if you use button inputs.
Let's say that you want, on clicking an input submit or button, to go to a new position in the text rather than just adjusting a variable. You can use data-go:
Where do you want to go? <input type="button" data-go="//North" value="North"> <input type="button" data-go="//South" value="South">
Subtitles are recommended so that you can avoid Describo (like explaining audio while it's playing) while also allowing people with trouble hearing or low volume the ability to take in your Visual Novel.
Subtitles are similar to video and audio structure, with some differences.
Phrases that are either numbered or have no info above are based on the general time in the Visual Novel. I don't recommend using these because these are fluid based on the text in your file, and so aren't very trustworthy. But here's how to do it:
00:00:00.00 --> 00:01:55.00
Listen to how slowly I can talk.
2
00:02:00.00 --> 00:02:05.00
Shut up, Ben.
In the HH:MM:SS.SS format, you don't have to state HH.
I DO recommend though tying times to specific audio files. You can do that like this:
explosion
00:00:00.00 --> 00:00:10.00
(explosion and screaming)
destruction
00:00:00.00 --> 00:00:15.00
(buildings crumbling)
The title is the name of the object in the .vn file. So if your object is called explosion, it's explosion here; if it's explosion#1, it's explosion#1 here.
