The Gromtroller

The Gromtroller node is the node which provides an interface between the game and the GromScript runtime. It has the following signals which should be hooked up to relevant UI and game systems to respond to the respective dialogue events that they represent.

The Gromtroller works by signalling changes to the dialogue state step by step, until a new dialogue state is reached ready for the user, which it then signals is the case through the prompt signal. Option selections and other dialogue events then get communicated to the GromScript runtime through this same node. This way, so long as all essential signals are connected and behave correctly, each sequence of instructions issued from the Gromtroller will always result in a valid dialogue state. (or it would, if it werent a buggy mess.)

Signals

All communication from the GromScript runtime to the game is given through signals. Hook up these signals to the relevant UI/game interface for displaying dialogue.

Essential signals

These signals must be connected to create functional interfacing with dialogue.

• new_option(idx: int, greyout: bool): signal to create a new option button for the player to click.
  • idx: index of the option. This might not match the button order, and must be stored when built, and returned to the Gromtroller when signalling which option was clicked.
  • greyout: if true, the button should be unclickable. Used to signify previously explored dialogue.
• speech_text_emitted(text: String): signal to append text to the current non-player character dialogue box.
• option_text_emitted(text: String): signal to append text to the most recently added option button.
• speaker_changed(speaker: String): change character to given name.
• prompt: signal that all text and options have finished building, and that the new state should be unlocked for the player to interact with.
• flush: signal to clear the current speech and options and get ready to build new speech and options.
• end: signal to end the dialogue and exit the interaction.
• start: signal to start a dialogue.

Other signals

These signals are not essential to dialogue function but may offer convenient hooks or debugging points.

• branch_entered
• branch_exited
• token_entered
• token_consumed
• error_thrown
• break_emitted
• text_emitted
• switch_mode
• reset

Methods

The Gromtroller has several methods which can be called to communicate user input to the GromScript runtime.

Essential methods

• void attach(): attaches to the default GromScript runtime. For standard use cases, this should be called in _ready().
• void read_till_stop(): tells GromScript to read all the dialogue it can until user input is required.
• bool speak_to(actor: String): tells GromScript to initiate dialogue with a specific actor. Returns false if actor has no default dialogue or some other error occurred.
• void select_option(option: int): tells GromScript to select the given option of the currently displaying set.
  • option should match the idx given by the new_option signal

Other methods

These methods provide functionality not usually desired but go wild if they suit your purposes.

• void spawn_gromtime(): spawns and attaches to a new GromScript runtime instead of attaching to an existing one. Provides asynchronous dialogue capability, where 2 dialogues can run in parallel.
• void attach_to_gromtime(idx: int): attach to a specific GromScript runtime (0 = default, 1 = debug, others can be made with spawn_gromtime).
• bool is_attached(): returns true if the Gromtroller is attached to a runtime.
• void next(): step forward one token in the dialogue. Useful only really for debugging purposes.
• void restart(): resets the current dialogue state entirely.
• Ref<GromScriptBranch> get_current_branch(): returns a reference to the GromScriptBranch object. Only useful for debugging.

Example Setup

The scene narrative_ui.tscn in ProjectGrominus is an example of how a Gromtroller can be set up with a UI scene to provide a functional interface.

See narrative_ui.gd