ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/pathfind.py

@@ -0,0 +1,138 @@
+"""Auto-pathing: route a blocked cutscene walk AROUND obstacles into clear straight legs.
+
+A FF9 field walk is straight-line + synchronous, so it can't round a corner (off the walkmesh) or pass
+a standing character (its collision box) on its own -- it presses into the obstacle and stalls. This
+finds a route over the walkmesh that avoids both, then string-pulls it down to a few waypoints (which
+the builder emits as a ``path``).
+
+Grid A* over the walkmesh bounds: a cell is FREE if its centre is on the walkmesh, at least
+``clearance`` from any wall (the player's controller radius), and at least ``obstacle_r`` from every
+other character's centre (= the collision distance, so the actor never enters a box). Pure stdlib;
+operates on a :class:`ff9mapkit.scene.bgi.BgiWalkmesh`.
+"""
+
+from __future__ import annotations
+
+import heapq
+
+from ..scene import cam
+
+_NEIGHBORS = [(-1, 0), (1, 0), (0, -1), (0, 1), (-1, -1), (-1, 1), (1, -1), (1, 1)]
+
+
+def _free(wmesh, x, z, obstacles, clearance, obstacle_r) -> bool:
+    if wmesh.point_on_walkmesh(int(round(x)), int(round(z))) is None:
+        return False
+    if clearance > 0:
+        d = wmesh.distance_to_boundary(int(round(x)), int(round(z)))
+        if d is not None and d < clearance:
+            return False
+    r2 = obstacle_r * obstacle_r
+    for ox, oz in obstacles:
+        if (x - ox) ** 2 + (z - oz) ** 2 < r2:
+            return False
+    return True
+
+
+def _clear(wmesh, a, b, obstacles, clearance, obstacle_r) -> bool:
+    """Is the straight leg a->b fully free (sampled ~every clearance)?"""
+    dx, dz = b[0] - a[0], b[1] - a[1]
+    dist = (dx * dx + dz * dz) ** 0.5
+    n = max(1, int(dist / max(8.0, clearance)))
+    for k in range(n + 1):
+        t = k / n
+        if not _free(wmesh, a[0] + dx * t, a[1] + dz * t, obstacles, clearance, obstacle_r):
+            return False
+    return True
+
+
+def _simplify(wmesh, pts, obstacles, clearance, obstacle_r) -> list:
+    """String-pull a dense point list to a few waypoints (drop a point when you can see past it).
+    Returns the waypoints AFTER the start, always ending at the exact goal (pts[-1])."""
+    out, i = [], 0
+    while i < len(pts) - 1:
+        j = len(pts) - 1
+        while j > i + 1 and not _clear(wmesh, pts[i], pts[j], obstacles, clearance, obstacle_r):
+            j -= 1
+        out.append(pts[j])
+        i = j
+    return out
+
+
+def _nearest_free_cell(free_cell, gi, gj, span=6):
+    """A free grid cell near (gi, gj) (the exact goal may sit within a margin of a wall/obstacle)."""
+    if free_cell(gi, gj):
+        return (gi, gj)
+    for ring in range(1, span + 1):
+        best = None
+        for di in range(-ring, ring + 1):
+            for dj in range(-ring, ring + 1):
+                if max(abs(di), abs(dj)) != ring:
+                    continue
+                if free_cell(gi + di, gj + dj):
+                    d = di * di + dj * dj
+                    if best is None or d < best[0]:
+                        best = (d, (gi + di, gj + dj))
+        if best:
+            return best[1]
+    return None
+
+
+def route(wmesh, start, goal, obstacles=(), *, cell=64.0, clearance=None, obstacle_r=None,
+          max_expand=20000):
+    """Waypoints routing ``start``->``goal`` around walls + obstacles, or ``None`` if unreachable.
+
+    Returns the interior waypoints + the exact goal (EXCLUDING start), suitable as a ``path``. Stays on
+    the walkmesh, >= ``clearance`` from walls, >= ``obstacle_r`` from each obstacle centre. ``obstacles``
+    is a list of (x, z) character centres."""
+    clearance = cam.COLLISION_RADIUS_W if clearance is None else clearance
+    obstacle_r = 2 * cam.OBJECT_COLLISION_W if obstacle_r is None else obstacle_r
+    sx, sz = float(start[0]), float(start[1])
+    gx, gz = float(goal[0]), float(goal[1])
+
+    def cell_xz(i, j):
+        return (sx + i * cell, sz + j * cell)
+
+    def free_cell(i, j):
+        x, z = cell_xz(i, j)
+        return _free(wmesh, x, z, obstacles, clearance, obstacle_r)
+
+    start_c = (0, 0)
+    goal_c = _nearest_free_cell(free_cell, round((gx - sx) / cell), round((gz - sz) / cell))
+    if goal_c is None:
+        return None
+    if start_c == goal_c:
+        return [(int(round(gx)), int(round(gz)))]
+
+    open_h = [(0.0, start_c)]
+    came = {}
+    g = {start_c: 0.0}
+    expand = 0
+    while open_h:
+        _, c = heapq.heappop(open_h)
+        if c == goal_c:
+            break
+        expand += 1
+        if expand > max_expand:
+            return None
+        for di, dj in _NEIGHBORS:
+            n = (c[0] + di, c[1] + dj)
+            if n != goal_c and not free_cell(*n):       # start/goal cells are taken as given
+                continue
+            step = cell * (1.41421356 if di and dj else 1.0)
+            ng = g[c] + step
+            if ng < g.get(n, 1e18):
+                g[n] = ng
+                came[n] = c
+                h = ((n[0] - goal_c[0]) ** 2 + (n[1] - goal_c[1]) ** 2) ** 0.5 * cell
+                heapq.heappush(open_h, (ng + h, n))
+    if goal_c not in came:
+        return None
+
+    chain = [goal_c]
+    while chain[-1] in came:
+        chain.append(came[chain[-1]])
+    chain.reverse()                                     # start_c .. goal_c
+    pts = [(sx, sz)] + [cell_xz(i, j) for (i, j) in chain[1:-1]] + [(gx, gz)]   # exact start..exact goal
+    wps = _simplify(wmesh, pts, obstacles, clearance, obstacle_r)
+    return [(int(round(x)), int(round(z))) for (x, z) in wps]

ff9mapkit/content/platform.py

@@ -0,0 +1,314 @@
+"""Carry-platform primitive -- a rideable lift/elevator that physically CARRIES the player within one
+field (no Field() re-entry warp), recreating FF9's Pandemonium-elevator mechanism.
+
+Decoded from Pandemonium/Elevator (fields 2712 `pd_elv` / 2713 `pd_evd`). The real ride is a fully
+SCRIPTED, control-locked carry -- NOT an engine attach (there is ZERO MoveTileLoop/AttachTile/SIM in
+either field). The boarding region disables control and `RunScriptSync`s a function grafted onto the
+PLAYER object (UID 250); that function moves the player frame-by-frame with `MoveInstantXZY` until he
+reaches the destination height, then control returns:
+
+  - region (tag 2 tread "!" / tag 3 action): ``DisableMove ; RunScriptSync(2, 250, ride_tag) ; EnableMove``
+  - the ride func (``ride_tag``, on the PLAYER): a per-frame loop
+      ``{ scratch = selfY +/- step ; MoveInstantXZY(line_x, scratch, line_z) ; Wait(1) ;
+         while (selfY hasn't reached arrive) }`` then SetPathing(1) (or the optional fade+Field tail).
+
+This is the kit's navigable ladder climb (:func:`ladder.navigable_climb_body`) MINUS the d-pad input
+and the mount/dismount arcs: instead of reading the held direction each frame, the carry advances a
+FIXED step toward the destination, so it is auto-driven and always terminates (a linear ride of
+~``duration`` frames). Every byte is emitted by the same proven primitives the climb uses (the ``_Asm``
+label assembler, the ``0xA1`` expression-arg snap, the ``line()`` interpolation, the ladder flag).
+
+selfY = -worldY (op78 field 1): a HIGHER physical position is a MORE-NEGATIVE selfY, so a lift going UP
+(arrive above board) advances selfY in the NEGATIVE direction. The carry derives the step sign + the
+arrival test from ``arrive.y`` vs ``board.y`` (they MUST differ -- a zero-height carry never moves).
+
+v1 emits the CARRY only; the visible platform is the human's (paint a ride surface, or drive a placed
+GEO model in lockstep -- a follow-up). docs: project memory `project-ff9-moving-platforms-elevators`.
+"""
+from __future__ import annotations
+
+import math
+import struct
+
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+from . import cutscene as _cutscene
+from .ladder import _Asm, _arg, _const, _selfv, _stmt, F_Y, LADDER_FLAG, find_player_entry, square_zone
+
+PLAYER_UID = 250          # the controlled player's runtime UID (standard across FF9 fields)
+FIRST_PLATFORM_TAG = 56   # player ride funcs start here -- clear of ladder (17+) / jump (40+) climb tags,
+                          #   below the object-carry player band (64+); one tag per platform
+RUNSCRIPT_LEVEL = 2       # the script level RunScriptSync uses (matches the real ladder/jump triggers)
+PLATFORM_SCRATCH = 3      # MAP.I16[3]: this frame's stepped selfY target (transient per-field)
+PLATFORM_START = 4        # MAP.I16[4]: the captured boarding selfY (the height the player rides FROM)
+PLATFORM_START_X = 5      # MAP.I16[5]: the captured boarding world-X
+PLATFORM_START_Z = 6      # MAP.I16[6]: the captured boarding world-Z
+DEFAULT_DURATION = 32     # ride frames (for the relative `rise` mode -- linear, always terminates)
+DEFAULT_SPEED = 30        # world-units/frame for the absolute `land` mode (ride duration = distance/speed)
+
+
+def _scratch() -> bytes:
+    """This frame's stepped selfY target (MAP.I16[PLATFORM_SCRATCH]); transient per-field."""
+    return _region._push_var(_region.MAP_INT16, PLATFORM_SCRATCH)
+
+
+def _scratch_start() -> bytes:
+    """The boarding selfY var (MAP.I16[PLATFORM_START]); captured from the player at ride start."""
+    return _region._push_var(_region.MAP_INT16, PLATFORM_START)
+
+
+def _scratch_x() -> bytes:
+    """The boarding world-X var (MAP.I16[PLATFORM_START_X]); captured at ride start (`land` mode)."""
+    return _region._push_var(_region.MAP_INT16, PLATFORM_START_X)
+
+
+def _scratch_z() -> bytes:
+    """The boarding world-Z var (MAP.I16[PLATFORM_START_Z]); captured at ride start (`land` mode)."""
+    return _region._push_var(_region.MAP_INT16, PLATFORM_START_Z)
+
+
+def _carry_land_body(land, *, speed: int, animation: int | None,
+                     warp_to: int | None, warp_entrance: int) -> bytes:
+    """Ride the player from WHEREVER he boards to the absolute landing point ``land`` = ``(x, z, y)``, at
+    ``speed`` world-units/frame, then re-attach to the walkmesh -- landing cleanly on the floor AT
+    ``land`` (no end-of-ride floor-snap warp). RELATIVE start (captures the boarding position, no
+    teleport-in) + ABSOLUTE end (the landing is a real floor). ``land`` must be ABOVE the boarding point
+    (the elevator rides UP -> selfY decreases). Used for inter-field-style lifts where you board at the
+    bottom and step off onto a higher floor elsewhere in the room."""
+    lx, lz = int(land[0]), int(land[1])
+    ly = int(land[2]) if len(land) > 2 else 0
+    lsy = -ly                                          # landing selfY (= -worldY)
+    speed = max(1, int(speed))
+
+    def selfx(): return _selfv(0)
+    def selfz(): return _selfv(2)
+    def selfy(): return _selfv(F_Y)
+
+    def interp(c_start: bytes, target: int) -> bytes:
+        # c_start + (target - c_start) * (cur - csy) / (lsy - csy)   -- linear, parameterised by selfY
+        return _arg(c_start,
+                    _const(target), c_start, bytes([_region.T_MINUS]),                 # (target - c_start)
+                    _scratch(), _scratch_start(), bytes([_region.T_MINUS]),            # (cur - csy)
+                    bytes([_region.T_MULT]),
+                    _const(lsy), _scratch_start(), bytes([_region.T_MINUS]),           # (lsy - csy)
+                    bytes([_region.T_DIV]), bytes([_region.T_PLUS]))
+
+    a = _Asm()
+    a.raw(opcodes.add_character_attribute(LADDER_FLAG) + opcodes.set_pathing(0))   # grip + detach; NO teleport
+    if animation is not None:
+        a.raw(opcodes.run_animation(int(animation)))
+    # capture the boarding position (x, z, selfY) -- the ride interpolates FROM here
+    a.raw(_stmt(_scratch_x(), selfx(), bytes([_region.T_ASSIGN])))
+    a.raw(_stmt(_scratch_z(), selfz(), bytes([_region.T_ASSIGN])))
+    a.raw(_stmt(_scratch_start(), selfy(), bytes([_region.T_ASSIGN])))
+    a.label("LOOP")
+    a.raw(_stmt(_scratch(), selfy(), _const(speed), bytes([_region.T_MINUS]), bytes([_region.T_ASSIGN])))  # step UP
+    a.raw(opcodes.encode(0xA1, interp(_scratch_x(), lx), _arg(_scratch()), interp(_scratch_z(), lz), arg_flags=0b111))
+    a.raw(opcodes.wait(1))
+    a.raw(_stmt(selfy(), _const(lsy), bytes([_region.T_GT])))      # selfY still above the landing?
+    a.jmp(_region.JMP_TRUE, "LOOP")
+    a.raw(opcodes.encode(0xA1, _arg(_const(lx)), _arg(_const(lsy)), _arg(_const(lz)), arg_flags=0b111))  # exact landing
+    if warp_to is not None:
+        a.raw(opcodes.fade_filter(6, 24, 0, 255, 255, 255) + opcodes.wait(25)
+              + _region.set_field_entrance(int(warp_entrance))
+              + opcodes.field(int(warp_to)) + opcodes.terminate_entry(255))
+    else:
+        a.raw(opcodes.remove_character_attribute(LADDER_FLAG) + opcodes.set_pathing(1))
+    a.raw(opcodes.RETURN)
+    return a.assemble()
+
+
+def _assemble_entry(funcs) -> bytes:
+    """Assemble a type-1 (region) entry from ``[(tag, body), ...]`` (the ladder/jump region layout):
+    the func table (``<tag:u16><fpos:u16>`` x N) then the concatenated bodies."""
+    table = b""
+    pos = len(funcs) * 4
+    for tag, body in funcs:
+        table += struct.pack("<HH", tag, pos)
+        pos += len(body)
+    return bytes([_region.REGION_ENTRY_TYPE, len(funcs)]) + table + b"".join(b for _, b in funcs)
+
+
+def carry_body(*, rise: int | None = None, land=None, speed: int = DEFAULT_SPEED,
+               duration: int = DEFAULT_DURATION, animation: int | None = None,
+               warp_to: int | None = None, warp_entrance: int = 0) -> bytes:
+    """The player's ride function, run in the player's context (the region RunScriptSync's it) so the
+    moves move the PLAYER. Two modes:
+
+    * ``land = (x, z, y)`` -- ride from WHEREVER he boards to that absolute landing point (a real floor),
+      so he steps off cleanly (no end-of-ride floor-snap). For inter-field-style lifts: board at the
+      bottom, ride up, let off on a higher floor elsewhere. ``land`` must be ABOVE the boarding point.
+    * ``rise = <units>`` -- lift him ``rise`` world-units vertically (positive = up) from his current
+      height, keeping x/z. A pure in-place vertical lift (needs a real floor at the top, else he
+      floor-snaps back down when collision re-enables).
+
+    Both are RELATIVE at the start (capture the boarding position, no teleport-in -- an earlier absolute
+    board-snap warped him under a platform model). VISIBILITY is governed by the FIELD CAMERA, not the
+    carry: a vertical rise stays rendered only when the camera's depthOffset + shallow pitch map it into
+    screen-Y (not depth -- the [100,3996] psxDepth cull) and its vrp band is tall enough to scroll up;
+    fork an elevator-style scene+camera (e.g. Pandemonium 2713). With ``warp_to`` the ride ENDS in a
+    fade + ``Field()`` re-entry (an inter-floor elevator)."""
+    if land is not None:
+        return _carry_land_body(land, speed=speed, animation=animation,
+                                warp_to=warp_to, warp_entrance=warp_entrance)
+    if rise is None:
+        raise ValueError("carry_body needs land=[x,z,y] (ride to a floor) or rise=<units> (vertical lift)")
+    rise = int(rise)
+    if rise == 0:
+        raise ValueError("carry_body: rise must be non-zero (positive = up) -- a zero ride never moves")
+    duration = max(1, int(duration))
+    smag = max(1, math.ceil(abs(rise) / duration))    # per-frame selfY step (terminates in ~duration frames)
+    up = rise > 0                                     # UP => selfY (= -worldY) DECREASES
+    step_tok = _region.T_MINUS if up else _region.T_PLUS
+    test_tok = _region.T_GT if up else _region.T_LT   # loop while selfY hasn't reached the target
+
+    def selfx(): return _selfv(0)                     # obj field 0 = world X
+    def selfz(): return _selfv(2)                     # obj field 2 = world Z
+    def selfy(): return _selfv(F_Y)                   # obj field 1 = worldY-up (= -pos.y)
+
+    a = _Asm()
+    a.raw(opcodes.add_character_attribute(LADDER_FLAG) + opcodes.set_pathing(0))   # grip + detach; NO teleport
+    if animation is not None:
+        a.raw(opcodes.run_animation(int(animation)))  # optional ride gesture (cosmetic; off by default)
+    # capture the boarding selfY, then the destination = start - rise (UP decreases selfY). Ride from there.
+    a.raw(_stmt(_scratch_start(), selfy(), bytes([_region.T_ASSIGN])))
+    a.raw(_stmt(_scratch(), _scratch_start(), _const(rise), bytes([_region.T_MINUS]), bytes([_region.T_ASSIGN])))
+    a.label("LOOP")
+    # step selfY one notch toward the target, keeping the player's current x/z (read live, written back)
+    a.raw(opcodes.encode(0xA1, _arg(selfx()),
+                         _arg(selfy(), _const(smag), bytes([step_tok])),
+                         _arg(selfz()), arg_flags=0b111))
+    a.raw(opcodes.wait(1))                                          # one ride frame (deterministic timing)
+    a.raw(_stmt(selfy(), _scratch(), bytes([test_tok])))           # selfY not yet at the target?
+    a.jmp(_region.JMP_TRUE, "LOOP")
+    a.raw(opcodes.encode(0xA1, _arg(selfx()), _arg(_scratch()), _arg(selfz()), arg_flags=0b111))  # exact final snap
+    if warp_to is not None:                           # ELEVATOR: ride then re-enter the destination floor
+        a.raw(opcodes.fade_filter(6, 24, 0, 255, 255, 255) + opcodes.wait(25)
+              + _region.set_field_entrance(int(warp_entrance))
+              + opcodes.field(int(warp_to)) + opcodes.terminate_entry(255))
+    else:                                             # in-screen ride: land + hand control back
+        a.raw(opcodes.remove_character_attribute(LADDER_FLAG) + opcodes.set_pathing(1))
+    a.raw(opcodes.RETURN)
+    return a.assemble()
+
+
+def platform_region(zone, ride_tag: int, *, trigger: str = "action", bubble: bool = True,
+                    player_uid: int = PLAYER_UID) -> bytes:
+    """A type-1 region entry that boards the player onto the ride (func ``ride_tag`` on the player).
+
+    ``trigger="action"`` (default): Init ``SetRegion`` / tread ``Bubble(1)`` (if ``bubble``) / action
+    ``DisableMove; RunScriptSync(player, ride_tag); EnableMove`` -- press to board. ``trigger="tread"``:
+    the dispatch is on the tread func (auto-board on walk-in). Control is held for the whole ride
+    (synchronous ``RunScriptSync``) -- the same proven shape as the ladder/jump trigger."""
+    init = _region.set_region(zone) + opcodes.RETURN
+    dispatch = (opcodes.DISABLE_MOVE
+                + opcodes.run_script_sync(RUNSCRIPT_LEVEL, player_uid, ride_tag)
+                + opcodes.ENABLE_MOVE + opcodes.RETURN)
+    if trigger == "tread":
+        body = _region.MOVEMENT_GATE + (opcodes.bubble(1) if bubble else b"") + dispatch
+        funcs = [(0, init), (_region.RANGE_TAG, body)]
+    else:                                             # "action" -- press-to-board (+ "!" prompt)
+        tread = _region.MOVEMENT_GATE + (opcodes.bubble(1) if bubble else b"") + opcodes.RETURN
+        action = _region.MOVEMENT_GATE + dispatch
+        funcs = [(0, init), (_region.RANGE_TAG, tread), (_region.INTERACT_TAG, action)]
+    return _assemble_entry(funcs)
+
+
+def inject_platform(data, zone, *, rise: int | None = None, land=None, speed: int = DEFAULT_SPEED,
+                    ride_tag: int = FIRST_PLATFORM_TAG,
+                    duration: int = DEFAULT_DURATION, animation: int | None = None,
+                    trigger: str = "action", bubble: bool = True, warp_to: int | None = None,
+                    warp_entrance: int = 0, player_uid: int = PLAYER_UID, activate: bool = True):
+    """Inject one carry platform: graft the ride function (``ride_tag``) onto the player entry, append a
+    boarding region that fires it, and arm the region. Pass ``land=[x,z,y]`` (ride from the boarding spot
+    to that landing floor) or ``rise=<units>`` (vertical lift). Returns ``(new_bytes, region_slot)``. For
+    multiple platforms pass a distinct ``ride_tag`` each (start at :data:`FIRST_PLATFORM_TAG`)."""
+    body = carry_body(rise=rise, land=land, speed=speed, duration=duration, animation=animation,
+                      warp_to=warp_to, warp_entrance=warp_entrance)
+    eb = EbScript.from_bytes(data)
+    pe = find_player_entry(eb)
+    data = edit.add_function(data, pe, ride_tag, body)
+    eb = EbScript.from_bytes(data)
+    slot = eb.first_free_slot()
+    data = edit.append_entry(data, slot, platform_region([tuple(p) for p in zone], ride_tag,
+                                                         trigger=trigger, bubble=bubble, player_uid=player_uid))
+    if activate:
+        data = edit.activate(data, opcodes.init_region(slot, 0))
+    return data, slot
+
+
+RIDE_WARMUP = 2           # tiny warm-up after control is handed; the rise then OVERLAPS the fade-in so the
+                          # camera pans up AS the map fades in (the player is occluded down the hole until
+                          # he emerges near the top -- the floor occlusion, not the fade, hides him)
+
+
+def entry_rise_body(*, land, rise: int, duration: int = DEFAULT_DURATION, animation: int | None = None) -> bytes:
+    """The on-arrival elevator ride, ENTIRELY in the player's post-fade ride function (RunScriptSync
+    controls the player reliably here -- a drop spliced into the player Init does NOT stick, the engine
+    re-places him on the floor). One self-contained function:
+
+      detach -> MoveInstantXZY to the EXACT hole bottom (lx, -ly+rise, lz) -> per-frame rise loop that
+      pins x/z to (lx, lz) CONSTANTS and only decreases selfY toward the floor -> exact floor snap ->
+      re-attach (land flush).
+
+    Everything is ABSOLUTE (no stale-selfY capture -> no overshoot) and the rise is a plain decrement (NO
+    division -> the land-mode divide-by-(land-start) garbage that flung the player sideways cannot happen).
+    x/z are re-asserted every frame so he can never drift left/right."""
+    lx, lz = int(land[0]), int(land[1])
+    ly = int(land[2]) if len(land) > 2 else 0
+    rise = abs(int(rise))
+    floor_selfy = -ly                                  # the let-off floor selfY (= -worldY)
+    bottom_selfy = -ly + rise                          # the hole bottom, `rise` below the floor
+    duration = max(1, int(duration))
+    smag = max(1, math.ceil(rise / duration))          # per-frame UP step (selfY decreases)
+
+    def selfy(): return _selfv(F_Y)
+
+    a = _Asm()
+    a.raw(opcodes.add_character_attribute(LADDER_FLAG) + opcodes.set_pathing(0))      # detach; don't floor-snap
+    a.raw(opcodes.encode(0xA1, _arg(_const(lx)), _arg(_const(bottom_selfy)), _arg(_const(lz)),
+                         arg_flags=0b111))                                            # drop to the hole bottom (abs)
+    if animation is not None:
+        a.raw(opcodes.run_animation(int(animation)))
+    a.label("LOOP")
+    a.raw(opcodes.encode(0xA1, _arg(_const(lx)),                                      # x pinned (no drift)
+                         _arg(selfy(), _const(smag), bytes([_region.T_MINUS])),       # selfY - step (rise up)
+                         _arg(_const(lz)), arg_flags=0b111))                          # z pinned
+    a.raw(opcodes.wait(1))
+    a.raw(_stmt(selfy(), _const(floor_selfy), bytes([_region.T_GT])))                 # still below the floor?
+    a.jmp(_region.JMP_TRUE, "LOOP")
+    a.raw(opcodes.encode(0xA1, _arg(_const(lx)), _arg(_const(floor_selfy)), _arg(_const(lz)),
+                         arg_flags=0b111))                                            # exact floor (abs)
+    a.raw(opcodes.remove_character_attribute(LADDER_FLAG) + opcodes.set_pathing(1))   # land flush on the floor
+    a.raw(opcodes.RETURN)
+    return a.assemble()
+
+
+def inject_entry_rise(data, *, land, rise: int, ride_tag: int = FIRST_PLATFORM_TAG,
+                      duration: int = DEFAULT_DURATION, animation: int | None = None,
+                      player_uid: int = PLAYER_UID):
+    """The on-ARRIVAL elevator: graft the self-contained drop+rise (:func:`entry_rise_body`) onto the
+    player and arm a post-control ``InitCode`` trigger that spins until ``usercontrol == 1`` then runs it
+    synchronously. NO Init-drop splice (it doesn't stick) and NO dividing land-mode (it flung the player
+    sideways) -- the whole ride is the absolute, division-free, x/z-pinned function. Returns new bytes."""
+    lx, lz = int(land[0]), int(land[1])
+    ly = int(land[2]) if len(land) > 2 else 0
+    out = data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    pe = find_player_entry(EbScript.from_bytes(out))
+    out = edit.add_function(out, pe, ride_tag,
+                            entry_rise_body(land=(lx, lz, ly), rise=rise, duration=duration, animation=animation))
+    # post-control trigger: spin until usercontrol==1, a tiny warm-up, then run the ride synchronously
+    a = _Asm()
+    a.label("WAITCTL")
+    a.raw(opcodes.wait(1))
+    a.raw(_region.cond_sysvar_eq(2, 0))                                  # usercontrol still 0 (no control yet)?
+    a.jmp(_region.JMP_TRUE, "WAITCTL")                                   # yes -> keep spinning (op_03 = backward-safe)
+    a.raw(opcodes.wait(RIDE_WARMUP)
+          + opcodes.DISABLE_MOVE
+          + opcodes.run_script_sync(RUNSCRIPT_LEVEL, player_uid, ride_tag)
+          + opcodes.ENABLE_MOVE + opcodes.RETURN)
+    entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + a.assemble()
+    slot = EbScript.from_bytes(out).first_free_slot()
+    out = edit.append_entry(out, slot, entry)
+    out = edit.activate(out, opcodes.init_code(slot, 0))
+    return out

ff9mapkit/content/player.py

@@ -0,0 +1,168 @@
+"""Player-function graft -- carry the donor field's player functions onto the fork player.
+
+The next step after object carry (:mod:`content.object`): when a carried object's interactive function
+``RunScript``s a PLAYER tag >= 2 (e.g. the field-122 cask's tag-2 does ``RunScript(player, 24)`` -> the
+player turns toward the cask), that tag doesn't exist on the blank fork player (tags ``[0, 1]`` only), so
+the object graft drops it to ``init_only``. This module grafts those donor player functions onto the fork
+player at a fresh tag band, the object's ``RunScript`` tag is remapped to the new tag (in
+:func:`content.object.remap_entry_refs`), and -- the load-bearing catch -- the donor Init's animation-pack
+loads are spliced so the grafted gestures' clips are actually loaded.
+
+It GENERALIZES the one-function jump/ladder graft (:func:`content.jump.inject_jump` /
+:func:`content.ladder.inject_ladder` each add ONE player function via :func:`eb.edit.add_function`) to N
+functions, with:
+
+  * :class:`PlayerTagAllocator` -- a single next-free allocator across the ladder (17+), jump (40+) and
+    object (64+) bands, so the bands never collide regardless of count.
+  * :func:`remap_player_tag_calls` -- the intra-graft player->player tag remap (depth-0 in practice).
+  * :func:`ensure_player_anim_packs` -- the donor Init's ``RunModelCode`` pack-loads spliced into the fork
+    player Init.
+
+Specs come from :func:`ff9mapkit.eventscan.scan_player_funcs` (only ``safety == "clean"`` funcs are
+grafted; the rest leave their seeding object ``init_only``). Full recipe: ``docs/PLAYER_GRAFT.md``.
+"""
+from __future__ import annotations
+
+from .. import eventscan
+from ..eb import EbScript, edit, opcodes
+from ..eb.disasm import iter_code
+from .jump import FIRST_JUMP_TAG
+from .ladder import FIRST_CLIMB_TAG, find_player_entry
+from .object import _arg_byte_offset
+
+FIRST_OBJECT_PLAYER_TAG = 64   # the object-referenced player-func band (clear of ladder 17+, jump 40+)
+DEFINE_PC_OP = 0x2C            # DefinePlayerCharacter -- the splice point for the anim-pack prologue
+
+
+class PlayerTagAllocator:
+    """Hands out fresh fork-player function tags, never colliding across the three graft bands
+    (ladder 17+ / jump 40+ / object 64+). Built from the fork player's existing tags (``{0, 1}`` on a
+    blank fork); :meth:`take` starts at the band floor and slides past any prior band's overflow, so a
+    field with > 24 jumps (which would push the jump band into 64) can't alias the object band. For every
+    in-budget field this returns exactly the fixed-counter tags the jump/ladder grafts use today (so their
+    in-game proofs + the hut golden are preserved); it only changes the previously-broken overflow case."""
+
+    FLOORS = {"ladder": FIRST_CLIMB_TAG, "jump": FIRST_JUMP_TAG, "object": FIRST_OBJECT_PLAYER_TAG}
+
+    def __init__(self, data):
+        eb = data if isinstance(data, EbScript) else EbScript.from_bytes(data)
+        self._used = {f.tag for f in eb.entry(find_player_entry(eb)).funcs}
+
+    def take(self, kind, n=1):
+        """``n`` fresh tags in ``kind``'s band ('ladder'|'jump'|'object'), none colliding with prior takes."""
+        t, out = self.FLOORS[kind], []
+        for _ in range(int(n)):
+            while t in self._used:
+                t += 1
+            self._used.add(t)
+            out.append(t)
+            t += 1
+        return out
+
+
+def remap_player_tag_calls(body, tagmap) -> bytes:
+    """Site (b): within a grafted player function body, remap an intra-graft player->player ``RunScript``'s
+    tag arg (arg2) to its fork tag. Depth-0 in practice (the census found no object-path player func calls
+    another player tag), so this is a defensive same-length pass; function-relative jumps survive untouched."""
+    if not tagmap:
+        return bytes(body)
+    b = bytearray(body)
+    for ins in iter_code(bytes(b), 0, len(b)):
+        if ins.op in eventscan.RUNSCRIPT_OPS:
+            uid, tag = ins.imm(1), ins.imm(2)
+            if uid in (eventscan.UID_PLAYER, eventscan.UID_SELF) and tag in tagmap:
+                bo = _arg_byte_offset(ins, 2)
+                if bo is not None:
+                    b[ins.off + bo] = tagmap[tag] & 0xFF
+    return bytes(b)
+
+
+def ensure_player_anim_packs(data, packs) -> bytes:
+    """Splice the donor player Init's ``RunModelCode`` anim-pack loads into the fork player Init (after
+    ``DefinePlayerCharacter``), so a grafted gesture's clip is actually loaded -- the fork player otherwise
+    loads only the blank-field default pack, leaving a clip from another pack SILENTLY unloaded
+    (docs/PLAYER_GRAFT.md S4). ``packs`` are decoded ``RunModelCode`` arg tuples (from
+    :func:`ff9mapkit.eventscan.scan_player_funcs`), re-encoded byte-exact. De-duped + idempotent (skips
+    packs the fork Init already loads). Generalizes :func:`content.jump.ensure_jump_animation`."""
+    if not packs:
+        return data
+    eb = EbScript.from_bytes(data)
+    pe = find_player_entry(eb)
+    init = eb.entry(pe).func_by_tag(0)
+    if init is None:
+        return data
+    have = {tuple(ins.args) for ins in eb.instrs(init)
+            if ins.op == eventscan.RUN_MODEL_CODE_OP and not any(ins.arg_is_expr)}
+    block = b"".join(opcodes.encode(eventscan.RUN_MODEL_CODE_OP, *p)
+                     for p in packs if tuple(p) not in have)
+    if not block:
+        return data
+    dpc = next((i for i in eb.instrs(init) if i.op == DEFINE_PC_OP), None)
+    rel = (dpc.end - init.abs_start) if dpc is not None else 0
+    return edit.insert_in_function(data, pe, 0, rel, block)
+
+
+def graft_player_funcs(data, specs, tagmap, *, load=None, graftable_safeties=("clean",)) -> bytes:
+    """Graft each graftable player function verbatim onto the fork player at its fork tag
+    (``tagmap[donor_tag]``) via :func:`eb.edit.add_function` -- the N-function generalization of the
+    one-func jump/ladder graft. Splices the donor Init's anim packs first (so the gestures' clips load).
+    Non-graftable funcs are skipped (their seeding object stays ``init_only``). ``specs`` come from
+    :func:`ff9mapkit.eventscan.scan_player_funcs`; bodies are inline (``body``) or loaded via
+    ``load(spec["bin"])``. Returns the new ``.eb`` bytes (unchanged when nothing is graftable).
+
+    ``graftable_safeties`` (default ``("clean",)``) selects which safety classes are grafted; the
+    text-carry path passes ``("clean", "text")`` so a ``text`` player func (one whose window TXID the carry
+    is about to remap + ship) is also grafted -- its bytes are graft-safe once its text is carried. Default
+    is byte-identical to before (only ``clean`` funcs)."""
+    ok = set(graftable_safeties)
+    clean = [s for s in specs if s.get("safety") in ok and int(s["donor_tag"]) in tagmap]
+    if not clean:
+        return data
+    packs = []
+    for s in clean:
+        for p in s.get("donor_init_packs") or []:
+            if tuple(p) not in packs:
+                packs.append(tuple(p))
+    data = ensure_player_anim_packs(data, packs)
+    pe = find_player_entry(EbScript.from_bytes(data))
+    for s in clean:
+        body = s.get("body")
+        if body is None:
+            if load is None:
+                raise ValueError(f"player_func spec (tag {s.get('donor_tag')}) has no body and no loader")
+            body = load(s["bin"])
+        body = remap_player_tag_calls(bytes(body), tagmap)
+        data = edit.add_function(data, pe, tagmap[int(s["donor_tag"])], body)
+    return data
+
+
+def remap_player_func_siblings(data, tagmap, slot_map) -> bytes:
+    """Post-graft pass: in each grafted player function, remap a CARRIED-sibling uid ref to that sibling's
+    fork slot. A grafted func may ``TurnTowardObject`` a carried sibling -- the save Moogle's funcs 13/14/15
+    each ``TurnTowardObject(<Moogle donor slot>)``; once the object graft has placed the Moogle at its fork
+    slot (``slot_map``: donor_idx -> fork_slot), rewrite the uid. Same-length 1-byte patch, exactly like
+    :func:`content.object.remap_entry_refs`. Only uids that are carried-object slots (in ``slot_map``) are
+    touched -- player/self/party uids are never in ``slot_map``. Runs AFTER both grafts so the map exists; a
+    no-op (byte-identical) without carried siblings (``slot_map`` empty / no matching ref)."""
+    if not slot_map or not tagmap:
+        return data
+    eb = EbScript.from_bytes(data)
+    pe = find_player_entry(eb)
+    fork_tags = set(tagmap.values())
+    b = bytearray(data)
+    for f in eb.entry(pe).funcs:
+        if f.tag not in fork_tags:
+            continue
+        for ins in eb.instrs(f):
+            spec = eventscan.REF_OPS.get(ins.op)
+            if not spec:
+                continue
+            for ai in spec.get("uid", ()):
+                if ai >= len(ins.arg_is_expr) or ins.arg_is_expr[ai]:
+                    continue
+                v = ins.imm(ai)
+                if v is not None and int(v) in slot_map:
+                    bo = _arg_byte_offset(ins, ai)
+                    if bo is not None:
+                        b[ins.off + bo] = slot_map[int(v)] & 0xFF
+    return bytes(b)