melon-lua 3.4.0__py3-none-any.whl

melon_lua/session.py

@@ -0,0 +1,396 @@
+"""High-level session: bind a .melsave file to a sandbox lifecycle.
+
+A `MelsaveSession` owns the full pipeline: read the save, spawn its objects
+into a WorldContext, compile/run Lua chips against that world, create/remove
+ropes, snapshot state, and write the modified scene back to a new .melsave.
+
+Typical agent workflow::
+
+    from melon_lua import MelsaveSession
+
+    session = MelsaveSession("input.melsave")
+    session.load()
+    session.run_chip(chip_source, ticks=100)
+    session.create_rope(from_id=1, to_id=2, kind="Simple")
+    snap = session.snapshot()
+    session.save_as("output.melsave")
+    session.close()
+
+The original `MelsaveDocument` is held internally so `save_as` can diff the
+live world against it without the caller managing references.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from .melsave import MelsaveDocument, read_melsave, spawn_document_into_world
+from .melsave_writer import write_world_to_melsave, build_diff_from_world
+from .world import WorldContext
+from .runner import MelonScriptRunner
+
+
+class MelsaveSession:
+    """One session = one save file + one world + one chip runner.
+
+    Lifecycle: created -> load() -> [run_chip / create_rope / snapshot]* ->
+    save_as() -> close().
+    """
+
+    def __init__(
+        self,
+        melsave_path: str | Path,
+        *,
+        tps: float = 20.0,
+        quiet: bool = True,
+    ):
+        self.melsave_path = Path(melsave_path)
+        self.tps = float(tps)
+        self._quiet = bool(quiet)
+        self._doc: Optional[MelsaveDocument] = None
+        self._world: Optional[WorldContext] = None
+        self._runner: Optional[MelonScriptRunner] = None
+        self._loaded = False
+
+    # ===== Lifecycle =====
+
+    def load(self) -> "MelsaveSession":
+        """Read the melsave, spawn all objects into a fresh world, build runner."""
+        if self._loaded:
+            return self
+        self._doc = read_melsave(self.melsave_path)
+        self._world = WorldContext()
+        spawn_document_into_world(self._doc, self._world)
+        self._runner = MelonScriptRunner(
+            tps=self.tps,
+            world=self._world,
+            quiet=self._quiet,
+        )
+        # Load existing mechanic gate wires from the save's raw constraints
+        self._load_gate_wires_from_doc()
+        self._loaded = True
+        return self
+
+    def _load_gate_wires_from_doc(self) -> None:
+        """Populate ``world.gate_wires`` from the document's raw constraints."""
+        assert self._world is not None
+        assert self._doc is not None
+        first = True
+        for obj in self._doc.objects:
+            raw = getattr(obj, "raw", None) or {}
+            cs = raw.get("constraints")
+            if not isinstance(cs, list) or not cs:
+                continue
+            self._world.gate_wires.from_constraint_dicts(cs, append=not first)
+            first = False
+
+    def close(self) -> None:
+        """Release the Box2D world and Lua VM. Idempotent."""
+        if self._world is not None:
+            self._world.b2_world = None
+            self._world._b2_bodies.clear()
+            self._world._b2_joints.clear()
+        self._runner = None
+        self._world = None
+        self._doc = None
+        self._loaded = False
+
+    def __enter__(self) -> "MelsaveSession":
+        return self.load()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    # ===== Chip execution =====
+
+    def run_chip(
+        self,
+        source: str,
+        *,
+        ticks: int = 1,
+        inputs: Optional[dict] = None,
+        chunk_name: str = "@session_chip.lua",
+    ) -> dict:
+        """Compile a Lua chip and run it for `ticks` ticks. Returns last tick result.
+
+        If ticks == 0, only compiles + calls OnInit (no OnTick). If ticks >= 1,
+        OnInit is called first, then OnTick runs `ticks` times.
+        """
+        self._require_loaded()
+        r = self._runner
+        assert r is not None
+        if not r.compile(source, chunk_name=chunk_name):
+            return {"error": r.last_error or "compile failed", "outputs": {}}
+        r.call_on_init()
+        if ticks <= 0:
+            return {"error": None, "outputs": r.get_outputs()}
+        if ticks == 1:
+            return r.run_tick(inputs=inputs)
+        provider = (lambda i: inputs) if inputs is not None else None
+        r.run_loop(ticks=ticks, inputs_provider=provider)
+        return {"error": r.last_error, "outputs": r.get_outputs()}
+
+    def compile_only(self, source: str, chunk_name: str = "@session_chip.lua") -> bool:
+        """Compile a chip without running. Returns True on success."""
+        self._require_loaded()
+        assert self._runner is not None
+        return self._runner.compile(source, chunk_name=chunk_name)
+
+    def tick(self, inputs: Optional[dict] = None) -> dict:
+        """Run a single OnTick on the already-compiled chip."""
+        self._require_loaded()
+        assert self._runner is not None
+        return self._runner.run_tick(inputs=inputs)
+
+    # ===== Entity / world access =====
+
+    @property
+    def world(self) -> WorldContext:
+        self._require_loaded()
+        assert self._world is not None
+        return self._world
+
+    @property
+    def runner(self) -> MelonScriptRunner:
+        self._require_loaded()
+        assert self._runner is not None
+        return self._runner
+
+    @property
+    def document(self) -> MelsaveDocument:
+        self._require_loaded()
+        assert self._doc is not None
+        return self._doc
+
+    def entities(self) -> list[dict]:
+        """Snapshot list of alive entities: {entity_id, local_id, object_id, name, x, y, angle}."""
+        self._require_loaded()
+        assert self._world is not None
+        out = []
+        for e in self._world.entities.values():
+            if not getattr(e, "alive", True):
+                continue
+            out.append({
+                "entity_id": e.entity_id,
+                "local_id": e.local_id,
+                "object_id": e.object_id,
+                "name": e.name,
+                "x": float(e.position_x),
+                "y": float(e.position_y),
+                "angle": float(e.angle),
+            })
+        return out
+
+    def get_entity(self, entity_id: int):
+        return self._world.get_entity(entity_id) if self._world else None
+
+    def spawn(self, name_or_id, x: float = 0.0, y: float = 0.0, **kw):
+        """Spawn a new entity into the world. Returns the Entity."""
+        self._require_loaded()
+        assert self._world is not None
+        return self._world.spawn_entity(name_or_id, x, y, **kw)
+
+    def remove(self, entity_id: int) -> bool:
+        """Remove an entity. Returns True if it existed."""
+        self._require_loaded()
+        assert self._world is not None
+        e = self._world.entities.get(entity_id)
+        if e is None:
+            return False
+        self._world.remove_entity(entity_id)
+        return True
+
+    # ===== Ropes / constraints =====
+
+    def create_rope(
+        self,
+        from_id: int,
+        to_id: int,
+        kind: str | int = "Simple",
+        **params,
+    ) -> int:
+        """Create a rope/constraint between two entities. Returns constraint_id."""
+        self._require_loaded()
+        assert self._world is not None
+        return self._world.create_rope(from_id, to_id, kind, **params)
+
+    def remove_rope(self, constraint_id: int) -> bool:
+        """Alias for destroy_rope. Removes a rope and its Box2D joint."""
+        self._require_loaded()
+        assert self._world is not None
+        return self._world.destroy_rope(constraint_id)
+
+    def set_rope_param(self, constraint_id: int, key: str, value) -> bool:
+        self._require_loaded()
+        assert self._world is not None
+        return self._world.set_rope_param(constraint_id, key, value)
+
+    def ropes(self) -> list[dict]:
+        """List all constraints in the registry."""
+        self._require_loaded()
+        assert self._world is not None
+        reg = self._world.constraints
+        from .constraints import KIND_IDS
+        out = []
+        for cid, c in reg._constraints.items():
+            out.append({
+                "id": cid,
+                "kind_id": c.constraint_id,
+                "kind": KIND_IDS.get(c.constraint_id, "Unknown"),
+                "start_local_id": c.start_object_id,
+                "end_local_id": c.end_object_id,
+                "distance": c.distance,
+            })
+        return out
+
+    # ===== Mechanic gate wires (signal connections) =====
+
+    def wire_gate(
+        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),
+    ) -> int:
+        """Hot-wire a mechanic gate connection between two containers.
+
+        Adds a signal wire from ``output_gate`` on container ``source_idx``
+        to ``input_gate`` on container ``target_idx``. The wire lives in the
+        session's ``GateWireRegistry`` and is serialized on ``save_as()``.
+
+        Args:
+            source_idx: Container index of the source (output) object.
+            output_gate: Output gate name on the source object.
+            target_idx: Container index of the target (input) object.
+            input_gate: Input gate name on the target object.
+            name: Optional display name for the wire.
+            start_point: Visual offset of the source port (local space).
+            end_point: Visual offset of the target port (local space).
+
+        Returns:
+            The wire_id (auto-incremented).
+        """
+        self._require_loaded()
+        assert self._world is not None
+        return self._world.gate_wires.connect(
+            source_idx, output_gate, target_idx, input_gate,
+            name=name, start_point=start_point, end_point=end_point,
+        )
+
+    def unwire_gate(
+        self,
+        wire_id: int | None = None,
+        *,
+        source_idx: int | None = None,
+        target_idx: int | None = None,
+        output_gate: str | None = None,
+        input_gate: str | None = None,
+    ) -> int:
+        """Hot-disconnect gate wire(s).
+
+        If ``wire_id`` is given, removes that specific wire.
+        Otherwise removes all wires matching the filter combination.
+        Returns the number of wires removed.
+        """
+        self._require_loaded()
+        assert self._world is not None
+        if wire_id is not None:
+            return 1 if self._world.gate_wires.disconnect(wire_id) else 0
+        return self._world.gate_wires.disconnect_matching(
+            source_idx=source_idx,
+            target_idx=target_idx,
+            output_gate=output_gate,
+            input_gate=input_gate,
+        )
+
+    def wires(self) -> list[dict]:
+        """List all gate wires in the registry."""
+        self._require_loaded()
+        assert self._world is not None
+        out = []
+        for w in self._world.gate_wires.list_all():
+            out.append({
+                "wire_id": w.wire_id,
+                "source_idx": w.source_idx,
+                "target_idx": w.target_idx,
+                "output_gate": w.output_gate,
+                "input_gate": w.input_gate,
+                "name": w.name,
+            })
+        return out
+
+    # ===== Snapshot / diff =====
+
+    def snapshot(self) -> dict:
+        """Return a serializable snapshot of the current world state."""
+        self._require_loaded()
+        assert self._world is not None
+        w = self._world
+        return {
+            "tick": w.current_tick,
+            "elapsed": w.elapsed_time,
+            "entities": self.entities(),
+            "ropes": self.ropes(),
+            "variables": dict(w.chip_variables),
+            "entity_count": sum(1 for e in w.entities.values() if getattr(e, "alive", True)),
+        }
+
+    def diff(self) -> dict:
+        """Return the WorldDiff as a plain dict (for inspection/logging)."""
+        self._require_loaded()
+        assert self._world is not None
+        assert self._doc is not None
+        d = build_diff_from_world(self._world, self._doc)
+        return {
+            "modified": {str(k): v for k, v in d.modified_objects.items()},
+            "added_count": len(d.added_objects),
+            "removed": sorted(d.removed_local_ids),
+            "constraint_lids": sorted(d.modified_constraints.keys()),
+        }
+
+    # ===== Write back =====
+
+    def save_as(
+        self,
+        out_path: str | Path,
+        *,
+        write_icon: bool = True,
+    ) -> Path:
+        """Diff the live world against the original save and write a new .melsave."""
+        self._require_loaded()
+        assert self._world is not None
+        assert self._doc is not None
+        return write_world_to_melsave(
+            self._world,
+            self._doc,
+            out_path,
+            write_icon=write_icon,
+        )
+
+    # ===== Logs / errors =====
+
+    @property
+    def logs(self) -> list:
+        self._require_loaded()
+        assert self._runner is not None
+        return self._runner.logs
+
+    @property
+    def last_error(self) -> Optional[str]:
+        return self._runner.last_error if self._runner else None
+
+    @property
+    def outputs(self) -> dict:
+        self._require_loaded()
+        assert self._runner is not None
+        return self._runner.get_outputs()
+
+    # ===== Internal =====
+
+    def _require_loaded(self) -> None:
+        if not self._loaded or self._world is None or self._runner is None or self._doc is None:
+            raise RuntimeError("MelsaveSession not loaded; call .load() or use as context manager")

melon_lua/spawn_queue.py

@@ -0,0 +1,190 @@
+"""Spawn requests — spawn.create returns requestId; entities created immediately (no artificial delay)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+from .catalog import resolve_spawn_name
+from .entity import Entity
+from .world import WorldContext
+
+SpawnKind = Literal["create", "clone", "clone_temp", "save", "mod"]
+
+
+@dataclass
+class SpawnOp:
+    request_id: int
+    kind: SpawnKind
+    alias_or_name: str = ""
+    x: float = 0.0
+    y: float = 0.0
+    angle: Optional[float] = None
+    object_id: Optional[int] = None
+    clone_entity_id: Optional[int] = None
+    save_or_mod_name: str = ""
+    dynamic: bool = True
+
+
+@dataclass
+class SpawnQueue:
+    world: WorldContext
+    pending_ops: list[SpawnOp] = field(default_factory=list)
+    _ready_callbacks: list[tuple[int, list[int]]] = field(default_factory=list)
+
+    def allocate_request_id(self) -> int:
+        self.world.spawn_request_counter += 1
+        rid = self.world.spawn_request_counter
+        self.world.spawn_requests[rid] = []
+        return rid
+
+    def enqueue_create(
+        self,
+        alias_or_name: str,
+        x: float,
+        y: float,
+        angle: Optional[float] = None,
+    ) -> int:
+        key = str(alias_or_name).strip()
+        oid = int(key) if key.isdigit() else None
+        rid = self.allocate_request_id()
+        op = SpawnOp(
+            request_id=rid,
+            kind="create",
+            alias_or_name=key,
+            x=float(x),
+            y=float(y),
+            angle=angle,
+            object_id=oid,
+        )
+        ent_ids = self._execute_one(op)
+        self.world.spawn_requests[rid] = ent_ids
+        self._ready_callbacks.append((rid, ent_ids))
+        return rid
+
+    def enqueue_clone(
+        self,
+        entity_id: int,
+        x: float,
+        y: float,
+        *,
+        temp: bool = False,
+    ) -> int:
+        rid = self.allocate_request_id()
+        op = SpawnOp(
+            request_id=rid,
+            kind="clone_temp" if temp else "clone",
+            x=float(x),
+            y=float(y),
+            clone_entity_id=int(entity_id),
+        )
+        ent_ids = self._execute_one(op)
+        self.world.spawn_requests[rid] = ent_ids
+        self._ready_callbacks.append((rid, ent_ids))
+        return rid
+
+    def enqueue_save(self, name: str, x: float, y: float) -> int:
+        rid = self.allocate_request_id()
+        op = SpawnOp(
+            request_id=rid,
+            kind="save",
+            x=float(x),
+            y=float(y),
+            save_or_mod_name=str(name),
+        )
+        ent_ids = self._execute_one(op)
+        self.world.spawn_requests[rid] = ent_ids
+        self._ready_callbacks.append((rid, ent_ids))
+        return rid
+
+    def enqueue_mod(self, name: str, x: float, y: float) -> int:
+        rid = self.allocate_request_id()
+        op = SpawnOp(
+            request_id=rid,
+            kind="mod",
+            x=float(x),
+            y=float(y),
+            save_or_mod_name=str(name),
+        )
+        ent_ids = self._execute_one(op)
+        self.world.spawn_requests[rid] = ent_ids
+        self._ready_callbacks.append((rid, ent_ids))
+        return rid
+
+    def flush(self) -> list[tuple[int, list[int]]]:
+        """Fire OnSpawned for entities already created this frame."""
+        results = list(self._ready_callbacks)
+        self._ready_callbacks = []
+        for op in self.pending_ops:
+            ent_ids = self._execute_one(op)
+            self.world.spawn_requests[op.request_id] = ent_ids
+            results.append((op.request_id, ent_ids))
+        self.pending_ops = []
+        return results
+
+    def _execute_one(self, op: SpawnOp) -> list[int]:
+        w = self.world
+        if op.kind in ("clone", "clone_temp"):
+            src = w.get_entity(op.clone_entity_id or 0)
+            if not src:
+                return []
+            e = w.spawn_entity(
+                name=src.name,
+                x=op.x,
+                y=op.y,
+                object_id=src.object_id,
+                dynamic=op.kind != "clone_temp" or True,
+            )
+            self._copy_entity_state(src, e, temp=op.kind == "clone_temp")
+            w.sync_body_from_entity(e.entity_id)
+            return [e.entity_id]
+
+        if op.kind == "save":
+            display = f"[save]{op.save_or_mod_name}"
+            e = w.spawn_entity(display, op.x, op.y, dynamic=True)
+            if op.angle is not None:
+                e.angle = float(op.angle)
+            return [e.entity_id]
+
+        if op.kind == "mod":
+            display = f"[mod]{op.save_or_mod_name}"
+            e = w.spawn_entity(display, op.x, op.y, dynamic=True)
+            if op.angle is not None:
+                e.angle = float(op.angle)
+            return [e.entity_id]
+
+        resolved = resolve_spawn_name(op.alias_or_name) or op.alias_or_name
+        e = w.spawn_entity(
+            name=resolved,
+            x=op.x,
+            y=op.y,
+            object_id=op.object_id,
+            dynamic=op.dynamic,
+        )
+        if op.angle is not None:
+            e.angle = float(op.angle)
+            if w.get_body(e.entity_id) is not None:
+                import math
+
+                body = w.get_body(e.entity_id)
+                if body is not None:
+                    body.angle = math.radians(float(op.angle))
+        return [e.entity_id]
+
+    @staticmethod
+    def _copy_entity_state(src: Entity, dst: Entity, *, temp: bool) -> None:
+        dst.scale_x = src.scale_x
+        dst.scale_y = src.scale_y
+        dst.angle = src.angle
+        dst.mass = src.mass
+        dst.gravity_scale = src.gravity_scale
+        dst.velocity_x = src.velocity_x if not temp else 0.0
+        dst.velocity_y = src.velocity_y if not temp else 0.0
+        dst.angular_velocity = src.angular_velocity if not temp else 0.0
+        dst.color_r, dst.color_g, dst.color_b, dst.color_a = (
+            src.color_r,
+            src.color_g,
+            src.color_b,
+            src.color_a,
+        )
+        dst.temperature = src.temperature
+        dst.health = src.health

melon_lua/stdlib_bit32_shim.lua

@@ -0,0 +1,105 @@
+-- Full bit32 for melon (Lua 5.2); works without LuaJIT `bit` library
+if bit32 ~= nil and type(bit32.band) == 'function' and type(bit32.btest) == 'function' then
+    return
+end
+
+local function to_u32(n)
+    n = math.floor(tonumber(n) or 0)
+    if n < 0 then n = n + 4294967296 end
+    return n % 4294967296
+end
+
+local function band(a, b)
+    a, b = to_u32(a), to_u32(b)
+    local r, p = 0, 1
+    for _ = 1, 32 do
+        if a % 2 == 1 and b % 2 == 1 then r = r + p end
+        a, b = math.floor(a / 2), math.floor(b / 2)
+        p = p * 2
+    end
+    return r
+end
+
+local function bor(a, b)
+    a, b = to_u32(a), to_u32(b)
+    local r, p = 0, 1
+    for _ = 1, 32 do
+        if a % 2 == 1 or b % 2 == 1 then r = r + p end
+        a, b = math.floor(a / 2), math.floor(b / 2)
+        p = p * 2
+    end
+    return r
+end
+
+local function bxor(a, b)
+    a, b = to_u32(a), to_u32(b)
+    local r, p = 0, 1
+    for _ = 1, 32 do
+        if a % 2 ~= b % 2 then r = r + p end
+        a, b = math.floor(a / 2), math.floor(b / 2)
+        p = p * 2
+    end
+    return r
+end
+
+local function bnot(a)
+    return to_u32(4294967295 - to_u32(a))
+end
+
+local function lshift(a, n)
+    return to_u32(to_u32(a) * (2 ^ (n % 32)))
+end
+
+local function rshift(a, n)
+    return math.floor(to_u32(a) / (2 ^ (n % 32)))
+end
+
+local function arshift(a, n)
+    a = to_u32(a)
+    n = n % 32
+    if a >= 2147483648 then
+        return to_u32(math.floor(a / (2 ^ n)) + (2 ^ (32 - n) - 1) * (2 ^ n))
+    end
+    return rshift(a, n)
+end
+
+bit32 = {
+    band = function(...) local a = select(1, ...); for i = 2, select('#', ...) do a = band(a, select(i, ...)) end; return a end,
+    bor = function(...) local a = select(1, ...); for i = 2, select('#', ...) do a = bor(a, select(i, ...)) end; return a end,
+    bxor = function(...) local a = select(1, ...); for i = 2, select('#', ...) do a = bxor(a, select(i, ...)) end; return a end,
+    bnot = bnot,
+    lshift = lshift,
+    rshift = rshift,
+    arshift = arshift,
+    lrotate = function(x, disp)
+        x, disp = to_u32(x), disp % 32
+        return to_u32(bor(lshift(x, disp), rshift(x, 32 - disp)))
+    end,
+    rrotate = function(x, disp)
+        x, disp = to_u32(x), disp % 32
+        return to_u32(bor(rshift(x, disp), lshift(x, 32 - disp)))
+    end,
+    btest = function(...)
+        local n = select('#', ...)
+        if n < 1 then return false end
+        local acc = to_u32(select(1, ...))
+        for i = 2, n do acc = band(acc, to_u32(select(i, ...))) end
+        return acc ~= 0
+    end,
+    extract = function(n, field, width)
+        n = to_u32(n)
+        field = field or 0
+        width = width or 1
+        local mask = lshift(1, width) - 1
+        return band(rshift(n, field), mask)
+    end,
+    replace = function(n, v, field, width)
+        n, v = to_u32(n), to_u32(v)
+        field = field or 0
+        width = width or 1
+        local mask = lshift(1, width) - 1
+        v = band(v, mask)
+        local cleared = band(n, bnot(lshift(mask, field)))
+        return to_u32(cleared + lshift(v, field))
+    end,
+}