BeatClock

Keeps time with the music: counts its beats and bars as they’re heard (allowing for the sound card’s delay and the player’s own audio offset, Game.AudioOffset, which a Calibration measures), and sends BeatMessage on every beat and BarMessage on the first beat of every bar, so sound players, counters, scripts and BeatPulses can follow along, and Spawners, Shooters, Movers and Switches with Beats set step to it. It follows whatever music is playing (a BackgroundMusic’s, a room’s or a script’s) and waits while there’s none. Music made with Audio > New Music says its own tempo; for other music, set Tempo.

Works with: BackgroundMusic (the music it keeps time with); BeatPulse (things that bop on its beat)

In a network game, each machine keeps its own entity with this on it: it isn’t sent.

Properties

Each is listed as its key in the scene file and the MCP tools, then its kind of value, its default and what it does.

tempo: a number = 0. Beats a minute. 0 takes the music’s own, when it says (music made with Audio > New Music does), and otherwise counts 120. (Field: a number.)
beatsPerBar: a whole number = 4. Beats in a bar: 4 for most music, 3 for a waltz. (Field: a number.)
offset: a number = 0. Seconds into the music of its first beat: for music with a lead-in, or to nudge the beat later (more) or earlier (less) until it sits right. It’s the music’s, the same for everyone; how late a player’s own speakers are is their audio offset (Game.AudioOffset), which the clock allows for on top. (Field: a number.)
beatMessage: text = “Beat”. Sent on every beat, with the beat’s number (0 for the first) as its data. Empty sends nothing. (Names a message.) (Field: a name.)
barMessage: text = “Bar”. Sent on the first beat of every bar, with the bar’s number (0 for the first). Empty sends nothing. (Names a message.) (Field: a name.)

Outputs

What anything can read with no code: a Counter’s, Bar’s or Text’s output, a Contraptions Wire’s output as its signal; Text shows names too, the rest read numbers, true as 1.

Beat (a whole number). The beat it’s on, counting from 0; -1 before the first.
Bar (a whole number). The bar it’s on, counting from 0.
BeatInBar (a whole number). Which beat of the bar it’s on, from 0 (the bar’s first, the downbeat) to BeatsPerBar - 1.

While the game runs

Not saved with the scene; scripts read them, and entity_get shows them as live while the game plays.

isPlaying: true or false. True while there’s music to keep time with.
currentTempo: a number. The tempo it counts at: its Tempo, or the music’s.
position: a number. Seconds into the music that have been heard (less the player’s audio offset), back to 0 each time it loops.
beats: a number. Beats heard since the first, with how far through this one: 8.5 is halfway through beat 8 (the ninth). It counts on as the music loops, and is below 0 before the first beat.
beat: a whole number. The beat it’s on, counting from 0; -1 before the first.
bar: a whole number. The bar it’s on, counting from 0.
beatInBar: a whole number. Which beat of the bar it’s on, from 0 (the bar’s first, the downbeat) to BeatsPerBar - 1.
phase: a number. How far through the beat it is, from 0 (on it) to almost 1 (the next is due).
secondsPerBeat: a number. How long a beat lasts, in seconds.
secondsFromBeat: a number. How far it is from the nearest beat, in seconds: negative just before it, positive just after. For timing a press to the music: if (Math.Abs(clock.SecondsFromBeat) < 0.1f) Perfect(); The player’s audio offset is allowed for, so a press on the beat as they hear it is 0.
shownBeats: a number. The beats to draw now: Beats ahead by the player’s visual offset (Game.VisualOffset, how late their screen shows things), so what’s drawn to the beat (a BeatPulse, notes coming down a lane) is seen just as the beat is heard. Only drawing goes by it.
shown: a number. The beats drawn: those counted, ahead by the player’s visual offset, for what shows the beat.

Scripts use it as BeatClock: its methods, events and values that aren’t saved with the scene.