Upload 3 files

GEOMETRY_DASH_MIDI_PLAN.md

@@ -0,0 +1,96 @@
+# Geometry Dash Level Creation from MIDI Files - Design and Implementation Plan
+
+This document outlines the detailed plan, architecture, and mathematical mappings required to convert MIDI musical data into fully editable, playable Geometry Dash 2.11 custom levels.
+
+---
+
+## 1. Overview and Core Concept
+
+The goal of this system is to act as a **virtual piano roll** in Geometry Dash.
+- **Horizontal Axis (X-axis) represents Time**: The horizontal coordinate translates to the musical beats/tempo of the song. Longer music notes result in longer horizontal lines of blocks.
+- **Vertical Axis (Y-axis) represents Pitch**: Instead of spreading pitches sparsely across all 128 standard MIDI keys, the system extracts the **active pitches** from the MIDI, sorts them, and assigns them sequential Y-levels. Each consecutive unique pitch is separated by exactly **1 grid block (30 Y-units)**.
+- **Visual Feedback via 8-Color Hue Channels**: Blocks are mapped to Geometry Dash's native Color Channels `1` through `8` based on their pitch class (e.g., `pitch % 8` or `pitch_index % 8`), creating a beautiful, rainbow-colored piano roll.
+
+---
+
+## 2. Cryptography and Level Serialization
+
+### 2.1 Decrypting & Encrypting `CCLocalLevels.dat`
+In Windows, the Geometry Dash save file is located at:
+`%localappdata%\GeometryDash\CCLocalLevels.dat`
+
+The save file is encrypted with a custom algorithm. The decryption process in Python:
+1. **XOR Decryption**: Read file as bytes, and XOR each byte with `0x0B` (`11`).
+2. **Base64 Decode**: Convert URL-safe base64 characters (`-` and `_` to `+` and `/`), and pad the string with `=` so its length is a multiple of 4. Decode base64 bytes.
+3. **Gzip Decompression**: Decompress using standard Gzip/Zlib library. This yields a clean XML string (`<plist>...`).
+
+Encryption is the exact reverse process:
+1. **Gzip Compression**: Compress XML string with Gzip.
+2. **Base64 Encode**: Encode bytes to Base64 and replace standard base64 characters (`+` and `/` with `-` and `_`), stripping any trailing padding `=`.
+3. **XOR Encryption**: XOR each byte with `0x0B` (`11`) and write to disk.
+
+### 2.2 Level String Compression (`k4` Key)
+Within the `CCLocalLevels.dat` XML structure, a level is represented as a dictionary under key `<k>k_0</k>` (or other indices). Inside this level dictionary:
+- `<k>k2</k><s>[Level Name]</s>` represents the Level Name.
+- `<k>k4</k><s>[Level String]</s>` represents the actual object/setting data.
+- The `k4` value itself is a compressed level string. It is encrypted/compressed similarly to the save file (Base64 + Gzip) but **without** the initial XOR 11 key.
+- Once decompressed, the level string looks like:
+  `kS1,30,kS2,35,...;[Object 1];[Object 2];[Object 3];...`
+- The first segment (before the first `;`) defines the level settings/header. Semicolons `;` separate individual objects.
+
+---
+
+## 3. Level Coordinate & Object Mappings
+
+### 3.1 Object Anatomy
+Each object is a comma-separated key-value list. For our generated virtual piano roll, we will use the basic solid cube block:
+- **Object ID (`1`)**: Basic solid block = `1`.
+- **Keys**:
+  - `1`: Object ID (`1` for solid block)
+  - `2`: X Position (Units, where 1 grid square = 30 units)
+  - `3`: Y Position (Units, where 1 grid square = 30 units)
+  - `21`: Color Channel ID (`1` through `8`)
+  - `32`: Scale (`1.0`)
+
+Example Block: `1,1,2,300,3,450,21,3` (Solid block at X=300, Y=450 on Color Channel 3).
+
+### 3.2 Pitch to Y-Axis Mapping
+To make the level clean and playable:
+1. We parse the MIDI file and find all unique pitches used across all tracks.
+2. Let $P = [p_0, p_1, \dots, p_{n-1}]$ be the sorted list of these active MIDI pitches (where $p_0 < p_1 < \dots < p_{n-1}$).
+3. We set a baseline Y position (e.g., $Y_{\text{base}} = 15 \times 30 = 450$ units, representing 15 blocks high).
+4. Each pitch $p_i$ is mapped to:
+   $$Y(p_i) = Y_{\text{base}} + i \times 30 \text{ units}$$
+5. This guarantees that notes are stacked directly on top of each other with zero vertical gaps.
+
+### 3.3 Time/Beat to X-Axis Mapping
+1. A standard beat grid is defined. Let $B$ be the number of GD grid blocks per beat (quarter note). By default, we use $B = 2$ blocks per beat.
+2. In GD, 1 block = 30 units. Therefore, 1 beat = $30 \times B$ horizontal units (e.g., 60 units).
+3. Given a MIDI note starting at beat $t_{\text{start}}$ (in quarter notes) with a duration of $d$ beats:
+   - **X Start position**: $X_{\text{start}} = t_{\text{start}} \times B \times 30$ units.
+   - **Length in blocks**: $L = d \times B$.
+   - We place $\lceil L \rceil$ consecutive blocks side-by-side to construct a solid line representing the duration of the musical note.
+   - For example, if a note starts at beat 4 and lasts 3 beats, with $B=2$, it starts at $X = 4 \times 2 \times 30 = 240$ and spans $3 \times 2 = 6$ blocks (placing blocks at X=240, 270, 300, 330, 360, 390).
+
+### 3.4 Color Assignment
+Each block's color channel (from 1 to 8) is determined by its active pitch index:
+$$\text{Color Channel} = 1 + (i \pmod 8)$$
+This gives an elegant, repeating rainbow gradient corresponding to rising pitch heights.
+
+---
+
+## 4. Implementation Details (`midi_to_gd.py`)
+
+A fully-featured Python tool will be written. It will support:
+1. **MIDI Parsing**: Utilizing `mido` (and falling back to a custom lightweight parser or installing `mido` via pip in the user's environment).
+2. **Direct Save Insertion**: Decrypts the user's local `CCLocalLevels.dat`, inserts the newly generated level string, and re-encrypts the save file.
+3. **Alternative Exports**: Supports exporting a standalone decrypted XML level file or a base64 level string for manual importing.
+
+---
+
+## 5. Implementation Roadmap
+1. Write this design document (`GEOMETRY_DASH_MIDI_PLAN.md`).
+2. Implement `midi_to_gd.py` CLI script.
+3. Implement `test_midi_to_gd.py` test suite.
+4. Execute test suites and verify all cryptographical and mapping functionality works correctly.
+5. Deliver and document usage instructions.

midi_to_gd.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""
+MIDI to Geometry Dash Level Creator (GD 2.11)
+Parses a MIDI file and transforms music notes into horizontal lines of solid cube blocks
+aligned to beats and structured like a beautiful vertical virtual piano roll.
+"""
+
+import os
+import sys
+import base64
+import gzip
+import zlib
+import re
+import argparse
+import xml.etree.ElementTree as ET
+from typing import List, Dict, Tuple, Set, Optional
+
+# Attempt to import mido
+try:
+    import mido
+except ImportError:
+    print("Error: 'mido' library is required to parse MIDI files.")
+    print("Please install it using: pip install mido")
+    sys.exit(1)
+
+
+def xor_data(data: bytes, key: int = 11) -> bytes:
+    """XORs bytes with a given key (default: 11 / 0x0B)."""
+    return bytes([b ^ key for b in data])
+
+
+def decrypt_save_file(filepath: str) -> str:
+    """
+    Decrypts a standard Windows Geometry Dash CCLocalLevels.dat or CCGameManager.dat.
+    Algorithm: XOR 11 -> base64 decode (with url-safe correction) -> gzip decompress
+    """
+    with open(filepath, "rb") as f:
+        encrypted_data = f.read()
+
+    # Step 1: XOR with 11
+    xor_decrypted = xor_data(encrypted_data, 11)
+
+    # Step 2: Base64 decode with URL-safe replacement
+    # standard base64 replacements for URL safe decoding
+    b64_str = xor_decrypted.decode("utf-8", errors="ignore")
+    normalized_b64 = b64_str.replace("-", "+").replace("_", "/")
+    
+    # Add base64 padding if needed
+    padding_needed = len(normalized_b64) % 4
+    if padding_needed:
+        normalized_b64 += "=" * (4 - padding_needed)
+
+    compressed_bytes = base64.b64decode(normalized_b64.encode("utf-8"))
+
+    # Step 3: Gzip decompress
+    # Gzip uses header bytes, standard gzip decompression or zlib decompress (with wbits magic)
+    try:
+        decompressed_data = gzip.decompress(compressed_bytes)
+    except Exception:
+        # Sometimes zlib decompression with no header is needed if gzip.decompress fails
+        decompressed_data = zlib.decompress(compressed_bytes, -zlib.MAX_WBITS)
+
+    return decompressed_data.decode("utf-8", errors="ignore")
+
+
+def encrypt_save_file(xml_data: str) -> bytes:
+    """
+    Encrypts a clean XML plist into a CCLocalLevels.dat compatible format.
+    Algorithm: gzip compress -> base64 encode -> URL-safe replace -> XOR 11
+    """
+    # Step 1: Gzip compress
+    compressed = gzip.compress(xml_data.encode("utf-8"))
+
+    # Step 2: Base64 encode
+    b64_encoded = base64.b64encode(compressed).decode("utf-8")
+
+    # Step 3: URL safe replace
+    url_safe_b64 = b64_encoded.replace("+", "-").replace("/", "_")
+
+    # Strip padding
+    url_safe_b64 = url_safe_b64.rstrip("=")
+
+    # Step 4: XOR with 11
+    encrypted_bytes = xor_data(url_safe_b64.encode("utf-8"), 11)
+    return encrypted_bytes
+
+
+def decrypt_level_string(level_string: str) -> str:
+    """
+    Decrypts the actual object string inside the level string (<k>k4</k>).
+    This string is NOT XORed, only Base64 decoded -> gzip decompressed.
+    """
+    normalized = level_string.replace("-", "+").replace("_", "/")
+    padding_needed = len(normalized) % 4
+    if padding_needed:
+        normalized += "=" * (4 - padding_needed)
+
+    compressed_bytes = base64.b64decode(normalized.encode("utf-8"))
+    try:
+        decompressed = gzip.decompress(compressed_bytes)
+    except Exception:
+        decompressed = zlib.decompress(compressed_bytes, -zlib.MAX_WBITS)
+    return decompressed.decode("utf-8", errors="ignore")
+
+
+def encrypt_level_string(decrypted_level: str) -> str:
+    """
+    Encrypts the decrypted object string back into the standard compressed k4 level string format.
+    """
+    compressed = gzip.compress(decrypted_level.encode("utf-8"))
+    b64_encoded = base64.b64encode(compressed).decode("utf-8")
+    return b64_encoded.replace("+", "-").replace("/", "_").rstrip("=")
+
+
+class MIDINote:
+    def __init__(self, pitch: int, start_time: float, end_time: float, velocity: int):
+        self.pitch = pitch
+        self.start_time = start_time  # in seconds or beats
+        self.end_time = end_time      # in seconds or beats
+        self.velocity = velocity
+
+    @property
+    def duration(self) -> float:
+        return self.end_time - self.start_time
+
+
+def parse_midi_notes(midi_path: str) -> List[MIDINote]:
+    """
+    Parses a MIDI file and extracts all note-on/note-off events,
+    converting times to beats (quarter notes).
+    """
+    mid = mido.MidiFile(midi_path)
+    ticks_per_beat = mid.ticks_per_beat
+    notes: List[MIDINote] = []
+
+    # Map tracking currently active note starts per channel and pitch
+    # key: (channel, pitch), value: (start_beat, velocity)
+    active_notes: Dict[Tuple[int, int], Tuple[float, int]] = {}
+
+    for track in mid.tracks:
+        current_ticks = 0
+        for msg in track:
+            current_ticks += msg.time
+            # Convert ticks to beats (quarter notes)
+            current_beat = current_ticks / ticks_per_beat
+
+            if msg.type == 'note_on' and msg.velocity > 0:
+                key = (msg.channel, msg.note)
+                # If note was already active (rare without note_off), close it first
+                if key in active_notes:
+                    start_beat, vel = active_notes.pop(key)
+                    notes.append(MIDINote(msg.note, start_beat, current_beat, vel))
+                active_notes[key] = (current_beat, msg.velocity)
+
+            elif msg.type == 'note_off' or (msg.type == 'note_on' and msg.velocity == 0):
+                key = (msg.channel, msg.note)
+                if key in active_notes:
+                    start_beat, vel = active_notes.pop(key)
+                    # Add note if duration is greater than 0
+                    if current_beat > start_beat:
+                        notes.append(MIDINote(msg.note, start_beat, current_beat, vel))
+
+    # Close any notes that remained active until the end of the track
+    # Use max length as end point
+    max_beat = max([n.end_time for n in notes]) if notes else 100.0
+    for (channel, pitch), (start_beat, vel) in active_notes.items():
+        if max_beat > start_beat:
+            notes.append(MIDINote(pitch, start_beat, max_beat, vel))
+
+    return notes
+
+
+def generate_gd_level_objects(notes: List[MIDINote], blocks_per_beat: float = 2.0) -> str:
+    """
+    Translates a list of MIDI notes into a string of Geometry Dash level objects.
+    Each unique pitch is mapped to a unique vertical lane.
+    Returns: The raw, decompressed object string.
+    """
+    if not notes:
+        return ""
+
+    # 1. Identify all unique pitches and sort them to assign Y coordinates
+    unique_pitches = sorted(list(set(note.pitch for note in notes)))
+    pitch_to_y_index = {pitch: i for i, pitch in enumerate(unique_pitches)}
+
+    # Base coordinates:
+    # 1 grid unit in GD = 30 units
+    # Start baseline height at Y = 15 blocks (450 units)
+    y_base = 15 * 30
+    x_offset = 10 * 30  # Start building 10 blocks into the level to give the player a safe start
+
+    objects: List[str] = []
+
+    # Format of an object: "key,value,key,value..."
+    # 1: ObjID (1 = Solid Cube Block)
+    # 2: X position
+    # 3: Y position
+    # 21: Color Channel
+    for note in notes:
+        y_index = pitch_to_y_index[note.pitch]
+        y_pos = y_base + y_index * 30
+
+        # Calculate time-to-X coordinates
+        start_x = x_offset + (note.start_time * blocks_per_beat) * 30
+        duration_blocks = note.duration * blocks_per_beat
+
+        # Determine number of blocks to place to span the duration of the note
+        # Always place at least 1 block
+        num_blocks = max(1, int(round(duration_blocks)))
+
+        # Assign color channel (1 through 8) based on pitch index
+        color_channel = 1 + (y_index % 8)
+
+        # Place the blocks horizontally side-by-side
+        for b in range(num_blocks):
+            block_x = start_x + b * 30
+            # Basic Solid Cube Block format: obj_id,1, x,block_x, y,y_pos, color_channel,color_channel
+            # Form: 1,1,2,block_x,3,y_pos,21,color_channel
+            obj_str = f"1,1,2,{block_x:.1f},3,{y_pos:.1f},21,{color_channel}"
+            objects.append(obj_str)
+
+    # Combine all objects separated by semicolons
+    return ";".join(objects) + ";"
+
+
+def build_full_level_string(objects_string: str) -> str:
+    """
+    Prepends standard level header/settings to the objects string.
+    """
+    # Standard GD 2.11 empty level header
+    header = "kS1,30,kS2,35,kS3,41,kS4,115,kS5,115,kS6,115,kS7,0,kS8,0,kS9,0,kS10,0,kS11,0,kS12,0,kS13,0,kS14,0,kS15,0,kS16,0,kS17,0,kS18,0,kS19,0,kS20,0,kS22,1,kS23,1,kS24,1,kS25,1,kS26,1,kS27,1,kS28,1,kS29,1,kS30,1,kS31,1,kS32,1,kS33,1,kS34,1,kS35,1,kS36,1,kS37,1,kS38,1,kS39,1,kS40,1,kS41,1,kS42,1,kS43,1,kS44,1,kS45,1,kS46,1,kS47,1,kS48,1,kS49,1,kS50,1,kS51,1,kS52,1,kS53,1,kS54,1,kS55,1,kS56,1,kS57,1,kS58,1,kS59,1,kS60,1,kS61,1,kS62,1,kS63,1,kS64,1,kS65,1,kS66,1,kS67,1,kS68,1,kS69,1,kS70,1,kS71,1,kS72,1,kS73,1,kS74,1,kS75,1,kS76,1,kS77,1,kS78,1,kS79,1,kS80,1,kS81,1,kS82,1,kS83,1,kS84,1,kS85,1,kS86,1,kS87,1,kS88,1,kS89,1,kS90,1,kS91,1,kS92,1,kS93,1,kS94,1,kS95,1,kS96,1,kS97,1,kS98,1,kS99,1,kS100,1,kS101,1,kS102,1,kS103,1,kS104,1,kS105,1,kS106,1,kS107,1,kS108,1,kS109,1,kS110,1,kS111,1,kS112,1,kS113,1,kS114,1,kS115,1,kS116,1,kS117,1,kS118,1,kS119,1,kS120,1,kS121,1,kS122,1,kS123,1,kS124,1,kS125,1,kS126,1,kS127,1,kS128,1,kS129,1,kS130,1,kS131,1,kS132,1,kS133,1,kS134,1,kS135,1,kS136,1,kS137,1,kS138,1,kS139,1,kS140,1,kS141,1,kS142,1,kS143,1,kS144,1,kS145,1,kS146,1,kS147,1,kS148,1,kS149,1,kS150,1,kS151,1,kS152,1,kS153,1,kS154,1,kS155,1,kS156,1,kS157,1,kS158,1,kS159,1,kS160,1,kS161,1,kS162,1,kS163,1,kS164,1,kS165,1,kS166,1,kS167,1,kS168,1,kS169,1,kS170,1,kS171,1,kS172,1,kS173,1,kS174,1,kS175,1,kS176,1,kS177,1,kS178,1,kS179,1,kS180,1,kS181,1,kS182,1,kS183,1,kS184,1,kS185,1,kS186,1,kS187,1,kS188,1,kS189,1,kS190,1,kS191,1,kS192,1,kS193,1,kS194,1,kS195,1,kS196,1,kS197,1,kS198,1,kS199,1,kS200,1,kA1,0,kA2,0,kA3,0,kA4,0,kA5,0,kA6,0,kA7,0,kA8,0,kA9,0,kA10,0,kA11,0,kA12,0,kA13,0,kA14,0,kA15,0,kA16,0,kA17,0,kA18,0,kA19,0,kA20,0"
+    return header + ";" + objects_string
+
+
+def insert_level_into_save(save_path: str, level_name: str, raw_objects_string: str):
+    """
+    Decrypts the local levels save file, parses the XML, appends/inserts the new level,
+    and saves/encrypts it back to CCLocalLevels.dat.
+    """
+    print(f"Reading and decrypting save file from {save_path}...")
+    decrypted_xml = decrypt_save_file(save_path)
+
+    # Standard clean level string creation
+    full_level_data = build_full_level_string(raw_objects_string)
+    encrypted_k4 = encrypt_level_string(full_level_data)
+
+    # Build XML dictionary block for this level
+    # Inside CCLocalLevels, the level map contains levels like k_0, k_1 etc under LLM_01 <d>
+    # We will search for <k>LLM_01</k> and insert our level dictionary under its children
+    print("Parsing save file structure...")
+    
+    # We use regex/string manipulation to insert cleanly to avoid XML namespace/formatting problems
+    # Finding the main dict under LLM_01: `<k>LLM_01</k><d><k>_isArr</k><t />`
+    match = re.search(r"<k>LLM_01</k><d><k>_isArr</k><t />", decrypted_xml)
+    if not match:
+        raise ValueError("Could not locate active levels dictionary (LLM_01) in save file.")
+
+    # Build a beautiful, minimal level dict structure
+    new_level_id = f"k_{int(time_hash()) % 100000}"
+    new_level_xml = f"""<k>{new_level_id}</k><d><k>kCEK</k><i>4</i><k>k2</k><s>{level_name}</s><k>k3</k><s>Converted MIDI Piano Roll</s><k>k4</k><s>{encrypted_k4}</s><k>k5</k><s>Player</s><k>k13</k><t /><k>k21</k><i>2</i><k>k16</k><i>1</i><k>k80</k><i>1</i></d>"""
+
+    insert_point = match.end()
+    modified_xml = decrypted_xml[:insert_point] + new_level_xml + decrypted_xml[insert_point:]
+
+    print(f"Successfully inserted '{level_name}' into decrypted XML.")
+    
+    # Re-encrypt
+    print("Encrypting save data...")
+    encrypted_bytes = encrypt_save_file(modified_xml)
+
+    # Backup the original CCLocalLevels.dat
+    backup_path = save_path + ".bak"
+    if not os.path.exists(backup_path):
+        os.rename(save_path, backup_path)
+        print(f"Created a safe backup of your save file at: {backup_path}")
+
+    # Write back the newly encrypted save file
+    with open(save_path, "wb") as f:
+        f.write(encrypted_bytes)
+    print("Save file successfully updated and re-encrypted!")
+
+
+def time_hash() -> str:
+    import time
+    return str(int(time.time()))
+
+
+def get_default_save_path() -> str:
+    """Returns the default Windows path for CCLocalLevels.dat."""
+    if sys.platform == "win32":
+        return os.path.join(os.environ["LOCALAPPDATA"], "GeometryDash", "CCLocalLevels.dat")
+    elif sys.platform == "darwin":
+        return os.path.expanduser("~/Library/Application Support/GeometryDash/CCLocalLevels.dat")
+    else:
+        return ""
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Convert MIDI file to standard Geometry Dash solid piano roll levels.")
+    parser.add_argument("midi", help="Path to the source .mid or .midi file")
+    parser.add_argument("-n", "--name", help="Name of the generated level (defaults to MIDI file name)")
+    parser.add_argument("-b", "--beats-scale", type=float, default=2.0, help="Blocks per beat/quarter note (default: 2.0)")
+    parser.add_argument("-s", "--save-file", help="Path to your CCLocalLevels.dat to inject directly into the game")
+    parser.add_argument("-e", "--export-string", action="store_true", help="Print/export the raw level string instead of updating save file")
+    
+    args = parser.parse_args()
+
+    if not os.path.exists(args.midi):
+        print(f"Error: MIDI file '{args.midi}' not found.")
+        sys.exit(1)
+
+    print(f"Parsing MIDI file: {args.midi}...")
+    try:
+        notes = parse_midi_notes(args.midi)
+    except Exception as e:
+        print(f"Error parsing MIDI file: {e}")
+        sys.exit(1)
+
+    print(f"Extracted {len(notes)} musical notes successfully.")
+
+    print("Generating block layout...")
+    raw_objects = generate_gd_level_objects(notes, args.beats_scale)
+    
+    level_name = args.name if args.name else os.path.splitext(os.path.basename(args.midi))[0]
+
+    if args.export_string:
+        full_level_data = build_full_level_string(raw_objects)
+        encrypted_k4 = encrypt_level_string(full_level_data)
+        print("\n--- Encrypted level string (k4 format) ---")
+        print(encrypted_k4)
+        print("------------------------------------------")
+        return
+
+    # Direct Injection Mode
+    save_path = args.save_file if args.save_file else get_default_save_path()
+
+    if not save_path or not os.path.exists(save_path):
+        print("\nCould not automatically locate CCLocalLevels.dat.")
+        print("Please provide the correct path to CCLocalLevels.dat using the -s/--save-file option.")
+        print("Or run with -e/--export-string to get the raw level data string.")
+        
+        # Still generate a standalone file for the user
+        standalone_out = f"{level_name}.gmd"
+        full_level_data = build_full_level_string(raw_objects)
+        encrypted_k4 = encrypt_level_string(full_level_data)
+        
+        # Build standard gmd plist file
+        gmd_content = f"""<?xml version="1.0"?>
+<plist version="1.0" gjver="2.0">
+    <dict>
+        <key>kCEK</key><i>4</i>
+        <key>k2</key><s>{level_name}</s>
+        <key>k3</key><s>MIDI converted Piano Roll</s>
+        <key>k4</key><s>{encrypted_k4}</s>
+        <key>k5</key><s>Player</s>
+    </dict>
+</plist>"""
+        with open(standalone_out, "w", encoding="utf-8") as f:
+            f.write(gmd_content)
+        print(f"\nSaved standalone importable level to: {standalone_out}")
+        print("You can import this .gmd file using standard GD editors/overlays.")
+    else:
+        try:
+            insert_level_into_save(save_path, level_name, raw_objects)
+        except Exception as e:
+            print(f"Error inserting level into save file: {e}")
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

test_midi_to_gd.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Unit and Integration Tests for midi_to_gd.py
+"""
+
+import os
+import unittest
+import zlib
+import base64
+import gzip
+import xml.etree.ElementTree as ET
+
+# Import functions from midi_to_gd
+from midi_to_gd import (
+    xor_data,
+    decrypt_save_file,
+    encrypt_save_file,
+    decrypt_level_string,
+    encrypt_level_string,
+    MIDINote,
+    generate_gd_level_objects,
+    build_full_level_string
+)
+
+
+class TestGeometryDashMIDICreator(unittest.TestCase):
+
+    def test_xor_data(self):
+        """Test that XOR data function behaves symmetrically."""
+        original = b"Hello, Geometry Dash!"
+        encrypted = xor_data(original, 11)
+        decrypted = xor_data(encrypted, 11)
+        self.assertEqual(original, decrypted)
+
+    def test_level_string_cryptography(self):
+        """Test symmetric encryption/decryption of the level string (<k>k4</k> format)."""
+        decrypted_original = "kS1,30,kS2,35;1,1,2,300,3,450,21,1;"
+        encrypted = encrypt_level_string(decrypted_original)
+        decrypted_back = decrypt_level_string(encrypted)
+        self.assertEqual(decrypted_original, decrypted_back)
+
+    def test_midi_to_gd_objects_mapping(self):
+        """Test converting MIDINotes to actual Geometry Dash object layout strings."""
+        notes = [
+            MIDINote(pitch=60, start_time=0.0, end_time=1.0, velocity=100),  # 1 beat
+            MIDINote(pitch=64, start_time=1.0, end_time=3.0, velocity=100),  # 2 beats
+        ]
+        
+        # 2 blocks per beat
+        raw_objects = generate_gd_level_objects(notes, blocks_per_beat=2.0)
+        
+        # Split objects
+        obj_list = [o for o in raw_objects.split(";") if o]
+        
+        # Pitch 60 (C4) and Pitch 64 (E4) are unique pitches. Sorted: [60, 64]
+        # pitch 60 is index 0 -> color channel 1, Y coordinate = 450
+        # pitch 64 is index 1 -> color channel 2, Y coordinate = 480
+        
+        # Check count of blocks:
+        # Note 1: 1 beat duration * 2 blocks/beat = 2 blocks
+        # Note 2: 2 beats duration * 2 blocks/beat = 4 blocks
+        self.assertEqual(len(obj_list), 6)
+        
+        # Verify first note block format
+        first_block = obj_list[0]
+        self.assertIn("1,1", first_block)  # obj id
+        self.assertIn("3,450.0", first_block)  # Y coordinate
+        self.assertIn("21,1", first_block)  # Color Channel 1
+        
+        # Verify note 2 block format
+        third_block = obj_list[2]
+        self.assertIn("1,1", third_block)  # obj id
+        self.assertIn("3,480.0", third_block)  # Y coordinate
+        self.assertIn("21,2", third_block)  # Color Channel 2
+
+    def test_full_level_string_builder(self):
+        """Test build_full_level_string combines correctly."""
+        raw_objects = "1,1,2,300,3,450,21,1;"
+        full_string = build_full_level_string(raw_objects)
+        self.assertTrue(full_string.startswith("kS1,30"))
+        self.assertTrue(full_string.endswith(raw_objects))
+
+
+if __name__ == "__main__":
+    unittest.main()