-
Notifications
You must be signed in to change notification settings - Fork 1
Cutscene Scripting Documentation
MirageVN's documentation is not yet complete. However, the demo cutscenes use almost all of MirageVN's built-in functionality at least once, and there are copious comments. This should be enough to get you started while full documentation is written.
Syntax: play_bgm(bgm : AudioStream, fade_time = 0.7)
Plays new BGM. Fades the current BGM out first.
Use null
to turn the BGM off. The fade will be slower.
Syntax: sfx(sfx, pos = Vector2(), channel : String = "SFX", delay : float = 0.0)
Plays a sound effect.
Returns the sound effect's emitter. Every call creates a new, unique emitter.
The returned emitter will emit the "finished" signal on finish if it finishes gracefully.
Syntax: ambiance(sound : AudioStream)
Plays background ambiance. No associated signal.
Syntax: set_bg(bg : Texture = null, instant : bool = false, no_textbox_hide = false)
Fades to a new background. Handles panning transforms gracefully.
The new background will have a clean panning transform. If you want the target bg to be transformed,
you will need to re-apply the panning transform with set_bg_transform_2
or set_bg_transform_2_target
.
Syntax: set_bg_fade_mask(texture : Texture = _default_bg_mask, invert : bool = false, contrast : float = 1.0)
Sets the fading mask for the next background transition. Retained through further transitions.
Syntax: configure_bg_distortion(mode : int)
Sets the background distortion configuration. There is a transition.
Distortion configurations are defined in _normal_configs
in Background.gd
.
Syntax: set_bg_normal_map(normal_map : Texture)
Sets what normal map texture is used by the background distortion system.
Syntax: get_bg()
Returns the background node.
You probably don't need to use this function.
Syntax: set_bg_transform_1(position : Vector2, zoom : Vector2, angle : float = 0.0)
Sets the start and end transforms of the current, or being-transitioned-away-from, background.
Syntax: set_bg_transform_1_target(position : Vector2, zoom : Vector2, angle : float = 0.0, time = 4.0)
Sets just the end transform of the current, or being-transitioned-away-from, background.
Syntax: set_bg_transform_2(position : Vector2, zoom : Vector2, angle : float = 0.0)
Sets the start and end transforms of the next, or being-transitioned-towards, background.
Syntax: set_bg_transform_2_target(position : Vector2, zoom : Vector2, angle : float = 0.0, time = 4.0)
Sets just the end transform of the next, or being-transitioned-towards, background.
Syntax: set_tachie(slot : int, tachie : Texture, animation : String = "", no_textbox_hide = false, time : float = -1)
Changes a tachie and optionally performs an animation during the transition.
By default, there are only five available tachie slots, from 1 to 5. To add more slots, edit Manager
's Scene node to contain more identical Tachie nodes, then add them to the tachie_slots
and tachie_owners
variables in Manager.gd
.
Pass null
as the tachie sprite texture to hide the tachie slot/make it invisible.
Manager will emit the "tachie_finished" signal when the transition/animation finishes.
Animations are defined in res://singletons/Tachie.gd
, in the special_anims
variable and
the play_animation()
function.
Syntax: do_tachie_animation(slot : int, animation : String, time : float = -1)
Makes a tachie (standing sprite) perform an animation. The current sprite will be retained.
Manager will emit the "tachie_finished" signal when the animation finishes.
Syntax: set_tachie_owner(slot : int, identity : String)
Sets the owner of a given tachie.
Used by the textbox identity system if an identity icon can't be found.
Note: the identity system is a huge hack. If you're making a full-size game, you should replace it.
Syntax: set_tachie_zoom(slot : int, zoom : float)
Sets how zoomed-in a tachie is, in base resolution pixels. There is a transition.
Note: if you want certain tachie to render over other tachie, you need to reposition them within their parent node. "Later" children of their parent node will render above "earlier" children. You can do this in code.
As such, because Tachie1 is at the bottom by default, it will render above other tachie by default, even if it has less zoom.
The base zoom and position of all tachie are defined in the anim_default
variable
in res://singletons/Tachie.gd
.
Tachie are scaled so that their top and bottom edges fit the screen by default, and then
zoomed in by the scale factor in anim_default
, and then positioned.
Syntax: set_tachie_offset(slot : int, offset : Vector2)
Sets the position offset for a tachie, in base resolution pixels. There is a transition.
The base zoom and position of all tachie are defined in the anim_default
variable
in res://singletons/Tachie.gd
.
Tachie are scaled so that their top and bottom edges fit the screen by default, and then
zoomed in by the scale factor in anim_default
, and then positioned.
Syntax: set_tachie_next_flipped(slot : int, flipped : bool = true)
Call right after set_tachie, e.g.
Manager.set_tachie(1, tachie_normal, "center")
Manager.set_next_tachie_flipped(1)
Causes a tachie to be flipped starting with the target of the next/current tachie transition.
This is retained past future transitions. To unflip the tachie, you must call this again with false in the second argument slot.
Syntax: animate_tachie(slot : int, animation : String = "")
Do not use. Probably broken.
Syntax: stop_tachie(slot : int)
Do not use. Probably broken.
Syntax: hide_tachie(slot : int)
Do not use. Broken.
Syntax: hide_all_tachie()
Do not use. Broken.
Syntax: set_env(saturation : float = 1.0, color : Color = Color(0.5, 0.5, 0.5), light : Color = Color(1.0, 1.0, 1.0))
Sets the environmental coloration for tachie (standing sprites).
Syntax: spawn_effect_raw(_atlas : Texture, _count : Vector2) -> Effect
Low-level animated overlay effect spawner.
Takes a Texture and a Vector2 with the number of horizontal and vertical animation frames.
The texture is treated as a spritesheet, and is animated from left to right, then top to bottom.
Syntax: spawn_effect(name : String)
Spawns an animated overlay effect by name.
There are two built in effects: "Bubble" and "Splash".
Edit this function to add more.
Syntax: screen_shake_start()
Stops screen shake.
There is a transition. No associated signal.
Syntax: screen_shake_stop()
Stops screen shake.
There is a transition. No associated signal.
Syntax: set_NVL_mode()
Switches to NVL mode. The textbox will be screen-sized and add new text instead of replacing it.
Use pageflip_NVL to manually clear the textbox and create a new page.
Syntax: set_ADV_mode()
Switches to NVL mode. The textbox will be small and replace its full text when updated.
Syntax: textbox_set_typein(onoff : bool)
Sets whether the type-in effect happens for newly-added text.
Syntax: textbox_set_continue_icon(mode : String)
Sets which continue icon the textbox displays: "done" for square, "next" for arrow.
Syntax: textbox_show()
Shows the text box. An animation plays.
Returns the name of the signal within Manager
that fires off when the animation finishes.
Syntax: textbox_hide(no_clear = false)
Hides the text box. An animation plays. Clears the textbox by default, pass true
to suppress.
Returns the name of the signal within Manager
that fires off when the animation finishes.
Syntax: textbox_set_identity(name : String = "<<NARRATOR>>", icon : Texture = null, bleep : AudioStream = null)
Sets the nametag, icon, and 'bleep' for the next line of text.
The nametag "<>" is special and causes the line to be treated as narration.
Warning: I have not tested identities other than "<>" in NVL mode. They might be broken.
You probably don't need to call this function directly.
Syntax: textbox_set_bbcode(bbcode : String)
Adds bbcode to the textbox.
Replaces existing bbcode in ADV mode, adds bbcode in NVL mode.
Supports newline characters (\n).
Godot bbcode docs: https://docs.godotengine.org/en/3.4/tutorials/ui/bbcode_in_richtextlabel.html
You probably don't need to call this function directly.
Syntax: textbox_clear()
Clears the textbox.
You probably don't need to call this function directly.
Syntax: choice(choices)
Presents the user with a choice.
See 1-1-Test.gd
in the demo project to see how to use choices.
Syntax: get_sec()
Gets the number of seconds that have passed since the game engine was booted.
Useful for debugging.
Not useful for logic; use get_process_delta_time
instead.
Syntax: change_to(target_level : String, flat_fade : bool = false)
Changes to a new scene.
Unless you're creating a gameplay VN, you probably do not want to use this function directly.
Syntax: call_cutscene(entity : Node, method : String)
Move to a new cutscene.
Note: incorrect use of this function can cause memory leaks, crashes, save corruption, etc.
Try to instead change scenes the same way the template does, with Manager.next_scene
Syntax: pop_input_mode(mode)
You probably don't need to use this unless you're making a gameplay-heavy VN or a minigame.
Syntax: pop_input_mode(mode)
You probably don't need to use this unless you're making a gameplay-heavy VN or a minigame.
Syntax: debug_text(s)
Adds text to an always-visible text layer on the screen.
Resets every frame.
Useful for debugging minigames.
Syntax: realtime_skip()
Returns true if the user is reading in skip mode or holding down the "skip" input.
Syntax: do_general_skip()
Returns whether non-timerlike general skippable things should be skipped this frame.
True if loading, holding the "skip" input, or the skip button is pressed.
You probably want to use do_timer_skip() instead.
Syntax: do_timer_skip()
Returns whether timers should be skipped this frame.
True if loading, holding the "skip" input, the skip button is pressed, or the user is performing inputs that should interrupt timers.
Syntax: cutscene_timer(time : float) -> SkippableTimer
Creates and returns a timer that's aware of do_timer_skip()
.
Syntax: save_to_dict() -> Dictionary
Copies save-related data into a dictionary.
Syntax: load_from_dict(data : Dictionary)
Loads save-related data out from a dictionary and then forcibly changes the scene to that save's cutscene script and fast-forwards (in a single frame) to where the user saved.