TyranoDsl

Build Status Gem Version

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 export-game 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.

Actions

  • export-game export the game to replace the current content of the Tyrano project
  • export-text print the text content of the game

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.

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.