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:
| Kind | A script gets |
|---|---|
| Number | A number |
| Boolean | true or false |
| String | Words |
| Thing | The thing it names (see below), or nil if it has none |
| Table | A table, which can hold named entries, lists, and tables in tables |
| Color | A color |
| Gradient | A gradient |
| Curve | A curve (a number along a line, with an envelope) |
| Range2 | A range2 (a min and a max) |
| Range3 | A 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)
endmarkers.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
| What | At most |
|---|---|
| Markers in a level | 20,000 |
| A marker's name | 64 bytes |
| A string value | 200 bytes |
| Values a name has | 8 |
| Tables inside tables | 3 deep |
| Entries in one table | 32 |
| Values one marker holds in all, tables counted | 256 |
| Functions listening for markers at once | 2000 |
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.