TriggerScript is based loosely on JavaScript (specifically, a subset of ECMAScript 5 in Strict Mode). For basic information on statements, operators, expressions, conditionals, variables, and the like, consult basic JavaScript or ES5 tutorials or documentation.
TriggerScript is still in development, many features are expected to change and be expanded upon. Do not be surprised if some scripts need re-writing as new features become available.
The body (the root scope) of a TriggerScript can contain only the following kinds of statements (besides comments):
on* (e.g. onPressure or onInteract) APIs to register handlersExample:
function helper(x) {
return x + 1;
}
onInteract(function () {
// Displays "3" when the player interacts with
// the prop the script is attached to.
say(helper(2));
});
The following are supported in TriggerScript and function approximately as they do in JavaScript:
varif= += -= *= /= %= |= &= ^=+ - * / % & | ^ + - * / % | & ^
(note: the mathematical operators will always coerce to numbers if possible, and treat any truthy non-number as 1)== === != !== <= >= < > && ||! - ~ typeof// comments and /* comments */functions (cannot be declared within other functions)Math object functions and propertiesThe following are not yet implemented in TriggerScript, but are planned:
for while doObject and Array data typesBoolean values are represented as 0 and 1undefined and null are represented as 0functions can only be declared in the global scope (no functions within other functions)A unique reference to an Entity.
Entities are generally players or mobs, that can move independently in the world. Note that, depending on world settings, a single user may have more than one entity, and some users may not have an entity (e.g. if they are "Spectators").
Players get new EntityIDs each time they join a world.
Note: EntityIDs can be compared as strings and all EntityIDs will be strictly > "0" and < "Z", however a "lower" EntityID does not imply anything meaningful (only useful for sorting, checking uniqueness, etc).
Registers a function to be called when a player collides with another entity inside of an Area.
Can only be called in the root scope. Only valid on Areas.
Note: Due to online latency, this event is not symmetrical - on player A's client, they may collide with player B, but on player B's client, they may have already moved and never get a collision. Due to this, the important game logic should generally be done by whichever player is "chasing" the other, so that the act of catching someone feels good and responsive (for example, in a traditional game of tag, the one who is "it" is chasing, in a game of capture the flag, all of the ones without the flag are doing the chasing).
The mathematical constant e. This is Euler's number, the base of natural logarithms.
The natural logarithm of 10.
The natural logarithm of 2.
The base-10 logarithm of e.
The base-2 logarithm of e.
Pi. This is the ratio of the circumference of a circle to its diameter.
The square root of 0.5, or, equivalently, one divided by the square root of 2.
The square root of 2.
Returns the absolute value of a number (the value without regard to whether it is positive or negative). For example, the absolute value of -5 is the same as the absolute value of 5.
Returns the arccosine (or inverse cosine) of a number.
Returns the arcsine of a number.
Returns the arctangent of a number.
Returns the angle (in radians) between the X axis and the line going through both the origin and the given point.
A number representing the Cartesian y-coordinate.
A number representing the Cartesian x-coordinate.
Returns the smallest integer greater than or equal to its numeric argument.
Returns the cosine of a number.
Returns e (the base of natural logarithms) raised to a power.
A number representing the power of e.
Returns the greatest integer less than or equal to its numeric argument.
Returns the natural logarithm (base e) of a number.
Returns the larger of two numbers.
Returns the smaller of two numbers.
Returns the value of a base taken to a specified power.
Returns a pseudorandom number between 0 and 1.
Returns a supplied number rounded to the nearest integer.
Returns the sine of a number.
Returns the square root of a number.
Returns the tangent of a number.
Check if an entity exists nearby (within approximately /world_user_vis_dist)
and is within the current or another Area.
When using a tag to identify another Area, the maximum range (fully including the source and target) is 512 in each axis.
An entity may not be nearby (and, therefore, no entity functions will
work on them) in any of the following situations:
If 0, or anything that is not an EntityID, is passed as ent_id, the result is always 0
[String or 0] The optional tag identifying which Area to operate on
[EntityID | 0] The Entity ID to query
onAreaEntityCollide(function (other_ent_id) {
if (areaContainsEntity(other_ent_id)) {
chatLocal('This is always true');
}
areaStateSet('last_collision', other_ent_id);
});
onAreaPlayerIn(1000, function () {
if (areaContainsEntity(areaStateGet('last_collision'))) {
chatLocal('This is only true if the entity is near us and within the Area');
}
});
Get area-scoped local (not saved) state on the Area the script is on, or the prop is in, or another Area.
[String or 0] The optional tag identifying which Area to operate on
[String] The field name to get
Set area-scoped local (not saved) state on the Area the script is on, or the prop is in, or another Area.
Note: local state is not saved, not shared with other players, and will be reset upon a player leaving and returning to the world.
[String or 0] The optional tag identifying which Area to operate on
[String] The field name to set
[String or Float or Integer] The value to set (0 clears)
Get area-scoped state from the Area the script is on, or the prop is in, or another Area.
Note: Area state is shared between all players and all scripts within the Area.
[String or 0] The optional tag identifying which Area to operate on
[String] The field name to get
Set area-scoped state on the Area the script is on, or the prop is in, or another Area.
Note: Area state is shared between all players and all scripts within the Area.
[String or 0] The optional tag identifying which Area to operate on
[String] The field name to get
[String or Float or Integer] The value to set (0 clears)
Invert the player's vertical velocity, maintaining horizontal velocity, optionally adding velocity.
[Float, 0..1] Additional horizontal velocity to apply (in the direction the prop is facing)
[Float, 0..1] Additional vertical velocity to apply
Center the player above the prop, instantly teleports them to the center of the Trigger, useful to chain before velSet().
Apply a damage effect to the player.
[Float, 0..1] Horizontal velocity to assign to the player
[Float, 0..1] Vertical velocity to assign to the player
[Float, 0..2] Seconds to stun the player
[Float, 0..10] Seconds to make the player immune to other damage effects
[Integer, 0..10000] Energy to remove from the player (if the current world has energy enabled)
Get an entity's (Markdown-escaped) display name
If the specified entity is not found, or ent_id is 0, returns "UNKNOWN"
Note: If ent_id is "me", then this will return the current user's display
name even if the active player does not have an entity (e.g. is a Spectator).
[EntityID | 0 | "me"] The Entity ID to query or "me" for the active player
Check if an entity exists nearby (within approximately /world_user_vis_dist)
An entity may not be nearby (and, therefore, no entity functions will
work on them) in any of the following situations:
If 0, or anything that is not an EntityID, is passed as ent_id, the result is always 0
[EntityID | 0] The Entity ID to query
onAreaEntityCollide(function (other_ent_id) {
if (entityExistsNearby(other_ent_id)) {
chatLocal('This is always true');
}
areaStateSet('last_collision', other_ent_id);
});
onAreaPlayerIn(1000, function () {
if (entityExistsNearby(areaStateGet('last_collision'))) {
chatLocal('This is only true if the entity is near us');
}
});
Get the active player's EntityID
Note: This will return 0 if the active player does not have an entity (e.g. is a Spectator).
If the entity is a player, get user-scoped state from their "global" bag, otherwise get entity-scoped state.
[EntityID] The Entity ID to query
[String] The field name to get
If the entity is a player, set a user-scoped state in their "global" bag, otherwise set entity-scoped state.
See userStateSet() for notes on special user state.
[EntityID] The Entity ID to query
[String] The field name to get
[String or Float or Integer] The value to store (0 clears)
Get an entity's type (e.g. "player" or "llamoo")
If the specified entity is not found, or 0 is passed, returns "unknown"
[EntityID | 0] The Entity ID to query
Get a player entity's User ID
If the specified entity is not found, or 0 is passed, returns the empty string ('')
[EntityID | 0] The Entity ID to query
Get prop-scoped local (not saved) state from this or another nearby prop.
[String or 0] The optional tag identifying which prop to operate on
[String] The field name to get
Set prop-scoped local (not saved) state on this or another nearby prop.
Note: local state is not saved, not shared with other players, and will be reset upon a player leaving and returning to the world.
[String or 0] The optional tag identifying which prop to operate on
[String] The field name to set
[String or Float or Integer] The value to set (0 clears)
Set prop-scoped local (not saved) state on all matching nearby props.
Note: local state is not saved, not shared with other players, and will be reset upon a player leaving and returning to the world.
[String] The tag identifying which props to operate on
[Integer, 1..32] The range in which to search for matching props
[String] The field name to set
[String or Float or Integer] The value to set (0 clears)
Add to a prop-scoped state on this or another nearby prop.
Note: all players who interact with this Trigger share the same prop state.
Note: if this script is on an Area, a tag is required and it will use the
matching prop closest to the player and within the Area.
[String or 0] The optional tag identifying which prop to operate on
[String] The field name to set
[Float or Integer] The value to add
Get prop-scoped state from this or another nearby prop.
Note: if this script is on an Area, a tag is required and it will use the
matching prop closest to the player and within the Area.
[String or 0] The optional tag identifying which prop to operate on
[String] The field name to get
Set prop-scoped state on this or another nearby prop.
Some props have states with special behaviors:
open on Doors opens the dooractive on Indicators turns on the light or paneltitle on any prop displays text floating above the propNote: all players who interact with this Trigger share the same prop state.
Note: if this script is on an Area, a tag is required and it will use the
matching prop closest to the player and within the Area.
[String or 0] The optional tag identifying which prop to operate on
[String] The field name to set
[String or Float or Integer] The value to set (0 clears)
Set prop-scoped state on all matching nearby props.
Note: all players who interact with this Trigger share the same prop state.
Note: if this script is on an Area, a tag is required and it will use
props found within a range around the player and within the Area.
[String] The tag identifying which props to operate on
[Integer, 1..32] The range in which to search for matching props
[String] The field name to set
[String or Float or Integer] The value to set (0 clears)
Play a sound coming from this or a tagged prop.
See soundPlay() for list of Sound IDs
[String] The tag identifying which prop to teleport to
[String] A valid Sound ID
[Float, 0..1] The volume at which to play the sound
Disables player movement controls for a limited time, useful when combined velSet().
[Float, 0..10] Seconds to stun the player
Teleports the player a relative distance. For Triggers, this is relative to the direction the Trigger is facing (note that a Trigger is placed initially facing you). For Areas, this position is relative from the lowest coordinate (southwest bottom) corner of the Area.
Note: maximum teleport distance is 32 voxels in Lost Frontier worlds, 1024
voxels otherwise. Use waygate() to teleport arbitrary distances in any
world.
[Float] distance right
[Float] distance forward
[Float] distance up
Teleports the player to (on top of) a nearby prop by tag
Note: prop most be within 32 voxels of the Trigger (or player, if this is
called from an Area script). Use waygate() or teleportRelative() instead
to teleport any distance.
[String] The tag identifying which prop to teleport to
Get user-scoped state from the current player.
[String] The field name to get
Set a user-scoped state on the current player.
Some user states have special behaviors:
[global.]title displays under the player's nameNote: User-scoped state is stored either in an "author" bag, accessible only by scripts on Triggers placed by the same author, or a "global" bag (the default), accessible by any Trigger (note that anyone with Area Builder access can effectively modify any state in the global bag, so generally the "author" bag is what you want for any gameplay state in an "Anyone Can Build" world).
Note: User state in the "global" bag is also reflected as Entity state for any users with nearby entities.
To put something in the author bag (e.g. to protect it), prefix a field
with "author.", see /userstate for details.
[String] The field name to get
[String or Float or Integer] The value to store (0 clears)
The types that can be stored in any persisted state or variable.