Music theory, arranging, and 16-bit study archetypes #
Practical arranging and harmonic voice-leading principles distilled from classic Mega Drive / Genesis soundtracks and enforced by ValidateScoreTheory in ../scripts/sound.go.
1. Scene playback baselines and structural archetypes #
Match playback mode, duration, tempo, and macro-form to the gameplay role:
| Scene / Event Type | Playback Mode | Typical Duration | Typical BPM Range | Musical Structure |
|---|---|---|---|---|
| Stage / Gameplay | Looped (audio.NewInfiniteLoop) | 60s to 180s+ | 100 to 160 BPM | Multi-section arc (Intro -> Theme A -> Theme B -> Climax -> Turnaround) to prevent loop fatigue. |
| Boss Battle | Looped (audio.NewInfiniteLoop) | 45s to 120s | 135 to 180+ BPM | Driving syncopation, harmonic minor or Phrygian tension, 4-op FM leads, octave :16 bass. |
| Title / Menu / Sanctuary | Looped (audio.NewInfiniteLoop) | 30s to 90s | 70 to 125 BPM | Memorable motif or pad/arpeggio texture setting world mood. |
| Game Over | One-off (Play(pcm, false)) | 4s to 15s | 60 to 90 BPM | Non-looping minor cadence or quiet resolution keeping retry friction low. |
| Stage Clear / Fanfare | One-off (Play(pcm, false)) | 5s to 15s | 120 to 160 BPM | Non-looping ascending brass/bell fanfare with clean final chord release. |
Never force every soundtrack into identical instruments or an 8-bar A + 8-bar B loop. Five classic reference scores live in scripts/:
| Archetype and Study Score | Tempo & Feel | Core Palette | Macro-Form Architecture |
|---|---|---|---|
Urban Club Groove (bare_knuckle_intro.music) | 100 BPM (moderato), syncopated house/funk | Zero guitars: 3-voice FM synth-brass, epiano1, psg_square lead + :8 delay, slap_bass_1, string_ensemble_1. | Through-composed 41 bars: 8-bar dark intro -> 8-bar pulsing buildup -> 8-bar brass hook -> 8-bar climax with high PSG counter-lead -> 9-bar drumless fade outro. |
Sci-Fi Shmup (gaiares_level2.music) | 148 BPM (allegro), propulsive | Bright FM lead + echo, vibraphone, epiano1, brass, :16 PSG arps, electric_bass + slap_bass_1. | Asymmetric loop (73 bars): 2-bar solo drum fill -> 33-bar loop (32 melodic + 1 solo drum-break bar) x 2 -> 5-bar fade. |
East-Asian Action (shinobi2_stage2.music) | 134 BPM (allegro), galloping momentum | shamisen / koto / orchestral_harp ostinato, galloping toms, FM lead, brass, driving bass. | Ostinato frame (98 bars): 4-bar intro -> 44-bar loop (A heroic -> B lift -> C breakdown -> 4-bar shamisen bridge) x 2 -> 6-bar fade. |
Neoclassical Action (elemental_master_stage1.music) | 150 BPM (allegro), dramatic rock/metal | Twin harmonizing FM guitars in 3rds/6ths, epiano1, strings, :16 driving bass. | Fanfare anthem (69 bars): 8-bar ceremonial fanfare with tom rolls -> 28-bar loop x 2 -> 5-bar fade. |
Lyrical Stage Ballad (ground_zero.music) | 96 BPM (andantino), spacious | Solo lead + :16 octave echo, epiano1, brass, strings, C1..C2 bass. | Evolving cycles (56 bars): 4-bar intro -> Cycle 1 (A+B, sparse bass) -> Cycles 2 and 3 (A+B, :16 bass + open-fifth arps) -> 4-bar coda. |
2. Cross-bar continuity vs. re-attacked stabs #
- Hold legato notes across barlines with
~: WriteC3:1~1orF5:8~ | :16instead ofC3:1 | C3:1, which creates an artificial attack transient on Beat 1. - Keep rhythmic chord stabs crisp: Write explicit
:8.re-attacks (*Nrepeats) with:16release gaps (R:16) at turnarounds so stabs punch cleanly:text(A4:8 E5:8.*2 F5*3 R:16 D5:8.*2 G5*2 G5:8 |)*9
3. Rhythmic signatures and bass engines #
- Tresillo stabs (
3+3+3+3+2+2): Grouping:16subdivisions in 3s (:8.) over straight4/4drums drives synth-brass hooks and plucked ostinatos (E4:8. A4 B4 C5 B4:8 A4). - Triplets (
:8t,:4t) over a:16backing: Combining~ties with:8tand:4tkeeps floating leads locked via exact 64-bit rational arithmetic with zero sample drift. - Rotate bass patterns by section:
- Pulsing pre-drop buildup:
(A2:8.*2 A2:4 A2:4.)*8 - Offbeat slap-bass:
((G2:16 A2:8)*4 A2:8. G2:16)*15 - Driving
:16rock octave bass:(C1 C2):16*4
- Pulsing pre-drop buildup:
- Half-bar call-and-response: Pair held
:2peaks on Beats 1 and 2 with:8. :8. :8answers on Beats 3 and 4 rather than splitting held halves into:4 :4.
4. Riff voicing, counter-melody, and harmony #
- Split 3-voice chords across separate channels: Put top, mid, and bottom chord voices on dedicated tracks and animate the bottom voice with
:16octave drops (A4:8 A3:16,B4:8 G3:16). - Add tracks instead of hijacking riff tracks: Keep 3-voice hooks running on
ch01..ch04when counter-melodies,:8echoes, bell doubles, and inner harmonies enter onch05..ch08. - Echo vs. double: Use
:16or:8delayed echoes only on sustained lyrical leads; use zero-delay stereo doubling (for example-0.18vs.+0.24pan) on fast syncopated chord stabs so echoes do not smear chord changes. - Harmonic palettes: Alternate Aeolian/Dorian vamps (
Am7 -> Fmaj7 | G), modal mixture (Cmajor with borrowedBb,Ab,Fm -> Gsus4 -> G), and neoclassical Phrygian/harmonic minor cadences (F -> Dm -> E7 -> Am). - Drum contrast: Avoid nonstop beat cymbals. Drop drums completely (
(R:1 |)*7) for atmospheric intros, enter via Beat 4 pickup rolls (R:2. (snare*3 kick):16 |), and vary every 4th/8th bar turnaround.
5. Voice-leading rules (ValidateScoreTheory) #
ValidateScoreTheory inspects all simultaneously sounding pitched voices:
- Allowed vertical intervals: Unisons, octaves, 3rds, 4ths, 5ths, 6ths, major 2nds/9ths (
diff == 2or14), tritones (diff == 6), minor 7ths (diff == 10), and major 7ths (diff == 11). Short passing/echo notes under0.25sare also permitted. - Forbidden vertical collisions:
- Sustained close minor 2nd (
diff == 1) when both notes last>= 0.25s. - Sustained flat 9th (
diff >= 13and(upper - lower)%12 == 1) when both last>= 0.30s(such asB2belowC5). - Simultaneous
Gnatural andG#/Abacross channels at any duration.
- Sustained close minor 2nd (
- Real voice-leading fixes:
- Hold pad notes until melody resolves: Keep low pads on
C3/E3while melody sustainsC5over aBbarline, then slide cleanly. - Isolate slow-tempo echo tails inside each measure: At
<= 100 BPM,:8notes exceed0.25s. Start echoes with a leading rest and release before the next bar (R:8 <lead>:2 R:8 <pickup>:4 |) so chromatic steps never bleed across barlines. - Common-tone pedal drones: Sustain only pitch classes shared by every chord in the progression (hold
C3, not[C3 G3], acrossCm -> Ab -> Fm -> G). On flat-VI chords (AbinCm), stick toAb,C,Eband avoidGnatural.
- Hold pad notes until melody resolves: Keep low pads on
