melon-lua 3.4.0__py3-none-any.whl

melon_lua/melsave_builder.py

@@ -0,0 +1,744 @@
+"""High-level builder for Melon Playground .melsave files (from scratch).
+
+Unlike `MelsaveSession` (which patches an existing save via world diff), this
+builder constructs a save **programmatically**: spawn items, add Lua chips,
+wire gates, and export — all verified against the real-device save format.
+
+Based on reverse-engineering of `1132luaexample.melsave` (verified working on
+real device: item + Lua chip + gate connection).
+
+Typical usage:
+
+    from melon_lua import MelsaveBuilder
+
+    b = MelsaveBuilder()
+    item = b.add_item(202, x=0.5, y=0.03, color=(0, 1, 0.3, 1))
+    chip = b.add_lua_chip(lua_source, x=-0.5, y=-0.03,
+                          inputs=[{"name": "target", "type": "entity"}],
+                          outputs=[{"name": "tick", "type": "number"},
+                                   {"name": "status", "type": "string"}])
+    b.connect(item, "entity", chip, "target", name="entity target")
+    b.save("output.melsave")
+"""
+from __future__ import annotations
+
+import copy
+import json
+import uuid
+import zipfile
+from pathlib import Path
+from typing import Any, Literal
+
+from .melsave_writer import write_melsave, connect_gates, MECHANIC_CONSTRAINT_ID
+
+# ---------------------------------------------------------------------------
+# Gate type system
+# ---------------------------------------------------------------------------
+
+# Gate DataType (used in mechanicSerializedInputs/Outputs)
+GATE_ENTITY = 1
+GATE_NUMBER = 2
+GATE_STRING = 4
+GATE_VECTOR = 8
+
+# lua_chip_inputs/outputs Type (same as gate DataType for most)
+# lua_chip_inputs/outputs LuaValue.Type (different enum)
+LUAVAL_NUMBER = 1
+LUAVAL_INTEGER = 2
+LUAVAL_STRING = 3
+LUAVAL_VECTOR = 4
+LUAVAL_COLOR = 5
+LUAVAL_ENTITY = 6
+
+# String alias → (GateDataType, LuaValue.Type)
+_TYPE_MAP: dict[str, tuple[int, int]] = {
+    "entity": (GATE_ENTITY, LUAVAL_ENTITY),
+    "number": (GATE_NUMBER, LUAVAL_NUMBER),
+    "num": (GATE_NUMBER, LUAVAL_NUMBER),
+    "string": (GATE_STRING, LUAVAL_STRING),
+    "str": (GATE_STRING, LUAVAL_STRING),
+    "vector": (GATE_VECTOR, LUAVAL_VECTOR),
+    "vec": (GATE_VECTOR, LUAVAL_VECTOR),
+    "int": (GATE_NUMBER, LUAVAL_INTEGER),
+    "integer": (GATE_NUMBER, LUAVAL_INTEGER),
+}
+
+# System gates that every chip has (auto-added)
+_SYS_INPUT_GATES = [
+    {"name": "activation", "type": "number", "value": 1.0},
+]
+_SYS_OUTPUT_GATES = [
+    {"name": "entity", "type": "entity"},
+    {"name": "activation", "type": "number", "value": 1.0},
+    {"name": "tick", "type": "number", "value": 0.0},
+    {"name": "status", "type": "string", "value": ""},
+]
+
+# ---------------------------------------------------------------------------
+# Default MetaData
+# ---------------------------------------------------------------------------
+
+_DEFAULT_META: dict[str, Any] = {
+    "UniqueId": "",  # filled at save time
+    "icon": {"AssetId": "Icon", "CanBeNull": False},
+    "metadata": {"ManifestId": "", "Name": ""},
+    "versionId": 7,
+    "appVersion": "36.0",
+    "mapName": "Default",
+    "CustomMapChangesVersion": 0,
+    "seed": -1,
+    "timeScale": 1.0,
+    "category": "video",
+    "CategoryValidated": "video",
+}
+
+# ---------------------------------------------------------------------------
+# Helpers for building saveObjects sub-structures
+# ---------------------------------------------------------------------------
+
+_FLOAT_MAX = 3.40282347e38
+
+
+def _make_lua_value(lv_type: int, **kw) -> dict:
+    """Build a complete LuaValue dict."""
+    v: dict[str, Any] = {
+        "Type": lv_type,
+        "NumberValue": kw.get("number_value", 0.0),
+        "IntegerValue": kw.get("integer_value", 0),
+        "StringValue": kw.get("string_value", None),
+        "VectorValue": {
+            "x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0,
+            "magnitude": 0.0, "sqrMagnitude": 0.0,
+        },
+        "ArrayValue": None,
+    }
+    return v
+
+
+def _make_meta_entry(key: str, *, string_value: str | None = None,
+                     int_value: int = 0, bool_value: bool = False) -> dict:
+    """Build a complete saveMetaDatas entry (9 fields)."""
+    return {
+        "key": key,
+        "boolValue": bool_value,
+        "stringValue": string_value,
+        "intValue": int_value,
+        "floatValue": 0.0,
+        "vector2Value": {"x": 0.0, "y": 0.0},
+        "vector3Value": {"x": 0.0, "y": 0.0, "z": 0.0},
+        "vector4Value": {
+            "x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0,
+            "magnitude": 0.0, "sqrMagnitude": 0.0,
+        },
+        "texture2DValue": None,
+    }
+
+
+def _number_gate_data(value: float = 0.0) -> str:
+    return json.dumps({
+        "Value": value, "Default": 0.0,
+        "Min": -_FLOAT_MAX, "Max": _FLOAT_MAX,
+        "IsCheckbox": False,
+    }, separators=(",", ":"))
+
+
+def _string_gate_data(value: str = "") -> str:
+    return json.dumps({
+        "IsMultiline": False, "Value": value,
+        "Default": None, "MaxLength": 2147483647,
+    }, separators=(",", ":"))
+
+
+def _make_mech_gate(key: str, data_type: int,
+                    gate_data: str | None = None) -> dict:
+    """Build a mechanicSerializedInputs/Outputs entry."""
+    return {
+        "Key": key,
+        "DataType": data_type,
+        "DataName": key,
+        "CanBeEdit": True,
+        "GateData": gate_data,
+        "GroupId": None,
+        "Group": 0,
+        "GroupName": None,
+    }
+
+
+def _resolve_type(type_alias: str) -> tuple[int, int]:
+    """Resolve a type alias string to (GateDataType, LuaValueType)."""
+    key = type_alias.lower().strip()
+    if key not in _TYPE_MAP:
+        raise ValueError(
+            f"Unknown type '{type_alias}'. Valid: {sorted(_TYPE_MAP.keys())}"
+        )
+    return _TYPE_MAP[key]
+
+
+def _gate_data_for(type_alias: str, value: Any) -> str | None:
+    """Build GateData JSON string for a gate with an initial value."""
+    key = type_alias.lower().strip()
+    if key in ("number", "num", "int", "integer"):
+        return _number_gate_data(float(value) if value is not None else 0.0)
+    if key in ("string", "str"):
+        return _string_gate_data(str(value) if value is not None else "")
+    # Entity, Vector, Color → no GateData (connected via wire)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Item (spawnable object) template loading
+# ---------------------------------------------------------------------------
+
+_ITEM_TEMPLATE_DIR = Path(__file__).parent / "data" / "item_templates"
+
+
+def _load_item_template(object_id: int) -> dict | None:
+    """Load a deep-copied item template by objectId.
+
+    Looks in the vendored data directory first, then falls back to the
+    source repo's temp/objectid_templates (for dev convenience).
+    """
+    for d in (_ITEM_TEMPLATE_DIR,
+              Path(__file__).parent.parent / "temp" / "objectid_templates"):
+        p = d / f"{object_id}.json"
+        if p.exists():
+            with open(p, "r", encoding="utf-8") as f:
+                return json.load(f)
+    return None
+
+
+def _build_item_save_objects(
+    object_id: int,
+    x: float,
+    y: float,
+    *,
+    z: float = -0.0005,
+    rotation: float = 0.0,
+    scale_x: float = 1.0,
+    scale_y: float = 1.0,
+    color: tuple[float, float, float, float] | None = None,
+    dynamic: bool = True,
+    freezed: bool = False,
+    template: dict | None = None,
+) -> dict:
+    """Build a complete saveObjects dict for a spawnable item."""
+    template_dict: dict
+    if template is not None:
+        template_dict = template
+    else:
+        template_dict = _load_item_template(object_id)  # type: ignore
+    if not template_dict:
+        raise ValueError(
+            f"No item template found for objectId={object_id}. "
+            f"Place a template at melon_lua/data/item_templates/{object_id}.json"
+        )
+    so = copy.deepcopy(template_dict)
+    so["objectId"] = object_id
+    so["instanceId"] = -abs(hash((object_id, x, y))) % (2**31) * -1
+    so["localId"] = 0
+    so["originLocalId"] = 0
+    so["parentId"] = -1
+    so["position"] = {"x": float(x), "y": float(y), "z": float(z)}
+    so["rotation"] = {"x": 0.0, "y": 0.0, "z": float(rotation)}
+    so["scale"] = {"x": float(scale_x), "y": float(scale_y), "z": 1.0}
+    if color is not None:
+        so["color"] = {"r": color[0], "g": color[1], "b": color[2], "a": color[3]}
+    so["gravity"] = dynamic
+    so["freezed"] = freezed
+    so["constraints"] = []
+    so["hingeJoints"] = []
+    so["distJoints"] = []
+    return so
+
+
+# ---------------------------------------------------------------------------
+# Chip (Lua chip) builder
+# ---------------------------------------------------------------------------
+
+_CHIP_TEMPLATE_PATH = Path(__file__).parent / "data" / "chip_template_1132.json"
+
+
+def _build_chip_save_objects(
+    lua_source: str,
+    x: float,
+    y: float,
+    *,
+    z: float = 0.0005,
+    inputs: list[dict] | None = None,
+    outputs: list[dict] | None = None,
+    variables: list[dict] | None = None,
+    tps: int = 30,
+    priority: int = 0,
+    instruction_cost: int = 1000,
+    title: str = "",
+    template: dict | None = None,
+) -> dict:
+    """Build a complete saveObjects dict for a Lua chip.
+
+    Args:
+        lua_source: The Lua source code.
+        x, y: Chip position.
+        inputs: List of {"name": str, "type": str, "value": optional} dicts.
+            Type aliases: entity/number/string/vector/int.
+        outputs: Same format as inputs.
+        variables: List of {"name": str, "value": float} for chip_variables.
+        tps: Ticks per second (1-60).
+        priority: Chip execution priority.
+        instruction_cost: Max instructions per tick.
+        title: Visual title shown on chip.
+        template: Optional pre-loaded chip template dict.
+    """
+    template_dict: dict
+    if template is not None:
+        template_dict = template
+    elif _CHIP_TEMPLATE_PATH.exists():
+        with open(_CHIP_TEMPLATE_PATH, "r", encoding="utf-8") as f:
+            template_dict = json.load(f)
+    else:
+        template_dict = _minimal_chip_template()
+    so = copy.deepcopy(template_dict)
+
+    inputs = inputs or []
+    outputs = outputs or []
+    variables = variables or []
+
+    so["position"] = {"x": float(x), "y": float(y), "z": float(z)}
+    so["rotation"] = {"x": 0.0, "y": 0.0, "z": 0.0}
+    so["scale"] = {"x": 1.0, "y": 1.0, "z": 1.0}
+    so["freezed"] = False
+    so["isActivationForced"] = False
+    so["isVisible"] = False
+    so["constraints"] = []
+    so["hingeJoints"] = []
+    so["distJoints"] = []
+
+    # --- lua_chip_inputs/outputs (saveMetaDatas) ---
+    chip_inputs: list[dict] = []
+    for inp in inputs:
+        gate_type, lv_type = _resolve_type(inp["type"])
+        is_entity = gate_type == GATE_ENTITY
+        chip_inputs.append({
+            "Name": inp["name"],
+            "Type": gate_type,
+            "LuaValue": _make_lua_value(lv_type),
+            "CanBeChanged": not is_entity,  # entity inputs are wire-connected
+        })
+
+    chip_outputs: list[dict] = []
+    for out in outputs:
+        gate_type, lv_type = _resolve_type(out["type"])
+        chip_outputs.append({
+            "Name": out["name"],
+            "Type": gate_type,
+            "LuaValue": _make_lua_value(lv_type),
+            "CanBeChanged": True,
+        })
+
+    # --- mechanicSerializedInputs/Outputs (mechanicData) ---
+    mech_inputs = [_make_mech_gate("activation", GATE_NUMBER,
+                                    _number_gate_data(1.0))]
+    for inp in inputs:
+        gate_type, _ = _resolve_type(inp["type"])
+        value = inp.get("value")
+        gd = _gate_data_for(inp["type"], value) if value is not None else None
+        mech_inputs.append(_make_mech_gate(inp["name"], gate_type, gd))
+
+    # System outputs: entity, activation, tick, status
+    mech_outputs = [
+        _make_mech_gate("entity", GATE_ENTITY, None),
+        _make_mech_gate("activation", GATE_NUMBER, _number_gate_data(1.0)),
+        _make_mech_gate("tick", GATE_NUMBER, _number_gate_data(0.0)),
+        _make_mech_gate("status", GATE_STRING, _string_gate_data("")),
+    ]
+    for out in outputs:
+        gate_type, _ = _resolve_type(out["type"])
+        value = out.get("value")
+        gd = _gate_data_for(out["type"], value) if value is not None else None
+        # Skip if name collides with system gate
+        if out["name"] not in ("entity", "activation", "tick", "status"):
+            mech_outputs.append(_make_mech_gate(out["name"], gate_type, gd))
+
+    so["mechanicData"] = [{
+        "activationInput": 1.0,
+        "floatParameters": [1.0],
+        "mechanicSerializedInputs": json.dumps(mech_inputs, ensure_ascii=False,
+                                                separators=(",", ":")),
+        "mechanicSerializedOutputs": json.dumps(mech_outputs, ensure_ascii=False,
+                                                 separators=(",", ":")),
+    }]
+
+    # --- chip_variables ---
+    var_list = []
+    for var in variables:
+        var_list.append({
+            "Key": var["name"],
+            "DataType": 2,
+            "GateData": _number_gate_data(float(var.get("value", 0.0))),
+        })
+
+    # --- saveMetaDatas ---
+    chip_id = str(uuid.uuid4())
+    metadata = json.dumps({
+        "ApiVersion": 1, "PreambleVersion": 1,
+        "BackendType": "LuaCSharp", "BackendVersion": "1.0.0",
+        "AppVersion": "36.0",
+        "SavedAtUnixSeconds": 0,
+        "Extras": {},
+    }, separators=(",", ":"))
+
+    visual_name = json.dumps({
+        "Title": title,
+        "TitleVisibilityType": 4,
+        "TitleColor": {
+            "x": 1.0, "y": 1.0, "z": 1.0, "w": 1.0,
+            "normalized": {"x": 0.5, "y": 0.5, "z": 0.5, "w": 0.5,
+                            "magnitude": 1.0, "sqrMagnitude": 1.0},
+            "magnitude": 2.0, "sqrMagnitude": 4.0,
+        },
+        "TitleFontType": 0,
+    }, separators=(",", ":"))
+
+    so["saveMetaDatas"] = [
+        _make_meta_entry("lua_chip_id", string_value=chip_id),
+        _make_meta_entry("lua_chip_source", string_value=lua_source),
+        _make_meta_entry("lua_chip_inputs",
+                         string_value=json.dumps(chip_inputs, ensure_ascii=False,
+                                                  separators=(",", ":"))),
+        _make_meta_entry("lua_chip_outputs",
+                         string_value=json.dumps(chip_outputs, ensure_ascii=False,
+                                                  separators=(",", ":"))),
+        _make_meta_entry("lua_chip_variables",
+                         string_value=json.dumps(var_list, ensure_ascii=False,
+                                                  separators=(",", ":"))),
+        _make_meta_entry("lua_chip_tps", int_value=tps),
+        _make_meta_entry("lua_chip_priority", int_value=priority),
+        _make_meta_entry("lua_chip_instruction_cost", int_value=instruction_cost),
+        _make_meta_entry("lua_chip_visual_name", string_value=visual_name),
+        _make_meta_entry("lua_chip_metadata", string_value=metadata),
+    ]
+
+    return so
+
+
+def _minimal_chip_template() -> dict:
+    """A minimal chip template with all required saveObjects fields.
+
+    Used when chip_template_1132.json is not available.
+    """
+    return {
+        "objectId": 507707712,
+        "instanceId": 0,
+        "modedObjectId": "",
+        "localId": 0,
+        "originLocalId": 0,
+        "parentId": -1,
+        "position": {"x": 0, "y": 0, "z": 0.0005},
+        "rotation": {"x": 0, "y": 0, "z": 0},
+        "scale": {"x": 1, "y": 1, "z": 1},
+        "color": {"r": 0, "g": 0, "b": 0, "a": 0},
+        "intensity": 0.0,
+        "bottomColor": {"r": 0, "g": 0, "b": 0, "a": 0},
+        "isGradientActive": False,
+        "layer": 0,
+        "sortingLayer": "Default",
+        "orderLayer": 0,
+        "gravity": True,
+        "freezed": False,
+        "ballooned": False,
+        "glued": False,
+        "rotationFrozen": False,
+        "notBreakable": False,
+        "isVisible": False,
+        "isMeltable": False,
+        "isHuman": False,
+        "isMutationPart": False,
+        "isActivationForced": False,
+        "prohibitDrag": False,
+        "prohibitBrokeByWater": False,
+        "interactionType": "Physic",
+        "hasInvisible": False,
+        "fluorescentIntensity": 0.0,
+        "fluorescentColor": {"r": 0, "g": 0, "b": 0, "a": 0},
+        "TreeBranch": None,
+        "LightSaveData": {
+            "IsActive": False, "ColorIsChanged": True,
+            "Color": {"r": 0, "g": 0, "b": 0, "a": 0},
+            "IsBrokenByWater": False, "ChildrenSaveData": None,
+            "<IsActive>k__BackingField": False,
+            "<ColorIsChanged>k__BackingField": True,
+            "<Color>k__BackingField": {"r": 0, "g": 0, "b": 0, "a": 0},
+            "<IsBrokenByWater>k__BackingField": False,
+            "<ChildrenSaveData>k__BackingField": None,
+        },
+        "BreakableSaveData": None,
+        "SpikeComponentData": None,
+        "TakenObjectData": None,
+        "humanData": [],
+        "mechanicData": [],
+        "brokenJoints": [],
+        "hingeJoints": [],
+        "distJoints": [],
+        "constraints": [],
+        "collisionIgnores": [],
+        "addData": [],
+        "saveMetaDatas": [],
+        "ContextMenuActionsRestrictionSaveData": None,
+        "pixelTargetColor": {"r": 0, "g": 0, "b": 0, "a": 0},
+        "isPixelTextureWasChanged": False,
+    }
+
+
+# ---------------------------------------------------------------------------
+# MelsaveBuilder
+# ---------------------------------------------------------------------------
+
+class MelsaveBuilder:
+    """Build a .melsave from scratch: items + Lua chips + gate connections.
+
+    Verified against 1132luaexample.melsave (real-device save with item + chip).
+
+    Example::
+
+        b = MelsaveBuilder()
+        item = b.add_item(202, x=0.5, y=0.03, color=(0, 1, 0.3, 1))
+        chip = b.add_lua_chip(source, x=-0.5, y=-0.03,
+                              inputs=[{"name": "target", "type": "entity"}],
+                              outputs=[{"name": "tick", "type": "number"}])
+        b.connect(item, "entity", chip, "target")
+        b.save("output.melsave")
+    """
+
+    def __init__(self, *, app_version: str = "36.0", map_name: str = "Default"):
+        self._containers: list[dict] = []
+        self._meta = copy.deepcopy(_DEFAULT_META)
+        self._meta["appVersion"] = app_version
+        self._meta["mapName"] = map_name
+        self._icon: bytes | None = None
+
+    # ------------------------------------------------------------------
+    # Add objects
+    # ------------------------------------------------------------------
+
+    def add_item(
+        self,
+        object_id: int,
+        x: float = 0.0,
+        y: float = 0.0,
+        *,
+        z: float = -0.0005,
+        rotation: float = 0.0,
+        scale_x: float = 1.0,
+        scale_y: float = 1.0,
+        color: tuple[float, float, float, float] | None = None,
+        dynamic: bool = True,
+        freezed: bool = False,
+        template: dict | None = None,
+    ) -> int:
+        """Add a spawnable item (e.g. plastic, metal, engine, rocket body).
+
+        Args:
+            object_id: The melon objectId (e.g. 202 = ResizablePlastic,
+                132 = engine, 14 = rocket body).
+            x, y: World position.
+            color: RGBA tuple (0-1 range), or None for default.
+            dynamic: If True, gravity affects the object.
+            freezed: If True, object is frozen in place.
+            template: Optional raw saveObjects dict to clone instead of
+                loading from the template pool.
+
+        Returns:
+            Container index (use for connect/save_as references).
+        """
+        so = _build_item_save_objects(
+            object_id, x, y, z=z, rotation=rotation,
+            scale_x=scale_x, scale_y=scale_y,
+            color=color, dynamic=dynamic, freezed=freezed,
+            template=template,
+        )
+        idx = len(self._containers)
+        self._containers.append({
+            "saveObjects": so,
+            "saveObjectChildren": [],
+        })
+        return idx
+
+    def add_lua_chip(
+        self,
+        lua_source: str,
+        x: float = 0.0,
+        y: float = 0.0,
+        *,
+        z: float = 0.0005,
+        inputs: list[dict] | None = None,
+        outputs: list[dict] | None = None,
+        variables: list[dict] | None = None,
+        tps: int = 30,
+        priority: int = 0,
+        instruction_cost: int = 1000,
+        title: str = "",
+    ) -> int:
+        """Add a Lua chip.
+
+        Args:
+            lua_source: Lua source code (must define OnTick at minimum).
+            x, y: World position.
+            inputs: List of gate dicts, each with:
+                - "name": gate name (string, spaces OK)
+                - "type": "entity" | "number" | "string" | "vector" | "int"
+                - "value": optional initial value (number/string)
+            outputs: Same format as inputs.
+            variables: List of {"name": str, "value": float} for persistent
+                chip variables.
+            tps: Ticks per second (default 30).
+            title: Visual title shown on the chip.
+
+        Returns:
+            Container index.
+        """
+        so = _build_chip_save_objects(
+            lua_source, x, y, z=z,
+            inputs=inputs, outputs=outputs, variables=variables,
+            tps=tps, priority=priority, instruction_cost=instruction_cost,
+            title=title,
+        )
+        idx = len(self._containers)
+        self._containers.append({
+            "saveObjects": so,
+            "saveObjectChildren": [],
+        })
+        return idx
+
+    def add_container(self, save_objects: dict) -> int:
+        """Add a raw container (pre-built saveObjects dict).
+
+        For advanced use when add_item/add_lua_chip don't fit.
+        """
+        idx = len(self._containers)
+        self._containers.append({
+            "saveObjects": save_objects,
+            "saveObjectChildren": [],
+        })
+        return idx
+
+    def add_ui_controller(self, controller, x: float = 0.0, y: float = 0.0) -> int:
+        """Add a UI controller (objectId=2046689600).
+
+        Args:
+            controller: A UIControllerBuilder with elements added.
+            x, y: World position.
+
+        Returns:
+            Container index.
+        """
+        so = controller.build_save_object(x=x, y=y)
+        return self.add_container(so)
+
+    # ------------------------------------------------------------------
+    # Wire gates
+    # ------------------------------------------------------------------
+
+    def connect(
+        self,
+        source_idx: int,
+        output_gate: str,
+        target_idx: int,
+        input_gate: str,
+        *,
+        name: str = "",
+        start_point: tuple[float, float] = (0.0, 0.0),
+        end_point: tuple[float, float] = (0.0, 0.0),
+    ) -> dict:
+        """Wire a mechanic gate connection: source.output → target.input.
+
+        The connection is stored on the **source** object's constraints list.
+        Every spawnable item has a built-in ``"entity"`` output gate that
+        provides the item's own entity id.
+
+        Args:
+            source_idx: Container index of the source (output) object.
+            output_gate: Output gate name on the source (e.g. "entity").
+            target_idx: Container index of the target (input) object.
+            input_gate: Input gate name on the target (e.g. "target").
+            name: Optional display name for the connection.
+        """
+        data = {"saveObjectContainers": self._containers}
+        return connect_gates(
+            data, source_idx, output_gate, target_idx, input_gate,
+            name=name, start_point=start_point, end_point=end_point,
+        )
+
+    # ------------------------------------------------------------------
+    # Introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def container_count(self) -> int:
+        return len(self._containers)
+
+    def containers(self) -> list[dict]:
+        """Return a list of (idx, objectId, type, position) tuples."""
+        out = []
+        for i, c in enumerate(self._containers):
+            so = c.get("saveObjects") or {}
+            oid = so.get("objectId", "?")
+            pos = so.get("position", {})
+            kind = "lua_chip" if oid == 507707712 else "item"
+            out.append({
+                "idx": i, "objectId": oid, "type": kind,
+                "x": pos.get("x", 0), "y": pos.get("y", 0),
+            })
+        return out
+
+    def get_container(self, idx: int) -> dict:
+        so = self._containers[idx].get("saveObjects")
+        return so if so is not None else {}
+
+    # ------------------------------------------------------------------
+    # MetaData / Icon
+    # ------------------------------------------------------------------
+
+    def set_meta(self, **kwargs) -> None:
+        """Override MetaData fields (appVersion, mapName, seed, etc.)."""
+        self._meta.update(kwargs)
+
+    def set_icon(self, icon_bytes: bytes) -> None:
+        """Set the save icon (PNG bytes)."""
+        self._icon = icon_bytes
+
+    def load_icon_from(self, path: str | Path) -> None:
+        """Load icon from a .png file."""
+        self._icon = Path(path).read_bytes()
+
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    def build_data(self) -> dict:
+        """Build the Data JSON dict (without writing to file)."""
+        return {"saveObjectContainers": copy.deepcopy(self._containers)}
+
+    def save(self, out_path: str | Path, *, write_icon: bool = True) -> Path:
+        """Write the .melsave ZIP file.
+
+        Args:
+            out_path: Output file path.
+            write_icon: If True and icon is set, include Icon entry.
+        """
+        meta = copy.deepcopy(self._meta)
+        if not meta.get("UniqueId"):
+            meta["UniqueId"] = str(uuid.uuid4())
+        data = self.build_data()
+        icon = self._icon if write_icon else None
+        return write_melsave(out_path, data, meta, icon)
+
+
+# Re-export for convenience
+__all__ = [
+    "MelsaveBuilder",
+    "connect_gates",
+    "MECHANIC_CONSTRAINT_ID",
+    "GATE_ENTITY",
+    "GATE_NUMBER",
+    "GATE_STRING",
+    "GATE_VECTOR",
+]