Map

What the mapper put in the map, by the names they gave it:

markers: points with a facing, such as spawns;
parts: objects the mod can move, hide or make solid, such as doors and lifts;
triggers: spaces that hear a player come in, look at them, use them or shoot them.

Making a map says how a mapper marks each.

Each is reached by its name, parts.door_a, or by a pattern, parts("barrier*"), where * stands for any text. A marker or a part the map does not have fails, naming the map. A method called on a set calls it on each member, as parts("barrier*"):remove().

A trigger’s handlers are given at a module’s top, by its name: triggers.buy_door:on("activated", fn). A name the map does not have declares triggers the mod makes while it runs, with trigger, as a revive point where a player fell. The server tests every trigger each tick, and what it last found is what a trigger’s players and a player’s is_inside and the like read. A trigger that fires on clients is heard by their scripts too, so a jump pad pushes a player at once, as their game predicts it.

A trigger reads name, position, properties, frozen, owner, exists and enabled. Set enabled to false, and the bodies inside are heard leaving and nothing sets it off; set true again, it hears the bodies inside come in.

markers

On the server markers: Markers

The map's markers, points with a facing, by name, markers.spawn0, or by a pattern, markers("spawn*"), in the map's order. A name the map has not fails.

parts

On the server parts: Parts

The map's parts, by name, parts.door_a, or by a pattern, parts("barrier*"), whose methods call each. One removed is left out of the sets made after.

triggers

On both sides triggers: Triggers

The map's triggers, and those the mod's handlers declare, by name, triggers.buy_door, or by a pattern, which lists those made at run time after the map's. One removed is left out of the sets made after.

Fields

What a player, p, or an entity, e, reads beside the mod’s state. A field of the other side’s fails.

Name	Type	Side	What it is
`p.use_target`	`(Trigger & {held: number?})?`	On both sides	The use trigger they would use, with the seconds `held` its key so far; on a client, the shown player's alone.
`e.name`	`string?`	On the server	A part's name in the map; nil for what the mod made.
`e.properties`	`{[string]: Property}?`	On the server	A part's properties, as the mapper set them.

is_inside

On the server p:is_inside(trigger) → boolean

Whether the player stands inside trigger, a touch or a use trigger, as the server last found them.

It fails for a trigger of another type, and is false for one removed.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

boolean

Fails

a value of the wrong type

To heal a player while they stand in a spring

local spring = trigger("spring", "touch", { box = vector.create(6, 3, 6) })
if p:is_inside(spring) then
    p:heal(5)
end

is_looking_at

On the server p:is_looking_at(trigger) → boolean

Whether the player is looking at trigger, a look trigger, as the server last found them: their view meeting it before anything that stops shots.

It fails for a trigger of another type, and is false for one removed.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

boolean

Fails

a value of the wrong type

To tell a player what they look at

local statue = trigger("statue", "look", { box = vector.create(1, 3, 1) })
if p:is_looking_at(statue) then
    say("The founder, 1921", { to = { p } })
end

is_using

On the server p:is_using(trigger) → boolean

Whether the player holds the use key on trigger, a use trigger, as the server last found them.

It fails for a trigger of another type, and is false for one removed.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

boolean

Fails

a value of the wrong type

time_inside

On the server p:time_inside(trigger) → number?

How many seconds the player has stood inside trigger, a touch or a use trigger, as the server last found them; nil when they are not.

It fails for a trigger of another type.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

number?

Fails

a value of the wrong type

time_looking_at

On the server p:time_looking_at(trigger) → number?

How many seconds the player has looked at trigger, a look trigger, as the server last found them; nil when they do not.

It fails for a trigger of another type.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

number?

Fails

a value of the wrong type

time_using

On the server p:time_using(trigger) → number?

How many seconds the player has held the use key on trigger, a use trigger, as the server last found them; nil when they do not.

It fails for a trigger of another type.

Name	Type	What it is
`trigger`	`Trigger`	Needed.

Returns

number?

Fails

a value of the wrong type

To show how far a player is through opening a crate

local crate = trigger("crate", "use", { box = vector.create(1, 1, 1) }, { activation_time = 4 })
local held = p:time_using(crate)
if held then
    say(`Opening: {math.floor(held / 4 * 100)}%`, { to = { p } })
end

trigger

On the server trigger(name, kind, { box?, cylinder?, sphere? }, options?) → Trigger

Makes a trigger at run time of a name a handler declared, of kind and shape, and gives it.

A name the map has no trigger of is declared by its handlers, triggers.revive:on(…), given at a module’s top; making one of a name no handler declared, or whose handlers hear an event kind does not, fails, as does one of a name the map has. An option of another type than kind’s fails: detect is a touch trigger’s, look a use trigger’s, means and weapons a damage trigger’s, and activation_time that of every type but damage. Each shape stands on its origin, a sphere and a box too. 1024 made at run time are alive at most.

One that fires_on_client is told each client as its player meets it, so their scripts hear it too: its name and properties, and those of all such, within what a client joining is told at once.

Name	Type	What it is
`name`	`string`	Needed.
`kind`	`"touch" \| "look" \| "use" \| "damage"`	Needed.
`shape`	`table`	A table of the options below. Those marked needed may not be left out.
`box`	`vector?`	A box of this size along x, y and z, in metres, each 0.01 to 1000. Not with `cylinder` or `sphere`.
`cylinder`	`TriggerCylinder?`	An upright cylinder. A table of the options below it. Not with `box` or `sphere`.
`cylinder.radius`	`number`0.01 to 1000	How far its side is from its upright axis. Needed.
`cylinder.height`	`number`0.01 to 1000	How tall it stands from its origin up. Needed.
`sphere`	`number?`0.01 to 1000	A ball of this radius, in metres. Not with `box` or `cylinder`.
`options`	`table?`	A table of the options below. It, and each option, may be left out.
`at`	`vector?`	Where its origin stands; at the world's origin without.
`angles`	`Angles?`	How it is turned about its origin.
`owner`	`(Player \| number)?`	The player it is about, whom `triggered_by` picks by.
`triggered_by`	`(Group \| ((Player?, Player) -> boolean))?`	Who sets it off, and no NPC; everyone, NPCs too, without.
`properties`	`({[string]: Property})?`	Its properties, as a mapper's: each a boolean, a number, a string or a list of them, 1024 at most.
`fires_on_client`	`boolean`default false	Whether the scripts of each client hear what it hears of their own player too.
`detect`	`("overlap" \| "center" \| "contain")?`	A touch trigger's: what of a body counts as inside, any of its box, its middle or all of it.
`activation_time`	`number?`0 or more	A touch, look or use trigger's: the seconds its condition lasts before `activated`; at once without.
`look`	`boolean?`	A use trigger's: whether the use key counts only while the player's view meets it.
`means`	`{string}?`	A damage trigger's: the means of damage it hears, as `"bullet"`; any without.
`weapons`	`{string}?`	A damage trigger's: the weapons it hears, by name; any without.

Returns

Trigger

Fails

a value of the wrong type
an option it does not have
a key it needs left out
a value outside its range
box and cylinder both
box and sphere both
cylinder and sphere both

To mark where a player fell, for a teammate to revive them

triggers.revive:on("activated", function(e)
    e.trigger:remove()
end)

local function revive_point(fallen)
    return trigger("revive", "use", { cylinder = { radius = 1, height = 2 } }, {
        at = fallen.position,
        owner = fallen,
        activation_time = 3,
        triggered_by = everyone - owner,
        properties = { hint = `Revive {fallen.name}` },
    })
end

on("killed", function(e)
    revive_point(e.victim)
end)

DeclaredTrigger:on

On the server DeclaredTrigger:on(event, fn)

Runs fn each time a trigger of this name, made at run time, hears event, given {trigger, player} as Trigger:on's handlers are.

A name the map has no trigger of reads as one declared: its handlers, given at a module’s top, declare the name, so trigger makes triggers of it. Their type is known only as one is made, which fails if its type does not hear an event its handlers do.

Name	Type	What it is
`event`	`TriggerHears`	Needed.
`fn`	`(e: TriggerEvent) -> ()`	Needed.

Fails

a value of the wrong type

To bring a player back where a teammate revived them

triggers.revive:on("activated", function(e)
    local fallen = e.trigger.owner
    if fallen then
        fallen:respawn()
        fallen:set_position(e.trigger.position)
    end
    e.trigger:remove()
end)

Trigger:on

On the server Trigger:on(event, fn)

On a client Trigger:on(event, fn)

Runs fn each time this trigger of the map hears event, given {trigger, player}.

On the server

It is given at a module’s top: a second for the same event in the same file replaces the first. A trigger hears its type’s events alone: a touch trigger entered and left, a look trigger looked_at and looked_away, a use trigger use_pressed, use_released and use_cancelled, a hold ended early by letting go, looking away or walking out. Each hears activated once its condition has lasted its activation_time: at once without one, once a stay, a look or a hold. A damage trigger hears activated on each shot or blast that reaches it, given attacker, as player too, amount, means, weapon, point, dir and projectile.

player is a person, a bot or an NPC: players and NPCs touch, players alone look and use. The dead and the gone are heard leaving, as left, looked_away and use_cancelled, and so is whom it held as it is disabled. Removed by a handler, it hears nothing more of what the server found that tick; disabled by one, nothing that starts or sets it off, so of four players pressing the use key on one buy trigger in a tick, one buys it. A trigger made at run time is listened to by its name before it is made, triggers.revive:on (DeclaredTrigger:on).

A body is followed along the way it went during the tick, so one crossing a thin trigger at a sprint is heard entering and leaving, in order. A player standing in several use triggers uses the first look trigger their view meets, else the one nearest their eyes. A damage trigger hears a shot only up to where it struck, with the damage it does that far.

Name	Type	What it is
`event`	`TriggerHears`	Needed.
`fn`	`(e: TriggerEvent) -> ()`	Needed.

Fails

a value of the wrong type

On a client

Runs fn each time a trigger that fires on this client hears event of the client’s own player, given {trigger, player}, as its game first predicts the player through it.

It is given at a script’s top by the trigger’s name, so one the server tells this client later, or makes at run time, is heard too; a set, triggers("pad*"):on(…), listens by its pattern. Only the server’s triggers that fire on clients are heard, and of them what a damage trigger hears is not. The server’s handler of the same trigger hears it too, a moment later.

While it runs, me reads the player as that moment left them, and me:set_velocity, add_velocity, tune, limit_view, set_position and set_angles move them from the next moment on, as the server’s handler orders it: the two agreeing show nothing, and differing a correction, once. Anywhere else, or on another player, those fail.

Name	Type	What it is
`event`	`TriggerHears`	Needed.
`fn`	`(e: TriggerEvent) -> ()`	Needed.

Fails

a value of the wrong type

To open a door for the player who buys it

triggers.buy_door:on("activated", function(e)
    say(`{e.player.name} opened the door`)
    e.trigger:remove()
end)

To launch a player off a jump pad as soon as they step on it

triggers.jump_pad:on("entered", function(e)
    me:set_velocity(vector.create(0, e.trigger.properties.launch, 0))
end)

Trigger:remove

On the server Trigger:remove()

Removes the trigger: it hears nothing more, reads exists false, and is left out of the sets made after. One removed already is left as it is.

To take away a revive point once it is used

local revive = trigger("revive", "use", { sphere = 1 })
revive:remove()

Trigger:players

On the server Trigger:players() → {Player}

The players and NPCs it holds, as the server last found them: those inside a touch trigger, looking at a look trigger or using a use trigger; none while it is disabled.

Returns: {Player}

To heal everyone standing in a spring

local spring = trigger("spring", "touch", { box = vector.create(6, 3, 6) })
for _, p in spring:players() do
    p:heal(5)
end

Trigger:attach

On the server Trigger:attach(to, { offset? }?)

Makes the trigger ride a player, an NPC, a model or a part, turning as it turns; once that goes, the trigger stays where it was.

One gone already is left as it is.

Name	Type	What it is
`to`	`Player \| Entity \| number`	Needed.
`options`	`table?`	A table of the options below. It, and each option, may be left out.
`offset`	`vector?`	Where its origin stays in the space of what it rides; at that origin without.

Fails

a value of the wrong type
an option it does not have

To make a zone that follows a player

local aura = trigger("aura", "touch", { sphere = 3 }, { owner = p, triggered_by = everyone - owner })
aura:attach(p, { offset = vector.create(0, 1, 0) })

Trigger:detach

On the server Trigger:detach()

Lets go of what the trigger rides, so it stays where it is.

Trigger:set_position

On the server Trigger:set_position(point)

Moves the trigger's origin to point at once, letting go of what it rides; it sweeps nothing on the way.

Name	Type	What it is
`point`	`vector`	Needed.

Fails

a value of the wrong type

To move a buy point to where the box now stands

local box = trigger("mystery_box", "use", { box = vector.create(2, 1, 1) })
box:set_position(vector.create(12, 0, -4))

Trigger:set_angles

On the server Trigger:set_angles(angles)

Turns the trigger about its origin to angles at once, letting go of what it rides; an angle left out is 0.

Name	Type	What it is
`angles`	`Angles`	Needed.

Fails

a value of the wrong type