Luawe All pages

Markers

A marker is a named point on the song's timeline, drawn as a small rounded diamond with a triangle pointing down at its beat. It does nothing by itself. When the song reaches it, it goes off, and whatever listens for its name hears it. A script that listens for DoShake can shake the screen every time the song gets to a marker with that name, on any beat the level's maker put one.

That is the point of a marker: the effect is written once, and the timeline says when. Moving a marker moves the shake. Adding a marker adds one.

Putting markers in a level

Markers are made in the editor, in the lane at the top of the timeline.

  • Press M, or right-click the lane and pick Add a marker here. The marker goes on the playhead, or where the mouse is.
  • Drag a marker to move it. Delete takes it away. Ctrl+C, Ctrl+V and Ctrl+D copy, paste and duplicate.
  • Double-click one to rename it, or pick it and use its rows in the inspector: Name, and Values.
  • Several markers can stand on one beat. They show as one diamond with a number in it, and a click on it lists them. A marker that is picked keeps its color and gets an outline.

A marker's name is what a script asks for. Every marker with the same name carries the same values, which is what the next part is about.

Listening for a marker

markers.on takes a name and a function. The function runs every time the song reaches a marker with that name:

markers.on("Bounce", function()
    camera:effect(cat.CameraEffect.pulse, 0.1, 0.3)
end)

With that script and a Bounce marker on every beat that should kick, the camera kicks on those beats and on no others.

What a marker carries

A marker can hand something over when it goes off: values, each with its own name and kind. In the editor, a marker called DoShake can have two values, Intensity and Length, both numbers. Each marker called DoShake fills them in for itself: a soft shake on one beat, a hard one on another.

The function is given the values one after the other, in the order the editor lists them, with the marker itself last:

markers.on("DoShake", function(intensity, length, marker)
    print("shake", intensity, length, "on beat", marker.beat)
    camera:effect(cat.CameraEffect.shake, intensity, length)
end)

A marker's value can be:

KindA script gets
NumberA number
Booleantrue or false
StringWords
ThingThe thing it names (see below), or nil if it has none
TableA table, which can hold named entries, lists, and tables in tables
ColorA color
GradientA gradient
CurveA curve (a number along a line, with an envelope)
Range2A range2 (a min and a max)
Range3A range3 (a min, a current and a max)

These are the kinds a thing's attributes have too.

A thing that was picked in the editor stays the thing that was picked, even if it is renamed. A thing that was only written down by name is the first thing with that name.

A table of things

A table is how a marker hands over many things, kept in groups of the maker's choosing. A marker called HideObjects with one table value, Objects, can hold Floors, a list of pieces of floor, and Blocks, a list of blocks. The function gets the table, and reads it like any other:

markers.on("HideObjects", function(objects)
    for _, floor in objects.Floors do
        floor.visible = false
    end
    for _, block in objects.Blocks do
        block.visible = false
    end
end)

A name for each entry, and a list inside it: the table is built to the shape the script wants.

The marker itself

The last value the function gets is the marker. It has its name, its beat, and values, which holds the same values by their names:

markers.on("DoShake", function(intensity, length, marker)
    print(marker.name, marker.beat, marker.values.Intensity)
end)

That is handy when a marker has many values, and only some are wanted: marker.values.Length.

Every marker, and stopping

Leave the name out (or give an empty one) and the function hears every marker. It then gets only the marker:

markers.on(function(marker)
    print("a marker:", marker.name, marker.beat)
end)

markers.on gives back a connection, like connect does. :disconnect() ends it:

local listener
listener = markers.on("Bounce", function(marker)
    print("bounce on beat", marker.beat)
    if marker.beat >= 32 then
        listener:disconnect() -- no more after beat 32
    end
end)

Looking markers up

Three functions answer without waiting for a marker to go off:

local shakes = markers.named("DoShake") -- a list, in the order of their beats
local all = markers.all()               -- every marker in the level
local next = markers.next("DoShake")    -- the next one the song has yet to reach, or nil

if next then
    print("next shake: beat", next.beat, "strength", next.values.Intensity)
end

markers.next() with no name is the next marker of any name. They give the same markers a listener is given: each has name, beat and values.

When a marker goes off

A level works its logic out in fixed steps, 48 to a beat. A marker goes off in the first step at or after its beat, so it is never late by more than a forty-eighth of a beat.

  • Markers on one beat go off one after another, in the order the editor lists them, all in that step.
  • At most 64 go off in one step. If more than that stand on a beat, the rest go off in the steps after it, still in order. The same is done when a frame had no time left.
  • A try that goes back to a checkpoint starts from there: markers before it are not heard again, markers after it are.
  • Moving about the timeline in the editor does not set markers off. Playing does, test play too. Test play from the playhead has run the scripts over what came before, so they have heard the earlier markers by then.

The limits

WhatAt most
Markers in a level20,000
A marker's name64 bytes
A string value200 bytes
Values a name has8
Tables inside tables3 deep
Entries in one table32
Values one marker holds in all, tables counted256
Functions listening for markers at once2000

What goes past a limit is left out as the level loads.

Markers and nodes

The Logic tab has two nodes for markers: When the song reaches a marker, which blinks each time one with its name is reached and puts its values into variables you pick, and Markers named, which puts the beats of those markers into a list. A level can use nodes for some effects and scripts for others, and both hear the same markers.

Next: waiting and tasks.