Skip to content

Cutscene Scripting Documentation

Alexander Nadeau edited this page Aug 17, 2022 · 12 revisions

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.

Audio

play_bgm

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.

sfx

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.

ambiance

Syntax: ambiance(sound : AudioStream)

Plays background ambiance. No associated signal.

Background

set_bg

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.

set_bg_fade_mask

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.

configure_bg_distortion

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.

set_bg_normal_map

Syntax: set_bg_normal_map(normal_map : Texture)

Sets what normal map texture is used by the background distortion system.

get_bg

Syntax: get_bg()

Returns the background node.

You probably don't need to use this function.

set_bg_transform_1

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.

set_bg_transform_1_target

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.

set_bg_transform_2

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.

set_bg_transform_2_target

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.

Tachie (standing sprites)

set_tachie

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.

do_tachie_animation

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.

set_tachie_owner

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.

set_tachie_zoom

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.

set_tachie_offset

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.

set_tachie_next_flipped

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.

animate_tachie

Syntax: animate_tachie(slot : int, animation : String = "")

Do not use. Probably broken.

stop_tachie

Syntax: stop_tachie(slot : int)

Do not use. Probably broken.

hide_tachie

Syntax: hide_tachie(slot : int)

Do not use. Broken.

hide_all_tachie

Syntax: hide_all_tachie()

Do not use. Broken.

Visual Presentation

set_env

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).

spawn_effect_raw

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.

spawn_effect

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.

screen_shake_start

Syntax: screen_shake_start()

Stops screen shake.

There is a transition. No associated signal.

screen_shake_stop

Syntax: screen_shake_stop()

Stops screen shake.

There is a transition. No associated signal.

Textbox

set_NVL_mode

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.

set_ADV_mode

Syntax: set_ADV_mode()

Switches to NVL mode. The textbox will be small and replace its full text when updated.

textbox_set_typein

Syntax: textbox_set_typein(onoff : bool)

Sets whether the type-in effect happens for newly-added text.

textbox_set_continue_icon

Syntax: textbox_set_continue_icon(mode : String)

Sets which continue icon the textbox displays: "done" for square, "next" for arrow.

textbox_show

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.

textbox_hide

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.

textbox_set_identity

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.

textbox_set_bbcode

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.

textbox_clear

Syntax: textbox_clear()

Clears the textbox.

You probably don't need to call this function directly.

Branching

choice

Syntax: choice(choices)

Presents the user with a choice.

See 1-1-Test.gd in the demo project to see how to use choices.

Low-level

get_sec

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.

change_to

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.

call_cutscene

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

pop_input_mode

Syntax: pop_input_mode(mode)

You probably don't need to use this unless you're making a gameplay-heavy VN or a minigame.

pop_input_mode

Syntax: pop_input_mode(mode)

You probably don't need to use this unless you're making a gameplay-heavy VN or a minigame.

debug_text

Syntax: debug_text(s)

Adds text to an always-visible text layer on the screen.

Resets every frame.

Useful for debugging minigames.

realtime_skip

Syntax: realtime_skip()

Returns true if the user is reading in skip mode or holding down the "skip" input.

do_general_skip

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.

do_timer_skip

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.

cutscene_timer

Syntax: cutscene_timer(time : float) -> SkippableTimer

Creates and returns a timer that's aware of do_timer_skip().

save_to_dict

Syntax: save_to_dict() -> Dictionary

Copies save-related data into a dictionary.

load_from_dict

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.