engine.js

// =============================================================================
// engine.js — Polyrhythmic Step Sequencer Engine for Max for Live
// =============================================================================
//
// Lives inside a [js engine.js] object in a Max for Live MIDI Effect device.
//
// INLETS
//   0 — clock ticks (bang), and all message-based control
//
// OUTLETS
//   0 — MIDI note output: [note, velocity] pairs → connect to [makenote] → [noteout]
//   1 — track playhead positions: [trackIdx, currentStep] → GUI / Push visualization
//   2 — loop region: [start, end] (-1, -1 = no loop override) → GUI / Push
//   3 — step data dump: [trackIdx, stepIdx, active, velocity, probability] → GUI init
//   4 — track data dump: [trackIdx, length, midiNote, muted] → GUI init
//
// MESSAGES (all sent to inlet 0)
//   bang                               — clock tick (advance and fire)
//   tick                               — same as bang, explicit form
//   jumpToStep <step>                  — snap all tracks to step (0-indexed)
//   setLoop <start> <end>              — define loop override region
//   clearLoop                          — release loop override
//   setStepActive <t> <s> <0|1>        — toggle a step on/off
//   setStepVelocity <t> <s> <0-127>    — set step velocity
//   setStepProbability <t> <s> <0-100> — set step fire probability
//   setTrackLength <t> <1-16>          — set natural loop length for track t
//   setTrackMute <t> <0|1>             — mute/unmute a track
//   setTrackNote <t> <0-127>           — reassign MIDI note for track t
//   reset                              — reset all playheads to step 0
//   getFullState                       — dump all state to outlets 3 and 4
//
// ARCHITECTURE NOTE
//   Each track has a natural loop length (1–16). In free mode, tracks advance
//   independently: track.currentStep = (track.currentStep + 1) % track.length
//   This creates polyrhythm — a track with length 3 cycles ~5x while a 16-step
//   track completes once.
//
//   When a loop override is set (loopStart / loopEnd), ALL tracks are constrained
//   to that region regardless of their natural length. This is the live performance
//   tool: define a subregion on the Push pads to lock everything into a loop.
//   Clear the override to release tracks back to their independent lengths.
//
// =============================================================================

inlets  = 1;
outlets = 5;

var NUM_TRACKS = 8;
var NUM_STEPS  = 16;

// Default MIDI notes: maps to standard Ableton drum rack pad layout
// C1=36 (Kick), C#1=37 (Snare), D1=38 (Clap), D#1=39 (HH Closed),
// E1=40 (HH Open), F1=41 (Tom Lo), F#1=42 (Tom Hi), G1=43 (Perc)
var DEFAULT_NOTES = [36, 37, 38, 39, 40, 41, 42, 43];
var TRACK_NAMES   = ["Kick", "Snare", "Clap", "HH Closed", "HH Open", "Tom Lo", "Tom Hi", "Perc"];

// ─── Data Structures ──────────────────────────────────────────────────────────

function makeStep() {
    return {
        active:      false,
        velocity:    100,   // 0–127
        probability: 100    // 0–100 (100 = always fires)
    };
}

function makeTrack(midiNote, name) {
    var steps = [];
    for (var i = 0; i < NUM_STEPS; i++) {
        steps.push(makeStep());
    }
    return {
        steps:       steps,
        length:      NUM_STEPS,  // natural loop length (1–16)
        currentStep: 0,
        midiNote:    midiNote,
        name:        name,
        muted:       false
    };
}

// ─── Global State ─────────────────────────────────────────────────────────────

var tracks = [];
for (var i = 0; i < NUM_TRACKS; i++) {
    tracks.push(makeTrack(DEFAULT_NOTES[i], TRACK_NAMES[i]));
}

var loopStart = null;   // null = no loop override active
var loopEnd   = null;

// ─── Clock / Tick ─────────────────────────────────────────────────────────────

// Called when a bang arrives on inlet 0 (from metro synced to transport)
function bang() {
    tick();
}

function tick() {
    // 1. Fire notes for the current step position of each track
    for (var i = 0; i < NUM_TRACKS; i++) {
        var track = tracks[i];
        if (track.muted) continue;

        var step = track.steps[track.currentStep];
        if (step.active) {
            // Probability gate: roll 0–99, fire if roll < probability
            var roll = Math.floor(Math.random() * 100);
            if (roll < step.probability) {
                outlet(0, track.midiNote, step.velocity);
            }
        }
    }

    // 2. Broadcast current playhead positions (for GUI and Push LED update)
    sendPlayheadState();

    // 3. Advance all step counters
    advanceSteps();
}

function advanceSteps() {
    for (var i = 0; i < NUM_TRACKS; i++) {
        var track = tracks[i];

        if (loopStart !== null && loopEnd !== null) {
            // Loop override: all tracks cycle within [loopStart, loopEnd]
            var regionLen = loopEnd - loopStart + 1;
            track.currentStep = loopStart + ((track.currentStep - loopStart + 1) % regionLen);
        } else {
            // Free mode: each track loops at its own natural length
            track.currentStep = (track.currentStep + 1) % track.length;
        }
    }
}

// ─── Performance Controls ─────────────────────────────────────────────────────

// Snap all track playheads to a specific step immediately.
// Used by Push pad taps for live playhead jumping.
function jumpToStep(step) {
    step = clamp(Math.floor(step), 0, NUM_STEPS - 1);
    for (var i = 0; i < NUM_TRACKS; i++) {
        tracks[i].currentStep = step;
    }
    sendPlayheadState();
    sendLoopState();
}

// Define a loop override region. All tracks will be constrained here
// regardless of their natural length. Order of start/end doesn't matter.
function setLoop(start, end) {
    // Allow either order (useful for two-finger hold gesture on Push)
    if (start > end) {
        var tmp = start;
        start = end;
        end = tmp;
    }
    loopStart = clamp(Math.floor(start), 0, NUM_STEPS - 1);
    loopEnd   = clamp(Math.floor(end),   0, NUM_STEPS - 1);

    // Clamp any out-of-region playheads to the loop start
    for (var i = 0; i < NUM_TRACKS; i++) {
        var cs = tracks[i].currentStep;
        if (cs < loopStart || cs > loopEnd) {
            tracks[i].currentStep = loopStart;
        }
    }
    sendPlayheadState();
    sendLoopState();
}

// Release the loop override. Tracks return to independent natural lengths.
function clearLoop() {
    loopStart = null;
    loopEnd   = null;
    sendLoopState();
}

// Reset all playheads to step 0.
function reset() {
    for (var i = 0; i < NUM_TRACKS; i++) {
        tracks[i].currentStep = 0;
    }
    sendPlayheadState();
}

// ─── Grid Input (from matrixctrl via "prepend grid") ─────────────────────────

// Called when the user clicks the step grid in the GUI.
// matrixctrl outputs [col, row, val] where col=stepIdx, row=trackIdx.
// "prepend grid" turns this into the message: grid col row val
function grid(col, row, val) {
    setStepActive(row, col, val);   // val is 0 or 1 from matrixctrl; let setStepActive convert
}

// ─── Step Editing ─────────────────────────────────────────────────────────────

function setStepActive(trackIdx, stepIdx, active) {
    if (!validStep(trackIdx, stepIdx)) return;
    tracks[trackIdx].steps[stepIdx].active = (active !== 0);
}

function setStepVelocity(trackIdx, stepIdx, velocity) {
    if (!validStep(trackIdx, stepIdx)) return;
    tracks[trackIdx].steps[stepIdx].velocity = clamp(Math.floor(velocity), 0, 127);
}

function setStepProbability(trackIdx, stepIdx, prob) {
    if (!validStep(trackIdx, stepIdx)) return;
    tracks[trackIdx].steps[stepIdx].probability = clamp(Math.floor(prob), 0, 100);
}

// ─── Track Configuration ──────────────────────────────────────────────────────

function setTrackLength(trackIdx, length) {
    if (!validTrack(trackIdx)) return;
    var track = tracks[trackIdx];
    track.length = clamp(Math.floor(length), 1, NUM_STEPS);
    // If playhead is now out of range, wrap it
    if (track.currentStep >= track.length) {
        track.currentStep = track.currentStep % track.length;
    }
    sendPlayheadState();
}

function setTrackMute(trackIdx, muted) {
    if (!validTrack(trackIdx)) return;
    tracks[trackIdx].muted = (muted !== 0);
}

function setTrackNote(trackIdx, note) {
    if (!validTrack(trackIdx)) return;
    tracks[trackIdx].midiNote = clamp(Math.floor(note), 0, 127);
}

// ─── State Output ─────────────────────────────────────────────────────────────

// Outlet 1: current playhead position for each track
function sendPlayheadState() {
    for (var i = 0; i < NUM_TRACKS; i++) {
        outlet(1, i, tracks[i].currentStep);
    }
}

// Outlet 2: current loop region (-1, -1 means no override)
function sendLoopState() {
    outlet(2,
        loopStart !== null ? loopStart : -1,
        loopEnd   !== null ? loopEnd   : -1
    );
}

// Outlets 3 and 4: full state dump (called on device load / GUI init)
//
// Outlet 3 sends [col, row, val] = [stepIdx, trackIdx, active]
// This format feeds directly into matrixctrl without conversion.
//
// Outlet 4 sends [trackIdx, length, midiNote, muted]
// Used to restore track length numboxes and mute toggles.
function getFullState() {
    for (var i = 0; i < NUM_TRACKS; i++) {
        var track = tracks[i];
        // Per-step data — col=stepIdx, row=trackIdx, val=active
        for (var j = 0; j < NUM_STEPS; j++) {
            var s = track.steps[j];
            outlet(3, j, i, s.active ? 1 : 0);
        }
        // Per-track data
        outlet(4, i, track.length, track.midiNote, track.muted ? 1 : 0);
    }
    sendPlayheadState();
    sendLoopState();
}

// ─── Utilities ────────────────────────────────────────────────────────────────

function clamp(val, lo, hi) {
    return Math.max(lo, Math.min(hi, val));
}

function validTrack(t) {
    return t >= 0 && t < NUM_TRACKS;
}

function validStep(t, s) {
    return validTrack(t) && s >= 0 && s < NUM_STEPS;
}