TriggerScript APi Reference

TriggerScript API Reference

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.

Anatomy of a Triggerscript :

The body (the root scope) of a TriggerScript can contain only
the following kinds of statements (besides comments):

▪ Function declarations (helper functions to call in your handlers)

▪ Calls to on* (e.g. onPressure or onInteract ) APIs to register handlers
                       

 Example:                 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));
                     });

Next part is in developpement ! Some informations can be false !

Basic language features
available
The following are supported in TriggerScript and function
approximately as they do in JavaScript:
▪ variable declarations: var
▪ conditionals: if
▪ assignment operators: = += -= *= /= %= |= &= ^=
▪ binary numeric/string operators: + - * / % & | ^ + - *
/ % | & ^ (note: the mathematical operators will always
coerce to numbers if possible, and treat any truthy nonnumber
as 1 )
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));
});
I Math
T EntityID
T StoredValue
F areaContainsEntity
F areaLocalGet
F areaLocalSet
F areaStateGet
F areaStateSet
F bounce
F buffAdd
F buffClear
F buffSet
F center
F chance
F chatBroadcast
F chatLocal
F chatSay
F damage
F energySet
F entityDisplayName
F entityExistsNearby
F entityMyID
F entityStateGet
F entityStateSet
F entityType
F entityUserID
F error
F onAreaEntityCollide
F onAreaPlayerIn
F onInteract
F onPressure
F orient
)
▪ binary logic operators: == === != !== <= >= < > && ||
▪ unary operators: ! - ~ typeof
▪ // comments and /* comments */
▪ global-scoped function s (cannot be declared within other
functions)
▪ Math object functions and properties
Basic language features not yet
implemented
The following are not yet implemented in TriggerScript, but are
planned:
▪ loops: for while do
▪ Object and Array data types
Differences from JavaScript
▪ Boolean values are represented as 0 and 1
▪ undefined and null are represented as 0
▪ function s can only be declared in the global scope (no
functions within other functions)
API Reference
Type StoredValue
StoredValue: string | number
The types that can be stored in any persisted state or variable.
Type EntityID
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
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).
Function onAreaEntityCollide
onAreaEntityCollide(f: (other_ent_id: EntityID) => void):
void
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).
Parameters
▪ f: (other_ent_id: EntityID) => void
Returns void
Example
Function onAreaPlayerIn
onAreaPlayerIn(f: () => void): void
Registers a function to be called when a player is inside of an
Area.
Can only be called in the root scope. Only valid on Areas.
Parameters
onAreaEntityCollide(function (other_ent_id) {
chatLocal('I touched ' +
entityDisplayName(other_ent_id));
});
Parameters
▪ f: () => void
Returns void
Example
onAreaPlayerIn(period: number, f: () => void): void
Registers a function to be called repeatedly when a player is
inside of an Area.
Can only be called in the root scope. Only valid on Areas.
Parameters
▪ period: number
▪ f: () => void
Returns void
Example
Function onInteract
onInteract(f: () => void): void
Registers a function to be called when a player interacts with the
prop.
Can only be called in the root scope. Only valid on interactable
props such as Trigger Buttons and Doors.
Parameters
▪ f: () => void
Returns void
onAreaPlayerIn(function () {
chatLocal('Hi!');
});
onAreaPlayerIn(1000, function () {
chatLocal('Hi!');
});
Example
Function onPressure
onPressure(f: () => void): void
Registers a function to be called when a player stands on the
prop.
Can only be called in the root scope. Only valid on Trigger
Pressure Plates, Trap Doors, and similar.
Parameters
▪ f: () => void
Returns void
Example
onPressure(period: number, f: () => void): void
Registers a function to be called repeatedly when a player
stands on the prop.
Can only be called in the root scope. Only valid on Trigger
Pressure Plates, Trap Doors, and similar.
Parameters
▪ period: number
▪ f: () => void
Returns void
Example
onInteract(function () {
chatLocal('Hi!');
});
onPressure(function () {
chatLocal('Hi!');
});
onPressure(1000, function () {
chatLocal('Hi!');
Interface Math
interface Math {
E: number;
LN10: number;
LN2: number;
LOG10E: number;
LOG2E: number;
PI: number;
SQRT1_2: number;
SQRT2: number;
abs(x: number): number;
acos(x: number): number;
asin(x: number): number;
atan(slope: number): number;
atan2(y: number, x: number): number;
ceil(x: number): number;
cos(radians: number): number;
exp(x: number): number;
floor(x: number): number;
log(x: number): number;
max(a: number, b: number): number;
min(a: number, b: number): number;
pow(base: number, exponent: number): number;
random(): number;
round(x: number): number;
sin(radians: number): number;
sqrt(x: number): number;
tan(radians: number): number;
}
Properties
chatLocal('Hi!');
});
Math.E
The mathematical constant e. This is Euler's number, the base of
natural logarithms.
Math.Math.LN10
The natural logarithm of 10.
Math.Math.LN2
The natural logarithm of 2.
Methods
Math.Math.LOG10E
The base-10 logarithm of e.
Math.Math.LOG2E
The base-2 logarithm of e.
Math.Math.PI
Pi. This is the ratio of the circumference of a circle to its
diameter.
Math.Math.SQRT1_2
The square root of 0.5, or, equivalently, one divided by the
square root of 2.
Math.Math.SQRT2
The square root of 2.
Math.abs
Math.abs(x: number): number
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.
Parameters
▪ x: number
Returns number
Returns number
Math.acos
Math.acos(x: number): number
Returns the arccosine (or inverse cosine) of a number.
Parameters
▪ x: number
Returns number
Math.asin
Math.asin(x: number): number
Returns the arcsine of a number.
Parameters
▪ x: number
Returns number
Math.atan
Math.atan(slope: number): number
Returns the arctangent of a number.
Parameters
▪ slope: number
Returns number
Math.atan2
Math.atan2(y: number, x: number): number
Math.atan2(y: number, x: number): number
Returns the angle (in radians) between the X axis and the line
going through both the origin and the given point.
Parameters
▪ y: number
A number representing the Cartesian y-coordinate.
▪ x: number
A number representing the Cartesian x-coordinate.
Returns number
Math.ceil
Math.ceil(x: number): number
Returns the smallest integer greater than or equal to its numeric
argument.
Parameters
▪ x: number
Returns number
Math.cos
Math.cos(radians: number): number
Returns the cosine of a number.
Parameters
▪ radians: number
Returns number
Math.exp
( )
Math.exp(x: number): number
Returns e (the base of natural logarithms) raised to a power.
Parameters
▪ x: number
A number representing the power of e.
Returns number
Math.floor
Math.floor(x: number): number
Returns the greatest integer less than or equal to its numeric
argument.
Parameters
▪ x: number
Returns number
Math.log
Math.log(x: number): number
Returns the natural logarithm (base e) of a number.
Parameters
▪ x: number
Returns number
Math.max
Math.max(a: number, b: number): number
Returns the larger of two numbers.
Parameters
▪ a: number
▪ b: number
Returns number
Math.min
Math.min(a: number, b: number): number
Returns the smaller of two numbers.
Parameters
▪ a: number
▪ b: number
Returns number
Math.pow
Math.pow(base: number, exponent: number): number
Returns the value of a base taken to a specified power.
Parameters
▪ base: number
▪ exponent: number
Returns number
Math.random
Math.random(): number
Returns a pseudorandom number between 0 and 1.
Returns number
Math.round
Math.round(x: number): number
Returns a supplied number rounded to the nearest integer.
Parameters
▪ x: number
Returns number
Math.sin
Math.sin(radians: number): number
Returns the sine of a number.
Parameters
▪ radians: number
Returns number
Math.sqrt
Math.sqrt(x: number): number
Returns the square root of a number.
Parameters
▪ x: number
Returns number
Math.tan
Math.tan(radians: number): number
Returns the tangent of a number.
Function areaContainsEntity
areaContainsEntity(tag: string | 0, ent_id: 0 |
EntityID): 0 | 1
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:
▪ The target player has disconnected or otherwise no longer
exists (e.g. trapped llamoo)
▪ The player running the script is far away from the target
If 0 , or anything that is not an EntityID, is passed as ent_id, the
result is always 0
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which Area to
operate on
▪ ent_id: 0 | EntityID
[EntityID | 0] The Entity ID to query
Returns 0 | 1
Example
Parameters
▪ radians: number
Returns number
onAreaEntityCollide(function (other_ent_id) {
if (areaContainsEntity(other_ent_id)) {
chatLocal('This is always true');
}
areaStateSet('last_collision', other_ent_id);
});
Function areaLocalGet
areaLocalGet(tag: string | 0, field: string): StoredValue
Get area-scoped local (not saved) state on the Area the script is
on, or the prop is in, or another Area.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which Area to
operate on
▪ field: string
[String] The field name to get
Returns StoredValue
Example
Function areaLocalSet
areaLocalSet(tag: string | 0, field: string, value:
StoredValue): void
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.
Parameters
onAreaPlayerIn(1000, function () {
if
(areaContainsEntity(areaStateGet('last_collision'))) {
chatLocal('This is only true if the entity is near
us and within the Area');
}
});
chatLocal('x = ' + areaLocalGet(0, 'x'));
▪ tag: string | 0
[String or 0] The optional tag identifying which Area to
operate on
▪ field: string
[String] The field name to set
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
Returns void
Example
Function areaStateGet
areaStateGet(tag: string | 0, field: string): StoredValue
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.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which Area to
operate on
▪ field: string
[String] The field name to get
Returns StoredValue
Example
onAreaPlayerIn(1000, function() {
areaLocalSet('time', areaLocalGet('time') + 1);
if (areaLocalGet('time') > 10) {
status('Time limit exceeded!');
waygate('default');
}
});
Example
Function areaStateSet
areaStateSet(tag: string | 0, field: string, value:
StoredValue): void
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.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which Area to
operate on
▪ field: string
[String] The field name to get
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
Returns void
Example
Function bounce
bounce(horiz_add: number, vert_add: number): void
Invert the player's vertical velocity, maintaining horizontal
velocity, optionally adding velocity.
Parameters
▪ horiz_add: number
chatLocal('x = ' + areaStateGet('x'));
areaStateSet('x', areaStateGet('x') + 1);
[Float, 0..1] Additional horizontal velocity to apply (in the
direction the prop is facing)
▪ vert_add: number
[Float, 0..1] Additional vertical velocity to apply
Returns void
Example
Function buffAdd
buffAdd(buff_id: string, delta_time: number): void
Add or remove time on a buff on the player.
Parameters
▪ buff_id: string
[String] Buff ID to apply
▪ delta_time: number
[Integer, -7200..7200] Seconds to add or subtract
Returns void
Example
Function buffClear
buffClear(buff_id: string): void
Remove a specific or all buffs from the player.
Parameters
▪ buff_id: string
bounce(0, 0);
buffAdd('sprint_m', 60);
[String] Buff ID to remove or "all"
Returns void
Example
Function buffSet
buffSet(buff_id: string, time: number): void
Set a buff on a player for a specific amount of time.
Parameters
▪ buff_id: string
[String] Buff ID to apply
▪ time: number
[Integer, 0..7200] Seconds
Returns void
Example
Function center
center(): void
Center the player above the prop, instantly teleports them to
the center of the Trigger, useful to chain before velSet().
Returns void
Example
buffClear('sprint_m');
buffSet('sprint_m', 60);
center();
Function chance
chance(chance: number): 0 | 1
Evaluates to 1 with the specified probability.
Parameters
▪ chance: number
[Float, 0..1] The probability of returning 1
Returns 0 | 1
Example
Function chatBroadcast
chatBroadcast(message: string | number, ...extra: (string
| number)[]): void
Broadcast a chat message to ALL players in the world, and
above the prop.
Note: requires the script author to have /world_trigger_chat
permissions.
Parameters
▪ message: string | number
[Any] The message to display
▪ ...extra: (string | number)[]
Returns void
Example
if (chance(0.1)) {
chatLocal('You got lucky!');
}
chatBroadcast('Hi!');
Function chatLocal
chatLocal(message: string | number, ...extra: (string |
number)[]): void
Display a message in local chat and above the prop to the
player interacting with the Trigger.
Parameters
▪ message: string | number
[Any] The message to display
▪ ...extra: (string | number)[]
Returns void
Example
Function chatSay
chatSay(message: string | number, ...extra: (string |
number)[]): void
Display a message above the prop to ALL players who are
nearby.
Only valid on Props.
Parameters
▪ message: string | number
[Any] The message to display
▪ ...extra: (string | number)[]
Returns void
Example
chatLocal('Hi!');
chatSay('Hi!');
Function damage
damage(
horiz_vel: number,
vert_vel: number,
stun_time: number,
invuln_time: number,
energy_loss: number,
): void
Apply a damage effect to the player.
Parameters
▪ horiz_vel: number
[Float, 0..1] Horizontal velocity to assign to the player
▪ vert_vel: number
[Float, 0..1] Vertical velocity to assign to the player
▪ stun_time: number
[Float, 0..2] Seconds to stun the player
▪ invuln_time: number
[Float, 0..10] Seconds to make the player immune to other
damage effects
▪ energy_loss: number
[Integer, 0..10000] Energy to remove from the player (if the
current world has energy enabled)
Returns void
Example
Function energySet
energySet(energy: number): void
Set the player's current Energy.
damage(0.35, 0.05, 0.35, 0, 500);
Parameters
▪ energy: number
[Integer, 0...20000] Energy value
Returns void
Example
Function entityDisplayName
entityDisplayName(ent_id: 0 | EntityID | "me"): string
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).
Parameters
▪ ent_id: 0 | EntityID | "me"
[EntityID | 0 | "me"] The Entity ID to query or "me" for the
active player
Returns string
Example
Function entityExistsNearby
entityExistsNearby(ent_id: 0 | EntityID): 0 | 1
energySet(10000);
onAreaEntityCollide(function (other_ent_id) {
chatLocal('I, ' + entityDisplayName(0) + ', touched '
+ entityDisplayName(other_ent_id));
});
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:
▪ The target player has disconnected or otherwise no longer
exists (e.g. trapped llamoo)
▪ The player running the script is far away from the target
If 0 , or anything that is not an EntityID, is passed as ent_id, the
result is always 0
Parameters
▪ ent_id: 0 | EntityID
[EntityID | 0] The Entity ID to query
Returns 0 | 1
Example
Function entityMyID
entityMyID(): 0 | EntityID
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).
Returns 0 | EntityID
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');
}
});
| EntityID
Example
Function entityStateGet
entityStateGet(ent_id: EntityID, field: string):
StoredValue
If the entity is a player, get user-scoped state from their "global"
bag, otherwise get entity-scoped state.
Parameters
▪ ent_id: EntityID
[EntityID] The Entity ID to query
▪ field: string
[String] The field name to get
Returns StoredValue
Example
Function entityStateSet
entityStateSet(ent_id: EntityID, field: string, value:
StoredValue): void
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.
var my_id = entityMyID();
if (my_id) {
chatLocal('My name is ' + entityDisplayName(my_id));
}
onAreaEntityCollide(function (other_ent_id) {
chatLocal('Their title is ' +
entityStateGet(other_ent_id, 'title'));
});
Parameters
▪ ent_id: EntityID
[EntityID] The Entity ID to query
▪ field: string
[String] The field name to get
▪ value: StoredValue
[String or Float or Integer] The value to store (0 clears)
Returns void
Example
Function entityType
entityType(ent_id: 0 | EntityID): "player" | "llamoo" |
"unknown"
Get an entity's type (e.g. "player" or "llamoo")
If the specified entity is not found, or 0 is passed, returns
"unknown"
Parameters
▪ ent_id: 0 | EntityID
[EntityID | 0] The Entity ID to query
Returns "player" | "llamoo" | "unknown"
Example
onAreaEntityCollide(function (other_ent_id) {
entityStateSet(other_ent_id, 'title', 'Tagged!');
});
onAreaEntityCollide(function (other_ent_id) {
chatLocal('I bumped into a ' +
entityType(other_ent_id));
});
Function entityUserID
entityUserID(ent_id: 0 | EntityID): string | 0
Get a player entity's User ID
If the specified entity is not found, or 0 is passed, returns the
empty string ('')
Parameters
▪ ent_id: 0 | EntityID
[EntityID | 0] The Entity ID to query
Returns string | 0
Example
Function error
error(message: string): void
Display an error message and immediately stop script execution.
Parameters
▪ message: string
Returns void
Example
Function orient
onAreaEntityCollide(function (other_ent_id) {
if (entityType(other_ent_id) === 'player') {
chatLocal('I bumped into ' +
entityUserID(other_ent_id));
}
});
error('Something went wrong');
orient(): void
Faces the player's camera in the direction of the Trigger.
Returns void
Example
Function propLocalGet
propLocalGet(tag: string | 0, field: string): StoredValue
Get prop-scoped local (not saved) state from this or another
nearby prop.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which prop to
operate on
▪ field: string
[String] The field name to get
Returns StoredValue
Example
Function propLocalSet
propLocalSet(tag: string | 0, field: string, value:
StoredValue): void
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
orient();
chatLocal('open = ' + propLocalGet(0, 'open'));
Note: local state is not saved, not shared with other players, and
will be reset upon a player leaving and returning to the world.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which prop to
operate on
▪ field: string
[String] The field name to set
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
Returns void
Example
Function propLocalSetAll
propLocalSetAll(
tag: string,
range: number,
field: string,
value: StoredValue,
): void
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.
Parameters
▪ tag: string
[String] The tag identifying which props to operate on
▪ range: number
[Integer, 1..32] The range in which to search for matching
props
▪ field: string
[String] The field name to set
propLocalSet(0, 'open', propLocalGet(0, 'open') != 1);
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
Returns void
Example
Function propStateAdd
propStateAdd(tag: string | 0, field: string, addend:
number): void
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.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which prop to
operate on
▪ field: string
[String] The field name to set
▪ addend: number
[Float or Integer] The value to add
Returns void
Example
Function propStateGet
propLocalSetAll('mydoor', 32, 'open', 1);
propStateAdd(0, 'x', 1);
propStateGet(tag: string | 0, field: string): StoredValue
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.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which prop to
operate on
▪ field: string
[String] The field name to get
Returns StoredValue
Example
Function propStateSet
propStateSet(tag: string | 0, field: string, value:
StoredValue): void
Set prop-scoped state on this or another nearby prop.
Some props have states with special behaviors:
▪ open on Doors opens the door
▪ active on Indicators turns on the light or panel
▪ title on any prop displays text floating above the 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.
Parameters
▪ tag: string | 0
[String or 0] The optional tag identifying which prop to
operate on
chatLocal('open = ' + propStateGet(0, 'open'));
operate on
▪ field: string
[String] The field name to set
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
Returns void
Example
Function propStateSetAll
propStateSetAll(
tag: string,
range: number,
field: string,
value: StoredValue,
): void
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.
Parameters
▪ tag: string
[String] The tag identifying which props to operate on
▪ range: number
[Integer, 1..32] The range in which to search for matching
props
▪ field: string
[String] The field name to set
▪ value: StoredValue
[String or Float or Integer] The value to set (0 clears)
void
propStateSet(0, 'open', propStateGet(0, 'open') != 1);
Returns void
Example
Function randNum
randNum(max: number): number
Evaluates to a (floating point) number between 0 (inclusive) and
max (exclusive).
Parameters
▪ max: number
[Float] The (exclusive) maximum value to return
Returns number
Example
Function randRange
randRange(max: number): number
Evaluates to an integer between 0 (inclusive) and max
(exclusive).
Parameters
▪ max: number
[Integer, 2..1e9] The (exclusive) maximum value to return
Returns number
Example
propStateSetAll('mydoor', 32, 'open', 1);
velSet(0, 0.5 + randNum(0.5));
chatLocal('Die rolled', randRange(6) + 1);
Function soundPlay
soundPlay(sound_id: string, volume: number): void
Play a sound.
Valid Sound IDs:
▪ bounce
▪ buff
▪ damage
▪ debuff
▪ door_close
▪ door_open
▪ eat
▪ indicator_off
▪ indicator_on
▪ pickup
▪ velocity_set
Parameters
▪ sound_id: string
[String] A valid Sound ID
▪ volume: number
[Float, 0..1] The volume at which to play the sound
Returns void
Example
Function soundPlay3D
soundPlay3D(tag: string, sound_id: string, volume:
number): void
Play a sound coming from this or a tagged prop.
See soundPlay() for list of Sound IDs
soundPlay('buff', 1);
Parameters
▪ tag: string
[String] The tag identifying which prop to teleport to
▪ sound_id: string
[String] A valid Sound ID
▪ volume: number
[Float, 0..1] The volume at which to play the sound
Returns void
Example
Function status
status(message: string | number, ...extra: (string |
number)[]): void
Display a message as a status message to the player interacting
with the Trigger.
Parameters
▪ message: string | number
[Any] The message to display
▪ ...extra: (string | number)[]
Returns void
Example
Function stun
stun(time: number): void
soundPlay3D('mypanel', 'buff', 1);
status('Hi!');
Disables player movement controls for a limited time, useful
when combined velSet().
Parameters
▪ time: number
[Float, 0..10] Seconds to stun the player
Returns void
Example
Function teleportRelative
teleportRelative(x: number, y: number, z: number): void
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.
Parameters
▪ x: number
[Float] distance right
▪ y: number
[Float] distance forward
▪ z: number
[Float] distance up
Returns void
Example
stun(0.5);
teleportRelative(0, 2, 0);
Function teleportToProp
teleportToProp(tag: string): void
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.
Parameters
▪ tag: string
[String] The tag identifying which prop to teleport to
Returns void
Example
Function timeMs
timeMs(): number
Get the current time since the Unix epoch in milliseconds.
Returns number
Example
Function timeSeconds
timeSeconds(): number
teleportToProp('mytarget');
var dt = timeMs() - propStateGet('last_time');
chatLocal('Time since last visitor = ' + dt);
propStateSet('last_time', timeMs());
Get the current time since the Unix epoch in seconds.
Returns number
Example
Function userMyID
userMyID(): string
Get the active player's UserID
Returns string
Example
Function userStateAdd
userStateAdd(field: string, addend: number): void
Add to a user-scoped state on the current player.
Parameters
▪ field: string
[String] The field name to get
▪ addend: number
[Float or Integer] The value to add
Returns void
Example
var today = timeSeconds() / 60 / 60 / 24;
chatLocal('I am ' + userMyID()));
userStateAdd('x', 1);
Function userStateGet
userStateGet(field: string): StoredValue
Get user-scoped state from the current player.
Parameters
▪ field: string
[String] The field name to get
Returns StoredValue
Example
Function userStateSet
userStateSet(field: string, value: StoredValue): void
Set a user-scoped state on the current player.
Some user states have special behaviors:
▪ [global.]title displays under the player's name
Note: 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.
Parameters
▪ field: string
[String] The field name to get
chatLocal('x = ' + userStateGet('x'));
[String] The field name to get
▪ value: StoredValue
[String or Float or Integer] The value to store (0 clears)
Returns void
Example
Function velSet
velSet(horiz_vel: number, vert_vel: number): void
Set the player's velocity (jump).
Parameters
▪ horiz_vel: number
[Float, 0..1] Horizontal velocity to assign to the player
▪ vert_vel: number
[Float, 0..1] Vertical velocity to assign to the player
Returns void
Example
Function waygate
waygate(waygate_id: string): void
Teleport the player to the specified waygate.
Parameters
if (userStateGet('title')) {
userStateSet('title', 0);
} else {
userStateSet('title', 'The King');
}
velSet(0, 0.18);
▪ waygate_id: string
[String] The Waygate ID to target
Returns void
Example
waygate('default');