Module plato

A pure Lua library to manage dialogues in point & click adventure games and other dialogue-driven genres.

Provides facilities for managing dialogue trees, and through the included strands module can also be used as a system to manage cutscenes.

See plato_demo.lua for a demonstration of how to use it.

Fields

_NAME Library name.
_VERSION Library version.

Outer functions

start(t, entry_point) Starts a new dialogue.
update(dt) Updates plato's internal strand.
get_choices() Get a reference to the table with the current dialogue choices, if any.
select(i) Select a dialogue choice.
clear() Stops the currently running dialogue from the outside.
get_state_table(t) Get the state table associated to a dialogue.
set_state_table(t, v) Set the state table associated to a dialogue.
check_state_table(v) Check if a table has the correct format for a state table.
set_environment(t) Specify the environment to use for the fields of the dialogue tables.
get_environment() Get the current environment table.
is_running() Check if there is a dialogue currently running.

Inner functions

exit() Stop the current dialogue.
option(i, text, f, ...) Add a dialogue option.
option_once(i, id, text, f, ...) Add a dialogue option selectable only once.
selection(...) Puts together the options and returns control to the game while waiting for a choice.
go(name) Jump to a different entry point of the dialogue table.
once(name) Return true only when called for the first time with a given name in the current dialogue.
divert(t[, entry_point]) Stop the current dialogue and jump to a new one.
get_state(key) Get a value from the state table associated to the dialogue.
set_state(key, value) Save a value in the state table associated to the dialogue.

Callbacks

callbacks.exit() Function to call when exiting a dialogue.
callbacks.start(t, entry_point) Function to call when starting a dialogue.
callbacks.go(entry_point) Function to call when accessing a dialogue entry point, before starting the associated function.
callbacks.select(text, extra) Function to call after selecting a dialogue choice.


Fields

_NAME
Library name.
_VERSION
Library version.

Outer functions

Functions meant to be run outside of a dialogue.
start(t, entry_point)
Starts a new dialogue. Cannot be used from within another dialogue (for that use divert).

Parameters:

  • t: table describing the dialogue (see here for details on the format of the table)
  • entry_point: (string) name of the entry of t. Defaults to "main" if not provided

Raises:

  • no dialogue must be running
  • t must be a table and entry_point must be a strong or nil
  • t must have the entry_point field (or "main" if not specified)

See also:

Usage:

    local t = {
    main = function()
        plato.option(1, "option 1", "exit")
        plato.option(2, "option 2", "exit")
        plato.selection()
    end,

    exit = function()
        -- do nothing, it's just an example!
    end
}

-- start the dialogue in the "main" entry point
plato.start(t)
update(dt)
Updates plato's internal strand. Does nothing if there is no dialogue running.

Parameters:

  • dt: (number) time elapsed since last update. Only important if calling strands's wait function from within the dialogue, in which case the units should be chosen consistently.

Raises:

If there are no choices or the index is out of bounds
get_choices()
Get a reference to the table with the current dialogue choices, if any. The array entries of the table are the text passed to option or option_once. Additionally, the table contains a "custom" field which is an array of the extra arguments passed to selection.

This is the table that should be used, when the dialogue is running, to display the dialogue choices.

Returns:

    (table) array containing the text of the dialogue choices, if a dialogue is running and there are choices.

Or

    (nil) otherwise
select(i)
Select a dialogue choice.

Parameters:

  • i: (integer) index of the selected choice

Raises:

if there are no choices or the index is out of bounds
clear()
Stops the currently running dialogue from the outside. Useful for resetting the dialogue system when loading a savegame. Resets everything but the dialogue states and the strand environment.
get_state_table(t)
Get the state table associated to a dialogue. The format of the table is described here.

Parameters:

  • t: (table) table describing the dialogue

Returns:

  1. (table) state table if the dialogue has been started or a table for this dialogue has already been set through set_state_table
  2. (nil) otherwise
set_state_table(t, v)
Set the state table associated to a dialogue. The table must in the right format, described here.

Parameters:

  • t: (table) table describing the dialogue
  • v: (optional table) state table. If not provided the state will be cleared

Raises:

If provided, v must have the correct format

See also:

check_state_table(v)
Check if a table has the correct format for a state table. Useful to ensure a table is suitable for set_state_table, i.e. it conforms to the appropriate format.

Parameters:

  • v: (table) table describing the dialogue

Returns:

    (bool) true if the format is correct, false otherwise
set_environment(t)
Specify the environment to use for the fields of the dialogue tables. See Strand environments for more details.

By default plato does not change the function environments.

Note: the change of environment only affects dialogues that are started for the first time after this function is called.

Parameters:

  • t: (table or nil) table to use as the environment. Pass nil to clear the setting and revert to the default

See also:

get_environment()
Get the current environment table. Returns nil unless the environment table has been set through set_environment.

Returns:

    (table) currently set environment table if any

Or

    (nil) otherwise

See also:

is_running()
Check if there is a dialogue currently running.

Returns:

    (bool) true if running, false otherwise

Inner functions

Functions meant to be called inside a dialogue.
exit()
Stop the current dialogue.
option(i, text, f, ...)
Add a dialogue option. Whether the option will actually be used depends on its weight: only the first viable option with the given weight will be presented as a choice in get_choices. See here for more information on weights.

Note: options don't need to be called in the order of their weights—only the order within each weight matters, the winning options are then sorted before being presented according to their weight. Likewise, weights don't have to be contiguous or start from any given number.

Parameters:

  • i: (integer) weight of the option
  • text: associated to the option. Can be of any type. Not processed by plato, will be passed as is when using get_choices
  • f: (string or function)
    • if a string this is the entry point of the dialogue table to jump to if the option is selected
    • if a function this will be called (from withing the dialogue strand) if the option is selected, effectively treating it as an anonymous entry point. Useful for short consequences that don't require their own entry point
  • ...: additional parameters for custom behaviour. Put sequentially in an array that can be accessed using the callbacks.select callback

See also:

option_once(i, id, text, f, ...)
Add a dialogue option selectable only once. The option will be skipped and the next weighted one will be chosen if it has already been selected. The state is saved in the current dialogue state table.

Parameters:

  • i: same as option
  • id: (string) a unique identifier (withing the current dialogue) for saving the state of whether the dialogue has been selected. option_once state is saved in its own subtable, so the name can be resused with once and set_state without conflicts.
  • text: same as option
  • f: same as option
  • ...: same as option

See also:

selection(...)
Puts together the options and returns control to the game while waiting for a choice. Must be used after all the appropriate option and option_once have been called for the dialogue system to work properly.

Plato expects the entry point in which this function is called to return after calling it. It is recommended to make it into a tail call by using it in the form return plato.selection(), to avoid call stack overflows.

Parameters:

  • ...: extra parameters that will be passed on the the table return by get_choices

Usage:

    t = {
    main = function()
        plato.option_once(1, "stayed", "stay", "main")
        plato.option(2, "leave", "exit")
        return plato.selection()
    end,

    exit = function()
        plato.exit()
    end
}
go(name)
Jump to a different entry point of the dialogue table. Used to chain different sections of the dialogue, as well as allowing looping by jumping back to a previous point.

Plato expects the entry point in which this function is called to return after calling it. It is recommended to make it into a tail call by using it in the form return plato.go(name), to avoid call stack overflows.

Parameters:

  • name: (string) name of the entry point to jump to

Raises:

the entry point must exist

Usage:

    -- don't do this, the dialogue will be stuck in an infinite loop!
local t = {
    main = function()
        return plato.go("next")
    end(),

    ["next"] = function()
        return plato.go("main")
    end()
}
once(name)
Return true only when called for the first time with a given name in the current dialogue. Useful to make some things happen only once, e.g. only showing an option once, only giving a particular answer the first time an option is chose.

The state is saved in the dialogue's state table.

Note: the state changes only if the function is run, so be careful if combining with other conditions using and and or as there may be short-circuiting if not used as the first condition.

Parameters:

  • name: (string) the identifier used when saving the state of whether this has been run already.

Usage:

    -- only show the next option once (skipped if we go
-- through the dialogue again of we go back one step
-- and repeat)
if plato.once("test") then
    plato.option(1, "option text", "next")
end
divert(t[, entry_point])
Stop the current dialogue and jump to a new one.

Parameters:

  • t: same as start
  • entry_point: same as start (optional)

See also:

get_state(key)
Get a value from the state table associated to the dialogue. Useful to retrieve values saved with set_state.

Parameters:

  • key: key to get the value of. Can be of any non-nil type

See also:

set_state(key, value)
Save a value in the state table associated to the dialogue. Useful to save some variables related to the dialogue (e.g., whether a question has been asked) that has no use outside of it.

Parameters:

  • key: key to associate the value to. Can be of any non-nil type
  • value: value to set. Can be any type, including nil to unset the key

See also:

Callbacks

Functions that can be set by the user to customise the behaviour of the library.

These can be set by setting a function of the appropriate format to the plato.callbacks table.

Usage:

callbacks.exit = function()
    -- do stuff
end
callbacks.exit()
Function to call when exiting a dialogue. Called by exit and divert before stopping the dialogue.
callbacks.start(t, entry_point)
Function to call when starting a dialogue. Called by start before starting the dialogue.

Parameters:

  • t: the dialogue table passed to start
  • entry_point: the entry point passed to start, or "main" if none was given
callbacks.go(entry_point)
Function to call when accessing a dialogue entry point, before starting the associated function. In addition to go, this callback is also used by start, divert, and selection (the latter only if the selected option uses a named entry point).

Parameters:

  • entry_point: the entry point passed to go
callbacks.select(text, extra)
Function to call after selecting a dialogue choice. Called by selection after a choice has been made and before running the function/jumping to the entry point specified by the option.

Useful for example if the player should speak the selected choice before continuing.

Parameters:

  • text: text that was passed to the option that was selected
  • extra: (table) an array containing the extra values passed to the option that was selected

See also:

generated by LDoc 1.5.0