@@ -1,6 +1,8 @@
 # mhfu
 
-What the modkit knows about Monster Hunter Freedom Unite (PSP, EU release ULES01213) at runtime.
+What the modkit knows about Monster Hunter Freedom Unite (PSP, EU release ULES01213): the game's
+addresses and structs, and the analysis of its code. Everything reads through one memory
+interface, so the same code runs on the running game, a RAM dump or the game's own files.
 
 ## Addresses
 
@@ -17,10 +19,52 @@ addresses.ENTITY.HP  # <HP +0x2E4 u16>, the field's offset
 ```
 
 ```bash
-python -m mhfu.addresses c -o addresses.gen.h      # MHFU_SCREEN_STATE, MHFU_ENTITY_HP, ...
-python -m mhfu.addresses lua -o addresses.gen.lua  # mhfu.addr.SCREEN_STATE, mhfu.addr.ENTITY.HP, ...
+mhfu addresses c -o addresses.gen.h      # MHFU_SCREEN_STATE, MHFU_ENTITY_HP, ...
+mhfu addresses lua -o addresses.gen.lua  # mhfu.addr.SCREEN_STATE, mhfu.addr.ENTITY.HP, ...
 ```
 
 Product code in this repository never writes an address as a number: a pre-commit check rejects
 one. For a value that only looks like an address, such as a MIPS jump opcode, end the line with
 a `noaddr` comment.
+
+## Memory and typed views
+
+```python
+from mhfu.files import Extracted
+from mhfu.memory import Image, Live
+from mhfu.structs import Entity
+
+game = Extracted.find("extracted/")  # the output of `mhp-formats extract`
+em75 = game.em(75)  # the Tigrex overlay, mapped where the game loads it
+em75.u32(em75.text.start)
+
+Entity(Image(dump, base), address).hp  # from a RAM dump
+Entity(Live(client), address).hp = 1  # in the running game, via ppsspp_debug.Client
+```
+
+A view's fields take their offset and type from `addresses.toml`; one that disagrees fails at
+import.
+
+## Overlay and EBOOT analysis
+
+The game's code is plain MIPS in `BOOT.BIN` and in its overlays (`game_task`, `game_sub`, one
+`emNN` per big monster, one per stage). `mhfu.mips` decodes it with
+[rabbitizer](https://github.com/Decompollaborate/rabbitizer) and finds functions, calls, switches
+and constants; the commands below are built on it. They read an extracted game from `--data` or
+`MHFU_DATA`.
+
+| Command | What it prints |
+|---|---|
+| `mhfu dis ADDR [COUNT]`, `xref ADDR`, `switch ADDR` | Disassembly, references, jump tables, in BOOT.BIN or `--overlay` |
+| `mhfu reloc OVERLAY DELTA -o OUT` | An overlay moved to another address |
+| `mhfu moveset`, `phases`, `chain SPECIES` | A big monster's moves, what ends each, what follows it |
+| `mhfu effects`, `attacks`, `abi` | The effects and attacks each move spawns; the engine-to-overlay interface |
+| `mhfu hitzones`, `hitboxes SPECIES` | Where a monster can be hit, and where it hits |
+| `mhfu census --log framework.log` | How long each move lasted in a real game, from the framework's log |
+| `mhfu intel --all` | All of the above per species, as `species/emNN.json` |
+| `mhfu stage ids\|maps\|exits\|surfaces` | Stage files, the map table, area exits |
+| `mhfu inject FILE_ID FILE` | Places a finished file for the framework's live injection |
+
+## Licence
+
+MIT.
@@ -1,11 +1,15 @@
 [project]
 name = "mhfu"
 version = "0.1.0"
-description = "Monster Hunter Freedom Unite (PSP) runtime knowledge: addresses and struct layouts."
+description = "Monster Hunter Freedom Unite (PSP) at runtime: addresses, live structs, automation, overlay analysis."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
-dependencies = []
+dependencies = ["ppsspp-debug", "rabbitizer>=1.16", "pyelftools>=0.31", "psutil>=6"]
+classifiers = ["Typing :: Typed"]
+
+[project.scripts]
+mhfu = "mhfu.cli:main"
 
 [build-system]
 requires = ["uv_build>=0.11,<0.12"]
 
@@ -12,7 +12,6 @@
 
 from __future__ import annotations
 
-import argparse
 import functools
 import re
 import sys
@@ -65,9 +64,18 @@ class Struct:
     doc: str
     fields: dict[str, Field]
     size: int | None = None
+    stride: int | None = None
+
+    @property
+    def step(self) -> int:
+        """Bytes from one of these to the next in a table: `stride`, else `size`."""
+        step = self.stride or self.size
+        if step is None:
+            raise TypeError(f"struct {self.name} has no size or stride in addresses.toml")
+        return step
 
     def __getattr__(self, name: str) -> Field:
-        fields = self.__dict__.get("fields", {})
+        fields: dict[str, Field] = self.__dict__.get("fields", {})
         if name in fields:
             return fields[name]
         raise AttributeError(f"struct {self.__dict__.get('name')} has no field {name}")
@@ -119,13 +127,16 @@ def parse(data: dict[str, Any]) -> Table:
         where = f"struct.{name}"
         if not _NAME.match(name):
             problems.append(f"{where}: names are UPPER_SNAKE_CASE")
-        if not isinstance(entry, dict) or set(entry) - {"doc", "size", "fields"}:
-            problems.append(f"{where}: expects doc, fields and an optional size")
+        if not isinstance(entry, dict) or set(entry) - {"doc", "size", "stride", "fields"}:
+            problems.append(f"{where}: expects doc, fields and an optional size or stride")
             continue
-        size = entry.get("size")
+        size, stride = entry.get("size"), entry.get("stride")
         if size is not None and (not isinstance(size, int) or size <= 0):
             problems.append(f"{where}: size must be a positive integer")
             size = None
+        if stride is not None and (not isinstance(stride, int) or stride <= 0):
+            problems.append(f"{where}: stride must be a positive integer")
+            stride = None
         _doc_ok(where, entry.get("doc"), problems)
         fields: dict[str, Field] = {}
         by_offset: dict[int, str] = {}
@@ -142,14 +153,14 @@ def parse(data: dict[str, Any]) -> Table:
             fields[fname] = Field(offset, fname, fentry["type"], fentry["doc"])
         if not fields:
             problems.append(f"{where}: has no fields")
-        structs[name] = Struct(name, entry.get("doc", ""), fields, size)
+        structs[name] = Struct(name, entry.get("doc", ""), fields, size, stride)
 
     # every generated name (Python and Lua namespace, C macro) must be unique
     for name in addresses.keys() & structs.keys():
         problems.append(f"{name}: is both an address and a struct")
     macros: dict[str, str] = {name: f"address.{name}" for name in addresses}
     for s in structs.values():
-        for member in [*s.fields, *(["SIZE"] if s.size else [])]:
+        for member in [*s.fields, *(["SIZE"] if s.size else []), *(["STRIDE"] if s.stride else [])]:
             macro = f"{s.name}_{member}"
             if macro in macros:
                 problems.append(
@@ -201,6 +212,8 @@ def render_c(t: Table) -> str:
         out += ["", f"/* struct {s.name}: {s.doc} */"]
         if s.size:
             out.append(f"#define MHFU_{s.name}_SIZE 0x{s.size:X}u")
+        if s.stride:
+            out.append(f"#define MHFU_{s.name}_STRIDE 0x{s.stride:X}u")
         for f in s.fields.values():
             out += [f"/* {f.type}: {f.doc} */", f"#define MHFU_{s.name}_{f.name} 0x{int(f):X}u"]
     out += ["", "#endif", ""]
@@ -222,6 +235,11 @@ def render_lua(t: Table) -> str:
         out += [f"    ---struct: {s.doc}", f"    {s.name} = {{"]
         if s.size:
             out += ["        ---the struct's size in bytes", f"        SIZE = 0x{s.size:X},"]
+        if s.stride:
+            out += [
+                "        ---bytes from one row to the next",
+                f"        STRIDE = 0x{s.stride:X},",
+            ]
         for f in s.fields.values():
             out += [f"        ---{f.type}: {f.doc}", f"        {f.name} = 0x{int(f):X},"]
         out.append("    },")
@@ -247,20 +265,10 @@ def __dir__() -> list[str]:
 
 
 def main(argv: list[str] | None = None) -> int:
-    ap = argparse.ArgumentParser(
-        prog="python -m mhfu.addresses",
-        description="Print the address table as a C header or a Lua module.",
-    )
-    ap.add_argument("lang", choices=sorted(RENDER))
-    ap.add_argument("-o", "--output", type=Path, help="write here instead of stdout")
-    ap.add_argument("--table", type=Path, help="read this TOML instead of the packaged one")
-    args = ap.parse_args(argv)
-    text = RENDER[args.lang](load(args.table) if args.table else table())
-    if args.output:
-        args.output.write_text(text, encoding="utf-8")
-    else:
-        sys.stdout.write(text)
-    return 0
+    """`python -m mhfu.addresses c|lua`, the same as `mhfu addresses c|lua`."""
+    from .cli import main as cli
+
+    return cli(["addresses", *(sys.argv[1:] if argv is None else argv)])
 
 
 if __name__ == "__main__":