Built-in Functions
Moontale's standard library
Variables
Name | Type | Description |
| String | 🚧 A String variable identifying the current Host as a dot-separated sequence of names. For example |
| String | The title of the current story |
| Map of string to table | The set of all passages in the story, keyed by their name. |
| Set of string | The set of tags assigned to the passage; you can use |
| Function | The rendering function for the passage's content. |
| [Number, Number] | The position of the passage node in the editor, in [x, y] pixels |
| String | The name of the currently rendering passage. |
| String | The name of the starting passage, as set in the editor. |
Basics
All functions in this section do not return a value.
Name | Arguments | Description |
| Any (multiple) | Displays each argument in the output. |
| String | Clears the screen and renders the passage with the given name. This will change the value of |
| Function or Table | Ensures that the given function is executed when the passage is reached, and not on any subsequent |
| None | Causes the current passage to be re-rendered. |
| String | Renders the passage with the given name in-line with the text. Note that this does not change the value of |
| None | Jumps to |
| None | 🚧 Clears all user-defined variables, then does a |
Entities
Broadly, an Entity is a non-text object that the Host is capable of handling.
Name | Arguments | Description |
| String | Outputs the entity with the given name |
| Outputs a horizontal line | |
| String | Draws an image ( |
| String | Plays the audio file ( |
Changers
A 'changer' is something that modifies a block of content - for example hiding/showing it, wrapping it with some formatting, or rendering it multiple times. Behind the scenes, changers are higher-order functions; they can be called with a single argument, which itself is a parameter-less function that renders the attached content. This means that $Color.red[Text]
is functionally equivalent to $Color.red(function() Text('Text') end)
, and $Link('Passage')[Text]
is the same as $Link('Passage')(function() Text('Text') end)
As a convenience, built-in changers will convert a single string argument to a content rendering function. So instead of Style.em(function Text('Text') end)
you could write Style.em('Text')
.
All functions in this section are themselves Changers, or return a Changer function.
If an entry is listed without parentheses, it should be used as such: for example, $Else[ Text ]
, not $Else()[ Text ]
Conditionals
The capitalization is required to avoid conflicting with Lua keywords
Name | Arguments | Description |
| Boolean | Renders its content if |
| Renders its content if neither the previous | |
| Boolean | Renders its content if |
Formatting
Note that these functions are written as table indexers, allowing the 'dot' syntax where the index is a string literal (the most common use case).
Name | Arguments | Description |
| String | Wraps the content in the named tag. For example, |
| String, Any | Wraps the content in the named tag, with the given additional arguments. For example, |
| String | Sets the named text alignment for the content. For example, |
| String | Colours the text with the given colour name (not case sensitive). For example, |
Interactivity
When nesting interactivity changers, the resulting callbacks will all be applied to the outer-most block. This means that if you have a 'link within a link', the outer link will perform both actions when clicked on.
Name | Arguments | Description |
| String, Function | Executes |
| String | Jumps to |
| Changer, Changer (optional) | Applies the |
Repetition
Name | Arguments | Description |
| Integer | Renders the content |
| Table | Renders the content for each item in |
| Table, String (multiple) | Renders the content for each item in |
Transformation
Name | Arguments | Description |
| String, String | 🚧 Executes a pattern replacement on the |
| String (multiple) | 🚧 Causes all |
| Table | 🚧 Temporarily overrides the given expressions (table keys) with their corresponding values. For example |
Miscellaneous
Name | Arguments | Description |
| String | Hides the block, and assigns it to a variable named |
| Changer (multiple) | Creates a Changer that combines each of its Changer arguments in order of outer-most to inner-most. For example, |
| 🚧 Renders the block's content and caches it, so that subsequent calls don't execute any embedded code a second time. |
Output
These are the low-level functions that produce user-visible text, and need to be implemented by the Host. You probably won't call these from Moontale directly (but you can, if you know what you're doing!)
Name | Arguments | Description |
| String, Any (multiple) | Encloses all further output in |
| None | Ends the tag from the last un-popped |
| String | Outputs the given text string (the argument must be a string; use |
| String, Any (multiple) | Outputs the given non-text object (e.g. |
| None | Clears the screen; normally called just before rendering the passage. |
| None | Tells the host that previously rendered text is no longer valid, typically because a new passage has been jumped to. |
| String, String | Emits a diagnostic message, such as a rendering error |
Moontale overrides some of these functions on start-up to facilitate proper event handling. In general, once the Host registers these functions it should not change them for the lifetime of the Lua VM
Note that any tag can be given as an argument to Push
and Object
; the list of valid tags will ultimately depend on the Host. The browser host, for instance, will faithfully emit all tags as HTML.
Most tags do not take any additional arguments. Notable exceptions are color(color)
and a(id)
. When developing custom tag conventions, you should use simple arguments (string, number etc.) rather than complex tables.
Input
While the Host can call any library-defined or user-defined Moontale function, the following should be called solely by the Host (unless your intention is to simulate user actions):
Name | Arguments | Description |
| String, Integer, Any (multiple) | Called when the named event occurs on the content with the given ID |
Interactive content is indicated with Push('a', id)
, where id
is a sequential integer. The Host is then responsible for calling RaiseEvent
with the ID for that span when an event occurs. Interactivity tags will never be nested.
The following is a non-exhaustive list of event names, a subset of the HTML DOM events:
Name | Description |
| The element was clicked or tapped on |
| The cursor entered the element's bounding region |
| The cursor exited the element's bounding region |
The Host should note that raising an event can call one or more of the Output functions, resulting in the content on screen changing and the mapping of IDs to user-visible content changing. If Clear()
is called as a result of an event, the Host should ignore any other events until the new content is on screen. This may result in e.g. mouseover
and mouseout
being un-balanced.
Last updated