MICROTONIC CUSHY-SKRIPTE - BESCHREIBUNG UND FUNKTIONSWEISE
Stand: 8. November 2026

======================================================================
ALLGEMEIN
======================================================================
Installation: Den jeweiligen Ordner (z. B. AutomationPainter.mtscript) in den
Microtonic-"Scripts"-Ordner legen und das Skript über das Scripts-Menü starten.
Die Skripte bestehen aus: <Name>.js (Starter), <Name>_main.cushy (Oberfläche),
<Name>_main.js (Logik), <Name>_main.schema (erlaubte Aktionen) und einer oder
mehreren .ivg-Dateien (Vektorgrafik des Spielfelds).

Technische Eckpunkte, die für alle Skripte gelten:
- Microtonic führt JavaScript als ECMAScript 3 aus. Es gibt dort keine Array-
  Methoden wie indexOf, map, forEach oder filter und kein Object.keys. Die Skripte
  verwenden deshalb nur ES3-Konstrukte.
- Der Zustand jedes Skripts liegt in einem globalen Objekt, dessen Name kleingeschrieben
  dem Skriptnamen entspricht (z. B. automationpainter). Die Oberfläche greift über
  @script.<name> darauf zu. Solange das Fenster geöffnet bleibt, bleibt der Zustand
  beim erneuten Laden des Skripts erhalten; beim Schließen des Fensters geht er verloren.
- Bedienung ausschließlich mit der Maus. Wo Parameter verändert werden (LissaMod,
  ElasticKaoss, PatchBreeder, AutomationPainter), geschieht das live über setParam.
- Alle Skripte wurden mit CushyLint und ESLint geprüft, die Grafiken mit IVG2PNG
  gerendert und die Logik gegen eine Nachbildung der Microtonic-API getestet.
  Ein Test in Microtonic selbst steht noch aus. Bitte Fehlermeldungen mit genauem
  Wortlaut und Skriptnamen melden.

======================================================================
NEU / GEÄNDERT IN DIESEM UPDATE
======================================================================
1) AutomationPainter v2 (siehe ausführliche Beschreibung unten)
   - Playhead-Fehler im Test halbiert (im Mittel 0,08 statt 0,16 Steps)
   - Parameter werden nur noch geschrieben, wenn sich der Wert ändert
   - Neu: UNDO (30 Stufen), SNAP (ganze Steps), REL (relativer Modus),
     4 Preset-Slots (SLOT / SAVE / LOAD), Lane-Marker, Live-Wertanzeige,
     Warnung bei doppeltem Ziel-Parameter
2) PacGroove: Fehlerbehebung. Die Funktion, die die vier Eckpunkte erkennt, benutzte
   Array.indexOf, das es in ES3 nicht gibt. Das hätte zur Laufzeit einen Fehler
   ausgelöst. Jetzt mit einer einfachen Schleife gelöst.

======================================================================
AUTOMATIONPAINTER v2  (Automation zeichnen)
======================================================================
Idee
  Mit der Maus Automationskurven für bis zu vier Parameter zeichnen. Die Kurven laufen
  synchron zum Pattern, solange Microtonic spielt.

Bedienung
  - LANE 1-4: wählt die Spur, auf die gemalt wird. Jede Spur hat eine eigene Farbe.
  - Auf der Fläche mit gedrückter Maus malen. Unten = 0, oben = 1, die Fläche ist eine
    Schleife über die Länge des gewählten Patterns (64 Spalten). Rechtsklick = Spur
    flach auf die Mitte (0,5) setzen.
  - PARAM: Parameter der Spur durchschalten (Morph, MastVol, OscFreq, OscDcy, ModAmt,
    ModRate, NFilFrq, NFilQ, NEnvDcy, Mix, DistAmt, EQFreq, EQGain, Level, Pan).
  - CH: Drum-Kanal der Spur (bei Morph / MastVol ohne Wirkung).
  - ON: Spur ein / aus. Malen schaltet eine Spur automatisch ein.
  - SHAPE: fertige Kurven (Rampe auf/ab, Dreieck, Sinus, Stufen, Zufall, flach).
  - SMOOTH: Kurve glätten.  CLEAR: Spur zurücksetzen und ausschalten.
  - UNDO: macht den letzten Strich, SHAPE, SMOOTH, CLEAR, Flatten oder LOAD rückgängig
    (30 Stufen).
  - SNAP: malt in ganzen Sequencer-Steps (treppenförmige Automation).
  - REL: relativer Modus. Die Kurve bewegt den Regler um den Wert herum, den er beim
    Start der Wiedergabe hatte. Mittellinie = unverändert.
  - SLOT / SAVE / LOAD: vier Preset-Plätze. Gespeichert werden alle vier Spuren
    (Kurven, Parameter, Kanal, REL) und der SNAP-Zustand.
  - Marker oben links: gefüllt = Spur läuft, mit Strich = relativ, Umriss = aus,
    Rahmen = aktive Spur.
  - Infozeile: zeigt die aktive Spur und während der Wiedergabe ihren aktuellen Wert.
    "(shared!)" erscheint, wenn zwei Spuren denselben Parameter ansteuern.

Funktionsweise
  - Jede Spur speichert 64 Werte zwischen 0 und 1. Beim Malen werden die Spalten
    zwischen zwei Mauspositionen linear gefüllt, damit schnelle Striche keine Lücken
    lassen.
  - Microtonic liefert nur ganze Steps (visuals.currentStep). Die Position zwischen
    den Steps schätzt das Skript aus der gemessenen Step-Dauer (geglättet). Eine
    Step-Änderung wird bis zu einen Tick zu spät bemerkt; das Skript rechnet das mit
    der halben Tick-Dauer heraus.
  - Während der Wiedergabe schreibt jede laufende Spur 30-mal pro Sekunde ihren Wert per
    setParam, aber nur, wenn er sich spürbar geändert hat.
  - Vor dem ersten Schreiben merkt sich das Skript den ursprünglichen Reglerwert jedes
    Parameters. Beim Stopp des Transports und beim Schließen des Fensters werden alle
    automatisierten Regler auf diese Werte zurückgesetzt.
  - Die Patterndaten werden nie angefasst.
  - Preset-Dateien liegen als JSON neben dem Skript:
    <Scripts-Ordner>/AutomationPainter.mtscript/AutomationPainter_slot1.json ... slot4.
    Wenn der Ordner nicht dort liegt, meldet die Infozeile "SAVE FAILED".

Hinweise
  - Der Playhead kann bei sehr abrupten Tempowechseln kurz hinterherhinken.
  - Zwei Spuren auf demselben Parameter überschreiben sich gegenseitig.

======================================================================
PACGROOVE  (Pac-Man spielt Drums)
======================================================================
Idee: Ein Labyrinth voller Punkte. Die Punktfarbe ist der Drum-Kanal (Labyrinth-
Spalten von links nach rechts = Kanal 1-8). Die vier großen Eckpunkte sind Akzente.
Bedienung: Maus bewegen, Pac-Man läuft den kürzesten Weg zur Zelle unter dem Zeiger.
Rechtsklick = Pause. NEW = neues Labyrinth, SPEED = Zugrate.
Funktionsweise: Jeder gefressene Punkt löst triggerChannel für seinen Kanal aus.
Punkte wachsen nach 6 s nach. Zwei Geister jagen Pac-Man; ein Biss schaltet 3 s stumm
(Pac-Man kann dann nicht fressen). Spielt Microtonic, zieht Pac-Man im Takt der Steps
(SPEED: ein Zug pro 2 Steps, pro Step oder 2 pro Step), sonst auf einem Timer. Das
Labyrinth wird per Tiefensuche erzeugt, danach werden einige Wände für Schleifen
entfernt. Pfade berechnet eine Breitensuche. Schreibt keine Patterns.

======================================================================
PENDULUMWAVE  (Pendelwelle)
======================================================================
Idee: Acht Pendel, eines pro Kanal. Pendel k schwingt pro Zyklus BASE+k Mal; sie
laufen auseinander und fallen einmal pro Zyklus wieder zusammen.
Bedienung: CYCLE (16/32/64/128 s), BASE (4/8/12/16 Schwingungen), SYNC (alle neu
starten, Unisono), HOLD (einfrieren). Klick auf ein Pendel = stumm, Rechtsklick =
alle wieder an.
Funktionsweise: Jeder Durchgang durch die Mitte löst triggerChannel aus. Die Längen
folgen der Physik (Länge ~ 1 / Schwingungen^2). Läuft ohne Transport, schreibt keine
Patterns.

======================================================================
PATCHBREEDER  (Sounds züchten)
======================================================================
Idee: Drum-Sounds per Zucht entwickeln. Die Mitte ist der Elternteil (aktueller Sound
des gewählten Kanals), außen 8 Mutanten.
Bedienung: Linksklick auf eine Kachel = vorhören (wird auf den Kanal geschrieben und
getriggert). Rechtsklick = von dieser Kachel weiterzüchten. REROLL = neue Mutanten,
REVERT = Ausgangssound, AMOUNT = Mutationsstärke (LOW/MID/HIGH), PING = Kanal triggern.
Funktionsweise: 12 Parameter werden mutiert (OscFreq, OscDcy, OscAtk, ModAmt, ModRate,
NFilFrq, NFilQ, NEnvDcy, Mix, DistAmt, EQFreq, EQGain), jede Kachel zeigt sie als
Balken. Level, Pan, Output, Choke und diskrete Schalter bleiben unberührt. Jede
Änderung erzeugt einen Undo-Punkt; beim Schließen bleibt der zuletzt gespielte Sound
auf dem Kanal.

======================================================================
ELASTICKAOSS  (XY-Pad mit Gummiband-Puck)
======================================================================
Idee: Ein Kaoss-Pad mit Physik. X und Y des Pucks steuern zwei Parameter des
gewählten Kanals.
Bedienung: ACTIVE einschalten, Puck mit gedrückter Maus ziehen (er hängt an einem
Gummiband und überschwingt). Loslassen: THROW = er fliegt weiter und prallt ab,
SNAP = er schnappt zur Mitte zurück (MODE). PAIR = Parameterpaar (Pitch/Noise-Filter,
Tone-/Noise-Decay, Mod Amount/Rate, Drive/EQ Freq). RANGE = Wirkungsbereich
(15/30/50 %). PING = Kanal triggern.
Funktionsweise: Feder-Dämpfer-Simulation. Die Mitte entspricht dem Sound beim
Einschalten. ACTIVE aus, Kanalwechsel oder Schließen stellen die Originalwerte wieder her.

======================================================================
PINBALLBEAT  (Flipper)
======================================================================
Idee: Acht Bumper sind die acht Kanäle; das Chaos der Kugel ist der Groove.
Bedienung: Linke / rechte Tischhälfte gedrückt halten = linker / rechter Flipper.
Klick = Kugel servieren (oder Neustart nach Game Over). Rechtsklick = Tisch anstoßen.
Funktionsweise: Jeder Bumper-Treffer löst triggerChannel aus, Velocity 60-127 je nach
Aufprallstärke. Die Flipper sind drehende Strecken; bei Kollision wird die
Geschwindigkeit des Kontaktpunkts zur Kugel addiert. Drei Kugeln pro Spiel.
Läuft ohne Transport, schreibt keine Patterns.

======================================================================
SNAKEBEAT  (Snake schreibt das Pattern)
======================================================================
Idee: Snake auf einem 8x16-Feld: Spalten = Kanäle, Zeilen = Steps.
Bedienung: Maus bewegen = die Schlange verfolgt die Zelle unter dem Zeiger. Klick =
ein Schritt Dash. Rechtsklick = Pause. NEW = neues Spiel.
Funktionsweise: Jeder gefressene Apfel schreibt die aktuelle Schlangenform ins
gewählte Pattern (Körper = Trigger, Kopf = Akzent). Die Wände umschließen das Feld
ringförmig. Das Skript berührt den Transport nicht; Play drückst du selbst.

======================================================================
LIFEGROOVE  (Game of Life als Pattern-Generator)
======================================================================
Idee: Conways Game of Life auf einem 8x16-Feld (Torus). Jede lebende Zelle ist ein
Trigger, Veteranen (ab 4 Generationen) werden Akzente.
Bedienung: Klick = Zelle umschalten. RUN, STEP, RANDOM, CLEAR.
Funktionsweise: Während Microtonic spielt, kommt pro Takt (beim Pattern-Umlauf) eine
neue Generation; im Stopp alle 0,6 s. Stirbt die Kolonie oder friert sie ein, werden
zufällige Funken gesetzt. Das Pattern wird bei jeder Generation geschrieben.

======================================================================
RADARPING  (Radar-Sequencer)
======================================================================
Idee: Ein Radar-Strahl rotiert; 8 Ringe = 8 Kanäle, der Winkel = Zeit.
Bedienung: Klick setzt einen Ping, nochmal = Akzent, nochmal = löschen. Rechtsklick =
alles löschen. SPEED, HOLD, RANDOM, CLEAR.
Funktionsweise: Überstreicht der Strahl einen Ping, wird triggerChannel ausgelöst
(Akzent = Velocity 127). Läuft ohne Transport, schreibt keine Patterns.

======================================================================
BEATBREAKER  (Breakout mit Drum-Kit)
======================================================================
Idee: Breakout; jede Stein-Spalte ist ein Kanal, die oberste Reihe ist Akzent.
Bedienung: Maus = Schläger, Klick = Ball starten, Rechtsklick = Pause.
Funktionsweise: Jeder zerstörte Stein löst triggerChannel aus (obere Reihen lauter).
Wird die Wand geräumt, kommt sie schneller zurück. Der Schläger lenkt den Ball je
nach Trefferpunkt ab, mit leichtem Zufall, damit der Ball nicht in einer Spalte hängt.

======================================================================
LISSAMOD  (Lissajous-LFO)
======================================================================
Idee: Ein Lissajous-Scope, dessen Punkt Pitch (horizontal, OscFreq) und Filter
(vertikal, NFilFrq) des gewählten Kanals moduliert.
Bedienung: ACTIVE, SHAPE (1:2, 2:3, 3:4, 3:5), DEPTH (0,25 / 0,5 / 1 Oktave),
RATE (0,1 / 0,25 / 0,5 / 1 Hz).
Funktionsweise: Modulation in Oktaven um die Reglerwerte beim Einschalten. Dreht man
einen der beiden Regler selbst, wird der neue Wert zur Mitte der Modulation.
Kanalwechsel, ACTIVE aus und Schließen stellen die Originalwerte wieder her.
