melon-lua 3.4.0__py3-none-any.whl

melon_lua/visuals.py

@@ -0,0 +1,115 @@
+"""Resolve sprite path per objectId for sandbox rendering.
+
+Supports:
+- built-in catalog sprites (objectId → spritePath)
+- .melmod custom textures (via register_melmod_override / custom_texture_png on Entity)
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+_PKG = Path(__file__).resolve().parent
+_DATA = _PKG / "data" / "sprites_by_object_id.json"
+_PACK = _PKG / "data" / "sprites_pack"
+_TRIAGE = _PKG.parent.parent / "lua-triage" / "object_sprites_by_id"
+
+# Runtime overrides from loaded .melmod packs: uniqueId or assetId -> (png_path, ppu)
+_MELMOD_OVERRIDES: dict[str, tuple[str, float]] = {}
+
+
+@lru_cache(maxsize=1)
+def _load_rows() -> dict[int, dict]:
+    for p in (_DATA, _TRIAGE / "sprites_by_object_id.json"):
+        if p.is_file():
+            data = json.loads(p.read_text(encoding="utf-8"))
+            return {int(r["objectId"]): r for r in data.get("sprites", []) if r.get("objectId") is not None}
+    return {}
+
+
+def _resolve_file(rel: str) -> str | None:
+    if not rel:
+        return None
+    rel_path = Path(rel.replace("/", "\\") if "\\" in str(_PKG) else rel)
+    for base in (_PKG / "data", _PACK, _TRIAGE):
+        if rel.startswith("sprites_pack/"):
+            cand = _PKG / "data" / rel_path
+        else:
+            cand = base / rel_path.name if base == _PACK and rel_path.name else base / rel_path
+        if cand.is_file():
+            return str(cand.resolve())
+        cand2 = _PKG / "data" / rel_path
+        if cand2.is_file():
+            return str(cand2.resolve())
+    full = _TRIAGE / rel
+    if full.is_file():
+        return str(full.resolve())
+    full = _TRIAGE / "images" / rel_path.name
+    return str(full.resolve()) if full.is_file() else None
+
+
+def sprite_path_for_object_id(object_id: int | None) -> str | None:
+    if object_id is None:
+        return None
+    row = _load_rows().get(int(object_id))
+    if not row:
+        return None
+    return _resolve_file(row.get("spritePath") or "")
+
+
+def fallback_sprite_path() -> str | None:
+    for name in (
+        "sprites_pack/images/0202_plastic_fallback.png",
+        "images/0202_plastic_fallback.png",
+        "0202_plastic_fallback.png",
+    ):
+        p = _resolve_file(name)
+        if p:
+            return p
+    return None
+
+
+def resolve_sprite(object_id: int | None, game_object_name: str = "") -> str | None:
+    del game_object_name
+    return sprite_path_for_object_id(object_id) or fallback_sprite_path()
+
+
+# --- Melmod custom texture integration ---
+
+def register_melmod_override(unique_or_asset: str, png_path: str, ppu: float = 256.0) -> None:
+    """Register a runtime override so that resolve_sprite_for_melmod can return the custom PNG.
+
+    Call this after loading a melmod pack for the parts you want to use.
+    unique_or_asset can be either the melmod uniqueId or the Part_<guid> assetId.
+    """
+    if unique_or_asset and png_path:
+        _MELMOD_OVERRIDES[str(unique_or_asset)] = (str(png_path), float(ppu))
+
+
+def clear_melmod_overrides() -> None:
+    _MELMOD_OVERRIDES.clear()
+
+
+def resolve_sprite_for_melmod(unique_or_asset: str | None) -> tuple[str, float] | None:
+    """Return (png_path, ppu) if a melmod override is registered for this key."""
+    if not unique_or_asset:
+        return None
+    return _MELMOD_OVERRIDES.get(str(unique_or_asset))
+
+
+def apply_melmod_texture(e, unique_or_asset: str | None) -> bool:
+    """If a melmod override exists for the key, attach it to the entity for preview/spawn.
+
+    Sets e.custom_texture_png and e.custom_texture_ppu, and also e.sprite_path for preview.
+    Returns True if applied.
+    """
+    hit = resolve_sprite_for_melmod(unique_or_asset)
+    if not hit:
+        return False
+    png, ppu = hit
+    e.custom_texture_png = png
+    e.custom_texture_ppu = ppu
+    e.sprite_path = png  # preview will prefer sprite_path if present
+    return True

melon_lua/vpcompile/__init__.py

@@ -0,0 +1,5 @@
+"""VPchip (Melon 36.x) graph → Lua compiler (subset)."""
+from .compile import compile_vp_graph
+from .graph import parse_chip_graph
+
+__all__ = ["compile_vp_graph", "parse_chip_graph"]

melon_lua/vpcompile/codegen.py

@@ -0,0 +1,163 @@
+"""Emit Lua from MelonGraph (C1 math subset)."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .ir import MelonGraph, VPNode
+from .nodes import REGISTRY
+from .nodes.flow import set_chip_variables
+
+
+
+def _slot_key(to_node: str, input_index: int) -> str:
+    return f"_in_{to_node}_{input_index}"
+
+
+def _wire_inputs(graph: MelonGraph) -> dict[str, dict[int, str]]:
+    """Map to_node -> input_index -> from_node uid."""
+    by_to: dict[str, dict[int, str]] = {}
+    for uid, n in graph.nodes.items():
+        for i, inp in enumerate(n.inputs):
+            co = inp.get("connectedOutputIdModel")
+            if not co:
+                continue
+            from_full = str(co.get("NodeId") or "")
+            for fu, fn in graph.nodes.items():
+                if fn.full_id == from_full:
+                    by_to.setdefault(uid, {})[i] = fu
+                    break
+    return by_to
+
+
+def _is_vector_node(n: VPNode) -> bool:
+    """Check if a node operates on vector data (GateDataType or input DataType)."""
+    gdt = n.raw.get("GateDataType")
+    if isinstance(gdt, str) and gdt.strip() == "Vector":
+        return True
+    for inp in n.inputs:
+        dt = inp.get("DataType")
+        if isinstance(dt, str) and dt.strip() == "Vector":
+            return True
+    return False
+
+
+def _build_var_uid_map(graph: MelonGraph) -> dict[str, str]:
+    """Map Variable node uid -> shared G key (MechanicConnectionId).
+
+    Variable nodes with the same MechanicConnectionId share state. Other nodes
+    reference a variable by uid; this map lets _input_exprs redirect those
+    references to the shared key so readers always see writer-updated state.
+    """
+    mapping: dict[str, str] = {}
+    for uid, n in graph.nodes.items():
+        if n.name == "Variable":
+            mci = n.raw.get("MechanicConnectionId")
+            if mci:
+                mapping[uid] = mci
+    return mapping
+
+
+def _parse_chip_variables(raw: str | list | None) -> dict[str, float]:
+    """Parse chip_variables JSON into a Key -> Value dict."""
+    if not raw:
+        return {}
+    try:
+        if isinstance(raw, str):
+            items = json.loads(raw)
+        else:
+            items = raw
+    except (json.JSONDecodeError, TypeError):
+        return {}
+    result: dict[str, float] = {}
+    for item in items:
+        key = item.get("Key")
+        if not key:
+            continue
+        sv = item.get("SerializedValue")
+        try:
+            sv_obj = json.loads(sv) if isinstance(sv, str) else (sv or {})
+            val = sv_obj.get("Value", 0.0)
+            result[key] = float(val) if val is not None else 0.0
+        except (json.JSONDecodeError, TypeError, ValueError):
+            result[key] = 0.0
+    return result
+
+
+def generate_lua(
+    graph: MelonGraph,
+    *,
+    max_gate_iter: int = 32,
+    chip_meta: dict[str, Any] | None = None,
+) -> str:
+    meta = chip_meta or {}
+    # Inject chip_variables so emit_variable can look up user-set values
+    set_chip_variables(_parse_chip_variables(meta.get("chip_variables")))
+    wires = _wire_inputs(graph)
+    var_uid_map = _build_var_uid_map(graph)
+    lines: list[str] = [
+        "-- @vp_generated Melon 36.x VPchip subset (C1)",
+        f"-- nodes={len(graph.nodes)} edges={len(graph.edges)}",
+    ]
+    if meta.get("instanceId"):
+        lines.append(f"-- instanceId={meta['instanceId']}")
+    lines.extend(
+        [
+            "local G = {}",
+            f"local chip_tps = {int(meta.get('tps', 20))}",
+            "",
+            "function OnInit()",
+            "end",
+            "",
+            "function OnTick()",
+            "  G._vp_tick = (G._vp_tick or 0) + 1",
+        ]
+    )
+
+    unimplemented: set[str] = set()
+
+    for uid in graph.topo_order:
+        n = graph.nodes[uid]
+        if emitter := REGISTRY.get(n.name):
+            ins = _input_exprs(n, uid, wires, graph, var_uid_map)
+            lines.extend(emitter(uid, ins, n))
+        else:
+            unimplemented.add(n.name)
+            lines.append(f"  -- TODO VP node {n.name} op={n.operation_type} uid={uid}")
+
+    lines.extend(["end", ""])
+    if unimplemented:
+        lines.insert(
+            2,
+            "-- TODO unimplemented: " + ", ".join(sorted(unimplemented)),
+        )
+    return "\n".join(lines)
+
+
+def _input_exprs(
+    n: VPNode,
+    uid: str,
+    wires: dict[str, dict[int, str]],
+    graph: MelonGraph,
+    var_uid_map: dict[str, str] | None = None,
+) -> list[str]:
+    wired = wires.get(uid, {})
+    # If this node consumes vectors, prefer _vec suffix from entity_read nodes
+    want_vec = _is_vector_node(n)
+    exprs: list[str] = []
+    for i, inp in enumerate(n.inputs):
+        if i in wired:
+            from_uid = wired[i]
+            # Redirect Variable node references to their shared key
+            if var_uid_map and from_uid in var_uid_map:
+                shared_key = var_uid_map[from_uid]
+                exprs.append(f'G["{shared_key}"]')
+                continue
+            from_node = graph.nodes.get(from_uid)
+            if want_vec and from_node and from_node.name in ("Position", "Velocity", "Elevation"):
+                exprs.append(f'G["{from_uid}_vec"]')
+            else:
+                exprs.append(f'G["{from_uid}"]')
+        else:
+            exprs.append("0")
+    return exprs

melon_lua/vpcompile/compile.py

@@ -0,0 +1,20 @@
+"""Public compile entry."""
+from __future__ import annotations
+
+from typing import Any
+
+from .codegen import generate_lua
+from .graph import parse_chip_graph
+
+
+def compile_vp_graph(
+    graph: dict[str, Any],
+    *,
+    tps: int = 20,
+    max_gate_iter: int = 32,
+    chip_meta: dict[str, Any] | None = None,
+) -> str:
+    ir = parse_chip_graph(graph)
+    meta = dict(chip_meta or {})
+    meta.setdefault("tps", tps)
+    return generate_lua(ir, max_gate_iter=max_gate_iter, chip_meta=meta)

melon_lua/vpcompile/graph.py

@@ -0,0 +1,112 @@
+"""Parse chip_graph JSON from VPchip saveMetaDatas."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .ir import MelonGraph, VPEdge, VPNode
+from .ops import op_name
+
+_UUID_RE = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+    re.I,
+)
+
+
+def _short_uid(full_id: str) -> str:
+    m = _UUID_RE.search(full_id or "")
+    if m:
+        return m.group(0)[:8]
+    return re.sub(r"[^a-zA-Z0-9_]", "_", (full_id or "n")[:32])
+
+
+def parse_chip_graph(graph: dict[str, Any]) -> MelonGraph:
+    nodes: dict[str, VPNode] = {}
+    edges: list[VPEdge] = []
+    full_to_uid: dict[str, str] = {}
+
+    for raw_n in graph.get("Nodes") or []:
+        full_id = str(raw_n.get("Id") or "")
+        op_val = raw_n.get("OperationType", 0)
+        if isinstance(op_val, str):
+            if op_val.isdigit():
+                op = int(op_val)
+            else:
+                from .ops import NAME_TO_OP
+                op = NAME_TO_OP.get(op_val, 0)
+        else:
+            op = int(op_val)
+        name = op_name(op, full_id)
+        uid = f"{name}_{_short_uid(full_id)}"
+        full_to_uid[full_id] = uid
+        nodes[uid] = VPNode(
+            uid=uid,
+            name=name,
+            operation_type=op,
+            full_id=full_id,
+            inputs=list(raw_n.get("Inputs") or []),
+            outputs=list(raw_n.get("Outputs") or []),
+            save_data=raw_n.get("SaveData"),
+            raw=raw_n,
+        )
+
+    for raw_n in graph.get("Nodes") or []:
+        to_full = str(raw_n.get("Id") or "")
+        to_uid = full_to_uid.get(to_full)
+        if not to_uid:
+            continue
+        to_name = nodes[to_uid].name
+        for inp in raw_n.get("Inputs") or []:
+            co = inp.get("connectedOutputIdModel")
+            if not co:
+                continue
+            from_full = str(co.get("NodeId") or "")
+            from_uid = full_to_uid.get(from_full)
+            if from_uid:
+                edges.append(
+                    VPEdge(
+                        from_node=from_uid,
+                        to_node=to_uid,
+                        from_port=str(co.get("Id") or "")[:48],
+                        to_port=str(inp.get("Id") or "")[:48],
+                    )
+                )
+
+    topo = _topo_sort(nodes, edges)
+    vs_raw = graph.get("ValidationState", 0)
+    if isinstance(vs_raw, str):
+        vs_map = {"Valid": 0, "Invalid": 1, "Warning": 2}
+        validation_state = vs_map.get(vs_raw, 0)
+    else:
+        validation_state = int(vs_raw)
+    return MelonGraph(
+        validation_state=validation_state,
+        nodes=nodes,
+        edges=edges,
+        topo_order=topo,
+    )
+
+
+def _topo_sort(nodes: dict[str, VPNode], edges: list[VPEdge]) -> list[str]:
+    indeg = {uid: 0 for uid in nodes}
+    adj: dict[str, list[str]] = {uid: [] for uid in nodes}
+    for e in edges:
+        if e.from_node in indeg and e.to_node in indeg:
+            adj[e.from_node].append(e.to_node)
+            indeg[e.to_node] += 1
+    q = [u for u, d in indeg.items() if d == 0]
+    order: list[str] = []
+    while q:
+        u = q.pop(0)
+        order.append(u)
+        for v in adj.get(u, []):
+            indeg[v] -= 1
+            if indeg[v] == 0:
+                q.append(v)
+    for u in nodes:
+        if u not in order:
+            order.append(u)
+    return order
+
+
+from .save_data import constant_value  # noqa: F401 — re-export

melon_lua/vpcompile/ir.py

@@ -0,0 +1,33 @@
+"""Intermediate representation for VPchip graphs."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class VPEdge:
+    from_node: str
+    to_node: str
+    from_port: str = ""
+    to_port: str = ""
+
+
+@dataclass
+class VPNode:
+    uid: str
+    name: str
+    operation_type: int
+    full_id: str
+    inputs: list[dict[str, Any]] = field(default_factory=list)
+    outputs: list[dict[str, Any]] = field(default_factory=list)
+    save_data: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class MelonGraph:
+    validation_state: int
+    nodes: dict[str, VPNode]
+    edges: list[VPEdge]
+    topo_order: list[str] = field(default_factory=list)

melon_lua/vpcompile/nodes/__init__.py

@@ -0,0 +1,22 @@
+"""VP node name → Lua emitter registry (sharded by domain)."""
+from __future__ import annotations
+
+from ._base import NodeEmitter
+from .entity_read import ENTITY_READ_EMITTERS
+from .entity_write import ENTITY_WRITE_EMITTERS
+from .flow import FLOW_EMITTERS
+from .logic import LOGIC_EMITTERS
+from .math_basic import MATH_BASIC_EMITTERS
+from .math_trig import MATH_TRIG_EMITTERS
+from .vector import VECTOR_EMITTERS
+
+REGISTRY: dict[str, NodeEmitter] = {}
+REGISTRY.update(MATH_BASIC_EMITTERS)
+REGISTRY.update(MATH_TRIG_EMITTERS)
+REGISTRY.update(VECTOR_EMITTERS)
+REGISTRY.update(FLOW_EMITTERS)
+REGISTRY.update(LOGIC_EMITTERS)
+REGISTRY.update(ENTITY_READ_EMITTERS)
+REGISTRY.update(ENTITY_WRITE_EMITTERS)
+
+__all__ = ["REGISTRY", "NodeEmitter"]

melon_lua/vpcompile/nodes/_base.py

@@ -0,0 +1,8 @@
+"""Shared types for VP node Lua emitters."""
+from __future__ import annotations
+
+from typing import Callable
+
+from ..ir import VPNode
+
+NodeEmitter = Callable[[str, list[str], VPNode], list[str]]

melon_lua/vpcompile/nodes/entity_read.py

@@ -0,0 +1,164 @@
+"""Shard D: entity read NodeOperationType emitters (Entity(1) placeholder)."""
+from __future__ import annotations
+
+from ..ir import VPNode
+from ._base import NodeEmitter
+
+
+def _assign(uid: str, expr: str) -> list[str]:
+  return [f'    G["{uid}"] = {expr}']
+
+
+def _g(i: int, ins: list[str], default: str = "0") -> str:
+  return ins[i] if i < len(ins) else default
+
+
+def _ent(ins: list[str], idx: int = 0) -> str:
+  if idx < len(ins):
+      return f"Entity(({_g(idx, ins)}))"
+  return "Entity(1)"
+
+
+def _emit_multi_xy(
+  uid: str,
+  ins: list[str],
+  n: VPNode,
+  *,
+  call: str,
+  ent_idx: int = 0,
+) -> list[str]:
+  """Emit position/velocity: scalar x as primary, x/y components in _o0/_o1.
+  Also store vector form in _vec for downstream vector nodes."""
+  e = _ent(ins, ent_idx)
+  outs = n.outputs or []
+  lines = [f"    local _vx, _vy = {call}"]
+  # Primary output is scalar x (backward compat with scalar chips)
+  lines.append(f'  G["{uid}"] = _vx')
+  # Component outputs
+  if len(outs) >= 2:
+      lines.append(f'  G["{uid}_o0"] = _vx')
+      lines.append(f'  G["{uid}_o1"] = _vy')
+  # Vector form for downstream vector nodes
+  lines.append(f'  G["{uid}_vec"] = {{x = _vx, y = _vy, z = 0, w = 0}}')
+  return lines
+
+
+def emit_position(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _emit_multi_xy(uid, ins, n, call=f"{e}:getPosition()")
+
+
+def emit_velocity(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _emit_multi_xy(uid, ins, n, call=f"{e}:getVelocity()")
+
+
+def emit_angular_velocity(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getAngularVelocity()")
+
+
+def emit_entity_angle(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getAngle()")
+
+
+def emit_elevation(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  tx, ty = _g(1, ins), _g(2, ins)
+  return _assign(uid, f"{e}:getElevation(({tx}), ({ty}))")
+
+
+def emit_mass(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getMass()")
+
+
+def emit_size(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _emit_multi_xy(uid, ins, n, call=f"{e}:getSize()")
+
+
+def emit_entity_id(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getId()")
+
+
+def emit_color(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  outs = n.outputs or []
+  lines = [f"    local _cr, _cg, _cb, _ca = {e}:getColor()"]
+  keys = ("r", "g", "b", "a")
+  for i in range(min(4, max(1, len(outs)))):
+      var = ("_cr", "_cg", "_cb", "_ca")[i]
+      lines.append(f'  G["{uid}_o{i}"] = {var}')
+      lines.append(f'  G["{uid}_{keys[i]}"] = {var}')
+  if not outs:
+      lines.append(f'  G["{uid}"] = _cr')
+  return lines
+
+
+def emit_temperature(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getTemperature()")
+
+
+def emit_voltage(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getVoltage()")
+
+
+def emit_entity_name(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f'{e}:getName() or ""')
+
+
+def emit_mass_center(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _emit_multi_xy(uid, ins, n, call=f"{e}:getCenterOfMass()")
+
+
+def emit_velocity_at_position(uid: str, ins: list[str], n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  px, py = _g(1, ins), _g(2, ins)
+  call = f"{e}:getVelocityAtPoint(({px}), ({py}))"
+  return _emit_multi_xy(uid, ins, n, call=call)
+
+
+def emit_gravity(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:getGravityScale()")
+
+
+def emit_can_be_activated(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return _assign(uid, f"{e}:canBeActivated()")
+
+
+def emit_collision(uid: str, ins: list[str], _n: VPNode) -> list[str]:
+  e = _ent(ins, 0)
+  return [
+      f"    -- Collision {uid}: read stub (collision state not exposed on Entity API)",
+      f'    G["{uid}"] = 0',
+      f"    -- entity {e} collision queries need subscribeCollision* at runtime",
+  ]
+
+
+ENTITY_READ_EMITTERS: dict[str, NodeEmitter] = {
+  "Position": emit_position,
+  "Velocity": emit_velocity,
+  "AngularVelocity": emit_angular_velocity,
+  "EntityAngle": emit_entity_angle,
+  "Elevation": emit_elevation,
+  "Mass": emit_mass,
+  "Size": emit_size,
+  "EntityID": emit_entity_id,
+  "Color": emit_color,
+  "Temperature": emit_temperature,
+  "Voltage": emit_voltage,
+  "EntityName": emit_entity_name,
+  "MassCenter": emit_mass_center,
+  "VelocityAtPosition": emit_velocity_at_position,
+  "CanBeActivated": emit_can_be_activated,
+  "Collision": emit_collision,
+}