feat(mhfu-port): a port's turn curves leave its clips module for <port>_turns.lua

Only `mhfu move play --curve` reads them, and moves carry their own copy, so the game never
loads the 31 KB module (the Zinogre's clips module: 35.8 -> 4.5 KB). mhfu.inject names a
port's libraries for both packages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sp00ktober

apps/studio/README.md

@@ -66,7 +66,7 @@ on the floor of the view (T hides it) is the turn: an arrow for frame 0, one for
 a handle for the end, which drags the clip's `turn`, or a fixed steer's angle, in whole degrees
 (Shift: 15). Every edit is one undo step.
 
-Play in game saves, writes the port's clips and moves modules to the memory stick's `mods/lib` as
+Play in game saves, writes the port's modules to the memory stick's `mods/lib` as
 `mhfu-port inject` does, and asks the running port to play the move by name; it refuses a move
 whose clip sits in another anim than in the saved manifest, since the game holds the build
 injected from the file. It writes only the modules that changed, and asks for the move from the

framework/include/mhfu/steer.h

@@ -72,7 +72,7 @@ typedef struct {
     uint8_t  stuck_main, stuck_sub, stuck_mode; /* entered on a class-2 wall: em75's (0,6) mode 1 */
     uint8_t  _pad[3];
     uint16_t keys[MHFU_STEER_KEYS]; /* YAW every KEY_STEP clip frames, the last at the clip's end:
-                                     * the clips module's `_turns` (mhfu_port.travel.Turn) */
+                                     * the port's turns module (mhfu_port.travel.Turn) */
 } mhfu_steer_spec_t;
 
 /* struct STEER_STATE in addresses.toml */

framework/lua/meta/mhfu.d.lua

@@ -647,7 +647,7 @@ function mhfu.move_block() end
 
 ---How a move turns and stops (mhfu/steer.h); every field is optional.
 ---@class mhfu.MoveSteer
----@field curve? string YAW while the clip plays: the entry's string in the clips module's `_turns`
+---@field curve? string YAW while the clip plays: the entry's string in `<port>_turns.lua`
 ---@field turn? "still"|"hunter"|"away"|"fixed" also: toward or away from the hunter at `rate`, or `total` over `frames`
 ---@field rate? integer YAW units an AI frame toward or away, default 64 (the Tigrex charge's)
 ---@field total? number degrees for "fixed", positive the way YAW grows

framework/mods/lua_host/bind_move.cpp

@@ -74,7 +74,7 @@ static int hex(int c)
 
 /* t.steer (mhfu/steer.h): turn = "still" | "hunter" | "away" | "fixed", rate (YAW units a
  * frame), total (degrees) over frames, dir (degrees), walls, stuck = { main, sub, mode }, curve
- * = the clips module's _turns string for the entry */
+ * = the entry's string in the port's turns module */
 static void steer_of(lua_State *L, int t, mhfu_steer_spec_t *sp)
 {
     mhfu_steer_init_spec(sp);

packages/mhfu-port/README.md

@@ -17,7 +17,7 @@ A manifest in `ports/` names the donor's files, the host and the build settings
 [`ports/`](../../ports)), and is the only input:
 
 ```bash
-uv run mhfu-port build ports/zinogre.toml    # zinogre.bin, the model PAC, and zinogre_clips.lua
+uv run mhfu-port build ports/zinogre.toml    # zinogre.bin, the model PAC, and its Lua modules
 uv run mhfu-port inject ports/zinogre.toml   # the same, placed for the framework to load
 ```
 

packages/mhfu-port/src/mhfu_port/cli/build.py

@@ -65,12 +65,13 @@ def _listed(written: list[Path]) -> str:
 
 
 def modules(m: manifest.Manifest, built: Built, where: Path, games: data.Data) -> list[Path]:
-    """Write the port's clips and moves modules into `where`, each whole and only when it
+    """Write the port's clips, turns and moves modules into `where`, each whole and only when it
     changed, since the game re-runs a module that changed on disk; those written. Raises
-    `ManifestError` for a move the moves module cannot carry, before either is written."""
+    `ManifestError` for a move the moves module cannot carry, before any is written."""
     known = moves.records(games.fu, m.port.host_species)
     texts = {
         layout.module_name(m): layout.lua(m, built.layout),
+        layout.turns_module_name(m): layout.turns_lua(m, built.layout),
         moves.module_name(m): moves.lua(m, built.layout, known),
     }
     where.mkdir(parents=True, exist_ok=True)

packages/mhfu-port/src/mhfu_port/layout.py

@@ -19,6 +19,7 @@
 from collections.abc import Collection, Mapping
 from dataclasses import dataclass, field
 
+from mhfu import inject
 from mhfu.entries import ENTRY_BANK, PART_STREAMS
 from mhp_formats.anim import AnimPack
 
@@ -31,8 +32,7 @@
 ENTRIES = {75: 123}
 """Executor entries per host species: the rows of its overlay's descriptor table (em75: dumped
 live). An unknown host gets one bank, or up to the last entry its own pack fills."""
-LIB = "lib"
-"""Where `require` finds a library, under the framework's mods directory."""
+LIB = inject.LIB
 
 
 class LayoutError(manifest.ManifestError):
@@ -249,20 +249,27 @@ def names(m: manifest.Manifest, layout: Layout) -> dict[int, str]:
 
 def module_name(m: manifest.Manifest) -> str:
     """The Lua module `mhfu_port`'s `P.define` requires for the port's clips."""
-    return f"{m.port.name}_clips.lua"
+    return inject.port_module(m.port.name, "clips")
+
+
+def turns_module_name(m: manifest.Manifest) -> str:
+    """The Lua module with the port's turn curves, which no mod needs: moves carry their own."""
+    return inject.port_module(m.port.name, "turns")
 
 
 _IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
-TURNS = "_turns"
-"""The clips module's key for `Layout.turns`; no clip may take the name."""
+
+
+def _source(m: manifest.Manifest) -> str:
+    return f"ports/{m.path.name}" if m.path is not None else f"the {m.port.name} manifest"
 
 
 def lua(m: manifest.Manifest, layout: Layout) -> str:
     """The module: each clip's name -> its executor entry, and the MHP3rd id it holds."""
-    src = f"ports/{m.path.name}" if m.path is not None else f"the {m.port.name} manifest"
     named = names(m, layout)
     out = [
-        f"-- {module_name(m)}, GENERATED by mhfu-port from {src}: {len(layout.entries)} clips of",
+        f"-- {module_name(m)}, GENERATED by mhfu-port from {_source(m)}: {len(layout.entries)}"
+        " clips of",
         f"-- MHP3rd file {m.source.anim} by executor entry. Do not edit: rebuild. mhfu_port's",
         "-- P.define reads it as the port's clips (name -> entry).",
         "return {",
@@ -271,16 +278,22 @@ def lua(m: manifest.Manifest, layout: Layout) -> str:
         name = named.get(e)
         if name is None:
             continue
-        if name == TURNS:
-            raise LayoutError(f"clip name {TURNS} is the module's own key")
         key = name if _IDENT.fullmatch(name) else f'["{name}"]'
         out.append(f"  {key} = {e},  -- MHP3rd {cid}")
-    if layout.turns:
-        out.append(
-            f"  -- entry -> YAW while it plays: 4 hex digits (0x10000 a turn) every {KEY_STEP}"
-            " clip frames, the last at its end"
-        )
-        out.append(f"  {TURNS} = {{")
-        out += [f'    [{e}] = "{t.lua()}",' for e, t in sorted(layout.turns.items())]
-        out.append("  },")
     return "\n".join([*out, "}", ""])
+
+
+def turns_lua(m: manifest.Manifest, layout: Layout) -> str:
+    """The turns module: entry -> YAW while it plays. `mhfu move play --curve` reads it."""
+    return "\n".join(
+        [
+            f"-- {turns_module_name(m)}, GENERATED by mhfu-port from {_source(m)}: entry -> YAW"
+            " while it plays,",
+            f"-- 4 hex digits (0x10000 a turn) every {KEY_STEP} clip frames, the last at its end."
+            " Do not edit: rebuild.",
+            "return {",
+            *(f'  [{e}] = "{t.lua()}",' for e, t in sorted(layout.turns.items())),
+            "}",
+            "",
+        ]
+    )

packages/mhfu-port/src/mhfu_port/moves.py

@@ -17,7 +17,7 @@
 from collections.abc import Collection, Mapping
 from typing import Any
 
-from mhfu import addresses, hitbox
+from mhfu import addresses, hitbox, inject
 from mhfu.files import Extracted, em_overlay
 
 from .layout import Layout
@@ -41,7 +41,7 @@ def hub(species: int) -> Pair | None:
 
 def module_name(m: Manifest) -> str:
     """The Lua module `P.define` requires for the port's moves and rules."""
-    return f"{m.port.name}_moves.lua"
+    return inject.port_module(m.port.name, "moves")
 
 
 BUILD = re.compile(r"^  build = 0x([0-9A-F]{8}),$", re.M)

packages/mhfu-port/src/mhfu_port/travel.py

@@ -338,7 +338,7 @@ def at(self, frame: ArrayLike) -> fk.Floats:
         return _curve(_grid(self.frames), np.asarray(self.keys, dtype=np.float64))(frame)
 
     def lua(self) -> str:
-        """The keys as 4 hex digits each, YAW's own 16 bits: the clips module's `_turns`."""
+        """The keys as 4 hex digits each, YAW's own 16 bits: the port's turns module."""
         return "".join(f"{k & 0xFFFF:04x}" for k in self.keys)
 
 

packages/mhfu-port/tests/test_build.py

@@ -172,7 +172,7 @@ def test_cli(data, tmp_path):
     port = m.port
     assert (tmp_path / port.pac).read_bytes() == out.read_bytes()
     assert (tmp_path / port.orig).read_bytes() == data.fu.read(port.host_frame)
-    for module in (layout.module_name(m), moves.module_name(m)):
+    for module in (layout.module_name(m), layout.turns_module_name(m), moves.module_name(m)):
         assert (lib / module).read_text() == (out.parent / module).read_text()
     assert "  charge = 61,  -- MHP3rd 61\n" in (lib / layout.module_name(m)).read_text()
     stamp = (lib / moves.module_name(m)).stat().st_mtime_ns