marble-v1 0.1.0__py3-none-any.whl

marble_v1/__init__.py

@@ -0,0 +1,3 @@
+from marble_v1.taskset import MarbleTaskset
+
+__all__ = ["MarbleTaskset"]

marble_v1/levels.py

@@ -0,0 +1,169 @@
+"""Level generation: solvable by construction.
+
+## Why levels are built forwards, not designed
+
+A level is only useful here if a solution is known to exist — an unsolvable task
+teaches a model nothing and is indistinguishable, from the outside, from a task
+the model simply failed. Designing a layout and then hunting for its solution
+gets that backwards and is expensive.
+
+So each piece is placed where the marble *actually is*. Simulate what has been
+built so far, read the path, drop the next piece onto it, and check the marble
+really strikes it. Repeat. The layout that comes out is a solution, and the ring
+goes wherever that solution ends up. Difficulty is the piece count.
+
+The one rule that keeps a level honest: **every piece must be struck.** A piece
+the marble sails past is a piece the level does not need, which would make the
+stated inventory a lie and quietly hand the model an easier task than the label
+claims.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from marble_v1.sim import (
+    ANCHOR,
+    MIN_SEPARATION,
+    POSITION_STEP,
+    ROTATION_STEP,
+    Kind,
+    Level,
+    Placement,
+    Verdict,
+    simulate,
+)
+
+DEEP = -20_000.0        # a ring far below everything: lets a run play out fully
+RING_DROP = 420.0       # how far under the last piece the ring sits
+MAX_ROT_STEPS = 6       # +/- 45 degrees, in 7.5 degree units
+FIRST_DEPTH = 520.0     # the first piece never sits right under the ramp
+
+# How far below the previous piece the next one may sit. The ceiling is the
+# important half: without it a piece can land wherever the marble happens to be
+# after a long fall — one generated level had eleven thousand units of empty air
+# between two pieces, which asks the model to guess where a free-falling marble
+# lands rather than to plan a bounce. A band also keeps runs short, and run
+# length is what generation cost is made of.
+BAND_NEAR = MIN_SEPARATION
+BAND_FAR = 900.0
+
+
+def _snap(v: float) -> float:
+    return round(v / POSITION_STEP) * POSITION_STEP
+
+
+@dataclass(frozen=True)
+class Generated:
+    level: Level
+    solution: list[Placement]
+    seed: int
+
+    @property
+    def pieces(self) -> int:
+        return len(self.solution)
+
+
+def _place_next(
+    rng: random.Random,
+    placements: list[Placement],
+    ceiling_y: float,
+    bounds: float,
+    attempts: int = 40,
+) -> Placement | None:
+    """Drop one more piece onto the current path, and keep it only if the marble
+    actually hits it."""
+    probe = Level(ring_x=0.0, ring_y=DEEP, bounds=bounds)
+    run = simulate(probe, placements, keep_trace=True)
+    # Fair game: below the last piece by at least a marble's worth of room, not
+    # so far below that the puzzle becomes a free-fall estimate, and inside the
+    # strip the player is allowed to build in.
+    lo, hi = ceiling_y - BAND_FAR, ceiling_y - BAND_NEAR
+    candidates = [p for p in run.trace if lo <= p[1] <= hi and abs(p[0]) <= bounds - 40]
+    if not candidates:
+        return None
+
+    for _ in range(attempts):
+        px, py = candidates[rng.randrange(len(candidates))]
+        kind = rng.choice(list(Kind))
+        rot = rng.randint(-MAX_ROT_STEPS, MAX_ROT_STEPS)
+        candidate = Placement(kind, _snap(px), _snap(py - ANCHOR[kind]), rot)
+        trial = placements + [candidate]
+        out = simulate(probe, trial)
+        if len(trial) - 1 in out.struck and out.verdict is Verdict.MISSED:
+            return candidate
+    return None
+
+
+def generate(
+    seed: int,
+    pieces: int,
+    bounds: float = 470.0,
+    ring_half_width: float = 118.0,
+) -> Generated | None:
+    """One level with `pieces` pieces, or None if this seed did not work out.
+
+    Failure is normal and cheap — the caller just moves to the next seed. Trying
+    to force a stubborn seed produces contrived layouts.
+
+    `ring_half_width` is the fine difficulty knob. Piece count alone turned out
+    to be far too coarse: measured on gemini-2.5-pro, one piece solved half the
+    time and two pieces solved none of it, with nothing in between. A wider mouth
+    makes a given piece count easier without changing what the model has to
+    reason about, which is what turns a cliff into a slope.
+    """
+    rng = random.Random(seed)
+    placements: list[Placement] = []
+    ceiling_y = -FIRST_DEPTH
+
+    for _ in range(pieces):
+        nxt = _place_next(rng, placements, ceiling_y, bounds)
+        if nxt is None:
+            return None
+        placements.append(nxt)
+        ceiling_y = nxt.y
+
+    # Where does the finished layout end up? That is where the ring goes.
+    probe = Level(ring_x=0.0, ring_y=DEEP, bounds=bounds)
+    run = simulate(probe, placements, keep_trace=True)
+    ring_y = _snap(min(p.y for p in placements) - RING_DROP)
+    crossing = next((p for p in run.trace if p[1] <= ring_y), None)
+    if crossing is None:
+        return None
+
+    level = Level(
+        ring_x=_snap(crossing[0]),
+        ring_y=ring_y,
+        ring_half_width=ring_half_width,
+        bounds=bounds,
+        inventory=_inventory(placements),
+    )
+
+    # Built forwards, verified backwards: if this does not score, the level is
+    # not what it claims and gets thrown away rather than shipped.
+    if not simulate(level, placements).scored:
+        return None
+    return Generated(level=level, solution=placements, seed=seed)
+
+
+def _inventory(placements: list[Placement]) -> dict[Kind, int]:
+    counts: dict[Kind, int] = {}
+    for p in placements:
+        counts[p.kind] = counts.get(p.kind, 0) + 1
+    return counts
+
+
+def stream(
+    start_seed: int,
+    pieces: int,
+    bounds: float = 470.0,
+    ring_half_width: float = 118.0,
+):
+    """Endless levels of a given size. Seeds that fail are skipped."""
+    seed = start_seed
+    while True:
+        made = generate(seed, pieces, bounds, ring_half_width)
+        seed += 1
+        if made is not None:
+            yield made

marble_v1/sim.py

@@ -0,0 +1,458 @@
+"""The marble simulator, ported from Swift.
+
+## Why this is a port and not a physics engine
+
+The original runs the whole attempt to completion before anything is drawn,
+with a fixed step and analytic contacts, because a layout that can give two
+different answers is a layout nobody can learn from. That property is why the
+game works, and it is also the entire reason this makes a usable RL
+environment: the reward is computed by arithmetic, not by a judge model, so
+there is nothing to talk it out of.
+
+## What was left behind
+
+The Swift original also accumulates a `RunPath` of exact parabolas, logs every
+strike with its strength, and tracks spin — all of it for drawing and for
+sound. None of it can change the outcome, so none of it is here. What survives
+is the physics loop and the verdict.
+
+## Determinism
+
+Bit-identity with the Swift version is deliberately NOT a goal: `sin`, `cos`
+and `atan2` may differ in the last place between platforms, and chasing that
+would cost weeks and buy nothing. What is required is that this module give the
+same answer for the same input on the machine that grades a rollout — which
+plain IEEE-754 doubles in a fixed operation order already provide. The
+consequence, and it matters: reference solutions must be generated by THIS
+simulator, never imported from the Swift one.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from enum import Enum
+
+# ---------------------------------------------------------------- constants
+
+STEP = 1.0 / 240        # fixed, and small: at 240 Hz a marble at full speed
+                        # moves less than its own radius, so it cannot tunnel
+TIME_LIMIT = 26.0
+GRAVITY = 1470.0
+MARBLE_RADIUS = 66.0
+STAR_RADIUS = 66.0
+
+BOUNCE_THRESHOLD = 90.0     # below this closing speed a contact is a roll
+SPRING_IMPULSE = 520.0
+ROLLING_DRAG = 0.0016
+MAX_SPEED = 1750.0
+NO_PROGRESS_LIMIT = 2.6
+STILL_LIMIT = 0.9
+STILL_SPEED = 40.0
+
+RAMP_RESTITUTION = 0.22
+RAMP_FRICTION = 0.90
+RAMP_INDEX = -1
+
+POSITION_STEP = 20.0                # the placement grid
+ROTATION_STEP = math.pi / 24        # 7.5 degrees
+
+LADDER_RADIUS = 470.0
+LADDER_SWEEP = 1.15
+LADDER_THICKNESS = 46.0 + 21.0      # tubeSpacing + tubeWidth
+
+PLATFORM_Y = -300.0
+SURFACE_THICKNESS = 26.0
+PLATFORM_COLLIDER_RADIUS = 8.0      # measured, not chosen — see the Swift note
+OPENING_SPEED = 230.0
+
+# The ramp the marble always starts on. Fixed: a puzzle needs a fixed starting
+# condition, or nothing learned from one attempt carries to the next.
+PLATFORM_CONTROLS = [(-560.0, 46.0), (-260.0, 22.0), (-90.0, -4.0), (10.0, -20.0)]
+PLATFORM_SURFACE = [(x, y + PLATFORM_Y) for x, y in PLATFORM_CONTROLS]
+
+
+class Kind(str, Enum):
+    LADDER = "ladder"
+    SPRING = "spring"
+    DRUM = "drum"
+    BLOCK = "block"
+    BELL = "bell"
+
+
+# size (w, h), restitution, surface friction
+SPEC: dict[Kind, tuple[tuple[float, float], float, float]] = {
+    Kind.LADDER: ((300.0, 120.0), 0.20, 0.985),
+    Kind.SPRING: ((96.0, 132.0), 0.62, 0.88),
+    Kind.DRUM: ((186.0, 76.0), 0.74, 0.93),
+    Kind.BLOCK: ((150.0, 108.0), 0.30, 0.86),
+    Kind.BELL: ((158.0, 82.0), 0.52, 0.91),
+}
+
+# How far below a point on the marble's path a piece's centre must sit for the
+# marble to land on its top face rather than through its middle.
+ANCHOR: dict[Kind, float] = {
+    Kind.LADDER: 0.0,       # the arc positions itself around its own centre
+    Kind.SPRING: 132.0 / 2 + MARBLE_RADIUS - 14,
+    Kind.DRUM: 76.0 / 2 + MARBLE_RADIUS - 10,
+    Kind.BLOCK: 108.0 / 2 + MARBLE_RADIUS - 6,
+    Kind.BELL: 82.0 / 2 + MARBLE_RADIUS - 8,
+}
+
+MIN_SEPARATION = 210.0      # between consecutive pieces, from the original solver
+
+# ---------------------------------------------------------------- colliders
+#
+# Three shapes cover every piece. Kept as plain tuples rather than classes: this
+# runs a few hundred thousand times per attempt.
+
+
+def _clamp(v: float, lo: float, hi: float) -> float:
+    return lo if v < lo else hi if v > hi else v
+
+
+def _segment_contact(px, py, radius, ax, ay, bx, by, bar):
+    """A capsule: a thick line with rounded ends."""
+    rx, ry = bx - ax, by - ay
+    length_sq = rx * rx + ry * ry
+    t = 0.0 if length_sq <= 0 else _clamp(((px - ax) * rx + (py - ay) * ry) / length_sq, 0.0, 1.0)
+    cx, cy = ax + rx * t, ay + ry * t
+    dx, dy = px - cx, py - cy
+    distance = math.hypot(dx, dy)
+    reach = radius + bar
+    if distance >= reach:
+        return None
+    # Dead centre: push straight up rather than dividing by zero. A normal of
+    # NaN would poison the whole run.
+    if distance <= 0.0001:
+        return (0.0, 1.0, reach)
+    return (dx / distance, dy / distance, reach - distance)
+
+
+def _box_contact(px, py, radius, cx, cy, w, h, corner, rotation):
+    """Everything box-like. A drum is this with a corner radius of half its
+    height, which makes it a capsule — the right shape for a disc edge-on."""
+    # Work in the box's own frame: a rotated box is only hard if you insist on
+    # staying in world space.
+    cos_r, sin_r = math.cos(-rotation), math.sin(-rotation)
+    dx, dy = px - cx, py - cy
+    lx = dx * cos_r - dy * sin_r
+    ly = dx * sin_r + dy * cos_r
+
+    half_w = max(0.0, w / 2 - corner)
+    half_h = max(0.0, h / 2 - corner)
+    qx = _clamp(lx, -half_w, half_w)
+    qy = _clamp(ly, -half_h, half_h)
+    ox, oy = lx - qx, ly - qy
+    distance = math.hypot(ox, oy)
+
+    if distance < 0.0001:
+        # Dead centre: push out the short way, which for a flat object is
+        # almost always up or down, and is what a marble resting on one wants.
+        ox, oy = 0.0, (1.0 if ly >= 0 else -1.0)
+        distance = 0.0
+
+    depth = radius + corner - distance
+    if depth <= 0:
+        return None
+
+    n = math.hypot(ox, oy)
+    nx, ny = (ox / n, oy / n) if n > 0 else (0.0, 1.0)
+    cos_b, sin_b = math.cos(rotation), math.sin(rotation)
+    return (nx * cos_b - ny * sin_b, nx * sin_b + ny * cos_b, depth)
+
+
+def _arc_contact(px, py, radius, cx, cy, arc_radius, start, end, thickness):
+    """A ladder: the concave inside of a circular arc."""
+    ox, oy = px - cx, py - cy
+    distance = math.hypot(ox, oy)
+    if distance <= 0.0001:
+        return None
+
+    # Only the concave side collides. A marble that has fallen past the outside
+    # of a ladder should carry on past it, not be caught by its back.
+    surface = arc_radius - thickness / 2
+    depth = radius - (surface - distance)
+    if depth <= 0 or distance >= surface:
+        return None
+
+    angle = math.atan2(oy, ox)
+    lo, hi = min(start, end), max(start, end)
+    while angle < lo - math.pi:
+        angle += 2 * math.pi
+    while angle > hi + math.pi:
+        angle -= 2 * math.pi
+    # A marble-radius of slack at each end, so the ball rolls off the tip
+    # rather than clipping through it.
+    slack = radius / max(1.0, arc_radius)
+    if not (lo - slack < angle < hi + slack):
+        return None
+
+    # The normal points from the surface towards the centre: the marble rides
+    # on the inside.
+    return (-ox / distance, -oy / distance, depth)
+
+
+# ---------------------------------------------------------------- the level
+
+
+@dataclass(frozen=True)
+class Placement:
+    kind: Kind
+    x: float
+    y: float
+    rot_steps: int = 0      # in units of ROTATION_STEP, so the action is integral
+
+    @property
+    def rotation(self) -> float:
+        return self.rot_steps * ROTATION_STEP
+
+    def collider(self):
+        r = self.rotation
+        if self.kind is Kind.LADDER:
+            # The arc is authored around a centre above the piece, so the player
+            # positions the *dip* of the ladder rather than an invisible circle.
+            centre_x = self.x - math.sin(r) * LADDER_RADIUS
+            centre_y = self.y + math.cos(r) * LADDER_RADIUS
+            mid = math.pi * 1.5 + r
+            half = LADDER_SWEEP / 2
+            return ("arc", centre_x, centre_y, LADDER_RADIUS,
+                    mid - half, mid + half, LADDER_THICKNESS)
+        (w, h), _, _ = SPEC[self.kind]
+        corner = h / 2 if self.kind is Kind.DRUM else 18.0
+        return ("box", self.x, self.y, w, h, corner, r)
+
+
+@dataclass
+class Level:
+    ring_x: float
+    ring_y: float
+    ring_half_width: float = 118.0
+    stars: list[tuple[float, float]] = field(default_factory=list)
+    bounds: float = 470.0
+    inventory: dict[Kind, int] = field(default_factory=dict)
+
+
+class Verdict(str, Enum):
+    SCORED = "scored"                  # through the ring with every star taken
+    SHORT_OF_STARS = "short_of_stars"  # through the ring, stars left behind
+    MISSED = "missed"                  # fell past the ring, or off the side
+    STALLED = "stalled"                # stopped moving, or stopped descending
+    TIMED_OUT = "timed_out"
+
+
+@dataclass
+class Outcome:
+    verdict: Verdict
+    time: float
+    stars_taken: int
+    stars_total: int
+    x_at_ring: float | None      # where it crossed the ring's line, if it did
+    miss_by: float | None        # how far outside the mouth that crossing was
+    final_x: float
+    final_y: float
+    struck: frozenset[int] = frozenset()
+    """Which placements the marble actually bounced off. A generated level whose
+    pieces are not all struck is a level with a smaller solution hiding in it,
+    which makes its stated inventory a lie."""
+    trace: list[tuple[float, float]] = field(default_factory=list)
+    """The path, when asked for. Only the generator needs it — it places the next
+    piece where the marble will actually be, which is the whole reason generated
+    levels are solvable by construction."""
+
+    @property
+    def scored(self) -> bool:
+        return self.verdict is Verdict.SCORED
+
+
+def opening_slide() -> tuple[float, float, float, float, float]:
+    """Where the marble is and how fast it is going when the scripted slide
+    down the fixed ramp ends. Returns (x, y, vx, vy, elapsed)."""
+    lift = MARBLE_RADIUS + SURFACE_THICKNESS / 2
+    fx = PLATFORM_CONTROLS[0][0] + 120
+    fy = PLATFORM_CONTROLS[0][1] + PLATFORM_Y + lift
+    tx = PLATFORM_CONTROLS[-1][0]
+    ty = PLATFORM_CONTROLS[-1][1] + PLATFORM_Y + lift
+
+    rx, ry = tx - fx, ty - fy
+    length = math.hypot(rx, ry)
+    slope = (-ry / length) if length > 0 else 0.0
+    # 5/7: a rolling sphere, not a sliding block.
+    acceleration = GRAVITY * slope * (5.0 / 7.0)
+    v0 = OPENING_SPEED
+    if acceleration > 0:
+        duration = (-v0 + math.sqrt(v0 * v0 + 2 * acceleration * length)) / acceleration
+    else:
+        duration = length / max(1.0, v0)
+    exit_speed = v0 + acceleration * duration
+    dx, dy = (rx / length, ry / length) if length > 0 else (1.0, 0.0)
+    return tx, ty, dx * exit_speed, dy * exit_speed, duration
+
+
+def _passes_within(ax, ay, bx, by, radius, px, py) -> bool:
+    """Distance from a point to a segment, thresholded. Stars are tested against
+    the whole step rather than its endpoint: at full speed the marble covers
+    seven units a step and would sail straight through one checked point by
+    point."""
+    dx, dy = bx - ax, by - ay
+    length_sq = dx * dx + dy * dy
+    t = 0.0 if length_sq <= 0 else _clamp(((px - ax) * dx + (py - ay) * dy) / length_sq, 0.0, 1.0)
+    return math.hypot(px - (ax + dx * t), py - (ay + dy * t)) <= radius
+
+
+def simulate(level: Level, placements: list[Placement], keep_trace: bool = False) -> Outcome:
+    """Run one attempt to completion and report what happened."""
+    colliders = [p.collider() for p in placements]
+    kinds = [p.kind for p in placements]
+    rotations = [p.rotation for p in placements]
+    ramp = [("seg", PLATFORM_SURFACE[i][0], PLATFORM_SURFACE[i][1],
+             PLATFORM_SURFACE[i + 1][0], PLATFORM_SURFACE[i + 1][1],
+             PLATFORM_COLLIDER_RADIUS)
+            for i in range(len(PLATFORM_SURFACE) - 1)]
+
+    x, y, vx, vy, time = opening_slide()
+    taken: set[int] = set()
+    struck: set[int] = set()
+    verdict = Verdict.TIMED_OUT
+    x_at_ring: float | None = None
+    miss_by: float | None = None
+
+    still_for = 0.0
+    deepest_y = y
+    deepest_at = time
+    trace: list[tuple[float, float]] = [(x, y)] if keep_trace else []
+
+    while time < TIME_LIMIT:
+        prev_x, prev_y = x, y
+
+        vy -= GRAVITY * STEP
+        # Terminal velocity. Not realism — a marble that keeps accelerating down
+        # a tall layout becomes impossible to aim, and the whole point is that
+        # the player can reason about where it will go.
+        speed = math.hypot(vx, vy)
+        if speed > MAX_SPEED:
+            k = MAX_SPEED / speed
+            vx, vy = vx * k, vy * k
+        x += vx * STEP
+        y += vy * STEP
+        time += STEP
+        if keep_trace:
+            trace.append((x, y))
+
+        for i, (sx, sy) in enumerate(level.stars):
+            if i not in taken and _passes_within(prev_x, prev_y, x, y, STAR_RADIUS, sx, sy):
+                taken.add(i)
+
+        # Through the ring? Crossing its line is the test, not proximity to it.
+        if (prev_y - level.ring_y) * (y - level.ring_y) <= 0 and prev_y != y:
+            t = (level.ring_y - prev_y) / (y - prev_y)
+            cross = prev_x + (x - prev_x) * t
+            if abs(cross - level.ring_x) <= level.ring_half_width:
+                x_at_ring = cross
+                miss_by = 0.0
+                verdict = (Verdict.SCORED if len(taken) == len(level.stars)
+                           else Verdict.SHORT_OF_STARS)
+                break
+            if x_at_ring is None:      # remember the first crossing, for diagnostics
+                x_at_ring = cross
+                miss_by = abs(cross - level.ring_x) - level.ring_half_width
+
+        if y < level.ring_y - 900 or abs(x) > level.bounds + 400:
+            verdict = Verdict.MISSED
+            break
+
+        # Contacts, deepest first: with two objects overlapping, resolving the
+        # shallow one first just pushes the marble further into the other.
+        best = None
+        for idx, c in enumerate(colliders):
+            hit = (_arc_contact(x, y, MARBLE_RADIUS, *c[1:]) if c[0] == "arc"
+                   else _box_contact(x, y, MARBLE_RADIUS, *c[1:]))
+            if hit and (best is None or hit[2] > best[1][2]):
+                best = (idx, hit)
+        for c in ramp:
+            hit = _segment_contact(x, y, MARBLE_RADIUS, *c[1:])
+            if hit and (best is None or hit[2] > best[1][2]):
+                best = (RAMP_INDEX, hit)
+
+        if best is not None:
+            idx, (nx, ny, depth) = best
+            on_ramp = idx == RAMP_INDEX
+            if on_ramp:
+                restitution, friction = RAMP_RESTITUTION, RAMP_FRICTION
+            else:
+                _, restitution, friction = SPEC[kinds[idx]]
+
+            # Push clear before touching the velocity, or the next step starts
+            # inside the object and the marble sinks further on every contact
+            # until it falls through.
+            x += nx * depth
+            y += ny * depth
+
+            approach = vx * nx + vy * ny
+            if approach < 0:
+                n_dx, n_dy = nx * approach, ny * approach
+                t_dx, t_dy = vx - n_dx, vy - n_dy
+                closing = -approach
+                if closing > BOUNCE_THRESHOLD:
+                    if not on_ramp:
+                        struck.add(idx)
+                    vx = t_dx * friction - n_dx * restitution
+                    vy = t_dy * friction - n_dy * restitution
+                    if not on_ramp and kinds[idx] is Kind.SPRING:
+                        # A spring pushes along its OWN axis, not along the
+                        # contact normal. Clip one on the side with a
+                        # normal-aligned impulse and it fires the marble
+                        # sideways, which is not what anyone who just pointed a
+                        # spring upwards expects.
+                        r = rotations[idx]
+                        vx += -math.sin(r) * SPRING_IMPULSE
+                        vy += math.cos(r) * SPRING_IMPULSE
+                else:
+                    # Resting or rolling: drop the normal component entirely and
+                    # let gravity work along the surface. Bouncing at this speed
+                    # is what makes a marble buzz on a flat surface instead of
+                    # rolling along it.
+                    vx = t_dx * (1 - ROLLING_DRAG)
+                    vy = t_dy * (1 - ROLLING_DRAG)
+
+        # Stuck? Two rules, because "stuck" has two shapes and only one of them
+        # is standing still. A marble rocking in the dip of a ladder is moving
+        # the whole time — friction here is metal on metal, so it can rock for
+        # fifteen seconds — and a run that shows nothing for that long is broken
+        # whatever the velocity says. Depth is the only thing a run makes
+        # progress on, so depth is what it is measured against.
+        still_for = still_for + STEP if math.hypot(vx, vy) < STILL_SPEED else 0.0
+        if y < deepest_y - 4:
+            deepest_y = y
+            deepest_at = time
+        if still_for > STILL_LIMIT or time - deepest_at > NO_PROGRESS_LIMIT:
+            verdict = Verdict.STALLED
+            break
+
+    return Outcome(
+        verdict=verdict,
+        time=time,
+        stars_taken=len(taken),
+        stars_total=len(level.stars),
+        x_at_ring=x_at_ring,
+        miss_by=miss_by,
+        final_x=x,
+        final_y=y,
+        struck=frozenset(struck),
+        trace=trace,
+    )
+
+
+def within_inventory(placements: list[Placement], inventory: dict[Kind, int]) -> bool:
+    """A layout that uses pieces the level never offered is not a solution."""
+    used: dict[Kind, int] = {}
+    for p in placements:
+        used[p.kind] = used.get(p.kind, 0) + 1
+    return all(n <= inventory.get(k, 0) for k, n in used.items())
+
+
+def on_grid(p: Placement) -> bool:
+    """Placements snap to the grid. Off-grid ones are rejected rather than
+    rounded: rounding silently changes the answer the model gave."""
+    return (abs(p.x / POSITION_STEP - round(p.x / POSITION_STEP)) < 1e-9
+            and abs(p.y / POSITION_STEP - round(p.y / POSITION_STEP)) < 1e-9)

marble_v1/taskset.py

@@ -0,0 +1,250 @@
+"""marble-v1 — place pieces so a falling marble lands in a ring.
+
+A marble rolls off a fixed ramp and falls. The model is given a ring somewhere
+below, an inventory of pieces, and the physical constants; it must say where to
+put each piece so the marble bounces its way into the ring. One reply, no
+retries, no simulator to poke at — the whole task is predicting a chain of
+bounces before any of them happen.
+
+## Why this environment exists
+
+Almost every RL environment scores its rollouts with a judge model or a rubric,
+and both can be argued with: a persuasive answer can score well without being
+right. Here the reward is computed by a fixed-step physics integrator. The
+marble goes through the ring or it does not, and no amount of confident prose
+moves that number. Reward hacking is not defended against here; it is impossible.
+
+Two more properties fall out of the same design:
+
+- **Infinite and solvable by construction.** Levels are built forwards along the
+  marble's real path (see `levels.py`), so a solution is known before the task is
+  handed out — a model that fails failed at something possible.
+- **Cheap.** No browser, no VM, no judge calls. One rollout is one model call
+  plus a few milliseconds of arithmetic, which matters when a training run wants
+  hundreds of thousands of them.
+
+Difficulty is the piece count, and it is the one knob: `--env.taskset.pieces`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterator
+from itertools import count
+
+import verifiers.v1 as vf
+
+from marble_v1 import levels as gen
+from marble_v1.sim import (
+    GRAVITY,
+    MARBLE_RADIUS,
+    POSITION_STEP,
+    SPRING_IMPULSE,
+    Kind,
+    Level,
+    Placement,
+    on_grid,
+    opening_slide,
+    simulate,
+    within_inventory,
+)
+
+PIECES = """| piece  | size (w x h) | bounciness | surface grip |
+|--------|--------------|------------|--------------|
+| ladder | 300 x 120    | 0.20       | 0.985        |
+| spring | 96 x 132     | 0.62       | 0.88         |
+| drum   | 186 x 76     | 0.74       | 0.93         |
+| block  | 150 x 108    | 0.30       | 0.86         |
+| bell   | 158 x 82     | 0.52       | 0.91         |"""
+
+PROMPT = """A marble rolls off a fixed ramp and falls under gravity. Place the pieces you
+are given so that it ends up passing through the ring.
+
+COORDINATES: x runs right, y runs up. Gravity is {gravity:.0f} units/s^2 downward.
+The marble has radius {radius:.0f} and leaves the ramp at ({sx:.0f}, {sy:.0f}) with
+velocity ({vx:.0f}, {vy:.0f}) units/s.
+
+THE RING: a horizontal mouth centred at ({ring_x:.0f}, {ring_y:.0f}), reaching {half_width:.0f}
+units either side of that centre. The marble scores by crossing y = {ring_y:.0f}
+with its x inside that mouth. It is lost if it falls {below:.0f} below the ring, or
+goes past x = +/-{kill:.0f}.
+
+YOUR PIECES — use exactly these, no more and no fewer:
+{inventory}
+
+{pieces}
+
+A bounce keeps `bounciness` of the speed into the surface and `grip` of the speed
+along it. A spring additionally fires the marble {impulse:.0f} units/s along its own
+axis, so rotating a spring aims it. Everything except the ladder is a rounded
+box; the ladder is a concave arc that cradles the marble.
+
+PLACEMENT RULES:
+- x and y must be multiples of {step:.0f}.
+- x must be within +/-{bounds:.0f} — you may only build inside that strip.
+- Rotation is in whole steps of 7.5 degrees, from -12 to 12.
+- A piece is positioned by its centre.
+
+Reply with your reasoning if you like, then give the layout as a JSON array in a
+fenced block. Only the last such block counts.
+
+```json
+[{{"kind": "block", "x": 120, "y": -800, "rot": 2}}]
+```"""
+
+
+def parse_layout(reply: str) -> list[Placement] | None:
+    """The last fenced JSON array in the reply, as placements, or None.
+
+    Strict about shape and forgiving about nothing: a layout that is silently
+    repaired is not the layout the model proposed, and scoring a repaired one
+    measures the repair.
+    """
+    blocks = re.findall(r"```(?:json)?\s*(\[.*?\])\s*```", reply, re.DOTALL)
+    if not blocks:
+        blocks = re.findall(r"(\[\s*\{.*?\}\s*\])", reply, re.DOTALL)
+    if not blocks:
+        return None
+    try:
+        rows = json.loads(blocks[-1])
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(rows, list):
+        return None
+
+    out: list[Placement] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            return None
+        try:
+            kind = Kind(str(row["kind"]).strip().lower())
+            out.append(Placement(kind, float(row["x"]), float(row["y"]), int(row["rot"])))
+        except (KeyError, ValueError, TypeError):
+            return None
+    return out
+
+
+class MarbleData(vf.TaskData):
+    ring: list[float]
+    """Centre x, centre y, half width."""
+    bounds: float
+    inventory: dict[str, int]
+    solution: list[dict]
+    """A layout known to score. Never shown to the model — it is here so a run can
+    say what a working answer looked like next to the one that was given."""
+
+
+class MarbleTask(vf.Task[MarbleData]):
+    def _level(self) -> Level:
+        rx, ry, hw = self.data.ring
+        return Level(
+            ring_x=rx,
+            ring_y=ry,
+            ring_half_width=hw,
+            bounds=self.data.bounds,
+            inventory={Kind(k): v for k, v in self.data.inventory.items()},
+        )
+
+    def _run(self, trace: vf.Trace):
+        """Parse, check the layout is legal, simulate. Returns (layout, outcome);
+        either can be None when the answer did not get that far."""
+        layout = parse_layout(trace.last_reply or "")
+        if layout is None:
+            return None, None
+        level = self._level()
+        legal = (
+            all(on_grid(p) for p in layout)
+            and all(abs(p.x) <= level.bounds and abs(p.rot_steps) <= 12 for p in layout)
+            and within_inventory(layout, level.inventory)
+            and len(layout) == sum(level.inventory.values())
+        )
+        if not legal:
+            return layout, None
+        return layout, simulate(level, layout)
+
+    @vf.reward(weight=1.0)
+    async def scored(self, trace: vf.Trace) -> float:
+        """Did the marble go through the ring. Computed by the integrator, so
+        there is nothing here to talk out of its answer."""
+        _, outcome = self._run(trace)
+        return float(outcome is not None and outcome.scored)
+
+    @vf.reward(weight=0.0)
+    async def answered_legally(self, trace: vf.Trace) -> float:
+        """Diagnostic. Separating this from `scored` is what tells a bad layout
+        apart from a bad answer — very different problems with the same zero."""
+        _, outcome = self._run(trace)
+        return float(outcome is not None)
+
+    @vf.reward(weight=0.0)
+    async def closeness(self, trace: vf.Trace) -> float:
+        """Diagnostic: 1 through the mouth, falling to 0 a mouth-width outside it.
+        Kept out of the training signal on purpose — a model paid for near misses
+        learns to aim near the ring rather than through it."""
+        _, outcome = self._run(trace)
+        if outcome is None or outcome.miss_by is None:
+            return 0.0
+        if outcome.scored:
+            return 1.0
+        return max(0.0, 1.0 - outcome.miss_by / self.data.ring[2])
+
+
+class MarbleConfig(vf.TasksetConfig):
+    pieces: int = 1
+    """How many pieces every level needs. The coarse difficulty knob."""
+    ring_half_width: float = 118.0
+    """How far the ring's mouth reaches either side of centre — the fine knob.
+
+    Piece count alone is far too coarse to calibrate with. Measured on
+    gemini-2.5-pro at the stock mouth: one piece 50%, two pieces 0%, three
+    pieces 0%. A cliff like that gives a training run nothing to climb, so the
+    mouth is what you widen to put a given piece count in a useful band.
+    """
+    seed: int = 0
+    """Where the level stream starts."""
+
+
+class MarbleTaskset(vf.Taskset[MarbleTask, MarbleConfig]):
+    INFINITE = True
+
+    def load(self) -> Iterator[MarbleTask]:
+        sx, sy, vx, vy, _ = opening_slide()
+        stream = gen.stream(
+            self.config.seed,
+            self.config.pieces,
+            ring_half_width=self.config.ring_half_width,
+        )
+        for idx in count():
+            made = next(stream)
+            level = made.level
+            inventory = {k.value: v for k, v in level.inventory.items()}
+            listing = "\n".join(f"- {n} x {k}" for k, n in sorted(inventory.items()))
+            yield MarbleTask(
+                MarbleData(
+                    idx=idx,
+                    prompt=PROMPT.format(
+                        gravity=GRAVITY,
+                        radius=MARBLE_RADIUS,
+                        sx=sx, sy=sy, vx=vx, vy=vy,
+                        ring_x=level.ring_x,
+                        ring_y=level.ring_y,
+                        half_width=level.ring_half_width,
+                        below=900,
+                        kill=level.bounds + 400,
+                        inventory=listing,
+                        pieces=PIECES,
+                        impulse=SPRING_IMPULSE,
+                        step=POSITION_STEP,
+                        bounds=level.bounds,
+                    ),
+                    ring=[level.ring_x, level.ring_y, level.ring_half_width],
+                    bounds=level.bounds,
+                    inventory=inventory,
+                    solution=[
+                        {"kind": p.kind.value, "x": p.x, "y": p.y, "rot": p.rot_steps}
+                        for p in made.solution
+                    ],
+                ),
+                self.config.task,
+            )

marble_v1-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: marble-v1
+Version: 0.1.0
+Summary: Place pieces so a falling marble lands in a ring — an RL environment whose reward is computed by a deterministic physics integrator, not a judge model.
+Project-URL: Homepage, https://github.com/p1at0/marble-v1
+License-Expression: MIT
+Keywords: environment,evals,physics,rl,spatial-reasoning,verifiers
+Requires-Python: >=3.11
+Requires-Dist: verifiers
+Description-Content-Type: text/markdown
+
+# marble-v1
+
+Place pieces so a falling marble lands in a ring. One reply, no tools, no
+simulator to poke at — the whole task is predicting a chain of bounces before
+any of them happen.
+
+```bash
+uv run eval @ eval.toml -m <model> \
+  --client.base-url <provider> --client.api-key-var <VAR>
+
+uv run eval @ eval.toml -m <model> --env.taskset.pieces 3   # harder
+```
+
+## What makes it different
+
+**The reward cannot be argued with.** There is no judge model and no rubric. A
+fixed-step physics integrator runs the layout and reports whether the marble
+went through the ring. Reward hacking is not defended against here; it is
+impossible.
+
+**Solvable by construction.** Levels are built forwards along the marble's real
+path, so a working layout is known before the task is handed out. A model that
+fails failed at something possible — which is not true of levels that are
+designed and then hoped over.
+
+**Infinite, and difficulty is one number.** `pieces` is the knob. Levels stream
+from a seed; there is no dataset to exhaust.
+
+**Cheap to run.** No browser, no VM, no judge calls. A rollout is one model call
+plus a few milliseconds of arithmetic — the difference between a training run
+being affordable and not.
+
+## The task
+
+A marble rolls off a fixed ramp with a known position and velocity and falls
+under gravity. The model is given the ring's position and mouth width, an
+inventory of pieces it must use exactly, each piece's size, bounciness and
+surface grip, and the placement grid. It replies with a JSON layout.
+
+Five pieces behave differently: a **spring** fires the marble along its own
+axis, so rotating one aims it; a **ladder** is a concave arc that cradles;
+**drum**, **block** and **bell** are rounded boxes with different bounce. All
+placements snap to a 20-unit grid and 7.5-degree rotation steps, so the action
+space is integral and an answer is either legal or it is not.
+
+## Rewards
+
+| name | weight | what it says |
+|---|---|---|
+| `scored` | 1.0 | the marble went through the ring |
+| `answered_legally` | 0.0 | a parseable layout obeying grid, strip and inventory |
+| `closeness` | 0.0 | 1 through the mouth, 0 a mouth-width outside it |
+
+The two diagnostics carry no weight on purpose. `closeness` is kept out of the
+training signal because a model paid for near misses learns to aim near the ring
+rather than through it. `answered_legally` exists because "could not format an
+answer" and "got the physics wrong" are very different failures that otherwise
+produce the same zero.
+
+## Difficulty
+
+Two knobs, and you need both. `pieces` alone is far too coarse — measured, it
+goes 50% → 0% between one piece and two, and a cliff gives a training run
+nothing to climb. `ring_half_width` is the fine one: a wider mouth converts near
+misses into hits without changing what the model has to reason about.
+
+Measured on `google/gemini-2.5-pro`, 10 tasks each, `null` harness:
+
+| pieces | mouth | solved | legal answers |
+|---|---|---|---|
+| 1 | 118 | **50%** | 100% |
+| 2 | 118 | 0% | 100% |
+| 2 | 300 | 10% | 100% |
+| 2 | 420 | **30%** | 100% |
+| 3 | 118 | 0% | 100% |
+
+The mouth knob moves the solve rate 0 → 10 → 30% at a fixed piece count, so any
+model can be put in a band where it solves neither everything nor nothing.
+
+`answered_legally` is 100% everywhere: no model in these runs failed to produce
+a legal layout. Every zero above is a physics failure, not a formatting one.
+
+## Baselines
+
+Measured on generated levels, no model involved (`calib.py`):
+
+| pieces | random legal layout scores | gold survives a one-step nudge |
+|---|---|---|
+| 1 | 3.7% | 58% |
+| 2 | 1.8% | 51% |
+| 3 | 1.4% | 31% |
+
+The first column is the floor a model has to beat to be doing anything — 50% at
+one piece is a 13x lift over guessing. The second says the solution is a basin
+rather than a needle: the task rewards approximately right physics, not exact
+recall.
+
+Widening the mouth does not hand the win to chance. At two pieces, taking the
+mouth from 118 to 420 moves the random floor only 1.8% → 6.4%, while it moves
+the model 0% → 30%.
+
+## What a rollout costs
+
+The environment's own overhead is a few milliseconds of arithmetic — no browser,
+no VM, no judge model. The model is what costs: a reasoning model produces long
+chains on these problems, and `gemini-2.5-pro` averaged about $0.16 per rollout
+in the runs above. Calibrate with a cheaper model first.
+
+## Provenance
+
+The simulator is a port of the one in a shipped iOS game, where determinism was
+the feature rather than a detail: a player who nudges one piece and re-runs has
+learned nothing if the same layout can give two answers. It is a fixed-step
+integrator with analytic contacts, not a physics engine.
+
+The port is checked against the original: on a five-piece reference layout the
+marble's finishing position matches exactly, and intermediate crossings agree to
+within one unit. Bit-identity across languages is explicitly not a goal — `sin`
+and `cos` may differ in the last place — so reference solutions are generated by
+this simulator rather than imported from it.
+
+## Files
+
+| file | what it is |
+|---|---|
+| `marble_v1/sim.py` | the simulator: colliders, pieces, the physics loop |
+| `marble_v1/levels.py` | level generation, solvable by construction |
+| `marble_v1/taskset.py` | prompt, answer parsing, rewards |
+| `calib.py` | difficulty measured without a model |
+| `summarise.py` | aggregate an eval run into the three numbers |

marble_v1-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+marble_v1/__init__.py,sha256=lpIQk7OBsNij0aGxewxQpjfqALElEU4sEX_Q4jJD8Sk,73
+marble_v1/levels.py,sha256=R3QMKJTlT9coSdnBx9_L3kTChMsOyt_3moho10D2WX0,5880
+marble_v1/sim.py,sha256=Uj9_ukS8kaSFxe_1aanI3kjrAlUA9-MkZVWNnbm6uSE,18003
+marble_v1/taskset.py,sha256=HGoVbevYiTQ7Qtx348NmHgzKEePLAv3W3ElTRzCyJl8,9630
+marble_v1-0.1.0.dist-info/METADATA,sha256=CUAtSFJzjwG7vUa8yXUv1do_rtXvF6VagUIr-xI4_oc,5894
+marble_v1-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+marble_v1-0.1.0.dist-info/RECORD,,

marble_v1-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any