Skip to content

Search

Documentation

scene

The node tree: its root, lookup by path and instancing, plus the component and preset vocabulary an editor's palette lists.

On this page

The node tree: its root, lookup by path and instancing, plus the component and preset vocabulary an editor's palette lists.

32 functions, 0 constants. Scripts reach it as scene::.

Functions

Argument kinds are the script values a call passes: node is a node handle, any a table or value of any kind, fn a callback.

function acts on what it does
added_since(string, int) -> [Node] — The nodes the component went onto after change tick tick, in node order. After a rollback restored the world, a tick from before it answers every holder.
apply_preset(Node, string) — Add every component a preset names to the node; a part that fails leaves the parts before it in place.
attach_scripts(Node) — Run every script the nodes under a node name, children first: what starts a scene built with scripts: false.
bindable_events(Node?) -> [str] — Every event a [[nodes.bindings.rows]] row may answer, in the order an editor offers them: the core hooks, and on a node the emitted: events it and its components announce.
binding_actions() -> [str] — Every action a binding row may do, in the order an editor offers them.
changed_since(string, int) -> [Node] — The nodes whose component was written, or put on, after change tick tick, in node order. After a rollback restored the world, a tick from before it answers every holder.
component_expects(string) -> [str]? — The components a component type needs something from, for ordering or grouping its sections; nil for a name nothing registered.
component_properties(string, any) -> any — What a component's apply would receive for params: the schema's defaults with a partial table merged over them. This is how a tool compares two spellings of the same component.
component_requires(string) -> [str]? — The components a component type brings: each a node lacks is put on at its defaults before the type's first write. Nil for a name nothing registered.
component_schema(string) -> any — A component type's property schema as a table, its properties in the order it writes them; nil for a name nothing registered.
component_tags(string) -> [str]? — The facets a component type is filed under, for filtering a palette; nil for a name nothing registered.
component_types() -> [str] — The names of every registered component type, not the components on any node.
get_node(string) -> Node — The node at an A/B/C path from the root, where .. climbs to the parent; nil when nothing matches.
instantiate(string, Node?, scene::InstantiateOptions?) — Build a scene document (TOML text, not a path) under a parent. scripts: false names each node's script without running it; root is the project the text names its files from, when it is not this one, and every path is made absolute against it.
keep_changes(Node?) — Keep every change under a node as it happens, each with what it replaced, until take_changes hands them over; nil stops, and what was kept goes. An editor's undo, which the changed event serves a frame late and merged.
node_by_id(string, Node?) -> Node — The node carrying a stable id, which survives the rename and the reparent a path does not; nil when nothing carries it. under bounds the search to one subtree, for a tool holding more than one tree.
parked() -> [str] — Every scene switch kept built, by the path it was asked for, oldest first.
preset_info(string) -> scene::Preset? — A preset's description, tags, the components it adds, and parts: each component's own properties by name. Nil for a name nothing registered.
presets() -> [str] — The names of every registered preset.
removed_since(string, int) -> [Node] — The nodes the component came off after change tick tick, freed ones included, oldest first: what the frame it came off in and the next still hear.
root() -> Node — The tree's root node.
set_variable(string, any) — Write a scene variable, coerced to the type it was declared with. Every node declaring on_variable_changed hears about it at the end of the tick; writing the value it already holds says nothing.
source(string) -> str? — A scene file's raw TOML text, project-relative and found inside the pack in a packed run; nil when missing.
switch(string, scene::SwitchOptions?) — Go to another scene at the end of this tick, so a script asking inside update is not moving the tree it runs in. The scene left stays built and parked, and a scene already parked comes back as it was, with no node built and no init run; each of their scripts is told on_parked_changed. A parked scene does not update, draw, take input or hear a hook, an event or a call, and a task its script awaits holds until it returns. A script reaching it can still read and write its components; it takes no new node or script. A digest and a snapshot cover it, a save holds nothing of it, and the change log says nothing of a park or a return. A file edited since the scene was built is built again on the way back. fade is seconds of crossover: the old scene's roots fade out to the clear colour over the first half, the switch happens, and the new scene's fade in over the second. What stays parked is bounded by itself: past 20,000 parked nodes the scene left longest ago is freed, and a system memory warning frees them all; a scene freed is built again the next time it is asked for, its init running. Reset is a switch to the file already there, which frees it and builds it again; to come back to a scene new from elsewhere, unload it first.
tagged(string) -> [Node] — Every node filed under a tag, in tree order; what a scene's tags key and node.add_tag feed.
take_changes() -> [scene::Change] — The changes kept since the last take, oldest first, emptying the list: { node, kind, id } with kind one of component (component, properties, was: the table asked before), attached, removed (was), added (parent), freed (parent, place, was: the subtree as scene text), renamed (was), moved (parent, was: { parent, place }), script (was: { source, props }, nil for none) and keys (was: every one of the node's own keys, visible to tags). Parents are stable ids, so a change outlives the nodes it names.
to_toml(Node, scene::ToTomlOptions?) -> string — The scene under a node, that node its root, as a scene file's text: what instantiate builds again. Each component is what was asked of it, a prefab's nodes are their instance's overrides, and root writes every path under that project's root as it spells it.
unload(string) — Lets go of a scene: frees it if it is parked, its scripts' on_free running as for any node freed, and drops what its file and prefabs have cached, the parsed text and the pictures they name. The scene running stays where it is, and a picture something still draws is read again when it next asks.
variable(string) -> any — A scene variable's value, or nil for a name nothing declared. A scene declares them under [variables].
variables() -> [scene::Variable] — Every declared variable as { name, type, value }, in name order.
warnings(Node) -> [scene::Warning] — What is off about the node, as { component, property, message }: a component missing one it expects, a write its component refused, and what a component says of itself. property is nil for the whole component; advisory only.
with_component(string) -> [Node] — Every node carrying the named component, in tree order. What a script asks instead of walking the tree itself.

Are you sure?