Messing up with NPC dialogs?

This mod provides a easy-to-use dialog API. This mod was extracted from the game Glitch, a game in the 2022 Minetest Game Jam. This mod is backward-compactible with the upstream.

On top of the upstream one, this mod did the following changes:

dialog.show_dialogtree now accepts a optional speech_id to specity the staring speech ID.
options of Speech definition tables now can be a function receiving the player object and returns a list of options.
Options now align to the bottom. Previously, options align to the top.

If this mod is installed to a Glitch game, this mod's functions will replace the ones provided by the game, while keeping the dialogs.

API

`dialog.register_dialogtree(name, def)`

name: The ID of the dialog tree.
def: A dialog tree definition table.

`dialog.register_speaker(name, def)`

name: The ID of the speaker.
def: A speaker defination table.

`dialog.show_dialogtree(player, dialogtree_id, speech_id)`

Show a dialog tree.

player: The player object of the target.
dialogtree_id: The ID of the dialog tree to be shown.
speech_id (Optional): The starting speech to be loaded. Default to "start" for string-indexed dialog trees or 1 to number-indexed ones. New in 1F616EMO fork.

Definition table

Speaker

A table containing informationof a speaker. Keys contain:

name: A string, the display name of the speaker. It should not be formspec-escaped.
portrait: A string of texture name, or a table of them, of the speaker. If it is a table, a random one will be chosen.
portrait_animated: A boolean. If true, portrait should specify a 8-frame 16x16 (16x128) png like the one in Glitch.

Dialog tree

A table containing information of a dialog tree. Keys contain:

speeches: A table, either number- or string-indexed, containing all the speech definitions. If number-indexed, the dialogs will be played one-by-one; if string-indexed, each speech mush contain at least one options.
force_stay: A boolean. If true, dialog window is forced to stay open. Known bug: force-keeping a dialog open does not work reliably if the player spam the Esc key. Workaround: Don't have any required dialogues.
on_exit(player) (Optional): A function being called when the entire dialogtree was left. Not called when the current speech has its own on_exit function.

Speech

A table containing information of a speech. Keys contain:

speaker: A string, the ID of the speaker.
text: A string, the text to be spoken by the speaker in the speech. It should not be formspec-escaped.
on_enter(player) (Optional): Called when this speech entered.
on_exit(player) (Optional): Called when this speech exited. If present and the speech is the last one of the dialog tree, the on_exit function of its dialog tree is not called.
options: Either one of the following:
- A table containing a list of options.
- function(player): A function receiving the current player as its parameter, and return a table containing a list of options. New in 1F616EMO fork.
- If the dialog tree is number-indexed, this key is optional, and a "Continue" option is automatically generated for the user to go to the next speech.

Option

A table containing information of an option. Keys contain:

text: A string, the text to be shown on the button. It should not be formspec-escaped.
action: A string, either one of the following:
- "quit": The dialog closes. on_exit callbacks of the speech or the dialog tree are called.
- "speech": Another speech opens.
When action = "speech":
- dialogtree_id (Optional): A string, the dialog tree to be searched for the speech. Default to the current dialog tree.
- next_speech: A string, or a number, of the speech to be shown.

Dialogs