How do I install this?

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:

  1. dialog.show_dialogtree now accepts a optional speech_id to specity the staring speech ID.
  2. options of Speech definition tables now can be a function receiving the player object and returns a list of options.
  3. 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.


dialog.register_dialogtree(name, def)

Register a dialog tree.

dialog.register_speaker(name, def)

Register a speaker.

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


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.


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.


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.



Do you recommend this mod?

  • No reviews, yet.