TyranoDsl

A DSL to write visual novels games in Ruby using TyranoBuilder.

TyranoBuilder is a good tool has many features like native web export but I don't like to click-heavy interface to write.

The goal is to provide a simple syntax you can use directly or you can build upon.

You create your TyranoBuilder project with the specific options and the library is used to modify the content without touching the other things.

The project is a WIP: I add things as I need them, if you have any issue or need something please ask me.

If you use it for a published VN, please tell me: it would make me happy and I'll add a link to it in this page.

Example:

declare_character 'Shinji', 
    'default' => 'default_stance.jpg',
    'angry' => 'angry.jpg'

declare_background 'School', 'background/school.jpg'

set_title_screen_background 'School'

start_scene 'First scene'
set_background 'School'
show_character 'Shinji', 'default', 434, 128
show_message_window
display_text 'Shinji', 'Hello!'
set_character_stance 'Shinji', 'angry'
display_text nil, 'Do you want to go in the eva ?'
ask_question [
                 {
                     'text' => 'Yes!',
                     'left' => 200,
                     'top' => 200,
                     'scene' => 'Second scene'
                 },
                 {
                     'text' => 'No!',
                     'left' => 200,
                     'top' => 300,
                     'scene' => 'Third scene',
                     'label' => 'a label'
                 }
             ]
start_scene 'Second scene'

How to use it

Install TyranoBuilder
Create a project in it
Install the gem
Execute tyrano-dsl PATH_TO_YOUR_TYRANO_PROJECT PATH_TO_YOUR_RUBY_CODE.rb in your project directory.

PATH_TO_YOUR_TYRANO_PROJECT should look like /Users/u/Library/Application\ Support/Steam/steamapps/common/TyranoBuilder/myproject/Test

If everything is OK it should update the files in your TyranoBuilder project.

You can then reopen the project in TyranoBuilder and see the changes.

If there is an error it should be displayed and the message should help you to fix the problem.

Current vocabulary

Background

`declare_background` Declare a background

declare_background(name, images_path)

name is a String representing the background's name
images_path is a String indicating the path to the background images

declare_background 'School', 'background/school.jpg'

`set_background` Set the background

show_background(name)

name is a String representing the background's name

set_background 'School'

Characters

`declare_character` Declare a character

declare_character(name, stances)

name is a String representing the character's name
stances is a Hash{String => String} providing a list of stances with the path to their corresponding images

declare_character 'Shinji', 
    'default' => 'default_stance.jpg',
    'angry' => 'angry.jpg'

`hide_character` Hide a character

hide_character(name)

name is a String representing the character's name

hide_character 'Shinji'

`set_character_stance` change the stance of a character

set_character_stance(name, stance)

name is a String representing the character's name
stance is a String defining the stance name

set_character_stance 'Shinji', 'angry'

`show_character` show a character

show_character(name, stance, left, top)

name is a String representing the character's name
stance is a String defining the stance name
left is an Integer defining the left position
top is an Integer defining the top position

show_character 'Shinji', 'default', 434, 128

Content

`ask_question` Ask a question

ask_question(possible_answers)

possible_answers is a list of possible answers with the corresponding target
- text is a String representing the text of the answer
- left is an Integer defining the left position
- top is an Integer defining the top position
- scene is a String indicating the name of the scene to jump if the answer is selected
- label (optional) is a String indicating the name of the label in the scene to jump if the answer is selected

ask_question [
                 {
                     'text' => 'Yes',
                     'left' => 200,
                     'top' => 200,
                     'scene' => 'Second scene'
                 },
                 {
                     'text' => 'No',
                     'left' => 200,
                     'top' => 300,
                     'scene_name' => 'Third scene',
                     'label_name' => 'a label'
                 }
             ]

Jump & Labels

`declare_label` Declare a label

declare_label(name)

name is a String representing the label's name

declare_label 'my label'

`conditional_jump` Jump to somewhere if a condition is met

conditional_jump(variable, operator, value, scene, label)

variable is a String indicating the name of the variable to be tested
operator is a String indicating the comparison operator to use: <, == (equal), >, != (different)
value is a String or a Float indicating the thing to compare the variable to, it can be a numerical value or the name of another variable
scene is a String indicating the name of the scene to jump to
label (optional) is a String indicating the name of the label in the scene to jump to

conditional_jump 'variable_1', '<', 10, 'Scene two'
conditional_jump 'variable_1', '=', 'variable_2', 'Scene two', 'Label three'

`jump` Jump to somewhere

jump(scene, label)

scene is a String indicating the name of the scene to jump to
label (optional) is a String indicating the name of the label in the scene to jump to

jump 'Scene two'
jump 'Scene two', 'Label three'

Variables

`declare_variable` Declare a variable

declare_variable(variable_name, initial_value)

variable_name is a String representing the variable name
initial_value is a Float representing the variable initial value

declare_variable 'happiness', 25

`update_variable` Update a variable

update_variable(variable_name, operation, value)

variable_name is a String representing the variable name
operator is a String indicating the operation to apply
- = set the variable with the value
- += add the value to the variable
- -= substract the value from the variable
- *= multiply the value with the variable
- /= divide the value with the variable
- %= set the variable with the reminder of the division with the value
value is a String or a Float indicating the thing to use as a value, it can be a numerical value or the name of another variable

update_variable 'happiness', '=', 25
update_variable 'happiness', '+', 'calmness'

Misc

`hide_message_window` Hide the message window

hide_message_window

hide_message_window

`include_file` Include a file

include_file(file_name)

name is a file_name representing the file to include

include_file('other_scene.rb')

`show_message_window` Show the message window

show_message_window

show_message_window

`start_scene` Start a new scene

start_scene(name)

name is a String representing the scene's name

start_scene 'First scene'

How the thing works

The tool works like a two passes compiler:

the first pass validates the syntax, the entry point is in parser.rb
the second generate the content, the entry point is in writer.rb
the content is applied to disk

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/archiloque/tyrano_dsl.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The code is available as open source under the terms of the MIT License.

TyranoDsl

How to use it

Current vocabulary

Background

declare_background Declare a background

set_background Set the background

Characters

declare_character Declare a character

hide_character Hide a character

set_character_stance change the stance of a character

show_character show a character

Content

ask_question Ask a question

Jump & Labels

declare_label Declare a label

conditional_jump Jump to somewhere if a condition is met

jump Jump to somewhere