Mozaic gotchas

Below is a cheat sheet highlighting Mozaic’s key differences, limitations, and “gotchas” relative to typical coding or scripting languages. If you’re guiding other LLMs (or developers) who want to generate code for Mozaic, these are some of the most important points to emphasize.

1. Limited String Handling

No string variables: Mozaic doesn’t allow you to store strings in variables.
Cannot do string interpolation: You must log strings as constants in braces (e.g., Log {Hello}), or log numeric variables separately (e.g., Log var).
No concatenation: There is no built-in method to build dynamic strings.
Gotcha: This means you can’t do myString = "Hello " + name or myString = {"Hello "}{name} in Mozaic. You also cannot store a string from user input in a variable.

2. Unique Event Model with Labelled Blocks

Mozaic scripts revolve around specific event blocks, each labeled with @EventName:

@OnLoad (runs once when the script loads)
@OnKnobChange (fires whenever a knob changes)
@OnPadDown / @OnPadUp (for pad presses/releases)
@OnControlChange (handles incoming CC)
@OnNoteOn / @OnNoteOff (handles incoming MIDI notes)
@OnMetroPulse (fires in sync with the internal or host clock)
@OnTimer (fires on your custom interval timer)
…etc.
You can also create custom blocks labeled @MyFunction and call them with Call @MyFunction. This is how you define reusable functions.

Gotcha:

These blocks must be capitalized exactly right (e.g., @OnKnobChange not @onknobchange).
If you define a custom block as @Foo, you must call it with Call @Foo—not Foo().
3. Integer vs. Float

Mozaic supports numeric variables, which can be integers or floats.
Certain built-ins (like TranslateScale) behave differently if you use integer vs. float.
Many MIDI-related functions expect integer inputs (0–127 for CC or velocity, 0–16383 for pitchbend), but you can do floating-point arithmetic in between.
Gotcha: You have to ensure you don’t accidentally truncate floats when you want a decimal result. E.g., a = 3 / 2 might become 1 if both are integers; to force float, do a = 3.0 / 2 or something similar.

4. Syntax Quirks

No curly braces for blocks (like C or Java). Instead, you have if condition ... endif.
No return statements. You just Call @Function and execution returns at the end of that block.
No parentheses around conditions: You do if x = 0 ... endif, not if (x == 0) { ... }.
No “functions” with parameter lists: Everything is a labeled block. You can pass data by assigning global variables, then using Call @BlockName.
No separate “module” or “class” concept.
5. Logging & Debugging

You use Log to output to the console, not Print.
Log {SomeText} logs a string literal.
Log varName logs the numeric value of varName.
No string interpolation—log text and numeric values separately.
Gotcha: Trying Log {Value = } varName or Log varName {units} leads to syntax errors. You must separate them or omit the extra text.

6. Variable Declarations & Scope

Mozaic variables are implicitly declared the first time you use them. There’s no var or int keyword.
Everything is global scope by default, except local loop variables (For i = 0 to 10).
“Local functions” are effectively subroutines—no truly private variables.
Gotcha: If you misspell a variable in one place, Mozaic might treat it as a new variable, causing silent bugs.

7. Timers and Event Scheduling

SetTimerInterval ms sets the period in milliseconds.
StartTimer begins firing @OnTimer events; StopTimer halts them.
ResetTimer resets the timer count to zero.
@OnMetroPulse is a separate event that can sync with the host clock, often used for LFO or rhythmic tasks.
Gotcha: Don’t confuse the script-based timer (@OnTimer) with the DAW/host’s clock pulses (@OnMetroPulse). They’re different and can lead to timing discrepancies if you rely on them incorrectly.

8. Built-In Functions & Conventions

Mozaic has many built-in functions that are unique:

MIDI sending: SendMIDICC channel, cc, value, SendMIDINoteOn channel, note, velocity, SendMIDIPitchbend channel, value, etc.
LFO: SetupLFO index, offset, amplitude, sync, frequency, SetLFOType index, {Sine|Square|RampUp|...}, GetLFOValue index, etc.
Knob: GetKnobValue knobIndex, LabelKnob knobIndex, {LabelText}, etc.
Random: Random min,max returns a random integer in [min..max].
Gotcha: The arguments and uppercase/lowercase must match exactly, or you’ll get syntax errors (unknown or invalid argument). For example, SetLFOType 0, {Sine} works, but SetLFOType 0, {sine} might fail, or SendMIDICC 0, 7, velocity must be spelled exactly.

9. No Data Structures Beyond Arrays

Mozaic supports:

Single variables (global)
Arrays (1D lists accessed via myArray[index])
But there are no dictionaries, objects, or complex data structures. The arrays also have a fixed maximum size limit (defined in your script or using dynamic array creation).

Gotcha: You can’t create multi-dimensional arrays or nested objects. If an LLM tries to do myArray[ i ][ j ], it won’t compile in Mozaic.