Music - AbstractPolygon/vcs-game-maker-absply GitHub Wiki

This feature is in early alpha - things may change or break.

The Music tab builds songs: a sequence of reusable patterns, each holding one or more instrument tracks of notes, played back using Sound tab presets as instruments.

Toolbar

The toolbar above the songs has these tools, left to right:

Export song bank — saves every song in the project, plus the Sound tab instruments they use, into a single .vcsmus file (the same database icon as the Sound tab's sound bank).

Import song bank — loads a song bank file. A song whose name matches one already in the project has its contents replaced (it keeps its ID, so blocks pointing at it still work); every other song in the file is added as a new song. Instruments are matched by name, like importing a single song.

Export song / Import song — save or load the current song as a single .vcsmus file (older .json files still import).

Auto-switch to whichever pattern is playing (target icon) — when on, the visible pattern follows playback as the song moves through its sequence.

Loop / Stop (Space) / Play the full pattern sequence (Space) — the playback controls. Loop, when on, repeats the song's preview playback until you stop it. Stop ends preview playback. Play plays the current song's sequence in the browser, and the button shows a speaker icon while it plays. Space toggles between Stop and Play.

DIM

Sits in the toolbar to the right of the Play button. Same DIM switch/percentage slider as the Sound tab - shared, project-wide setting (changing it here changes it on the Sound tab too). When on, every note plays at this percentage of its set volume instead of full volume.

Songs

Click the + button in the bottom-right corner to add a new song. Each card has:

Song name / Tempo (BPM) — the song's name and default tempo.
ID (the badge in the card's top-left) — a permanent number, separate from the name or list position.

Export / Import — save or load a song as a .vcsmus file (older .json files still import).

Auto-switch to whichever pattern is playing (target icon) — when on, the visible pattern automatically follows playback as the song moves through its sequence.

Loop / Stop (Space) / Play the full pattern sequence (Space) — the playback controls for this song, previewed directly in the browser. Loop repeats the song's preview playback until stopped. A playing song keeps going if you switch to another tab - come back and press Stop to end it. Space toggles between Stop and Play depending on whether the song is currently playing.

Delete this song — asks for confirmation. Only shown when there's more than one song.

Click the chevron in the top-left corner to collapse a song down to just its name/tempo row. Drag the strip at the top of a card to reorder songs in the list.

Sequence

The order patterns play in for this song - a row of chips, each referencing one pattern:

Add pattern — appends a chip for one of this song's patterns to the sequence.

Click a chip to make it the active pattern shown/edited below.
×N on a chip / dragging its right-edge handle — repeats that pattern that many times in a row before moving to the next chip, without needing N separate identical chips.
The × on a chip removes it from the sequence.
Each chip's "ID: N" badge is its position in the sequence (1 = first) - used by the "When sequence chip has finished playing" block on the Actions tab. This is a position, not a permanent identity - it changes if chips are reordered, inserted, or deleted before it.
Drag a chip's body to reorder the sequence.

Patterns

The active pattern (picked via the Sequence chips, or the name field below) shows:

Pattern name — a combobox: pick an existing pattern from this song, or type a new name to create one.

Add pattern / Duplicate this pattern — create a new empty pattern, or a copy of the current one.

Length (steps) — how many steps long the pattern is.
Use pattern tempo checkbox + Tempo (BPM) — override the song's tempo just for this pattern.

Export (Shift+E) / Import (Shift+I) (a .vcsmus file; older .json files still import), Loop, Stop / Play this pattern (Shift+Space toggles between these two) — save/load just this one pattern as a standalone file, plus preview controls scoped to it.

Delete this pattern — only shown when the song has more than one pattern.

Click the chevron in the top-left corner to collapse a pattern down to just its name/length/tempo row. Whether the Pattern Editor is open or collapsed is one setting for the tab - it stays as you left it when you pick a different pattern, or add or duplicate a pattern or song - and it starts collapsed each new browser session.

Instruments

Each pattern holds one or more instrument tracks - one row of notes per track, all drawn together in the piano roll below. Click Add instrument to add a track. Each track row has:

A radio button — selects this track as the one currently being edited in the piano roll below.
A color dot — this instrument's note color, set on its Sound tab card.
Instrument — which Sound tab preset this track plays. Only sounds tagged with the Instrument icon on the Sound tab show up in this dropdown.
Channel — which of the two sound channels (0 or 1) this track plays on.

Show/Hide in piano roll (eye icon) — hides this track's notes from the piano roll view without muting or deleting them.

Mute — silences this instrument during playback, for every pattern in this song.

Solo — silences every OTHER instrument in this song during playback.

Copy this instrument's notes / Paste copied notes onto this instrument — copies a track's notes onto another track (in this or another pattern/song).

Remove this instrument row — only shown when the pattern has more than one track.

Click the chevron next to "Instruments" to collapse the section down to a row of instrument chips - click a chip to make that instrument the active one.

Piano roll

The piano roll is where you actually place notes for a pattern - a grid with pitch running down the rows and time running across the columns (one column per step, per the pattern's Length setting). Every visible track's notes are drawn on this same shared grid, but only the currently active track (selected in Instruments above) can be edited here.

Click a cell to place or remove a note for the active track at that pitch/step.
Drag a note's right-edge handle to change its duration.
The Vol row below the roll shows a volume bar per note - drag it to change that note's volume, as a percentage of the instrument's base volume, for just that note. Notes from other (visible, non-active) tracks show as faint "ghost" bars for reference.
Click a step number in the header to move the playhead there - seeks immediately if already playing, otherwise playback starts from there next.

Toolbar

The piano roll's toolbar, left to right:

Undo (Ctrl+Z) / Redo (Ctrl+Y) — steps back and forward through this pattern's edit history (name, tempo, step count, tracks/notes). Each pattern keeps a separate history.

Move (V) — drag a placed note to a different pitch or step. With a selection made, dragging moves all the selected notes together.

Draw (B) — click a cell to place a note.

Erase (E) — click a placed note to remove it.

Rectangle select (M) — drag a box to select several notes; use Move to drag them together.

Note duration snap (magnet icon) — toggles whether placing and resizing notes snaps to the slice count below, or moves freely.

Slices per step (dropdown) — how many equal slices each step is divided into for snapping.

Zoom — Fit (scales the roll to the pattern's length), the current percentage, Zoom out, a slider (25% to 1600%) and Zoom in. They resize the piano roll's step width.

Export pattern (Shift+E) / Import pattern (Shift+I), Loop, Stop and Play this pattern (Shift+Space) — the same pattern controls as in the Pattern card, repeated here so they stay reachable while the Instruments section is expanded.

DPC+ music

With the DPC+ kernel the Music tab's notes play on the sound chip's three voices (channels 0, 2 and 3) plus the TIA's channel 1. The piano roll only offers the notes the chip can play, instruments use the waveform drawn on their sound card, and arpeggio intervals are semitones. Percussion goes in the Hit row. An envelope on an arpeggio applies to the last step only.

Using music from your blocks

See the Actions tab's Music category for every music-related block: playing/stopping/pausing a song (by name or runtime ID), watching for a song or sequence chip finishing, and watching for a specific instrument's notes being played.