Built-in Functions
Moontale's standard library
Last updated
Moontale's standard library
Last updated
All functions in this section do not return a value.
Broadly, an Entity is a non-text object that the Host is capable of handling.
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 ]
The capitalization is required to avoid conflicting with Lua keywords
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).
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.
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!)
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.
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):
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:
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.
Name
Type
Description
Host
String
🚧 A String variable identifying the current Host as a dot-separated sequence of names. For example RichText.Unity.TMP, HTML, RichText.LOVE.SYSL
Story
String
The title of the current story
Passages
Map of string to table
The set of all passages in the story, keyed by their name.
Passages[name].tags
Set of string
The set of tags assigned to the passage; you can use if(tags['my-tag']) to check for a tag's presence
Passages[name].content
Function
The rendering function for the passage's content.
Passages[name].position
[Number, Number]
The position of the passage node in the editor, in [x, y] pixels
PassageName
String
The name of the currently rendering passage.
StartPassage
String
The name of the starting passage, as set in the editor.
Name
Arguments
Description
Show(...)
Any (multiple)
Displays each argument in the output.
Jump(passage)
String
Clears the screen and renders the passage with the given name. This will change the value of PassageName .
Once(fn)
Function or Table
Ensures that the given function is executed when the passage is reached, and not on any subsequent Reloads. If a Table is passed, it treats each key-value pair as an instruction to set a variable. For example $Once{ gold = gold + 5 }
Reload()
None
Causes the current passage to be re-rendered.
Display(passage)
String
Renders the passage with the given name in-line with the text. Note that this does not change the value of PassageName.
SoftReset()
None
Jumps to StartPassage, re-running any startup-tagged passages.
HardReset()
None
🚧 Clears all user-defined variables, then does a SoftReset(). This is a 'best effort' function - it is possible to 'leak' state into places that this function won't touch, such as the Passages table. If this is a concern, the host should destroy and re-create the Lua VM.
Name
Arguments
Description
Entity[tag]
String
Outputs the entity with the given name
Entity.hr
Outputs a horizontal line
Image(path)
String
Draws an image (img entity) with the given path
Audio(path)
String
Plays the audio file (audio entity) with the given path. You will probably want to combine this with once
Name
Arguments
Description
If(condition)
Boolean
Renders its content if condition is truthy
Else
Renders its content if neither the previous If or any of the ElseIf calls following it were entered
ElseIf(condition)
Boolean
Renders its content if condition is truthy and neither the previous If or any of the ElseIf calls following it were entered
Name
Arguments
Description
Style[tag]
String
Wraps the content in the named tag. For example, Style.em.
Style(tag, ...)
String, Any
Wraps the content in the named tag, with the given additional arguments. For example, Style('line-height', 25)
Align[alignment]
String
Sets the named text alignment for the content. For example, Align.left, Align.justify
Color[color]
String
Colours the text with the given colour name (not case sensitive). For example, Color.darkred
Name
Arguments
Description
On[event](callback)
String, Function
Executes callback when event occurs over the content; for example $On.click<<x = x + 1>>
Link(passage)
String
Jumps to passage when the content is clicked
Hover(hovering, normal)
Changer, Changer (optional)
Applies the hovering changer when the cursor is over the content, and normal when it is not. For example, Hover(Color.red, Color.blue) .
Note that any use of this function will cause a Reload to happen when the cursor position changes; make sure to use Once where appropriate!
Name
Arguments
Description
Repeat(count)
Integer
Renders the content count times in a row, with the number of the current iteration (1-indexed) assigned to index
ForEach(iterable)
Table
Renders the content for each item in iterable, setting the variables key and value to the key and value of each entry. This is equivalent to ForEach(iterable, 'key', 'value').
ForEach(iterable, ...)
Table, String (multiple)
Renders the content for each item in iterable, mapping each entry to variables with the names given in the subsequent arguments.
Name
Arguments
Description
Replace(pattern, replacement)
String, String
🚧 Executes a pattern replacement on the text() emissions within the block
Strip(...)
String (multiple)
🚧 Causes all Push(tag) emissions (with their paired Pop()s) to be dropped. For example, $Strip('em')[ Some $Style.em[text] ] will render Some text without the em instruction of the inner block.
With(replacements)
Table
🚧 Temporarily overrides the given expressions (table keys) with their corresponding values. For example With{['style.em'] = color.blue}
Name
Arguments
Description
Name[name]
String
Hides the block, and assigns it to a variable named name. The block can subsequently be displayed with $name.
Combine(...)
Changer (multiple)
Creates a Changer that combines each of its Changer arguments in order of outer-most to inner-most. For example, $Combine(Style.em, Style.u)[Text] equates to $Style.em[$Style.u[Text]].
Freeze
🚧 Renders the block's content and caches it, so that subsequent calls don't execute any embedded code a second time.
Name
Arguments
Description
Push(tag, ...)
String, Any (multiple)
Encloses all further output in tag, until pop() is called.
Pop()
None
Ends the tag from the last un-popped push() instruction. push() and pop() must be balanced.
Text(text)
String
Outputs the given text string (the argument must be a string; use show if the argument might not be one)
Object(tag, ...)
String, Any (multiple)
Outputs the given non-text object (e.g. hr).
Clear()
None
Clears the screen; normally called just before rendering the passage.
Invalidate()
None
Tells the host that previously rendered text is no longer valid, typically because a new passage has been jumped to.
Log(message, trace)
String, String
Emits a diagnostic message, such as a rendering error
Name
Arguments
Description
RaiseEvent(event, id, ...)
String, Integer, Any (multiple)
Called when the named event occurs on the content with the given ID
Name
Description
click
The element was clicked or tapped on
mouseover
The cursor entered the element's bounding region
mouseout
The cursor exited the element's bounding region