ALWAYS call this tool first, before any other, when composing a game track. Creates an empty project where layers (independent channels: melody, harmony, bass, drums) are added one by one via add_layer. Each layer may have a completely different length and rhythm from the others (e.g. a 4-note bass loop while the melody plays a 32-note phrase), matching how independent channels work on real NES/SNES hardware.

Use this tool BEFORE composing any melody, harmony, or bass line. It maps the scene's EMOTION/MOOD to the technically correct musical scale (VGM theory: major = joy/safe town, dorian = heroic/adventure, phrygian = hostile/exotic, natural_minor = melancholy/dungeon, mixolydian = folk/open road, lydian = magical/dreamlike, minor_pentatonic = tension/combat).

Accepted moods: safe_exploration, heroic_exploration, nostalgic_town, melancholic_dungeon, hostile_exotic_biome, magical_dreamlike, combat, victory, classic_retro.

Returns the chosen scale AND a list of MIDI pitches ready for add_layer — no need to invent note numbers from memory.

Generate the correct MIDI notes for a musical scale, to use as a palette of valid pitches when composing. Use this tool (or suggest_scale_for_mood) ALWAYS before inventing note numbers manually — that avoids out-of-key / random-sounding melodies.

scale_type accepts: major, natural_minor, major_pentatonic, minor_pentatonic, dorian, mixolydian, phrygian, lydian.

Add ONE independent layer/channel to the project. Call this tool multiple times to stack as many layers as you want (melody, harmony, bass, drums) — each layer has its own length and rhythm, without needing to match the others in note count.

layer_type accepts: 'melody', 'harmony', 'bass', 'drums'.

Format of 'notes': each item is [pitch_or_piece, start_time_in_beats, duration_in_beats, optional_velocity_0_to_127]. If layer_type='drums', pitch may be a string ('kick', 'snare', 'closed_hihat', 'open_hihat', 'crash', 'ride', 'clap', 'rimshot', 'low_tom', 'mid_tom', 'high_tom') or a GM percussion MIDI number. Portuguese drum names are also accepted.

swing_offset: add a fixed offset (in beats, e.g. 0.02 to 0.08) to every ODD-index note, simulating light swing/humanization. Use 0.0 for straight quantized rhythm (classic chiptune aesthetic). For deliberate off-beats (e.g. hi-hat on 0.5, 1.5, 2.5), place start_time directly in the notes list — no swing_offset needed.

chiptune_program (ignored if layer_type='drums'): 'pulse_lead' (melody, NES pulse timbre, GM 80), 'pulse_harmony' (countermelody, GM 81), 'triangle_bass' (bass, NES triangle approx, GM 38).

Schedule a tempo (BPM) change at a specific absolute beat. Use for horizontal resequencing inside a single file — e.g. speed up when entering boss phase 2, or slow down for tension before a climax.

List all layers already added to the project, with note counts and duration for each. Use before export_midi to verify that every planned layer (melody, bass, drums, harmony) was actually added, or to decide whether to add more.

Render all project layers into a single multi-track .mid file. Call last, after all add_layer calls. Returns loop metadata (beats and bars) for configuring loop points in the engine (Godot/Unity/ FMOD/Wwise), since MIDI does not store that natively.

Default destination_dir is assets/midi/ (or NOBU_MIDI_DIR).