Rakugo Singleton
Rakugo is automatically setup as a singleton when you turn on the Rakugo addon. This means that you can call Rakugo from anywhere in your code.
Full Exemple
Here is Full Exemple how can you make node connect to Rakugo Dialogue System that parse and execute RakuScript:
extends Node
const file_path = "res://Timeline.rk"
func _ready():
Rakugo.add_custom_regex("HW", "^hello_world$")
Rakugo.sg_custom_regex.connect(_on_custom_regex)
Rakugo.sg_say.connect(_on_say)
Rakugo.sg_step.connect(_on_step)
Rakugo.sg_ask.connect(_on_ask)
Rakugo.sg_menu.connect(_on_menu)
Rakugo.parse_and_execute_script(file_path)
func _on_say(character:Dictionary, text:String):
prints("say", character.get("name", "null"), text)
func _on_step():
prints("Press 'Enter' to continue...")
func _on_ask(character:Dictionary, question:String, default_answer:String):
prints("ask", character.get("name", "null"), question, default_answer)
func _on_menu(choices:Array):
prints("menu", choices)
func _on_custom_regex(key:String, result:RegExMatch):
prints("custom regex", key, result.strings)
func _process(delta):
if Rakugo.is_waiting_step() and Input.is_action_just_pressed("ui_accept"):
Rakugo.do_step()
if Rakugo.is_waiting_ask_return() and Input.is_action_just_pressed("ui_up"):
Rakugo.ask_return("Bob")
if Rakugo.is_waiting_menu_return() and Input.is_action_just_pressed("ui_down"):
Rakugo.menu_return(0)
file_path and script_name
file_path
is a path to a file, like : "res://Timeline.rk".
script_name
is file name without extension. From "res://Timeline.rk" it is "Timeline".
It works in Rakugo like bellow :
Only methods parse_script or parse_and_execute_script, use a file_path. For others and signals is a script_name.
References
Signals
sg_say
- args:
character:Dictionary, text:String
Send when a Say instruction is executed then Rakugo waiting call of do_step
func _ready():
Rakugo.sg_say.connect(_on_say)
func _on_say(character:Dictionary, text:String):
prints("say", character.get("name", "null"), text)
sg_step
Send after a Say instruction is executed.
func _ready():
Rakugo.sg_step.connect(_on_step)
func _on_step():
prints("Press 'Enter' to continue...")
sg_ask
- args:
character:Dictionary, question:String, default_answer:String
Send when a Ask instruction is executed then Rakugo waiting call of ask_return.
func _ready():
Rakugo.sg_ask.connect(_on_ask)
func _on_ask(character:Dictionary, question:String, default_answer:String):
prints("ask", character.get("name", "null"), question, default_answer)
sg_menu
- args:
choices:Array
Send when a Menu instruction is executed then Rakugo waiting call of menu_return.
func _ready():
Rakugo.sg_menu.connect(_on_menu)
func _on_menu(choices:PackedStringArray):
prints("menu", choices)
sg_execute_script_start
- args:
script_name:String
Send when the script with this script_name
execution is started.
func _ready():
Rakugo.sg_execute_script_start.connect(_on_execute_script_start)
func _on_execute_script_start(script_name:String):
prints("execute_script_start", script_name)
sg_execute_script_finished
- args:
script_name:String, error_str:String
Send when the script with this script_name
execution is finished.
If execution fail error_str
contains error message, instead is empty.
func _ready():
Rakugo.sg_execute_script_finished.connect(_on_execute_script_finished)
func _on_execute_script_finished(script_name:String, error_str:String):
prints("execute_script_finished", script_name)
sg_custom_regex
- args:
key:String, result:RegExMatch
Send when a custom instruction is executed.
You can add one with add_custom_regex.
func _ready():
Rakugo.parser_add_regex_at_runtime("HW", "^hello_world$")
Rakugo.sg_custom_regex.connect(_on_custom_regex)
...
Rakugo.parse_and_execute_script(file_path)
func _on_custom_regex(key:String, result:RegExMatch):
match(key):
"HW":
prints("regex hello, world !")
sg_variable_changed
- args:
var_name:String, value:Variant
Send when a Rakugo's variable is changed.
sg_character_variable_changed
- args:
character_tag:String, var_name:String, value:Variant
Send when a Rakugo's character variable is changed.
Methods
replace_variables
- params:
text:String
Will replace any <var_name>
with value of RakugoVar with var_name
in given script.
Note
String is replaced with a value when you use/read it, not on assignment.
# example
Rakugo.replace_variables("You have <player.life> life points left")
# will - return:`#!gdscript "You have 5 life points left"`
set_variable
- params:
var_name:String, value:Variant
## set or create a global variable
Rakugo.set_variable("life", 5)
## set or create a variable on character
Rakugo.set_variable("Sy.life", 5)
get_variable
- params:
var_name:String
- return:
Variant
Return null
if not found or character with this tag does not exist. Print an error in this case.
## get a global variable
var life = Rakugo.get_variable("life")
## get a character's variable
var sy_life = Rakugo.get_variable("Sy.life")
has_variable
- params:
var_name:String
- return:
bool
Return false
if not found or character with this tag does not exist. Print an error in this case.
## check if a global variable exists
var has_life = Rakugo.has_variable("life")
## check if a character's variable exists
var has_sy_life = Rakugo.has_variable("Sy.life")
define_character
- params:
char_tag:String, char_name:String
get_character
- params:
char_tag:String
- return:
Dictionary
If a character with this char_tag
is not found return an empty Dictionary and print an error.
get_narrator
- return:
Dictionary
Returns character with name defined in Project Settings: addons/rakugo/narrator/name
add_custom_regex
- params:
key:String, regex:String
Add new custom instruction to RkScript.
When this custom instruction is read it send signal sg_custom_regex.
Use it before parse_script or parse_and_execute_script.
func _ready():
Rakugo.parser_add_regex_at_runtime("HW", "^hello_world$")
Rakugo.sg_custom_regex.connect(_on_custom_regex)
...
Rakugo.parse_and_execute_script(file_path)
func _on_custom_regex(key:String, result:RegExMatch):
match(key):
"HW": prints("regex hello, world !")
You can use these Rakugo tokens in your regex :
Example : ^show_char (?<tag>{NAME})$
GDocs about regex : https://docs.godotengine.org/en/stable/classes/class_regex.html
parse_script
- params:
file_path:String
- return:
Error
Parse a script and store it. You can execute it with execute_script.
If all goes well return OK
. If not print an error and return ERR_FILE_CANT_OPEN
if file can not be opened, or FAILED
in other cases.
execute_script
- params:
script_name:String
- return:
Error
Execute a script previously registered with parse_script.
If all goes well return OK
, print an error and return FAILED
instead.
You do not have to use parse_script and execute_script at same time.
const file_path = "res://Timeline.rk"
const script_name = file_path.get_file().get_basename()
func _ready():
Rakugo.parse_script(file_path)
func _process(_delta):
...
Rakugo.execute_script(script_name)
parse_and_execute_script
- params:
file_path:String
Do parse_script, if return OK
then do execute_script.
save_game
- params:
save_name:String = "quick"
Save all variables, characters, script_name and last line readed on last executed script, in user://save/save_name/save.json file.
load_game
- params:
save_name:String = "quick"
Load all variables, characters, script_name and last line read on last executed script, from user://save/save_name/save.json file if existed.
Parse the script with script_name
. To run it use resume_loaded_script (just bellow).
resume_loaded_script
Run the loaded script from last line readed.
is_waiting_step
- return:
bool
Returns true
when Rakugo waiting call of do_step.
do_step
Use it when is_waiting_step return true
, to continue script reading process.
is_waiting_ask_return
- return:
bool
Returns true
when Rakugo waiting call of ask_return.
ask_return
- params:
result:Variant
Use it when is_waiting_ask_return return true
, to continue script reading process.
result
is the answer to the question ask by sg_ask.
is_waiting_menu_return
- return:
bool
Returns true
when Rakugo waiting call of menu_return.
menu_return
- params:
index:int
Use it when is_waiting_menu_return return true
, to continue script reading process.
index
is the index of chosen choice in the choices array given by sg_menu.