nnnotes 0.1.0__py3-none-any.whl

nnnotes/adv.py

@@ -0,0 +1,243 @@
+"""ADV (2D story) extractor: episode script + text/sound/video shards -> episode.json.
+
+The episode `.asset` is an AdvEpisodeCollection MonoBehaviour whose `Collection`
+is the flat command list (UnityPy read_typetree decodes it directly). The
+`-Text/-Sound/-SoundCueSheet/-Video` sibling keys are plain-JSON TextAssets.
+Output is a self-contained JSON a viewer can play without any game code.
+
+`resources` is the episode's asset closure as AdvEpisodeResourceLoader.AddEpisodeLoadingTask
+builds it row by row (see `closure`); cue sheets are not listed (the -SoundCueSheet shard holds them).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .catalog import Catalog
+from .config import apk_missing
+from . import master, unity
+from .advcommand import COMMAND
+
+# AdvEpisodeResourceLoader.AddEpisodeLoadingTask, per command: (resource kind, catalog-key prefix) of the asset named
+# by TargetAssetName. The address is prefix + name; a blank name loads nothing (GetXxxAssetAddress). Costume rows load
+# nothing (the model is the Character row with the same TargetName and TargetAssetIndex).
+RESOURCE_PREFIX = {
+    "Character": ("live2d", "Character/Live2D/"),
+    "Stage": ("stage", "Adv/Stage/"),
+    "Still": ("still", "Adv/Still/"),
+    "Frame": ("frame", "Adv/Frame/"),
+    "Effect": ("effect", "Adv/Effect/"),              # instance keyed by TargetName (LoadParticleEffect)
+    "PostEffect": ("posteffect", "Adv/PostEffect/"),
+    "Timeline": ("timeline", "Adv/Timeline/"),        # TargetAssetName, else TargetName
+    "ChatStamp": ("chatstamp", "Adv/Chat/Stamp/"),
+}
+# Resources derived from other fields
+TRANSITION_PREFIX = "Adv/Transition/"      # FadeOut / FadeIn: TargetAssetName, else the player settings' default
+TALK_WINDOW_PREFIX = "UI/Prefab/Parts/Adv/Talk/"   # TalkWindow: TargetAssetName, else DEFAULT_TALK_WINDOW
+DEFAULT_TALK_WINDOW = "UIDefaultTalkWindow"
+CHAT_WINDOW_PREFIX = "Adv/Chat/Prefabs/"   # ChatWindow: MasterAdvChat[TargetChatID]._chatWindowAssetName
+CHAT_ICON_PREFIX = "Adv/Chat/Icon/"        # ChatTalk / ChatStamp: MasterAdvChat[TargetChatID]._chatIconAssetName
+VIDEO_ADDRESS = "Cri/Video/{0}"            # Movie / Clip: the -Video row of VideoID, _assetName (VideoAssetHelper)
+EMBEDDED_PREFIX = "Emb"                    # AddressableConsts.TryResolveAddressInternal: address, else "Emb" + address
+PLAYER_SETTINGS_KEY = "EmbCommon/Adv/Settings/AdvPlayerSettings"
+TRANSITION_COMMANDS = ("FadeOut", "FadeIn")
+VIDEO_COMMANDS = ("Movie", "Clip")
+CHAT_ICON_COMMANDS = ("ChatTalk", "ChatStamp")
+
+LANGS = ("_japanese", "_english", "_traditionalChinese", "_simplifiedChinese", "_korean")
+
+
+@dataclass
+class AdvExtract:
+    adv_id: int
+    asset: str
+    commands: list[dict]
+    text: dict
+    sounds: dict
+    cuesheets: dict
+    videos: dict
+    resources: list[dict]
+    master: dict          # MasterAdv row: playback mode, title text id
+    title: dict | None    # MasterText lines of the title (embedded master)
+
+
+def _master_row(adv_id: int, master_dir: Path) -> dict:
+    for r in master.table(master_dir, "MasterAdv"):
+        if r["_id"] == adv_id:
+            return r
+    raise KeyError(f"MasterAdv has no row {adv_id}")
+
+
+def _master_text(text_id: str, master_dir: Path) -> dict:
+    for r in master.table(master_dir, "MasterText"):
+        if r["_id"] == text_id:
+            return {lang[1:]: r[lang] for lang in LANGS}
+    raise KeyError(f"MasterText has no row {text_id}")
+
+
+def _text_of(cat: Catalog, key: str) -> str | None:
+    if not cat.has(key):
+        return None
+    for p in cat.fetch_key(key):
+        ta = unity.textassets(unity.load(p))
+        if ta:
+            return next(iter(ta.values()))
+    return None
+
+
+def extract(cat: Catalog, master_dir: Path, adv_id: int) -> AdvExtract:
+    row = _master_row(adv_id, master_dir)
+    a = row["_advEpisodeAsset"]
+    base = f"Adv/Episode/{a}/{a}"
+
+    # 1) episode command list (MonoBehaviour typetree)
+    coll = None
+    for p in cat.fetch_key(base):
+        tt = unity.first_mono(unity.load(p), must_have="Collection")
+        if tt:
+            coll = tt["Collection"]
+            break
+    if coll is None:
+        raise RuntimeError(f"episode Collection not found for {a}")
+
+    # 2) shards
+    def shard(suf):
+        t = _text_of(cat, f"{base}{suf}")
+        return unity.parse_shard(t)["rows"] if t else []
+
+    text_rows = shard("-Text")
+    sound_rows = shard("-Sound")
+    cue_rows = shard("-SoundCueSheet")
+    video_rows = shard("-Video")
+    text_idx = unity.shard_index(text_rows)
+    sound_idx = unity.shard_index(sound_rows)
+
+    # 3) enrich commands
+    out_cmds = []
+    for c in coll:
+        name = COMMAND.get(c["Command"], f"Cmd{c['Command']}")
+        item = {"i": c["Index"], "cmd": name, "raw": c["Command"]}
+        # Keep every non-default field verbatim (speaker text ids/colors,
+        # camera distance, motion fade, parameters...), dropping only empties.
+        for k, v in c.items():
+            if k in ("Index", "Command"):
+                continue
+            if v in (None, "", 0, 0.0) or v == []:
+                continue
+            item[k] = v
+        if c.get("VoiceIDs"):
+            item["voiceCues"] = [
+                sound_idx[v].get("_cueName") for v in c["VoiceIDs"] if v in sound_idx
+            ]
+        tid = c.get("AdvTextID")
+        if tid and tid in text_idx:
+            r = text_idx[tid]
+            item["lines"] = {lang[1:]: r.get(lang, "") for lang in LANGS}
+        out_cmds.append(item)
+
+    # 4) resource closure
+    chats: dict = {}
+    default_transition: list[str] = []
+
+    def chat(chat_id: int) -> dict:
+        if not chats:
+            chats.update({r["_id"]: r for r in master.table(master_dir, "MasterAdvChat")})
+        if chat_id not in chats:
+            raise KeyError(f"MasterAdvChat has no row {chat_id}")
+        return chats[chat_id]
+
+    def transition() -> str:
+        if not default_transition:
+            default_transition.append(_default_transition(cat))
+        return default_transition[0]
+
+    resources = closure(coll, cat.has, unity.shard_index(video_rows), chat, transition)
+
+    return AdvExtract(
+        adv_id=adv_id, asset=a, commands=out_cmds,
+        text={r["_id"]: {lang[1:]: r.get(lang, "") for lang in LANGS} for r in text_rows if "_id" in r},
+        sounds={r["_id"]: r for r in sound_rows if "_id" in r},
+        cuesheets={r["_id"]: r for r in cue_rows if "_id" in r},
+        videos={r["_id"]: r for r in video_rows if "_id" in r},
+        resources=resources,
+        master=row,
+        title=_master_text(row["_titleTextId"], master_dir) if row["_titleTextId"] else None,
+    )
+
+
+def _name(v) -> str | None:
+    """A name field as GetXxxAssetAddress reads it: None when null, empty or white space, else the value as is."""
+    return v if isinstance(v, str) and v.strip() else None
+
+
+def closure(rows: list[dict], has, videos: dict, chat, default_transition) -> list[dict]:
+    """The assets AddEpisodeLoadingTask loads for the episode's rows (raw `Collection` rows, `Command` numbers),
+    as [{kind, address, present}] sorted by (kind, address).
+
+    `has(address)`: whether the catalog has the address; `videos`: -Video rows by id; `chat(id)`: the MasterAdvChat
+    row of a chat id; `default_transition()`: the player settings' default transition (called only when a
+    FadeOut / FadeIn row has no transition name). A row with IgnoreData only registers its Key: it loads nothing.
+    An Effect instance is keyed by TargetName: a row without one loads nothing. Talk window prefabs are embedded
+    content: the address resolves to the "Emb" key when the catalog does not have the plain one.
+    """
+    found: dict[tuple, dict] = {}
+
+    def add(kind: str, address: str) -> None:
+        found.setdefault((kind, address), {"kind": kind, "address": address, "present": has(address)})
+
+    for c in rows:
+        if c.get("IgnoreData"):
+            continue
+        name = COMMAND.get(c["Command"])
+        tgt = _name(c.get("TargetAssetName"))
+        if name in RESOURCE_PREFIX:
+            kind, prefix = RESOURCE_PREFIX[name]
+            if name == "Timeline":
+                tgt = tgt or _name(c.get("TargetName"))
+            if name == "Effect" and not _name(c.get("TargetName")):
+                tgt = None
+            if tgt:
+                add(kind, prefix + tgt)
+        if name in TRANSITION_COMMANDS:
+            add("transition", TRANSITION_PREFIX + (tgt or default_transition()))
+        elif name == "TalkWindow":
+            address = TALK_WINDOW_PREFIX + (tgt or DEFAULT_TALK_WINDOW)
+            add("talkwindow", address if has(address) else EMBEDDED_PREFIX + address)
+        elif name in VIDEO_COMMANDS and (c.get("VideoID") or 0) > 0:
+            # PrepareVideoTask: a VideoID without a -Video row (or without an asset name) loads nothing
+            asset = _name((videos.get(c["VideoID"]) or {}).get("_assetName"))
+            if asset:
+                add("video", VIDEO_ADDRESS.format(asset))
+        if (c.get("TargetChatID") or 0) > 0:
+            if name == "ChatWindow":
+                window = _name(chat(c["TargetChatID"]).get("_chatWindowAssetName"))
+                if window:
+                    add("chatwindow", CHAT_WINDOW_PREFIX + window)
+            elif name in CHAT_ICON_COMMANDS:
+                icon = _name(chat(c["TargetChatID"]).get("_chatIconAssetName"))
+                if icon:
+                    add("chaticon", CHAT_ICON_PREFIX + icon)
+    return sorted(found.values(), key=lambda d: (d["kind"], d["address"]))
+
+
+def _default_transition(cat: Catalog) -> str:
+    """AdvPlayerSettings._defaultTransitionAssetAddress (embedded content: the catalog needs the APK's)."""
+    if not cat.has(PLAYER_SETTINGS_KEY):
+        raise apk_missing("the default ADV transition (AdvPlayerSettings)")
+    for p in cat.fetch_key(PLAYER_SETTINGS_KEY):
+        tt = unity.first_mono(unity.load(p), must_have="_defaultTransitionAssetAddress")
+        if tt:
+            return tt["_defaultTransitionAssetAddress"]
+    raise RuntimeError(f"{PLAYER_SETTINGS_KEY}: no _defaultTransitionAssetAddress")
+
+
+def to_json(x: AdvExtract) -> dict:
+    return {
+        "advId": x.adv_id, "asset": x.asset,
+        "commandCount": len(x.commands),
+        "commands": x.commands,
+        "text": x.text, "sounds": x.sounds,
+        "cuesheets": x.cuesheets, "videos": x.videos,
+        "resources": x.resources,
+        "master": x.master, "title": x.title,
+    }

nnnotes/advcommand.py

@@ -0,0 +1,29 @@
+"""The ADV command numbers (AdvSystem.Asset.AdvCommand): the `Command` of an episode's rows, by value.
+
+A module of its own, with no imports, so that readers of episode data that load no bundles (the voices index) name
+commands as the story export does."""
+
+# AdvCommand enum; values 0-69, 8 and 22 unused.
+COMMAND = {
+    0: "In", 1: "Out", 2: "Talk", 3: "Delay", 4: "Shake", 5: "FadeOut",
+    6: "FadeIn", 7: "Focus", 9: "Forward", 10: "Back", 11: "Flash",
+    12: "Brightness", 13: "MoveToRight", 14: "MoveToLeft", 15: "Bgm",
+    16: "SoundVolume", 17: "Expression", 18: "Pause", 19: "Resume",
+    20: "Location", 21: "Motion", 23: "Character", 24: "Costume", 25: "Stage",
+    26: "Movie", 27: "Clip", 28: "Subtitles", 29: "Wait", 30: "Still",
+    31: "Se", 32: "Angle", 33: "Pan", 34: "Tilt", 35: "TalkWindow",
+    36: "ChatWindow", 37: "ChatTalk", 38: "ChatStamp", 39: "ChatRead",
+    40: "ChoiceSet", 41: "ChoiceShow", 42: "GoTo", 43: "PostEffect",
+    44: "Frame", 45: "Timeline", 46: "Look", 47: "Pedestal", 48: "Track",
+    49: "DoF", 50: "Role", 51: "CameraShake", 52: "Voice", 53: "Zoom",
+    54: "Effect", 55: "Alpha", 56: "ForceAuto", 57: "StageEnv",
+    58: "RimLight", 59: "CancelDelay", 60: "MoveToUp", 61: "MoveToDown",
+    62: "MoveToForward", 63: "MoveToBack", 64: "MoveToDirection",
+    65: "ChatTyping", 66: "LookTarget", 67: "PanV2", 68: "MotionLoop",
+    69: "EyeBlink",
+}
+
+
+def name(value) -> str:
+    """The command's name ("Cmd<value>" for a value the enum does not list)."""
+    return COMMAND.get(value, f"Cmd{value}")

nnnotes/advmedia.py

@@ -0,0 +1,178 @@
+"""ADV episode assets beyond the scene: frames, particle effects, post-effect profiles, stills, chat and talk windows.
+
+One JSON file per kind at the story root, written only when the episode's resource closure (adv.closure) has that
+kind; textures go to the story's `textures/` (PNG, named like the scene's) and every Shader object of the loaded
+bundle closures is handed back to advscene, which dumps them with the scene's shaders into `shaders/`:
+
+  frames.json       Frame: "Adv/Frame/" + TargetAssetName (UIAdvWidget.SetFrame / AdvFrame), keyed by
+                    TargetAssetName; each a prefab node list (AdvFrame, CanvasGroup, uGUI, Animator with its
+                    controller and clips, UIParticle / ParticleSystem). Frame texts (TargetTextIDs) are episode
+                    text ids (episode.json `text`).
+  effects.json      Effect: "Adv/Effect/" + TargetAssetName, instantiated once per TargetName
+                    (AdvEpisodeResourceLoader.LoadParticleEffect): `effects` by TargetAssetName (AdvParticleEffect,
+                    ParticleSystem modules and renderers, Animator), `instances` TargetName -> TargetAssetName
+  posteffects.json  PostEffect: "Adv/PostEffect/" + TargetAssetName, a URP VolumeProfile (not instantiated;
+                    AdvGlobalVolume.ToggleVolume adds it as a child volume), keyed by TargetAssetName
+  stills.json       Still: "Adv/Still/" + TargetAssetName (AdvStill, CanvasGroup, uGUI, DOTweenSequence
+                    animations), keyed by TargetAssetName
+  chat.json         ChatWindow / ChatTalk / ChatStamp: `chats` (the MasterAdvChat rows of the episode's chat ids),
+                    `windows` ("Adv/Chat/Prefabs/" + _chatWindowAssetName, AdvChatWindow prefabs), `icons`
+                    ("Adv/Chat/Icon/" + _chatIconAssetName) and `stamps` ("Adv/Chat/Stamp/" + TargetAssetName) as
+                    sprites, `text` / `sounds` / `cueSheets`: the rows of the shared chat shards
+                    (Adv/Chat/AdvChat-Text, -Sound, -SoundCueSheet); the cue sheet those rows name, AdvSe_Common,
+                    is in no language's catalog and not in the APK (1.0.1 data), so nothing is decoded for them
+  talkwindows.json  TalkWindow: "UI/Prefab/Parts/Adv/Talk/" + TargetAssetName (embedded content), keyed by window
+                    name (the default window is also in ui/ui.json in its drawn form)
+
+Prefabs are exported with export.Exporter (references resolved, AnimatorControllers followed, clips in the
+generic format). TextMeshPro text components always keep their layout and style (size, alignment, colours,
+margins, text). The font data follows `fonts`: "open" (default) exports none of it -- font / sprite / style sheet
+assets become {asset, name} and TextMeshPro materials {material, shader}, each with a note, so a viewer draws the
+text with a font of its own; "game" exports the font assets and their materials with the atlas textures like any
+other asset. A MonoBehaviour whose script is missing (Unity runs nothing for it) is recorded as such.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .catalog import Catalog
+from .export import HEADER, Exporter
+from .jsonio import write_json
+from .player import PlayerData
+from . import adv, unity
+from . import master as master_mod
+
+TMP_SHADER_PREFIX = "TextMeshPro/"
+TMP_ASSETS = ("TMP_FontAsset", "TMP_SpriteAsset", "TMP_StyleSheet")
+FONT_CHOICES = ("open", "game")
+FONT_NOTE = "font data not exported (fonts: open): draw the text with a font of your own"
+CHAT_SHARDS = {"text": "Adv/Chat/AdvChat-Text", "sounds": "Adv/Chat/AdvChat-Sound",
+               "cueSheets": "Adv/Chat/AdvChat-SoundCueSheet"}
+# resource kind -> (story.json key = file key, file, address prefix removed from the entry keys; None: last segment)
+FILES = {
+    "frame": ("frames", "frames.json", adv.RESOURCE_PREFIX["Frame"][1]),
+    "effect": ("effects", "effects.json", adv.RESOURCE_PREFIX["Effect"][1]),
+    "posteffect": ("postEffects", "posteffects.json", adv.RESOURCE_PREFIX["PostEffect"][1]),
+    "still": ("stills", "stills.json", adv.RESOURCE_PREFIX["Still"][1]),
+    "talkwindow": ("talkWindows", "talkwindows.json", None),
+}
+CHAT_KINDS = ("chatwindow", "chaticon", "chatstamp")
+CHAT = ("chat", "chat.json")
+KINDS = tuple(FILES) + CHAT_KINDS
+INDEX_KEYS = tuple(k for k, _, _ in FILES.values()) + (CHAT[0],)
+
+
+class MediaExporter(Exporter):
+    """export.Exporter for uGUI and particle prefabs: AnimatorControllers followed, missing-script MonoBehaviours
+    recorded; with fonts="open" the TextMeshPro font / sprite / style sheet assets and materials as name stubs."""
+
+    def __init__(self, cat: Catalog, out_dir: Path, player: PlayerData, fonts: str = "open"):
+        if fonts not in FONT_CHOICES:
+            raise ValueError(f"fonts={fonts!r}")
+        super().__init__(cat, out_dir, player=player, stub_assets=TMP_ASSETS if fonts == "open" else (),
+                         follow=("AnimatorController",))
+        self.fonts = fonts
+
+    def scriptable(self, o) -> dict:
+        out = super().scriptable(o)
+        if self.fonts == "open" and out.get("asset") in TMP_ASSETS:
+            return {**out, "note": FONT_NOTE}
+        return out
+
+    def material(self, o) -> dict:
+        if self.fonts == "game":
+            return super().material(o)
+        tt = o.read_typetree()
+        shader = self.deref(o, tt["m_Shader"])
+        name = self.add_shader(shader) if shader is not None else None
+        if name is None or not name.startswith(TMP_SHADER_PREFIX):
+            return super().material(o)
+        return {"material": tt["m_Name"], "shader": {"shader": name}, "note": FONT_NOTE}
+
+    def component(self, o) -> dict:
+        if o.type.name == "MonoBehaviour":
+            tt = o.read_typetree()
+            if not tt["m_Script"]["m_PathID"]:
+                return {"type": "MonoBehaviour", "class": None, "missingScript": True,
+                        **self.value(o, {k: v for k, v in tt.items() if k not in HEADER})}
+        return super().component(o)
+
+
+def _suffix(address: str, prefix: str | None) -> str:
+    if prefix is None:
+        return address.rsplit("/", 1)[-1]
+    if not address.startswith(prefix):
+        raise ValueError(f"{address}: not under {prefix}")
+    return address[len(prefix):]
+
+
+def effect_instances(commands: list[dict]) -> dict[str, str]:
+    """TargetName -> TargetAssetName of the effect instances (LoadParticleEffect: the first asset loaded under a
+    TargetName is the instance every later Effect row with that TargetName drives)."""
+    out: dict[str, str] = {}
+    for c in commands:
+        if c["cmd"] == "Effect" and not c.get("IgnoreData") and adv._name(c.get("TargetName")) \
+                and adv._name(c.get("TargetAssetName")):
+            out.setdefault(c["TargetName"], c["TargetAssetName"])
+    return out
+
+
+def _chat(cat: Catalog, master: Path, ex: Exporter, episode: dict, resources: list[dict]) -> dict:
+    rows = {r["_id"]: r for r in master_mod.table(master, "MasterAdvChat")}
+    ids = sorted({c["TargetChatID"] for c in episode["commands"] if c.get("TargetChatID")})
+    doc: dict = {"chats": {str(i): rows[i] for i in ids if i in rows},
+                 "windows": {}, "icons": {}, "stamps": {}}
+    for r in resources:
+        if r["kind"] == "chatwindow":
+            doc["windows"][_suffix(r["address"], adv.CHAT_WINDOW_PREFIX)] = ex.export_key(r["address"])
+        elif r["kind"] == "chaticon":
+            doc["icons"][_suffix(r["address"], adv.CHAT_ICON_PREFIX)] = ex.key_sprite(r["address"])
+        elif r["kind"] == "chatstamp":
+            doc["stamps"][_suffix(r["address"], adv.RESOURCE_PREFIX["ChatStamp"][1])] = ex.key_sprite(r["address"])
+    for name, key in CHAT_SHARDS.items():
+        t = adv._text_of(cat, key)
+        doc[name] = unity.parse_shard(t)["rows"] if t else []
+    return doc
+
+
+def extract(cat: Catalog, player: PlayerData, master: Path, episode: dict, out_dir: Path,
+            fonts: str = "open") -> dict:
+    """Write the kind files the episode needs (`fonts`: see the module docstring). Returns {"files": {index key:
+    file or None} for every INDEX_KEYS entry, "shaders": {name: Shader object}, "counts": {index key: entries},
+    "textures": textures written}."""
+    out_dir = Path(out_dir)
+    by_kind: dict[str, list[dict]] = {}
+    for r in episode["resources"]:
+        if r["kind"] in KINDS:
+            by_kind.setdefault(r["kind"], []).append(r)
+    files: dict[str, str | None] = dict.fromkeys(INDEX_KEYS)
+    shaders: dict = {}
+    counts: dict[str, int] = {}
+    textures = 0
+
+    def done(ex: Exporter, name: str, doc: dict) -> None:
+        nonlocal textures
+        ex.resolve_pending()
+        write_json(out_dir / name, doc)
+        for k, o in ex.shaders.items():
+            shaders.setdefault(k, o)
+        textures += len(ex.textures)
+
+    for kind, (key, name, prefix) in FILES.items():
+        if kind not in by_kind:
+            continue
+        ex = MediaExporter(cat, out_dir, player, fonts)
+        entries = {_suffix(r["address"], prefix): ex.export_key(r["address"]) for r in by_kind[kind]}
+        doc: dict = {key: entries}
+        if kind == "effect":
+            doc["instances"] = effect_instances(episode["commands"])
+        done(ex, name, doc)
+        files[key] = name
+        counts[key] = len(entries)
+    chat = [r for k in CHAT_KINDS for r in by_kind.get(k, [])]
+    if chat:
+        ex = MediaExporter(cat, out_dir, player, fonts)
+        done(ex, CHAT[1], _chat(cat, master, ex, episode, chat))
+        files[CHAT[0]] = CHAT[1]
+        counts[CHAT[0]] = len(chat)
+    return {"files": files, "shaders": shaders, "counts": counts, "textures": textures}

nnnotes/advscene.py

@@ -0,0 +1,113 @@
+"""ADV presentation data -> scene.json + textures + shaders.
+
+Everything the game uses to present an ADV episode besides the episode script,
+the Live2D models and the audio:
+
+  player          colour space, quality levels, URP pipelines, renderer data and
+                  features, post-process data (APK boot data, see player.py)
+  cameraManager   the app's Main/Sub camera prefab
+  advScene        the ADV scene (AdvSceneRoot + scene camera)
+  characterField  AdvCharacterField prefab (Field / Anchors / Stages)
+  backgroundField AdvBackgroundField prefab (backdrop mesh + sprite renderer)
+  globalVolume    AdvGlobalVolume prefab (volumes + profiles)
+  settings        AdvPlayerSettings (+ focus data), AdvMasterIdSettings
+  stages          every stage prefab the episode uses (AdvStage, lights,
+                  background sprite, volume profiles)
+  resources       Resources.Load materials the runtime draws with (Cubism mask
+                  pass: Mask / MaskCulling)
+  postTextures    per camera renderer: post-process data textures used by the
+                  URP chain (film grain textures, indexed by FilmGrain.type)
+
+Objects are exported with export.Exporter (references resolved, textures as
+PNG). Shaders referenced anywhere, every Shader in the loaded bundle closures,
+the ADV camera renderer's shaders and the shaders handed in by the caller (those
+of advmedia's kind files) are dumped with shader.py into one `shaders/`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .catalog import Catalog
+from .export import Exporter
+from .jsonio import write_json
+from .player import PlayerData
+from . import shader as shader_mod
+
+ADV_KEYS = {
+    "cameraManager": "EmbCommon/Prefab/CameraManager",
+    "advScene": "EmbScene/Adv",
+    "characterField": "EmbCommon/Adv/Prefab/AdvCharacterField",
+    "backgroundField": "EmbCommon/Adv/Prefab/AdvBackgroundField",
+    "globalVolume": "EmbCommon/Adv/Prefab/AdvGlobalVolume",
+}
+SETTINGS_KEYS = {
+    "playerSettings": "EmbCommon/Adv/Settings/AdvPlayerSettings",
+    "masterIdSettings": "EmbCommon/Adv/Settings/AdvMasterIdSettings",
+}
+STAGE_PREFIX = "Adv/Stage/"
+
+
+# Resources.Load paths used by the ADV runtime (Cubism mask pass materials)
+RESOURCES = {
+    "cubismMask": "Live2D/Cubism/Materials/Mask",
+    "cubismMaskCulling": "Live2D/Cubism/Materials/MaskCulling",
+}
+
+
+def camera_renderer(player_graphics: dict, pipeline: str, renderer_index: int) -> str:
+    rl = player_graphics["pipelines"][pipeline]["m_RendererDataList"]
+    i = player_graphics["pipelines"][pipeline]["m_DefaultRendererIndex"] if renderer_index < 0 else renderer_index
+    return rl[i]
+
+
+def extract(cat: Catalog, player: PlayerData, episode: dict, out_dir: Path, shaders: dict | None = None) -> dict:
+    """Write scene.json, textures/ and shaders/. `shaders`: further {name: Shader object} to dump with the scene's
+    (the scene's object wins for a name both have)."""
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    ex = Exporter(cat, out_dir, player=player)
+    graphics = player.graphics()
+    doc: dict = {"player": graphics}
+    for name, key in ADV_KEYS.items():
+        doc[name] = ex.prefab(key)
+    doc["settings"] = {name: ex.asset(key) for name, key in SETTINGS_KEYS.items()}
+    doc["resources"] = {name: ex.material(player.resource(path)) for name, path in RESOURCES.items()}
+
+    stages = {}
+    for c in episode["commands"]:
+        if c["cmd"] == "Stage" and c.get("TargetAssetName"):
+            key = STAGE_PREFIX + c["TargetAssetName"]
+            stages.setdefault(c["TargetAssetName"], None)
+            if stages[c["TargetAssetName"]] is None:
+                stages[c["TargetAssetName"]] = ex.prefab(key)
+    doc["stages"] = stages
+
+    # shaders: model closures, everything referenced above, the ADV camera renderer
+    for r in episode["resources"]:
+        if r["kind"] == "live2d":
+            ex.closure_shaders(r["address"])
+    renderers = set()
+    for node in doc["cameraManager"]["nodes"]:
+        for comp in node["components"]:
+            if comp.get("class") == "UniversalAdditionalCameraData":
+                renderers.add(camera_renderer(graphics, graphics["defaultPipeline"],
+                                              comp["m_RendererIndex"]))
+    for rn in sorted(renderers):
+        for o in player.renderer_shaders(rn):
+            ex._shader(o)
+    for name, o in (shaders or {}).items():
+        ex.shaders.setdefault(name, o)
+    # post-process textures the URP chain samples (film grain lookup by FilmGrain.type)
+    doc["postTextures"] = {rn: {"filmGrainTex": [ex.texture(o) for o in player.post_textures(rn, "filmGrainTex")]}
+                           for rn in sorted(renderers)}
+    sdir = out_dir / "shaders"
+    index: list = []
+    for name in sorted(ex.shaders):
+        shader_mod.dump_objects([ex.shaders[name]], sdir, ex.shaders[name].assets_file.name, index)
+    shader_summary = shader_mod.write_index(index, sdir)
+    doc["shaders"] = {"index": "shaders/shaders.json", "names": shader_summary["names"],
+                      "cameraRenderers": sorted(renderers)}
+    doc["convention"] = ("Unity space (left-handed, Y up); transforms are local TRS; "
+                         "quaternions (x,y,z,w); colours in the project's Gamma space")
+    write_json(out_dir / "scene.json", doc)
+    return {"stages": list(stages), "textures": len(ex.textures), **shader_summary}