melon-lua 3.4.0__py3-none-any.whl

melon_lua/entity.py

@@ -0,0 +1,88 @@
+"""Mock Entity — matches every field the real Entity API touches.
+
+Fields are populated based on the 60+ methods in EntityApiModule.cs (IL2CPP dump)
+and the signatures in Example_ApiReference_en.lua. This is NOT a physics body:
+state is set directly by setters. A future IPhysicsWorld hook can drive motion.
+"""
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Entity:
+    entity_id: int
+    local_id: int = 0
+    name: str = "object"
+    object_id: Optional[int] = None
+    localized_name: str = ""
+    sprite_path: Optional[str] = None
+
+    # Transform
+    position_x: float = 0.0
+    position_y: float = 0.0
+    angle: float = 0.0  # degrees
+    scale_x: float = 1.0
+    scale_y: float = 1.0
+    base_size_x: float = 1.0
+    base_size_y: float = 1.0
+
+    # Physics
+    velocity_x: float = 0.0
+    velocity_y: float = 0.0
+    angular_velocity: float = 0.0
+    mass: float = 1.0
+    center_of_mass_x: float = 0.0
+    center_of_mass_y: float = 0.0
+    gravity_scale: float = 1.0
+    is_frozen: bool = False
+    is_rotation_frozen: bool = False
+    collision_enabled: bool = True
+    physic_material: str = "Default"
+
+    # Health / Temperature
+    temperature: float = 20.0
+    on_fire: bool = False
+    health: float = 100.0
+    breakable: bool = False
+
+    # Visuals
+    color_r: float = 1.0
+    color_g: float = 1.0
+    color_b: float = 1.0
+    color_a: float = 1.0
+    visible: bool = True
+
+    # Electricity
+    voltage: float = 0.0
+
+    # Interaction
+    draggable: bool = True
+    activation_input: float = 0.0
+    can_be_activated: bool = False
+
+    # Hierarchy
+    parent_id: Optional[int] = None
+    children_ids: list[int] = field(default_factory=list)
+
+    # Custom texture override (from .melmod)
+    custom_texture_png: str | None = None
+    custom_texture_ppu: float | None = None
+
+    # Bookkeeping
+    alive: bool = True
+    custom_data: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def normal_x(self) -> float:
+        import math
+        a = math.radians(self.angle)
+        return math.cos(a)
+
+    @property
+    def normal_y(self) -> float:
+        import math
+        a = math.radians(self.angle + 90)
+        return math.sin(a)
+
+    def real_size(self) -> tuple[float, float]:
+        return (self.base_size_x * self.scale_x, self.base_size_y * self.scale_y)

melon_lua/melmod.py

@@ -0,0 +1,164 @@
+"""Melmod loader for Melon Playground custom texture mods (.melmod).
+
+.melmod is a ZIP with:
+- MetaData: JSON { uniqueId, category, type, Icon, ... }
+- Data: JSON { parts: [ { mainTexture: {AssetId}, pixelsPerUnit, collidersJson, ... } ] }
+- Part_<guid>: raw PNG bytes for the main texture
+- Icon: PNG
+
+This module extracts and provides:
+- list of parts with png path, ppu, pixel size
+- ability to resolve by uniqueId or assetId
+- physical size = pixel_size / ppu (in meters, matching game sprite import)
+"""
+from __future__ import annotations
+
+import json
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MelmodPart:
+    unique_id: str
+    asset_id: str
+    png_path: str
+    ppu: float
+    pixel_w: int
+    pixel_h: int
+    # physical size in meters (width, height)
+    phys_w: float
+    phys_h: float
+
+
+@dataclass
+class MelmodEntry:
+    file: str
+    unique_id: str
+    category: str | None
+    type: str | None
+    icon_png: str | None
+    parts: list[MelmodPart]
+
+
+def _extract_png(zf: zipfile.ZipFile, entry: str, out_path: Path) -> None:
+    raw = zf.read(entry)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = out_path.with_suffix(".tmp.bin")
+    tmp.write_bytes(raw)
+    # Pillow will validate on open; we just move after
+    tmp.replace(out_path)
+
+
+def load_melmod_pack(pack_dir: str | Path, extract_dir: str | Path | None = None) -> list[MelmodEntry]:
+    """Load all .melmod from a directory.
+
+    If extract_dir is given, PNGs are extracted there (idempotent).
+    Returns list of MelmodEntry with resolved PNG paths and computed physical sizes.
+    """
+    pack_dir = Path(pack_dir)
+    if extract_dir is None:
+        extract_dir = pack_dir.parent / (pack_dir.name + "_extracted")
+    extract_dir = Path(extract_dir)
+    extract_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest_path = extract_dir / "manifest.json"
+    entries: list[MelmodEntry] = []
+
+    for mf in sorted(pack_dir.glob("*.melmod")):
+        with zipfile.ZipFile(mf) as z:
+            meta = json.loads(z.read("MetaData").decode("utf-8", errors="replace"))
+            data = json.loads(z.read("Data").decode("utf-8", errors="replace"))
+            uid = meta.get("uniqueId") or mf.stem
+            cat = meta.get("category")
+            typ = meta.get("type")
+
+            icon_png = None
+            if "Icon" in z.namelist():
+                ip = extract_dir / f"{uid}_Icon.png"
+                if not ip.exists():
+                    _extract_png(z, "Icon", ip)
+                icon_png = str(ip)
+
+            parts: list[MelmodPart] = []
+            for part in data.get("parts", []):
+                asset = part.get("mainTexture", {}).get("AssetId")
+                ppu = float(part.get("pixelsPerUnit", 256.0))
+                if not asset or asset not in z.namelist():
+                    continue
+                pngp = extract_dir / f"{uid}_{asset}.png"
+                if not pngp.exists():
+                    _extract_png(z, asset, pngp)
+                from PIL import Image  # lazy
+                with Image.open(pngp) as im:
+                    pw, ph = im.size
+                phys_w = pw / ppu if ppu > 0 else 0.0
+                phys_h = ph / ppu if ppu > 0 else 0.0
+                parts.append(MelmodPart(
+                    unique_id=uid,
+                    asset_id=asset,
+                    png_path=str(pngp),
+                    ppu=ppu,
+                    pixel_w=pw,
+                    pixel_h=ph,
+                    phys_w=phys_w,
+                    phys_h=phys_h,
+                ))
+            entries.append(MelmodEntry(
+                file=mf.name,
+                unique_id=uid,
+                category=cat,
+                type=typ,
+                icon_png=icon_png,
+                parts=parts,
+            ))
+
+    # Write/refresh manifest
+    man = []
+    for e in entries:
+        man.append({
+            "file": e.file,
+            "uniqueId": e.unique_id,
+            "category": e.category,
+            "type": e.type,
+            "icon": e.icon_png,
+            "parts": [
+                {
+                    "assetId": p.asset_id,
+                    "png": p.png_path,
+                    "ppu": p.ppu,
+                    "size": [p.pixel_w, p.pixel_h],
+                    "physSize": [p.phys_w, p.phys_h],
+                } for p in e.parts
+            ],
+        })
+    manifest_path.write_text(json.dumps(man, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # Auto-register for visuals / preview
+    try:
+        from . import visuals as _vis
+        for e in entries:
+            for p in e.parts:
+                _vis.register_melmod_override(e.unique_id, p.png_path, p.ppu)
+                _vis.register_melmod_override(p.asset_id, p.png_path, p.ppu)
+    except Exception:
+        pass
+
+    return entries
+
+
+def find_part(entries: list[MelmodEntry], asset_id: str) -> MelmodPart | None:
+    for e in entries:
+        for p in e.parts:
+            if p.asset_id == asset_id:
+                return p
+    return None
+
+
+def find_by_unique(entries: list[MelmodEntry], unique_id: str) -> MelmodEntry | None:
+    for e in entries:
+        if e.unique_id == unique_id:
+            return e
+    return None

melon_lua/melsave.py

@@ -0,0 +1,275 @@
+"""Read Melon Playground .melsave archives (ZIP: Data, MetaData, Icon).
+
+APK flow (IL2CPP): SavesManager.TryDeserialize / SaveConverter.Convert(json) →
+SaveObjectDataContainer with saveObjectContainers[] of { saveObjects, saveObjectChildren }.
+
+This module extracts a sandbox-friendly view: metadata + flat object list with
+objectId, position, rotation, scale, flags, and catalog-resolved names.
+"""
+from __future__ import annotations
+
+import json
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from . import catalog as _catalog
+
+
+@dataclass
+class MelsaveObject:
+    index: int
+    object_id: int
+    instance_id: int
+    name: str
+    localized_hint: str = ""
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+    rotation_z: float = 0.0
+    scale_x: float = 1.0
+    scale_y: float = 1.0
+    parent_id: int = -1
+    gravity: bool = True
+    freezed: bool = False
+    children_count: int = 0
+    visible: bool = True
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class MelsaveDocument:
+    path: str
+    save_name: str
+    category: str
+    app_version: str
+    version_id: int
+    map_name: str
+    object_count: int
+    objects: list[MelsaveObject]
+    metadata: dict[str, Any]
+    data_extras: dict[str, Any]
+
+
+def _vec3(d: Any, key: str, default: float = 0.0) -> tuple[float, float, float]:
+    if not isinstance(d, dict):
+        return default, default, default
+    v = d.get(key) or {}
+    if not isinstance(v, dict):
+        return default, default, default
+    return (
+        float(v.get("x", default)),
+        float(v.get("y", default)),
+        float(v.get("z", default)),
+    )
+
+
+def _resolve_name(object_id: int) -> tuple[str, str]:
+    prof = _catalog.get_profile_by_object_id(object_id)
+    if not prof:
+        return f"objectId_{object_id}", ""
+    name = str(prof.get("name") or f"objectId_{object_id}")
+    hint = str(prof.get("category") or prof.get("buttonName") or "")
+    return name, hint
+
+
+def read_melsave(path: str | Path) -> MelsaveDocument:
+    path = Path(path)
+    with zipfile.ZipFile(path, "r") as zf:
+        if "Data" not in zf.namelist():
+            raise ValueError(f"Not a .melsave (missing Data): {path}")
+        data = json.loads(zf.read("Data").decode("utf-8"))
+        meta: dict[str, Any] = {}
+        if "MetaData" in zf.namelist():
+            meta = json.loads(zf.read("MetaData").decode("utf-8"))
+
+    containers = data.get("saveObjectContainers") or []
+    objects: list[MelsaveObject] = []
+    child_index = 100000  # offset so children don't collide with root indices in simple lists
+
+    for idx, container in enumerate(containers):
+        so = container.get("saveObjects") or {}
+        if so:
+            oid = int(so.get("objectId", 0))
+            name, hint = _resolve_name(oid)
+            px, py, pz = _vec3(so, "position")
+            _, _, rz = _vec3(so, "rotation")
+            sx, sy, _ = _vec3(so, "scale", 1.0)
+            children = container.get("saveObjectChildren") or []
+            objects.append(
+                MelsaveObject(
+                    index=idx,
+                    object_id=oid,
+                    instance_id=int(so.get("instanceId", 0)),
+                    name=name,
+                    localized_hint=hint,
+                    x=px,
+                    y=py,
+                    z=pz,
+                    rotation_z=rz,
+                    scale_x=sx,
+                    scale_y=sy,
+                    parent_id=int(so.get("parentId", -1)),
+                    gravity=bool(so.get("gravity", True)),
+                    freezed=bool(so.get("freezed", False)),
+                    children_count=len(children) if isinstance(children, list) else 0,
+                    raw=so,
+                )
+            )
+
+        # Also parse direct children as separate spawnable objects.
+        # objectId==0 children are named sub-components (Motor, PistonPart, Wheel, Handle...).
+        # They carry their own world position/rotation in the save, so we can spawn them.
+        # We treat objectId=0 as "part" with the childName as the visual name.
+        kids = container.get("saveObjectChildren") or []
+        for k in kids:
+            if not isinstance(k, dict):
+                continue
+            koid = int(k.get("objectId", 0))
+            kname = k.get("childName") or "part"
+            khint = kname
+            kpx, kpy, _ = _vec3(k, "position")
+            _, _, krz = _vec3(k, "rotation")
+            ksx, ksy, _ = _vec3(k, "scale", 1.0)
+            objects.append(
+                MelsaveObject(
+                    index=child_index,
+                    object_id=koid,
+                    instance_id=int(k.get("instanceId", 0)),
+                    name=kname,
+                    localized_hint=khint,
+                    x=kpx,
+                    y=kpy,
+                    z=0.0,
+                    rotation_z=krz,
+                    scale_x=ksx,
+                    scale_y=ksy,
+                    parent_id=int(k.get("parentId", -1)),
+                    gravity=bool(k.get("gravity", True)),
+                    freezed=bool(k.get("freezed", False)),
+                    children_count=0,
+                    raw=k,
+                )
+            )
+            child_index += 1
+
+    md = meta.get("metadata") or {}
+    save_name = str(md.get("Name") or path.stem)
+    return MelsaveDocument(
+        path=str(path.resolve()),
+        save_name=save_name,
+        category=str(meta.get("category") or ""),
+        app_version=str(meta.get("appVersion") or ""),
+        version_id=int(meta.get("versionId", 0)),
+        map_name=str(meta.get("mapName") or ""),
+        object_count=len(objects),
+        objects=objects,
+        metadata=meta,
+        data_extras={
+            "averagePosition": data.get("averagePosition"),
+            "autoLightData": data.get("autoLightData"),
+        },
+    )
+
+
+def document_to_dict(doc: MelsaveDocument, *, include_raw: bool = False) -> dict[str, Any]:
+    """JSON-serializable summary for inspection / API discussion."""
+    objs = []
+    for o in doc.objects:
+        row: dict[str, Any] = {
+            "index": o.index,
+            "objectId": o.object_id,
+            "name": o.name,
+            "instanceId": o.instance_id,
+            "position": {"x": o.x, "y": o.y, "z": o.z},
+            "rotationZ": o.rotation_z,
+            "scale": {"x": o.scale_x, "y": o.scale_y},
+            "parentId": o.parent_id,
+            "gravity": o.gravity,
+            "freezed": o.freezed,
+            "childrenCount": o.children_count,
+        }
+        if o.localized_hint:
+            row["catalogHint"] = o.localized_hint
+        if include_raw:
+            row["raw"] = o.raw
+        objs.append(row)
+
+    by_oid: dict[str, int] = {}
+    for o in doc.objects:
+        k = str(o.object_id)
+        by_oid[k] = by_oid.get(k, 0) + 1
+
+    return {
+        "format": "MelonLuaSandbox.melsave.v1",
+        "source": doc.path,
+        "save": {
+            "name": doc.save_name,
+            "category": doc.category,
+            "appVersion": doc.app_version,
+            "versionId": doc.version_id,
+            "mapName": doc.map_name,
+        },
+        "stats": {
+            "objectCount": doc.object_count,
+            "uniqueObjectIds": len(by_oid),
+            "countsByObjectId": by_oid,
+        },
+        "objects": objs,
+        "extras": doc.data_extras,
+    }
+
+
+def list_objects(path: str | Path) -> list[MelsaveObject]:
+    return read_melsave(path).objects
+
+
+def spawn_document_into_world(doc: MelsaveDocument, world: Any, *, melmod_overrides: dict[int, str] | None = None) -> list[int]:
+    """Spawn all objects (roots + children saved in the melsave) into WorldContext.
+
+    melmod_overrides: optional map instanceId -> melmod uniqueId or Part_assetId
+    """
+    ids: list[int] = []
+    for o in doc.objects:
+        e = world.spawn_entity(
+            str(o.object_id),
+            o.x,
+            o.y,
+            object_id=o.object_id,
+            angle=o.rotation_z,
+            scale_x=o.scale_x,
+            scale_y=o.scale_y,
+            is_frozen=o.freezed,
+            gravity_scale=0.0 if not o.gravity else 1.0,
+        )
+        raw_col = (o.raw or {}).get("color") if isinstance(o.raw, dict) else None
+        if isinstance(raw_col, dict) and any(
+            abs(float(raw_col.get(k, 0.0))) > 1e-6 for k in ("r", "g", "b", "a")
+        ):
+            e.color_r = float(raw_col.get("r", 1.0))
+            e.color_g = float(raw_col.get("g", 1.0))
+            e.color_b = float(raw_col.get("b", 1.0))
+            e.color_a = float(raw_col.get("a", 1.0))
+        # if the child entry had isVisible=False we can hide it
+        if not o.visible:
+            try:
+                e.visible = False
+            except Exception:
+                pass
+        # Apply melmod custom texture if provided for this instance
+        if melmod_overrides:
+            key = o.instance_id
+            uid = melmod_overrides.get(key) or melmod_overrides.get(int(key)) if isinstance(key, (int, float)) else None
+            if uid:
+                try:
+                    from . import visuals as _vis
+                    _vis.apply_melmod_texture(e, str(uid))
+                except Exception:
+                    pass
+        raw_lid = int(o.raw.get("localId", 0)) if isinstance(o.raw, dict) else 0
+        if not raw_lid:
+            raw_lid = o.index + 1 if o.index < 100000 else o.index
+        e.local_id = raw_lid
+        ids.append(e.entity_id)
+    return ids