Node Editor Reference Guide

Updated on 24 March 2024

Overview

This folder contains Lua script files which will be referenced by both TE and TEN to work with the node trigger system.
Tomb Editor uses metadata from comments in these files to build UI, while TEN uses actual functions to execute node scripts.

On level compile, all files from this directory are copied to Scripts\NodeCatalogs folder and executed on level start-up, given that level contains any volumes. Therefore, NodeFunctions.lua file in TEN Scripts\NodeCatalogs folder should never be modified.

Format

Lua node scripts should follow this convention: several metadata signatures should be followed by actual function body which should start with conventional LevelFuncs.Engine.Node.prefix.

The amount of argument metadata signatures should be the same as actual function arguments and should be listed in the same order.

Metadata signature reference

Comment metadata signature reference (metadata block is indicated by a keyword which starts with !):

  • !Name “NAME” – NAME will be visible name for this function in node editor.
  • !Conditional “True” – this is a condition node, otherwise if “False”, it’s action (or if !Conditional is not specified).
  • !Description “DESC” – DESC will be a tooltip for a given function. You can use \n symbol to begin from a new line.
  • !Arguments “ARGDESC1” “ARGDESC2” “ARGDESC…” – infinite amount of args, with ARGDESC parameters separated by commas as follows:
  • 0-100 – numerical value specifying width of control in percent of node width. For whole-line controls, this can be omitted.
  • NewLine – keyword which specifies if this and following arguments should appear on new UI line, until another argument with another NewLine is encountered.
  • Boolean, Numerical, Vector3, String, Color, LuaScript, Moveables, Statics, Cameras, Sinks, FlybyCameras, Volumes, Rooms, SoundEffects, WadSlots, Enumeration, CompareOperator – keywords which specify argument type and its appearance in UI.
  • {DEFAULT} – default value for this argument, contained in brackets. For the Numerical value type, it can be provided as is, e.g. {100}. For String value type, the default string must be quoted, e.g. {"Default string"}.
    Complex value types, such as Color or Vector3, should use TEN Lua API notation, e.g. TEN.Color(255,255,255)
  • [ENUMDESC1 | ENUMDESC2 | ENUMDESC…] – custom enumeration descriptors for this argument, as follows:
    • For Numerical and Vector3 value types, first and second ENUMDESC values determine min/max UI range of value. Optional third argument specifies amount of decimal places (for integer, set it to 0). Optional
      fourth and fifth values determine mouse wheel increment and alternate increment (with shift button
      pressed) respectively.

    • For String value type, specifying NoMultiline as ENUMDESC hides button which engages multiline editing.

    • For Moveables and WadSlots lists, ENUMDESC values will filter out object ID names which contain any of
      ENUMDESCs only.

    • For Enumeration, ENUMDESC values will be displayed as is but converted to numericals, starting from 1, on compilation
      in order of appearance.

    • Any other string value except listed above – tooltip for a given argument control.

    • !Ignore – if this keyword is used, nearest encountered function declaration will be ignored. Useful if you need to place helper functions which must be ignored by the parser (however, it is recommended to use _System.luafile for those).
    • Metadata blocks can appear in any order.

Metadata parsing happens until real function block starts (which should start with LevelFuncs.Engine.Node prefix).

Conditional node functions (those with !Conditional = “True” specified) must return boolean value, otherwise
their behaviour is undefined.

ARGDESC parameters can appear in any order, e.g. !Argument "Foo, Numerical, 20" is equal to !Argument "Numerical, 20, Foo".

There could be several !Argument blocks, which will append arguments to previously parsed ones.

There could be several !Description blocks, which will append as a new line to previous description block.

ENUMDESC parameters should NOT be quoted, or else parsing will fail miserably.

Argument types 

    • Boolean – a value which can be either true or false. Appears as a checkbox with argument description as a label.

    • Numerical – numerical floating-point value. Range, limits and decimals can be specified by ENUMDESC descriptors (see above).

    • Vector3 – Three floating-point values, can be used either for position or rotation. Range, limits and decimals can be specified by ENUMDESC descriptors (see above).

    • String – Raw text string, length is unlimited. If parsed to functions which draw on-screen strings, \n combination may be used to start a new line.

    • Color – RGB color value, appears as color picker in UI.

    • LuaScript – Existing lua function list from level script file.

    • Moveables – A list of moveables in level which have lua names assigned.

    • Statics – A list of statics in level which have lua names assigned.

    • Cameras – Same as above, but cameras.

    • Sinks – Same as above, but sinks.

    • FlybyCameras – Same as above, but flybys.

    • Volumes – Same as above, but volumes.

    • Rooms – A list of existing rooms in level. Accessed by room name specified in TE UI.

    • SoundEffects – A list of sound effects. Internally converted to numerical effect slot ID.

    • WadSlots – A list of object slots which exist in all loaded wads. Internally accessed by numerical ID and/or
      Objects.ObjID. lua enumeration which is identical to TE/TEN object slot enumeration.

    • Enumeration – Custom enumeration determined by ENUMDESC descriptors. Internally these descriptors are
      converted to numerical index.

    • CompareOperator – Comparison operator enumeration, ranging from equal to various less-or-equal and more-or-equal operators. Internally converted to numerical value and should be passed to LevelFuncs.CompareValue helper function along with operand and reference to check against, like this: LevelFuncs.CompareValue(operand, reference, operator).

Example

-- !Name "Check moveable health"
-- !Description "Compares selected moveable health with given value."
-- !Conditional "True"
-- !Arguments "NewLine, Moveables, Moveable to check"
-- !Arguments "NewLine, CompareOperator, 70, Kind of check"
-- !Arguments "Numerical, 30, [ 0 | 1000 | 0 ], Hit points value"

LevelFuncs.CheckEntityHealth = function(moveableName, operator, value)
    local health = TEN.Objects.GetMoveableByName(entityName):GetHP()
    return LevelFuncs.CompareValue(health, value, operator)
end

Here, !Arguments signature lists 3 parameters, which will be called “Moveable to check”, “Kind of check” and “Hit points value” respectively.

First argument, “Moveable to check”, will occupy whole second line of a
node UI, because the width is not explicitly stated for it. The next two arguments, “Kind of check” and “Hit points value”, will occupy the same next line, because the NewLine keyword is not specified for third argument.

Second argument, “Kind of check”, will occupy 70 percent of line width, while “Hit points value” will occupy 30 percent. Note that arguments sitting on the same line should sum to 100 percent width, otherwise UI symmetry is not guaranteed.

Also note that “Hit points value” argument is placed on separate !Arguments block, and this is correct, since it will appear after previous argument block. Also, being numerical argument, it will allow user to only define values between 0 and 1000. All other values will be clamped. Decimal places for a value won’t show, as third parameter in square brackets is set to 0.

LevelFuncs.CheckEntityHealth function declaration should contain same amount of arguments and in the same order as metadata argument signature. Therefore, moveableName will be read from “Moveable to check”
UI argument, operator will be read from “Kind of check”, and so on.