From 74cc08f1bf860dc52f7f85d5b4d513378f385b99 Mon Sep 17 00:00:00 2001 From: DramaticShape Date: Tue, 4 Aug 2026 10:43:35 -0400 Subject: [PATCH] dramatic stadium --- .gitignore | 39 ++ CHANGELOG.md | 191 ++++++ README.md | 61 ++ lib/BattleScene.lua | 102 ++- lib/ModSetting.lua | 83 ++- lib/OverworldBattle.lua | 135 +++- lib/Stadium.lua | 516 ++++++++++++++ lib/StadiumBuild.lua | 709 +++++++++++++++++++ lib/StadiumFragment.lua | 1016 ++++++++++++++++++++++++++++ lib/StadiumFx.lua | 436 ++++++++++++ lib/StadiumInstall.lua | 261 +++++++ lib/StadiumMon.lua | 350 ++++++++++ lib/StadiumPack.lua | 553 +++++++++++++++ lib/StadiumRig.lua | 443 ++++++++++++ lib/StadiumRom.lua | 314 +++++++++ lib/StadiumScreen.lua | 218 ++++++ lib/StadiumStage.lua | 330 +++++++++ lib/Voxel3D.lua | 24 + lib/VoxelScene.lua | 28 + main.lua | 20 +- manifest.json | 4 +- mod.card | 10 +- model_extract/README.md | 168 +++++ model_extract/baseroms/.gitignore | 5 + model_extract/baseroms/README.md | 25 + model_extract/pipeline/README.md | 93 +++ model_extract/pipeline/battle.py | 122 ++++ model_extract/pipeline/build.py | 345 ++++++++++ model_extract/pipeline/effects.py | 225 ++++++ model_extract/pipeline/fragment.py | 735 ++++++++++++++++++++ model_extract/pipeline/glb.py | 274 ++++++++ model_extract/pipeline/rom.py | 120 ++++ tests/dramatic_shape_test.lua | 256 ++++++- tests/stadium_budget_test.lua | 149 ++++ tests/stadium_extract_test.lua | 128 ++++ tests/stadium_pack_probe.lua | 115 ++++ tests/stadium_shots.lua | 294 ++++++++ tools/stadium_pack.py | 572 ++++++++++++++++ 38 files changed, 9419 insertions(+), 50 deletions(-) create mode 100644 lib/Stadium.lua create mode 100644 lib/StadiumBuild.lua create mode 100644 lib/StadiumFragment.lua create mode 100644 lib/StadiumFx.lua create mode 100644 lib/StadiumInstall.lua create mode 100644 lib/StadiumMon.lua create mode 100644 lib/StadiumPack.lua create mode 100644 lib/StadiumRig.lua create mode 100644 lib/StadiumRom.lua create mode 100644 lib/StadiumScreen.lua create mode 100644 lib/StadiumStage.lua create mode 100644 model_extract/README.md create mode 100644 model_extract/baseroms/.gitignore create mode 100644 model_extract/baseroms/README.md create mode 100644 model_extract/pipeline/README.md create mode 100644 model_extract/pipeline/battle.py create mode 100644 model_extract/pipeline/build.py create mode 100644 model_extract/pipeline/effects.py create mode 100644 model_extract/pipeline/fragment.py create mode 100644 model_extract/pipeline/glb.py create mode 100644 model_extract/pipeline/rom.py create mode 100644 tests/stadium_budget_test.lua create mode 100644 tests/stadium_extract_test.lua create mode 100644 tests/stadium_pack_probe.lua create mode 100644 tests/stadium_shots.lua create mode 100644 tools/stadium_pack.py diff --git a/.gitignore b/.gitignore index c10636b..68bd0ab 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,42 @@ __pycache__/ # agent worktrees and local scratch .claude/ + +# ------- Pokemon Stadium data +# +# NONE OF THIS SHIPS, and none of it is in the repository. The battle models +# are Pokemon Stadium's own data: what the mod carries is the READER for them +# (lib/StadiumRom, StadiumFragment, StadiumFx, StadiumBuild) and the player +# supplies the cartridge, exactly as this engine already asks them to supply +# the Game Boy ROM it is a recompilation of. +# +# So the ROM itself, everything model_extract/pipeline extracts out of it, and +# the packs tools/stadium_pack.py builds from those are all ignored. What IS +# tracked is the pipeline, the notes, and the two READMEs that say where to +# put a ROM. +# +# At runtime the packs are built on the player's own machine, on first run, +# into the save directory -- never into the mod folder (see StadiumInstall). + +# the cartridge, wherever it is dropped, and the checksum note that comes +# with one. The Zone.Identifier pattern has no colon in it on purpose: it is +# an NTFS alternate data stream, and the separator reaches git as U+F03A +# rather than as ':' -- so matching on the suffix alone is what actually works +*.z64 +*.n64 +*.v64 +*Zone.Identifier +model_extract/baseroms/**/checksum.md5 + +# everything the pipeline extracts from it +model_extract/glb/ +model_extract/js/ +model_extract/textures/ +model_extract/manifest.json +model_extract/moves.json +model_extract/viewer.html + +# and the packed models built from those -- the local oracle the Lua +# extractor is diffed against (tests/stadium_extract_test.lua), rebuilt with +# tools/stadium_pack.py whenever it is wanted +assets/stadium/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 242770b..96668f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,196 @@ # Changelog +## 1.6.0 + +### Added + +- **STADIUM battles: two new rungs on the 3D-BTL row.** The row that used + to read ON / OFF now reads **2D-3D / STADIUM A / STADIUM B / OFF**. 2D-3D + is what ON always was -- the fight staged on the map with the Game Boy's + own pics stood up on their tiles as quads. Both STADIUM rungs keep the + whole staging and replace those quads with the **Pokemon Stadium battle + models**: all 151 species, skinned, lit and animated, playing the + animation the move being used actually calls for. + + **STADIUM A** stands them on the map, in the world's own light and + weather. **STADIUM B** stands them on two discs against the sky and draws + no map at all -- the Game Boy's own framing, staged rather than found. + + B exists because the map does not always cooperate. Half of Kanto's + interiors are furniture, a cave floor can be nothing but two-cell + corridors, and some maps have nowhere a fight can be SEEN from a low + camera and are declined outright -- which drops the player back to the + flat battle screen with no warning. A carried stage has none of those + problems: it works on every map, at every step, and the framing is the + same every time. What it gives up is the thing A is for, which is + fighting somewhere real. + + It is abstracted from the GROUND, not from the world. The sky behind the + discs is the hour's own -- gold at dusk, navy at midnight -- and a fight + in a cave or a shop is under that place's void and its own flat light, so + walking into Mt. Moon at night and starting a battle looks like Mt. Moon + at night. + + The discs themselves are flat: one quad apiece, wearing a painted circle + that fades out at its rim, sized to the Pokemon standing on it. The fade + is an ordered dither baked into the texture's alpha rather than a smooth + ramp -- the scene shader discards under half alpha outright, so a ramp + would come out as a hard-edged circle -- which is the same trick the sky's + own bands use and reads as intended on a mode built out of visible texels. + + Nothing else about the fight moves. The arena is picked the same way, the + camera is solved the same way, and the HUDs, the frosted text box, the + move animations and the depth of field are all exactly what 2D-3D draws + -- because every one of those is hung off the arena's CELLS rather than + off the pics. Swapping what stands on a cell changes nothing about where + the cell projects to, which is why this is a rung on the mode rather than + a second mode. + + The animations are driven from the fight itself, at four seams: a move + plays the animation that species' own battle table names for that move + (the Stadium ROM's per-species move table, packed into the assets, keyed + by the same Gen 1 move id the engine's move defs already carry -- so DIG + really does put Diglett into the ground), damage plays the hit reaction, + fainting plays the faint and holds on its last frame, and a send-out + plays the entrance while the engine's own grow-out-of-the-ball scale + runs. Between all of that, the standby loop. The eyes blink and go + dizzy on their own counter, which is a texture animation glTF has no + channel for and the pack carries anyway. Charmander's tail flame and + Weezing's gas are there too, drawn additively over the body. + + The models go through the mod's OWN vertex format and shader rather than + a path of their own, which is what earns them everything the rest of the + diorama has: the depth buffer decides what is in front of what, the sun + pass throws a shadow of the actual pose, the hour's tint lands on them, + the hit flash flattens them and the tilt-shift and depth of field see + them as part of the picture. Skinning is done on the CPU -- these are + 674-vertex models and exactly two are ever on screen -- and once per + frame, so the sun, the camera and both VR eyes draw the same posed mesh. + + It declines per POKEMON rather than per battle: a species whose pack is + missing, a substitute doll, or the trainer's own pic before the send-out + all fall back to the flat card, on that side alone, with the other side + keeping its model. + + Stored as new values on the same key, with 2D-3D still first -- so a save + written before this update reads back as exactly the mode it was written + for. + +- **The models are built on your machine, from your own cartridge.** The + mod ships no Pokemon Stadium data and cannot: it is that game's. What it + ships is the READER. + + Drop a Pokemon Stadium (US) ROM -- `.z64`, `.n64` or `.v64`, the byte + order is detected -- into a `baseroms/` folder beside the game, and the + first time it runs the 151 battle models are built out of it on a loading + screen, in about ten seconds, one species a frame. After that they sit in + the save directory and are read like any other asset. Until then the two + STADIUM rungs simply are not on the row: they are skipped rather than + shown and refused, because a setting that can be selected and then does + nothing is indistinguishable from a broken mod. + + This is the same arrangement the engine already has for the Game Boy ROM + it is a recompilation of, and it is why nothing ROM-derived is in this + repository. + + Doing it needed the whole extraction pipeline in Lua: the archive and its + Yay0 streams (`StadiumRom`), a geo-layout walk and an F3DEX2 interpreter + with six texture codecs and a bit-packed animation sampler + (`StadiumFragment`), the generated flame and gas stand-ins (`StadiumFx`), + and the bind-pose measurement and packer (`StadiumBuild`). + + **Pure Lua, and deliberately so: it runs anywhere LOVE does, phones + included.** No FFI, no native helper, no second process, nothing outside + the standard library and stock LOVE calls. On desktop it is about seven + seconds and peaks at 68 MB of Lua heap, 32 MB of which is the cartridge + itself; the working set does not grow across the run. + `tests/stadium_budget_test.lua` measures both and fails if either stops + being bounded, because a transient peak a desktop shrugs off is what gets + a process killed on a phone. On Android the save directory is the app's + external-files folder, so `baseroms/` there is reachable over USB or a + file manager without root. + +- `tools/stadium_pack.py` now reads the ROM directly rather than a + pre-extracted tree, which makes it the ORACLE the Lua port is verified + against: `tests/stadium_extract_test.lua` runs both over the same + cartridge and requires all 151 packed files to come out **byte for byte + identical**. That is the only honest test of a port of that much numeric + code -- every rounding mode, iteration order and off-by-one shows up as a + differing byte, and there are thirty-four megabytes of them. + +- `ModSetting:setValue`, which sets a setting by its stored value rather + than by its place on the ladder, and `ModSetting:setGate`, which lets a + rung exist only when there is something behind it. 3D-BTL grew two rungs + in the middle of itself, and every caller that had counted to two would + otherwise have quietly meant something else afterwards. + +- `tests/stadium_shots.lua`, a shot driver for both rungs, with a control + mode and a pinned clock so two runs of it can be compared. + +### Fixed + +- **The eyes blinked several times a second.** A texture animation was + running on a clock of its own and wrapping on its own stream's length. + Rattata's standby loop is forty frames and its blink is five -- `6 8 7 8 + 6`, open through shut and back -- so that played it six times a second, + and every species with a short blink twitched the same way. + + Two things were wrong, and the data says so plainly: 507 of the 691 + animation/texture-animation pairs in the set are exactly the same length + as each other, which is what one shared frame counter looks like from the + outside. So the texture animation now rides the SKELETAL animation's own + frame, and it HOLDS its last entry past the end of its stream rather than + looping -- which is what the game's own sampler does (`func_80017540`). + Rattata now blinks once at the top of each idle loop and keeps its eyes + open for the other thirty-five frames. + + The frame is not recomputed for the textures; `pose` stashes the one it + resolved and `textures` reads it, so the two cannot drift apart. + +- **The faint animation no longer plays while the HP bar is still + draining.** `onFaint` runs the instant HP reaches zero, but the engine + queues the visible collapse behind the move animation and the bar drain + -- and that drain takes real time, some two and a half seconds on a + full-health Pokemon. The model was therefore lying down while its own + health went on emptying above it. + + The request is now recorded when HP hits zero and played when the bar + reaches zero, off the engine's own `shownHP` -- the same number the bar is + drawn from, so the two cannot drift. A faint that stops being owed in the + meantime (a revive, a battler replaced under us) is dropped rather than + fired late at whoever is standing there. Measured rather than eyeballed: + the shot driver's `DS_FAINT` case prints the frame the bar empties against + the frame the animation starts, and they are the same frame. + +- Two ordering bugs in the extraction pipeline that made its output + **non-reproducible**. The generated flame nodes were deduplicated through + a Python `set` of tuples containing strings, so their order moved with + `PYTHONHASHSEED` and Ponyta, Rapidash and Moltres got differently-seeded + flames on different runs of the same build; and texture registration + order came from iterating a `set` of ints, which is stable across runs + but is a CPython implementation detail rather than a fact about the data. + Both now go in order of appearance, which is the game's own order and the + one a Lua port can reproduce. + +### Changed + +- The packed format is now **DSM3**: textures are stored as raw RGBA rather + than PNG. An ImageData over those bytes costs nothing where a PNG costs a + decode on the frame a battle starts -- but the reason it was done is that + PNG means zlib, and Python's deflate and LOVE's need not agree byte for + byte, which would have made the extractor impossible to check against the + packer. Uncompressed pixels are the same pixels whoever wrote them. The + set is 34 MB rather than 24 MB, and it is generated locally rather than + shipped, so that is a trade worth making. + +### Known + +- Three species -- Exeggutor, Tangela and Magmar -- have standby loops that + are corrupt in the source extraction, throwing bones hundreds of units + off the body. The packer measures each species' loop against its own bind + pose and marks those three to hold the bind pose instead, so they stand + still and look like themselves rather than coming apart. + ## 1.5.5 ### Added diff --git a/README.md b/README.md index 4b2b42b..4b34c2c 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,67 @@ on the menu while the foe stands out on the map, and no angle holds a composition that is half frame and half world — so with it on, the shot holds the one the rig was solved for. +## STADIUM battles + +The **3D-BTL** row has four rungs: + +| rung | the fight | +| --- | --- | +| **2D-3D** | staged on the map, with the Game Boy's own pics stood up on their tiles | +| **STADIUM A** | staged on the map, with the Pokémon Stadium battle models | +| **STADIUM B** | the same models on two discs against the sky, with no map drawn | +| **OFF** | the engine's own battle screen | + +All 151 species, skinned and animated, playing the animation the move being +used actually calls for — the Stadium ROM's own per-species move table, so +**DIG** really does put Diglett into the ground. Damage plays the hit +reaction, fainting plays the faint and holds there, a send-out plays the +entrance, and between all of that the standby loop runs. Eyes blink and go +dizzy; Charmander's tail flame and Weezing's gas are drawn over the body. + +**B is for the maps that cannot host a fight.** Half of Kanto's interiors are +furniture, a cave floor can be nothing but corridors, and a map where neither +Pokémon can be *seen* from a low camera is declined outright — which drops you +back to the flat battle screen. B carries its stage, so it works everywhere +and looks the same every time. It is abstracted from the ground, not from the +world: the sky behind the discs is the hour's own, and a fight in a cave is +under that cave's void and its own flat light. + +### Getting the models + +**They are not in this mod, and they cannot be** — they are Pokémon Stadium's +data. What ships is the reader; you supply the cartridge, exactly as this +engine already asks you to supply the Game Boy ROM it is a recompilation of. + +1. Put a **Pokémon Stadium (US)** ROM in a `baseroms/` folder beside the game. + `.z64`, `.n64` and `.v64` all work — the byte order is detected. + In a packaged build, `baseroms/` goes in the save directory; the mod logs + the exact path on startup when it cannot find one. +2. Start the game. The 151 models are built out of the ROM on a loading + screen, in about ten seconds. +3. The two STADIUM rungs appear on the 3D-BTL row. + +The built models live in the save directory, not in the mod folder, and are +rebuilt automatically if the format changes or the ROM does. Until they exist +the STADIUM rungs are simply not on the row — skipped rather than shown and +refused, because a setting you can select that then does nothing is worse than +one that is not there. + +**This works on mobile.** The extraction is pure Lua — no FFI, no native +helper, no second process — so it runs anywhere LÖVE does. It peaks at about +68 MB of Lua heap (32 MB of that the cartridge itself) with a working set that +does not grow across the run, and `tests/stadium_budget_test.lua` fails if +either stops being true. On Android the save directory is the app's +external-files folder, so `baseroms/` there is reachable over USB or a file +manager without root; the build is slower than a desktop's ~7 s but runs one +species a frame behind the progress bar either way. + +Developers can pre-build them with `tools/stadium_pack.py`, which reads the +same ROM through `model_extract/pipeline`. That path is also the *oracle*: +`tests/stadium_extract_test.lua` runs it and the in-game Lua extractor over +the same cartridge and requires all 151 packed files to come out byte for byte +identical. + ## VR The **VR** options row (OFF / ON, off by default) drives a PCVR headset diff --git a/lib/BattleScene.lua b/lib/BattleScene.lua index 66f13ca..566731c 100644 --- a/lib/BattleScene.lua +++ b/lib/BattleScene.lua @@ -315,12 +315,24 @@ end local function castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh, atlasFor, cards, token, host, neighbors, - water, nbWater) + water, nbWater, groundY) if not ShadowMap.available() then return end local sig = shadowSignature(state, arena, terrain, nbMesh, token) if not ShadowMap.stale(sig) then return end if not ShadowMap.begin(cx, cy, vw, vh) then return end + -- STADIUM B: the two discs are the only ground there is, so they are the + -- only thing the sun has to see besides the Pokemon themselves. Everything + -- below this is a map that is not in the shot. + if arena.discs then + pcall(function() + V.require("StadiumStage").cast(ShadowMap, arena, groundY or 0) + end) + pcall(function() V.require("Stadium").cast(ShadowMap) end) + ShadowMap.finish(sig) + return + end + ShadowMap.draw(terrain, atlasFor(host), nil) for i, nb in ipairs(neighbors) do ShadowMap.draw(nbMesh[i], atlasFor(nb.map), Mat4.translate(nb.ox, 0, nb.oy)) @@ -354,6 +366,13 @@ local function castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh, ShadowMap.snug(card.model)) end ShadowMap.sprites(false) + -- and the STADIUM models, when that rung is the one running. NOT marked + -- as sprites: that flag exists so a flat card's cut-out is kept off the + -- water (see ShadowMap.sprites), and these are real geometry standing in + -- the world -- a Gyarados at the water's edge should put a Gyarados on + -- the water. Un-snugged for the same reason: snug is a bias for a card + -- rooted to the ground plane, and a model has thickness of its own. + pcall(function() V.require("Stadium").cast(ShadowMap) end) ShadowMap.finish(sig) end @@ -363,6 +382,11 @@ end -- the one nearer the camera and therefore the one a mismatch would show up -- against. function BattleScene.groundY(map, arena) + -- STADIUM B's discs are carried, not found: their tops ARE the ground + -- plane, so there is no terrain height to read and reading one would put + -- the stage at whatever elevation the map happens to have at a spot the + -- fight is not actually happening on + if arena and arena.discs then return 0 end local ok, h = pcall(VoxelScene.groundAt, map, arena.playerCell[1], arena.playerCell[2]) return (ok and h) or 0 @@ -452,10 +476,25 @@ function BattleScene.render(state, arena, textures, token) -- moving, and a shimmer on background windows would fight the mons Voxel3D.glassGlint = 0 + -- STADIUM B stands the fight on two carried discs against the sky, with no + -- map in the shot at all (see StadiumStage). Everything below still runs -- + -- the letterbox, the camera solve, the sun, the pins, the tint, the depth + -- of field -- because none of it is about the terrain; what changes is + -- which geometry the two passes draw. + local discs = arena.discs and true or false + -- shares the free-roam mode's request/evict bookkeeping, so a battle warms -- exactly the meshes walking around would have and nothing extra - local terrain, nbMesh, water, nbWater = prefetchArena(state, host) - if not terrain then return nil end + local terrain, nbMesh, water, nbWater + if discs then + -- and nothing is meshed for a disc fight, which is the other half of why + -- the rung works everywhere: there is no waiting for a chunk to build, so + -- the first frame of the first battle on a cold map is the finished shot + nbMesh, water, nbWater = {}, nil, {} + else + terrain, nbMesh, water, nbWater = prefetchArena(state, host) + if not terrain then return nil end + end local lx, ly, s, pw, ph = BattleScene.letterbox() if not (pw > 0 and ph > 0 and s > 0) then return nil end @@ -487,7 +526,7 @@ function BattleScene.render(state, arena, textures, token) local cards = monCards(arena, groundY, textures) Voxel3D.camera = nil castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh, atlasFor, - cards, token, host, neighbors, water, nbWater) + cards, token, host, neighbors, water, nbWater, groundY) -- An opaque void either way. Outdoors the camera is low enough that the -- horizon is genuinely in frame, so it is sky; indoors it is the dark end @@ -496,6 +535,18 @@ function BattleScene.render(state, arena, textures, token) -- geometry stops. local sky = VoxelScene.skyColor(host, 1) or VoxelScene.skyShade(INDOOR_SHADE, 1) + -- On STADIUM B the void is not a backdrop behind the scenery -- it IS the + -- scenery, because the map is not drawn. So outdoors it gets the full + -- treatment the free-roam camera gets: the banded gradient and the hour's + -- own sun or moon hanging in it (Voxel3D.beginScene paints those when the + -- sky it is handed carries bands). Indoors there is nothing to dress: a + -- room's void is one flat shade, which is what a room looks like past the + -- wall, and the disc fight in a cave is lit and coloured as that cave. + if discs and VoxelScene.skyColor(host, 1) then + local Sky = V.require("Sky") + local okDress, dressed = pcall(Sky.dress, sky) + if okDress and dressed then sky = dressed end + end Voxel3D.camera = cam -- the sun is turned up for the arena and put back afterwards, so the @@ -528,6 +579,13 @@ function BattleScene.render(state, arena, textures, token) if not Voxel3D.beginScene(rw, rh, cx, cy, vw, vh, sky, "battle") then return end + if discs then + -- STADIUM B: the two platforms, and nothing else. No terrain, no + -- neighbouring maps, no water, no grass and no flowers -- see the + -- matching skips further down. What is behind them is the sky the + -- clear painted. + V.require("StadiumStage").draw(arena, groundY) + else Voxel3D.draw(terrain, atlasFor(host), nil) for i, nb in ipairs(neighbors) do Voxel3D.draw(nbMesh[i], atlasFor(nb.map), @@ -549,6 +607,7 @@ function BattleScene.render(state, arena, textures, token) Mat4.translate(nb.ox, 0, nb.oy)) end end + end -- The mons, standing on their tiles. Depth-tested like everything else, -- so a ledge or a tree between the camera and a Pokemon really is in -- front of it, and the alpha discard cuts the sprite's own outline out of @@ -579,24 +638,35 @@ function BattleScene.render(state, arena, textures, token) end Voxel3D.glass(true) Voxel3D.seams(true) + -- and the STADIUM models, inside the same flash window and with the + -- same camera-ward pull, so a Pokemon standing on its tile still wins + -- the depth test against the tile. They manage the wireframe and the + -- glass mask around their own draws (StadiumRig), which is why this + -- sits outside the pair above rather than inside it. + local okStadium, stadiumErr = pcall(function() + V.require("Stadium").draw(BattleBillboard.PULL) + end) + if not okStadium then V.require("Stadium").report(stadiumErr) end if flashing then Voxel3D.flatten(nil) end -- grass and flowers ride the same camera-ward pull the free-roam pass -- gives them, measured against THIS camera's pitch rather than the -- orbit's -- there is no character here for them to overdraw, but the -- pull is also what keeps a tuft from z-fighting the floor it stands on local pull = VoxelScene.pull(math.max(pitch, 0.05)) - Voxel3D.draw(ChunkMesher.grass(host), atlasFor(host), nil, pull) - for _, nb in ipairs(neighbors) do - Voxel3D.draw(ChunkMesher.grass(nb.map), atlasFor(nb.map), - Mat4.translate(nb.ox, 0, nb.oy), pull) - end - local fpull = math.max(0, pull - 8 * math.sin(math.max(pitch, 0.05))) - Voxel3D.draw(ChunkMesher.flowers(host), atlasFor(host), nil, fpull, - ShadowMap.snug(nil)) - for _, nb in ipairs(neighbors) do - Voxel3D.draw(ChunkMesher.flowers(nb.map), atlasFor(nb.map), - Mat4.translate(nb.ox, 0, nb.oy), fpull, - ShadowMap.snug(Mat4.translate(nb.ox, 0, nb.oy))) + if not discs then + Voxel3D.draw(ChunkMesher.grass(host), atlasFor(host), nil, pull) + for _, nb in ipairs(neighbors) do + Voxel3D.draw(ChunkMesher.grass(nb.map), atlasFor(nb.map), + Mat4.translate(nb.ox, 0, nb.oy), pull) + end + local fpull = math.max(0, pull - 8 * math.sin(math.max(pitch, 0.05))) + Voxel3D.draw(ChunkMesher.flowers(host), atlasFor(host), nil, fpull, + ShadowMap.snug(nil)) + for _, nb in ipairs(neighbors) do + Voxel3D.draw(ChunkMesher.flowers(nb.map), atlasFor(nb.map), + Mat4.translate(nb.ox, 0, nb.oy), fpull, + ShadowMap.snug(Mat4.translate(nb.ox, 0, nb.oy))) + end end local canvas = AntiAlias.resolve(Voxel3D.endScene(), pw, ph, "battle") if not canvas then return end diff --git a/lib/ModSetting.lua b/lib/ModSetting.lua index 2bed605..33c44ad 100644 --- a/lib/ModSetting.lua +++ b/lib/ModSetting.lua @@ -47,6 +47,42 @@ local function indexOf(self, value) return 1 end +-- ------- rungs that are not always there +-- +-- A ladder may carry a rung that cannot be selected right now -- STADIUM +-- needs models built out of a ROM the player supplies, and until that has +-- happened there is nothing behind the option. `gate` is asked per rung and +-- decides whether it exists at all this frame. +-- +-- Skipped rather than shown-and-refused, deliberately. A row that can be +-- cycled onto and then does nothing is indistinguishable from a broken mod; +-- a row that simply has fewer stops reads as the mod not offering something, +-- which is the truth. What the player is missing, and how to get it, is said +-- once in the row's help text instead of implied by a dead setting. +-- +-- values[1] is never gated: it is the default and the fallback, so there is +-- always at least one rung to land on. +function ModSetting:setGate(gate) + self.gate = gate + return self +end + +function ModSetting:allows(i) + if i == 1 or not self.gate then return true end + local ok, allowed = pcall(self.gate, self.values[i], i) + return (not ok) or allowed and true or false +end + +-- How many rungs are live, for a caller that wants to know whether a row is +-- worth showing at all. +function ModSetting:rungs() + local n = 0 + for i = 1, #self.values do + if self:allows(i) then n = n + 1 end + end + return n +end + -- What the player left it at last session. Read lazily rather than at load -- time: the loader fills modOptions before a mod runs, but reading through -- the API keeps this honest about where the value lives. @@ -63,7 +99,13 @@ function ModSetting:read() end function ModSetting:get() - return self.values[self:read()] + local i = self:read() + -- a rung that was live when it was stored and is not now -- the player + -- moved the ROM, or opened the same save on another machine -- reads as + -- the default rather than as a mode with nothing behind it. The stored + -- value is left alone, so putting the ROM back restores their choice. + if not self:allows(i) then return self.values[1] end + return self.values[i] end function ModSetting:level() @@ -91,8 +133,32 @@ function ModSetting:setIndex(i, game) return value end +-- Set by the STORED VALUE rather than by its place on the ladder, for a +-- caller that knows which setting it wants and not where it sits -- a +-- preset, or an assertion. An unrecognised value lands on values[1], the +-- same default indexOf answers everywhere else, so this can never leave a +-- setting holding something the row cannot display. +-- +-- Worth having as its own entry point because a ladder's ORDER is not a +-- promise: 3D-BTL grew a third rung in the middle of itself (see +-- OverworldBattle), and every caller that had counted to two would have +-- silently meant something else afterwards. +function ModSetting:setValue(value, game) + return self:setIndex(indexOf(self, value), game) +end + +-- Step to the next rung that is actually live, in `dir`. Bounded by the +-- ladder's length so a gate that refuses everything still terminates on +-- values[1], which allows() never gates. function ModSetting:cycle(game, dir) - return self:setIndex(self:read() + (dir or 1), game) + dir = dir or 1 + local n = #self.values + local i = self:read() + for _ = 1, n do + i = ((i + dir - 1) % n + n) % n + 1 + if self:allows(i) then break end + end + return self:setIndex(i, game) end -- Adopt a value set from somewhere else (the mod manager's settings page, @@ -109,7 +175,12 @@ function ModSetting:row() return { id = "DRAMATIC_SHAPE:" .. self.key, label = self.label, - value = function() return self_.labels[self_:read()] end, + -- the label of the rung actually in force, which is not the stored one + -- when that rung has been gated away (see get) + value = function() + local i = self_:read() + return self_.labels[self_:allows(i) and i or 1] + end, step = function(game, dir) self_:cycle(game, dir) return true @@ -120,7 +191,11 @@ end -- The row the mod manager's own settings page builds for this mod. function ModSetting:schema(help) local choices = {} - for i, v in ipairs(self.values) do choices[i] = { self.labels[i], v } end + -- gated rungs are left off the manager's page too, so the two rows agree + -- about what can be chosen + for i, v in ipairs(self.values) do + if self:allows(i) then choices[#choices + 1] = { self.labels[i], v } end + end if #self.values == 2 and self.values[1] == false then return { key = self.key, type = "toggle", label = self.label, default = self.values[1], help = help } diff --git a/lib/OverworldBattle.lua b/lib/OverworldBattle.lua index 2114264..c074008 100644 --- a/lib/OverworldBattle.lua +++ b/lib/OverworldBattle.lua @@ -60,13 +60,47 @@ if DEBUG == nil or DEBUG == false then DEBUG = nil end OverworldBattle.KEY = "battles" OverworldBattle.LABEL = "3D-BTL" --- On by default: a mod whose headline is "the world in 3D" should not need --- the player to go and find the switch before the world shows up in a --- battle. ON is first, so it is also what an unreadable stored value falls --- back to. -OverworldBattle.setting = ModSetting.new(OverworldBattle.KEY, - OverworldBattle.LABEL, - { true, false }, { "ON", "OFF" }) +-- Four rungs, and the ladder's order is the order they were added in rather +-- than OFF-to-most: +-- +-- 2D-3D the mode this file was written for: the fight is staged on +-- the map and the two Pokemon are the GB's OWN PICS, stood up +-- on their tiles as quads (BattleBillboard). +-- STADIUM A the same staged fight with the Pokemon Stadium battle models +-- in place of those quads -- skinned, animated, and playing the +-- animation the move being used actually calls for (see +-- lib/Stadium.lua). The world is still the world: the fight +-- happens on real ground, in the map's own weather and light. +-- STADIUM B the same models on a pair of DISCS against the sky, with no +-- map at all -- the Game Boy's own framing, staged rather than +-- found (see lib/StadiumStage.lua). Works everywhere, including +-- the maps that have nowhere to put a fight. +-- OFF the engine's own white battle screen. +-- +-- 2D-3D stays FIRST because ModSetting's values[1] is both the default and +-- what an unrecognised stored value falls back to, and the stored value for +-- this row has been `true` since the row existed. Keeping `true` at the head +-- means every save written before the STADIUM rungs existed reads back as +-- the 2D-3D it was written for, and a mod whose headline is "the world in +-- 3D" still does not need the player to go and find the switch. +-- +-- The stored value for STADIUM A is still the bare string "stadium" it was +-- before there was a B, so a save written against the three-rung ladder +-- keeps the mode it chose. +-- +-- Both STADIUM rungs are GATED on the models existing: the mod ships no +-- Pokemon Stadium data, and until the player's own ROM has been found and +-- built from (StadiumInstall) the row simply has two fewer stops. See +-- ModSetting.setGate for why they are skipped rather than shown and refused. +OverworldBattle.setting = + ModSetting.new(OverworldBattle.KEY, OverworldBattle.LABEL, + { true, "stadium", "stadiumB", false }, + { "2D-3D", "STADIUM A", "STADIUM B", "OFF" }) + :setGate(function(value) + if value ~= "stadium" and value ~= "stadiumB" then return true end + local ok, install = pcall(V.require, "StadiumInstall") + return ok and install and install.available() + end) -- Whether the VR row is ON -- read lazily, because VR requires modules -- that sit above this one. While it is, this mode stops being optional: @@ -83,6 +117,15 @@ function OverworldBattle.enabled() return OverworldBattle.setting:get() and true or false end +-- Whether the STADIUM rung is the one selected -- read through Stadium so +-- there is one answer to that question and it lives with the mode it +-- describes. Required lazily: Stadium sits above this file and requires it +-- back (for the row), which a load-time require would deadlock. +function OverworldBattle.stadium() + local ok, stadium = pcall(V.require, "Stadium") + return (ok and stadium and stadium.enabled()) and true or false +end + -- ------- BACK SPRITES: the player's own mon stays on the menu -- -- The staged shot stands BOTH mons on the map, which is the mode's whole @@ -173,6 +216,10 @@ function OverworldBattle.wantsFront() local g = require("src.core.Game") local ow = g and g.overworld if not (ow and ow.map and ow.player) then return false end + -- STADIUM B carries its own stage, so the answer is yes on every map and + -- there is nothing to search or to cache + local okS, stadium = pcall(V.require, "Stadium") + if okS and stadium and stadium.discs() then return true end if staged.mapId ~= ow.map.id then local ok, arena = pcall(BattleArena.find, ow.map, ow.player.cellX, ow.player.cellY, @@ -420,6 +467,31 @@ function OverworldBattle.forceOG(g) return true end +-- Where THIS fight stands, on whichever rung is running: the map's own +-- ground, or the pair of discs STADIUM B carries with it. +-- +-- The one place the two rungs actually diverge, and it is worth stating +-- plainly. On every other rung the answer can be NO -- a corridor, a shop +-- floor, a map whose authored entry is a refusal -- and the battle then plays +-- exactly as the vanilla game does. STADIUM B cannot fail: its stage is not +-- something the map has to have room for, so a fight in the tightest cave in +-- Kanto is staged as readily as one on Route 1. +function OverworldBattle.stageFor(state) + local ok, stadium = pcall(V.require, "Stadium") + if ok and stadium and stadium.discs() and Voxel3D.available() then + local okStage, arena = pcall(function() + return V.require("StadiumStage").arena(state.map) + end) + if okStage and arena then return arena end + -- the discs could not be built; fall through to the map, which is a + -- worse picture but a real one + end + local okFind, arena = pcall(BattleArena.find, state.map, + state.player.cellX, state.player.cellY, + state.player.surfing) + return (okFind and arena) or nil +end + -- Stage a battle triggered from `state`, if this mode can. Returns true when -- a session started -- which is also the only case where anything visible -- changes, so a map with no room for an arena plays exactly the vanilla @@ -430,10 +502,8 @@ function OverworldBattle.begin(state, battle) if not (state and state.map and state.player) then return false end if not Voxel3D.available() then return false end - local ok, arena = pcall(BattleArena.find, state.map, - state.player.cellX, state.player.cellY, - state.player.surfing) - if not (ok and arena) then return false end + local arena = OverworldBattle.stageFor(state) + if not arena then return false end -- the fight is staged from here on, so the layout it is composed for is not -- optional any more (see forceOG) @@ -443,6 +513,9 @@ function OverworldBattle.begin(state, battle) armed = false, token = 0 } cullCast(state) BattleCam.reset() + -- and, on the STADIUM rung, the pair of models that will stand on this + -- arena's two cells. Declines quietly on any other rung. + pcall(function() V.require("Stadium").begin(arena) end) return true end @@ -473,6 +546,7 @@ function OverworldBattle.finish() restoreCast() session = nil Voxel3D.camera = nil + pcall(function() V.require("Stadium").finish() end) end -- ------- per-frame @@ -524,6 +598,17 @@ function OverworldBattle.update(dt) -- slice: nothing visible can hitch on them ChunkMesher.pump(true) + -- The STADIUM models, ahead of the pics, because what they decide is + -- WHICH pics are needed: a side a model is standing on gets no billboard + -- texture rendered for it at all (see Stadium.covers). Posed and skinned + -- here too, once for the frame -- the sun pass, the camera and, in a + -- headset, both eyes all draw the same skinned meshes. + pcall(function() + local host = (session.arena and session.arena.map) or session.state.map + V.require("Stadium").update(dt, session.battle, + BattleScene.groundY(host, session.arena)) + end) + -- The mons' textures are rendered HERE, with no canvas bound, for the same -- reason the scene is: the pics layer binds its own targets, and doing that -- inside somebody else's frame means putting the frame back afterwards. @@ -710,6 +795,9 @@ function OverworldBattle.invalidate() BattleDOF.invalidate() BattleHud.invalidate() BattlePics.invalidate() + -- the STADIUM models hold meshes and textures of this graphics context + -- like everything else here does + pcall(function() V.require("Stadium").invalidate() end) end -- ------- the battle screen's background @@ -908,6 +996,14 @@ local OFF = { -- feet ended up, in canvas coordinates. function OverworldBattle.sideTexture(battle, side) if not (innerPics and battle) then return nil end + -- On the STADIUM rung a side standing a MODEL needs no pic: rendering one + -- anyway would hang a second, flat copy of the same Pokemon on the same + -- cell. Asked per side, so a species with no pack -- or a substitute + -- doll, or the trainer before the send-out -- still comes through here. + local okS, covered = pcall(function() + return V.require("Stadium").covers(battle, side) + end) + if okS and covered then return nil end if not sideVisible(battle, side) then return nil end local canvas = texCanvasFor(side) if not canvas then return nil end @@ -985,7 +1081,16 @@ function OverworldBattle.textures(battle) end out.enemy = okE and enemy or nil out.player = okP and player or nil - if not (out.enemy or out.player) then return nil end + -- On the STADIUM rung both sides can legitimately have no pic -- the pair + -- of them are models -- and this table must still come back, because it + -- carries the HIT FLASH, and because the VR eye pass uses its presence to + -- decide there is a staged fight to draw at all. + local okStanding, standing = pcall(function() + return V.require("Stadium").standing() + end) + if not (out.enemy or out.player or (okStanding and standing)) then + return nil + end out.flash = OverworldBattle.flashing(battle) return out end @@ -1008,6 +1113,12 @@ function OverworldBattle.install() OverworldState.dramaticShapeBattleHook = true end + -- the STADIUM rung's own four wraps, which drive the models' animations + -- off the fight (see Stadium.install). Idempotent in the same way, and + -- installed whichever rung the row is on: the wraps do nothing at all + -- while no stadium session is live. + pcall(function() V.require("Stadium").install() end) + local BattleState = require("src.battle.BattleState") if BattleState.dramaticShapeBattleHook then return end diff --git a/lib/Stadium.lua b/lib/Stadium.lua new file mode 100644 index 0000000..1103b20 --- /dev/null +++ b/lib/Stadium.lua @@ -0,0 +1,516 @@ +-- STADIUM battles: the two Pokemon as real 3D models. +-- +-- The 3D-BTL row's third rung. OFF is the engine's own white battle field; +-- 2D-3D stands the GB's own pics up on the map as quads (BattleBillboard); +-- STADIUM replaces those quads with the Pokemon Stadium battle models -- +-- skinned, animated, and playing the animation the move being used +-- actually calls for. +-- +-- The models come out of the Stadium ROM through model_extract, and are +-- packed into assets/stadium/NNN.dsm by tools/stadium_pack.py. Nothing here +-- knows about the ROM; the pack is the interface. +-- +-- ------- what this file is, and is not +-- +-- It is the MODE: which species is out on each side, which animation the +-- fight is asking each of them for, whether the model or the flat pic is +-- standing in this frame, and the two draw calls. The arithmetic is +-- StadiumRig's, the file format is StadiumPack's, and one side's own state +-- is StadiumMon's. +-- +-- It is not a rewrite of the staged battle. The arena is picked the same +-- way, the camera is solved the same way, the HUDs and the text box and the +-- move animations and the depth of field are all exactly what 2D-3D draws +-- -- because all of those are hung off the arena's CELLS, not off the +-- pics. Swapping what stands on a cell changes nothing about where the cell +-- projects to. That is why this is an option on the mode rather than a +-- second mode. +-- +-- ------- declining, per Pokemon +-- +-- Every gate here is per SIDE and per FRAME, not per battle: +-- +-- no pack for that species, or its meshes would not build -> that side +-- falls back to its flat pic, and the other side keeps its model +-- +-- the side is showing a TRAINER (the foe's class before the send-out, +-- the player's own back before "Go!") -> that is not a Pokemon and there +-- is no model for it; the pic stands, exactly as in 2D-3D +-- +-- a SUBSTITUTE is up -> the engine replaces the pic with the mini doll, +-- which is the thing the player is being told is there. A model of the +-- Pokemon behind the doll would be a lie about the battle state. +-- +-- So `covers` is asked per side per frame, and OverworldBattle renders a +-- billboard texture for exactly the sides it answers false for. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local Voxel3D = V.require("Voxel3D") +local StadiumPack = V.require("StadiumPack") +local StadiumMon = V.require("StadiumMon") + +local Stadium = {} + +-- The stored values of the two 3D-BTL rungs that select this mode. Strings +-- rather than further booleans so an older save's `true` still means the +-- 2D-3D it was written for (see OverworldBattle.setting). +-- +-- A the models on the MAP -- real ground, the map's own light and sky +-- B the models on two DISCS against the sky, with no map at all +-- +-- Everything below is shared: which species is out, which animation the +-- fight is asking for, the skinning, the draw. The difference is entirely +-- in what the camera is pointed at, which is BattleScene's business and +-- StadiumStage's. +Stadium.VALUE = "stadium" +Stadium.VALUE_B = "stadiumB" + +-- ------- the live pair + +local session = nil -- nil when no staged fight is running + +local function game() + return require("src.core.Game") +end + +-- Whether the row is on this rung. Deliberately NOT gated on whether the +-- packs are installed: a mod folder without assets/stadium still cycles the +-- row, and each Pokemon declines on its own when its pack does not load -- +-- which is one message on the console rather than a row that silently +-- refuses to move. +function Stadium.selected() + return Stadium.mode() ~= nil +end + +-- "A", "B", or nil when the row is on neither stadium rung. +function Stadium.mode() + local OverworldBattle = V.require("OverworldBattle") + local value = OverworldBattle.setting:get() + if value == Stadium.VALUE then return "A" end + if value == Stadium.VALUE_B then return "B" end + return nil +end + +-- Whether the fight is staged on the DISCS rather than on the map. Asked by +-- BattleScene (what to draw the pair against), BattleArena (whether the map +-- has to have room) and BattleCam (which framing to solve). +function Stadium.discs() + return Stadium.mode() == "B" +end + +function Stadium.enabled() + if not Stadium.selected() then return false end + return Voxel3D.available() +end + +-- A staged fight has begun on `arena`. Called from OverworldBattle.begin, +-- which is the one place that knows a fight is being staged at all. +function Stadium.begin(arena) + Stadium.finish() + if not Stadium.enabled() then return false end + session = { + arena = arena, + groundY = 0, + player = StadiumMon.new("player"), + enemy = StadiumMon.new("enemy"), + -- what each side has been TRANSFORMED into, if anything (see install) + transform = {}, + -- sides that are going to collapse, but whose HP bar has not finished + -- emptying yet (see faintReady) + faintPending = {}, + } + return true +end + +function Stadium.finish() + if not session then return end + session.player:release() + session.enemy:release() + session = nil +end + +function Stadium.active() + return session ~= nil +end + +-- ------- which species each side is showing + +-- The National Dex number for a battler, which is the number the Stadium +-- packs are keyed by. The engine's species are string keys ("PIKACHU") and +-- carry their dex number on the definition, so this is one lookup rather +-- than a table of its own. +local function dexOf(species) + if not species then return nil end + local data = game() and game().data + local def = data and data.pokemon and data.pokemon[species] + return def and def.dex or nil +end + +-- Whether this side is showing a TRAINER rather than a Pokemon. +local function showingTrainer(battle, side) + if side == "enemy" then + return (battle.showEnemyTrainer and battle.trainerPic) and true or false + end + return (battle.showPlayerBack and battle.playerBackPic) and true or false +end + +-- Whether this side has anything on the field at all this frame. +-- +-- Mirrors BattleState's own guards, the same way OverworldBattle.sideVisible +-- mirrors them for the flat cards: there is no seam that reports "the foe is +-- off screen right now", and a model left standing through a send-out or a +-- damage blink would be the one thing in the frame that ignored the battle. +local function onField(battle, side) + local battler = side == "player" and battle.player or battle.enemy + if not (battler and battler.sprite) then return false end + if side == "enemy" then + if battle.enemyHidden or battle.enemySendingOut then return false end + else + if battle.safari or battle.demo or battle.sendingOut then return false end + end + local ok, hidden = pcall(battle.fxHidden, battle, battler) + if ok and hidden then return false end + -- a fainted Pokemon is gone once its slide has finished, exactly as its + -- pic is + if battler.fainted then + local okF, sliding = pcall(battle.fxFaintActive, battle, battler) + if not (okF and sliding) then return false end + end + return true +end + +-- Whether the 3D model is standing in for this side's pic this frame. The +-- one question OverworldBattle asks, and the answer that decides whether a +-- billboard texture gets rendered for that side at all. +function Stadium.covers(battle, side) + if not (session and battle) then return false end + local mon = session[side] + if not (mon and mon.rig) then return false end + if showingTrainer(battle, side) then return false end + local battler = side == "player" and battle.player or battle.enemy + -- the substitute doll is what the player is being shown is out there + if battler and battler.substituteHP then return false end + return true +end + +-- ------- the collapse waits for the bar +-- +-- `onFaint` runs the instant HP reaches zero, which is NOT when a Pokemon +-- falls over. The engine queues the collapse -- the slide, the cry, the +-- "fainted!" line -- to run after the move animation and the HP-bar drain +-- (BattleState.onFaint's own comment), and the drain takes real frames: a +-- 150 HP mon's bar walks down over some four seconds. +-- +-- So asking for the faint animation at `onFaint` played it against a bar +-- that was still emptying: the Pokemon lay down, and then its health went on +-- draining above the corpse. What the player reads as the moment of death is +-- the bar hitting zero, and that is what this waits for. +-- +-- `shownHP` is the engine's own bar position (BattleState.stepHPDrain walks +-- it toward mon.hp a point at a time), so this is not a guess at the timing +-- -- it is the same number the bar is drawn from. +local function faintReady(battler) + if not battler then return false end + -- nothing is animating the bar for this battler: there is nothing to wait + -- for, and waiting forever would mean never collapsing at all + if battler.shownHP == nil then return true end + return battler.shownHP <= 0 +end + +-- Whether a pending collapse is still owed. A switch, a revive or a battler +-- that was replaced under us drops it rather than firing late at whoever is +-- standing there now. +local function faintStillDue(battler) + return (battler and battler.faintQueued + and battler.mon and (battler.mon.hp or 0) <= 0) and true or false +end + +-- named for the suite: the timing rule is the whole of this change, and it +-- is testable without a graphics context where the mode itself is not +Stadium._faintReady = faintReady +Stadium._faintStillDue = faintStillDue + +-- ------- per frame +-- +-- Runs from OverworldBattle.update, before the pics are rendered and before +-- the scene is drawn: what this decides is exactly which sides need a pic. +function Stadium.update(dt, battle, groundY) + if not session then return end + session.groundY = groundY or session.groundY or 0 + if not battle then return end + + local arena = session.arena + for _, side in ipairs({ "enemy", "player" }) do + local mon = session[side] + local battler = side == "player" and battle.player or battle.enemy + local dex = nil + if battler and not showingTrainer(battle, side) then + dex = session.transform[side] or dexOf(battler.mon and battler.mon.species) + end + -- the collapse this side is owed, once its bar has finished emptying + if session.faintPending and session.faintPending[side] then + if not faintStillDue(battler) then + session.faintPending[side] = nil + elseif faintReady(battler) then + session.faintPending[side] = nil + if mon and mon.rig then mon:request("faint") end + end + end + + mon:setSpecies(dex) + mon.visible = (mon.rig ~= nil) and onField(battle, side) + and not (battler and battler.substituteHP) + -- cleared up front, so a side that has just lost its rig cannot leave + -- last frame's matrix behind it + mon.model_matrix = nil + + if mon.rig then + -- the send-out grow, borrowed whole from the engine: the pic scales + -- up out of the ball in three steps and so does the model + local okG, grow = pcall(battle.growInScale, battle, battler) + mon.scale = (okG and grow) or 1 + mon:update(dt or 0) + if mon.visible and arena then + local cell = arena[side] + local other = arena[side == "player" and "enemy" or "player"] + if cell and other then + mon.model_matrix = mon:matrix(cell[1], session.groundY, cell[2], + other[1] - cell[1], + other[2] - cell[2]) + mon:build() + else + mon.model_matrix = nil + end + else + mon.model_matrix = nil + end + end + end + Stadium.debug(dt) +end + +-- ------- the draws +-- +-- Both take the pass as they find it: this is called from inside +-- BattleScene's own beginScene/endScene window (and, in a headset, from +-- VoxelScene's), so the camera, the shadow map, the hour's tint and the hit +-- flash are all already set. StadiumRig turns the wireframe and the glass +-- mask off around its own draws and puts them back. + +function Stadium.draw(pull) + if not session then return end + for _, side in ipairs({ "enemy", "player" }) do + local mon = session[side] + if mon.rig and mon.visible and mon.model_matrix then + mon.rig:draw(mon.model_matrix, pull) + end + end +end + +-- The same models as the SUN sees them, so a Pokemon throws the shadow of +-- the pose it is actually in -- an outstretched wing puts an outstretched +-- wing on the ground. +function Stadium.cast(shadowMap) + if not session then return end + for _, side in ipairs({ "enemy", "player" }) do + local mon = session[side] + if mon.rig and mon.visible and mon.model_matrix then + mon.rig:caster(shadowMap, mon.model_matrix) + end + end +end + +-- Which state a side's model is playing, or nil. Named for the shot drivers: +-- checking that an animation starts on the right FRAME is an ordering +-- question, and a screenshot cannot answer one. +function Stadium.animOf(side) + if not session then return nil end + local mon = session[side] + return mon and mon.state or nil +end + +-- How wide the Pokemon on `side` stands, in world pixels, or nil when there +-- is not one. What STADIUM B sizes that side's platform to (StadiumStage). +function Stadium.footprint(side) + if not session then return nil end + local mon = session[side] + if not (mon and mon.model) then return nil end + local r = mon:worldRadius() + return (r > 0) and r or nil +end + +-- Whether anything at all is standing this frame -- what the shadow +-- signature keys on alongside the pics' own token. +function Stadium.standing() + if not session then return false end + return (session.player.visible or session.enemy.visible) and true or false +end + +-- ------- what the fight asks for +-- +-- The animation state machine is driven from four points in the engine's +-- own battle, and each is a wrap rather than a rewrite: the inner function +-- runs exactly as it always did and this reads what went past. + +local function sideOf(battle, battler) + if not (session and battler) then return nil end + if battler == battle.player then return "player" end + if battler == battle.enemy then return "enemy" end + return nil +end + +local function ask(battle, battler, state, animIndex, auxIndex) + local side = sideOf(battle, battler) + if not side then return end + local mon = session[side] + if mon and mon.rig then mon:request(state, animIndex, auxIndex) end +end + +function Stadium.install() + local BattleState = require("src.battle.BattleState") + if BattleState.dramaticShapeStadiumHook then return end + BattleState.dramaticShapeStadiumHook = true + + -- THE ATTACK. performMove is the one place a move is actually used, and + -- the move's own `index` is the Gen 1 move id the Stadium tables are + -- keyed by -- so the species' own animation for that move comes straight + -- out of the pack, with no name mapping and no per-move code. + local innerMove = BattleState.performMove + function BattleState:performMove(user, target, moveInst, isCalled) + if session then + local side = sideOf(self, user) + local mon = side and session[side] + if mon and mon.rig then + local okDef, def = pcall(self.moveDef, self, moveInst) + local index = okDef and def and def.index or nil + if not (index and mon:attack(index)) then + -- a move the table has nothing for still swings: the generic + -- attack is what the species' own reaction slot resolves to + mon:request("attack") + end + end + end + return innerMove(self, user, target, moveInst, isCalled) + end + + -- THE HIT. applyDamage is where HP actually comes off, which is the + -- moment the reaction belongs to -- ahead of the bar drain and the + -- message, both of which take frames. + local innerDamage = BattleState.applyDamage + function BattleState:applyDamage(target, dmg) + local dealt = innerDamage(self, target, dmg) + -- a substitute soaking the hit means the Pokemon behind it did not + -- flinch, and its model is not the thing on screen anyway + if session and (dealt or 0) > 0 and not (target and target.substituteHP) then + ask(self, target, "hit") + end + return dealt + end + + -- THE FAINT. Held on its last frame rather than looped (see StadiumMon's + -- STATES), because a Pokemon that collapses and then stands back up + -- while the message is still on screen is worse than no animation. + -- + -- RECORDED HERE, PLAYED LATER. This runs the moment HP reaches zero, which + -- is several seconds before the Pokemon is supposed to fall over -- the + -- engine queues the collapse behind the move animation and the HP-bar + -- drain. Marking the side and letting Stadium.update fire it when the bar + -- empties is what keeps the two together (see faintReady). + local innerFaint = BattleState.onFaint + function BattleState:onFaint(battler) + if session and not (battler and battler.faintQueued) then + local side = sideOf(self, battler) + if side and session.faintPending then + session.faintPending[side] = true + end + end + return innerFaint(self, battler) + end + + -- THE ENTRANCE. startGrowIn is the send-out: the ball opens, the pic + -- scales up over twelve frames, and the model plays the animation the + -- battle system's own entrance slot names. + local innerGrow = BattleState.startGrowIn + function BattleState:startGrowIn(battler) + if session then ask(self, battler, "entrance") end + return innerGrow(self, battler) + end + + -- TRANSFORM. The engine records a transform by swapping the battler's + -- sprite and nothing else, so this is the only seam that reports one -- + -- and it reports the side, which is all that is needed to point that + -- side's model at the copied species. Cleared when a side's own species + -- changes under it (a switch, or the next battle). + local innerSpecies = BattleState.speciesSprite + function BattleState:speciesSprite(species, isPlayerSide) + if session then + session.transform[isPlayerSide and "player" or "enemy"] = dexOf(species) + end + return innerSpecies(self, species, isPlayerSide) + end + + -- and a switch or a send-out ends any transform on that side + local innerSwitch = BattleState.resolveSwitch + function BattleState:resolveSwitch(newMon) + if session then session.transform.player = nil end + return innerSwitch(self, newMon) + end +end + +-- ------- when a draw goes wrong +-- +-- The draw and the shadow cast are both called through a pcall, because a +-- throw inside the scene pass would hand the whole voxel mode to Pipelines' +-- guard and retire it for the session. Swallowed silently, though, a broken +-- model is indistinguishable from an invisible one -- so the first failure +-- of a battle says so, once, and the rest of the fight carries on without +-- it. +local reported = false + +function Stadium.report(err) + if reported then return end + reported = true + V.mod.log:warn("stadium: a model failed to draw: %s -- this battle runs " + .. "without it", tostring(err)) +end + +-- DS_STADIUM_DEBUG=1 prints what each side resolved to once a second, which +-- is how "nothing is on screen" gets told apart from "nothing was asked +-- for". Read through pcall: the loader's sandbox does not hand a mod `os`, +-- and a diagnostic must never be why the mod fails to load. +local DEBUG = select(2, pcall(function() return os.getenv("DS_STADIUM_DEBUG") end)) +if DEBUG == nil or DEBUG == false then DEBUG = nil end + +local debugAt = 0 + +function Stadium.debug(dt) + if not (DEBUG and session) then return end + debugAt = debugAt + (dt or 0) + if debugAt < 1 then return end + debugAt = 0 + for _, side in ipairs({ "enemy", "player" }) do + local mon = session[side] + local m = mon.model_matrix + V.mod.log:info("stadium %s: dex=%s rig=%s visible=%s anim=%s t=%.2f " + .. "height=%.1f at=%s", + side, tostring(mon.species), tostring(mon.rig ~= nil), + tostring(mon.visible), tostring(mon.anim), mon.time or 0, + mon.model and mon:worldHeight() or 0, + m and ("%.0f,%.0f,%.0f"):format(m[4], m[8], m[12]) or "-") + end +end + +function Stadium.invalidate() + if session then + session.player:release() + session.enemy:release() + end + StadiumPack.invalidate() + -- the discs are a mesh and a texture like anything else, and a graphics + -- context that went away took them with it + pcall(function() V.require("StadiumStage").invalidate() end) +end + +return Stadium diff --git a/lib/StadiumBuild.lua b/lib/StadiumBuild.lua new file mode 100644 index 0000000..c84b479 --- /dev/null +++ b/lib/StadiumBuild.lua @@ -0,0 +1,709 @@ +-- STADIUM battles: turning the ROM into assets/stadium/NNN.dsm. +-- +-- The Lua half of tools/stadium_pack.py: measure the bind pose, decide +-- whether a species' standby loop can be trusted, and write the packed file. +-- Together with StadiumRom, StadiumFragment and StadiumFx this is everything +-- between `baserom.z64` and a Pokemon standing on a battle tile. +-- +-- The Python remains the ORACLE. tests/stadium_extract_test.lua runs this +-- over the same ROM and requires all 151 files to come out byte for byte +-- identical to what the packer writes. That is a strong test in a way a unit +-- test of any one function here would not be: every rounding mode, every +-- iteration order, every off-by-one in an index shows up as a differing byte, +-- and there are thirty-four megabytes of them. +-- +-- ------- stepped, not blocking +-- +-- `StadiumBuild.job()` returns a coroutine-backed job that does one species +-- per `step()`, so the caller can draw a progress bar between them +-- (StadiumInstall). A species is a few tens of milliseconds; the whole set is +-- around half a minute, which is far too long to spend inside one frame and +-- perfectly fine spread across a loading screen. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumRom = V.require("StadiumRom") +local StadiumFragment = V.require("StadiumFragment") +local StadiumFx = V.require("StadiumFx") + +local StadiumBuild = {} + +local floor = math.floor +local sin, cos = math.sin, math.cos +local pi = math.pi +local char = string.char +local concat = table.concat +local frexp = math.frexp +local roundHalfEven = StadiumFragment.roundHalfEven + +-- The battle system's fixed context slots, in slot order from 165. The mod +-- indexes this list by POSITION, so the ORDER is the format's contract and +-- has to stay identical to StadiumPack.CONTEXT and to the packer's CONTEXTS. +StadiumBuild.CONTEXTS = { + "idle", "hit", "faint", "entrance", "reaction_169", "reaction_170", + "reaction_171", "reaction_172", "reaction_173", "reaction_174", + "struggle", "idle_alt", "faint_alt", "flinch", "reaction_179", + "reaction_180", "reaction_181", "reaction_182", "entrance_alt", + "idle_return", +} + +-- Which context name wins when several claim the same animation. +local NAME_PREF = { "idle", "hit", "faint", "entrance", "struggle", "flinch" } + +local N_MOVES = StadiumRom.N_MOVES +local CTX_BASE = 165 +local NONE16 = 0xFFFF + +-- ------- the bind pose + +-- The game's rotation as a 3x3, rows first (src/F420.c func_8000F730): +-- Rx*Ry*Rz in row-vector form. +local function quatBasis(r) + local sx, cx = sin(r[1] / 32768 * pi), cos(r[1] / 32768 * pi) + local sy, cy = sin(r[2] / 32768 * pi), cos(r[2] / 32768 * pi) + local sz, cz = sin(r[3] / 32768 * pi), cos(r[3] / 32768 * pi) + return { cy * cz, sx * sy * cz - cx * sz, cx * sy * cz + sx * sz }, + { cy * sz, sx * sy * sz + cx * cz, cx * sy * sz - sx * cz }, + { -sy, sx * cy, cx * cy } +end + +-- 3x4 (three rotation rows plus a translation column) times the same. +local function matMul(a, b) + local out = {} + for r = 1, 3 do + local ar = a[r] + out[r] = { + ar[1] * b[1][1] + ar[2] * b[2][1] + ar[3] * b[3][1], + ar[1] * b[1][2] + ar[2] * b[2][2] + ar[3] * b[3][2], + ar[1] * b[1][3] + ar[2] * b[2][3] + ar[3] * b[3][3], + ar[1] * b[1][4] + ar[2] * b[2][4] + ar[3] * b[3][4] + ar[4], + } + end + return out +end + +-- One component of one bone's t/r/s at a frame. The extractor's own shape: a +-- bare number when the component holds still for the whole animation, one +-- number a frame when it does not. +local function component(comps, i, frame, fallback) + if comps == nil then return fallback end + local c = comps[i] + if type(c) == "table" then + local n = #c + if n == 0 then return fallback end + return c[frame % n + 1] + end + return c +end + +-- The bone TRS an animation holds at `frame`, rest where it is silent. +local function animSample(bones, anim, frame) + local tracks = anim.tracks + return function(i) + local b = bones[i] + local tr = tracks[i] + if not tr then return b.t, b.r, b.s end + return { component(tr.t, 1, frame, b.t[1]), + component(tr.t, 2, frame, b.t[2]), + component(tr.t, 3, frame, b.t[3]) }, + { component(tr.r, 1, frame, b.r[1]), + component(tr.r, 2, frame, b.r[2]), + component(tr.r, 3, frame, b.r[3]) }, + { component(tr.s, 1, frame, b.s[1]), + component(tr.s, 2, frame, b.s[2]), + component(tr.s, 3, frame, b.s[3]) } + end +end + +local function restSample(bones) + return function(i) + local b = bones[i] + return b.t, b.r, b.s + end +end + +-- Every bone's draw matrix at one instant, as 3x4 rows. +-- +-- The game keeps bone scale OUT of the matrix chain: it accumulates in its own +-- stack, a bone's local translation is pre-multiplied by the PARENT's +-- accumulated scale, and the bone's own accumulated scale is applied to the +-- finished matrix at draw time. +-- +-- Two chains, and the distinction is the whole point: `pivot` is the +-- rotation/translation a CHILD inherits, and the draw matrix is that with the +-- bone's own accumulated scale applied on the right. Folding the scale into +-- the chain instead applies every ancestor's scale twice -- which is exactly +-- the multiplicative propagation glTF has and the game does not. +local function bindMatrices(bones, sample) + sample = sample or restSample(bones) + local pivot, draw, acc = {}, {}, {} + local IDENT = { { 1, 0, 0, 0 }, { 0, 1, 0, 0 }, { 0, 0, 1, 0 } } + for i = 1, #bones do + local bt, br, bs = sample(i) + local p = bones[i].parent + local pa = (p >= 0) and acc[p + 1] or { 1.0, 1.0, 1.0 } + local pm = (p >= 0) and pivot[p + 1] or IDENT + local r1, r2, r3 = quatBasis(br) + local m = matMul(pm, { + { r1[1], r1[2], r1[3], bt[1] * pa[1] }, + { r2[1], r2[2], r2[3], bt[2] * pa[2] }, + { r3[1], r3[2], r3[3], bt[3] * pa[3] }, + }) + local a = { pa[1] * bs[1], pa[2] * bs[2], pa[3] * bs[3] } + acc[i] = a + pivot[i] = m + -- scale on the right: the bone's own space, so it cannot reach children + draw[i] = { + { m[1][1] * a[1], m[1][2] * a[2], m[1][3] * a[3], m[1][4] }, + { m[2][1] * a[1], m[2][2] * a[2], m[2][3] * a[3], m[2][4] }, + { m[3][1] * a[1], m[3][2] * a[2], m[3][3] * a[3], m[3][4] }, + } + end + return draw +end + +StadiumBuild.bindMatrices = bindMatrices +StadiumBuild.animSample = animSample + +-- The axis-aligned box the whole model occupies under `mats`, in game units +-- after the model_root scale. +local function poseBox(data, mats) + local root = data.rootScale[1] + local lo1, lo2, lo3 = 1e30, 1e30, 1e30 + local hi1, hi2, hi3 = -1e30, -1e30, -1e30 + for _, prim in ipairs(data.prims) do + local pos, skin = prim.pos, prim.skin + for i = 1, prim.nverts do + local m = mats[skin[i] + 1] + if m then + local x, y, z = pos[i * 3 - 2], pos[i * 3 - 1], pos[i * 3] + local a = (m[1][1] * x + m[1][2] * y + m[1][3] * z + m[1][4]) * root + local b = (m[2][1] * x + m[2][2] * y + m[2][3] * z + m[2][4]) * root + local c = (m[3][1] * x + m[3][2] * y + m[3][3] * z + m[3][4]) * root + if a < lo1 then lo1 = a end + if b < lo2 then lo2 = b end + if c < lo3 then lo3 = c end + if a > hi1 then hi1 = a end + if b > hi2 then hi2 = b end + if c > hi3 then hi3 = c end + end + end + end + return lo1, lo2, lo3, hi1, hi2, hi3 +end + +-- (height, floor, radius): how tall the mon is, where its lowest point sits +-- relative to the model's own origin, and how wide it is -- all in game units +-- after the model_root scale. +-- +-- Measured on the BIND POSE, which is the one pose in the set that can be +-- trusted for this. It reproduces the verified glTF export exactly on all 151 +-- species, and it is immune to the animation quirks a handful of them carry +-- (see idleIsBroken) -- quirks that would otherwise decide how big every OTHER +-- frame of those species is drawn. +-- +-- The floor is the interesting number, and it reads cleanly: 119 of the 151 +-- sit within 5% of zero, which says the model origin IS where the game stands +-- a Pokemon on its field. Every species that does not is one that hovers. +local function stance(data) + local lo1, lo2, lo3, hi1, hi2, hi3 = poseBox(data, bindMatrices(data.bones)) + if lo1 > hi1 then return 0.0, 0.0, 0.0 end + local w, d = hi1 - lo1, hi3 - lo3 + return hi2 - lo2, lo2, (w > d and w or d) / 2 +end + +StadiumBuild.stance = stance + +-- Whether this species' standby loop is corrupt in the source data. +-- +-- A handful come out of the extraction with animations that throw bones +-- hundreds of units off the body -- Exeggutor, Tangela and Magmar, whose +-- channel streams the game's own index arithmetic evidently reads differently +-- from the way this does. Played, they look like a Pokemon coming apart; the +-- mod would rather stand them still. +-- +-- The test is deliberately narrow, because "differs from the bind pose" is NOT +-- brokenness. It is asked only of the STANDBY loop -- the one animation that +-- is supposed to stay where it is, since a faint is meant to end far from the +-- standing pose and an attack is meant to lunge -- and it wants both a large +-- size blow-up and real drift, or an enormous amount of one. Dewgong is what +-- calibrates it: its idle is 2.4x its own bind pose because the BIND is the +-- collapsed one, and it drifts barely at all, so it must not be caught. +local function idleIsBroken(data, idle) + if idle == nil then return false end + local bones = data.bones + local _, lo2, _, _, hi2 = poseBox(data, bindMatrices(bones)) + local span = hi2 - lo2 + if span <= 0 then return false end + local worstH, worstDrift = 1.0, 0.0 + local frame = 0 + while frame < idle.frames do + local _, flo2, _, _, fhi2 = poseBox(data, + bindMatrices(bones, animSample(bones, idle, frame))) + local h = (fhi2 - flo2) / span + if h > worstH then worstH = h end + local d1 = (flo2 - lo2) / span + local d2 = (fhi2 - hi2) / span + if d1 < 0 then d1 = -d1 end + if d2 < 0 then d2 = -d2 end + if d1 > worstDrift then worstDrift = d1 end + if d2 > worstDrift then worstDrift = d2 end + frame = frame + 3 + end + return (worstH > 2.5 and worstDrift > 1.5) + or worstDrift > 2.0 or worstH > 3.4 +end + +-- ------- writing + +local function clamp(v, lo, hi) + if v < lo then return lo end + if v > hi then return hi end + return v +end + +-- Toward zero, which is what Python's int() does to a float and NOT what +-- floor() does to a negative one. +-- +-- It matters in exactly one place, and it is easy to miss: almost everything +-- reaching the integer writers below has already been rounded, so truncation +-- is a no-op on it. The exception is the generated effects' crossed quads +-- (StadiumFx), whose vertices are raw floats and straddle the origin -- so +-- the ones at negative x, and only those, come out a unit adrift if this +-- floors. +local function trunc(v) + if v >= 0 then return floor(v) end + return -floor(-v) +end + +-- 16.16, which holds every bone scale in the set (-31 .. 100) with more +-- precision than anything can see. +local function fixed(v) + return clamp(roundHalfEven(v * 65536), -2147483648, 2147483647) +end + +-- IEEE 754 single, little-endian, rounded to nearest with ties to even -- the +-- same rounding Python's struct.pack('= 255 then + return char(0, 0, 128, 127 + sign) -- overflow + elseif E <= 0 then + -- subnormal: no exponent left, so the mantissa carries the whole value + mant = roundHalfEven(x / 2 ^ -149) + if mant >= 8388608 then + mant, E = mant - 8388608, 1 + else + E = 0 + end + else + mant = roundHalfEven((m * 2 - 1) * 8388608) + if mant == 8388608 then -- rounded up into the next + mant, E = 0, E + 1 + if E >= 255 then return char(0, 0, 128, 127 + sign) end + end + end + local b4 = sign + floor(E / 2) + local b3 = (E % 2) * 128 + floor(mant / 65536) + local b2 = floor(mant / 256) % 256 + local b1 = mant % 256 + return char(b1, b2, b3, b4) +end + +StadiumBuild.f32 = f32 + +local Writer = {} +Writer.__index = Writer + +local function newWriter() + return setmetatable({ parts = {}, n = 0 }, Writer) +end + +function Writer:raw(s) + self.n = self.n + 1 + self.parts[self.n] = s +end + +function Writer:u8(v) + self:raw(char(v % 256)) +end + +function Writer:i8(v) + v = clamp(trunc(v), -128, 127) + self:raw(char(v % 256)) +end + +function Writer:u16(v) + v = v % 65536 + self:raw(char(v % 256, floor(v / 256))) +end + +function Writer:i16(v) + v = clamp(trunc(v), -32768, 32767) % 65536 + self:raw(char(v % 256, floor(v / 256))) +end + +function Writer:u32(v) + v = v % 4294967296 + self:raw(char(v % 256, floor(v / 256) % 256, floor(v / 65536) % 256, + floor(v / 16777216) % 256)) +end + +function Writer:i32(v) + v = clamp(trunc(v), -2147483648, 2147483647) % 4294967296 + self:raw(char(v % 256, floor(v / 256) % 256, floor(v / 65536) % 256, + floor(v / 16777216) % 256)) +end + +function Writer:f32(v) + self:raw(f32(v)) +end + +function Writer:bytes() + return concat(self.parts) +end + +-- One component of one bone's t/r/s in one animation. `values` is the +-- extractor's own shape: a bare number when the component holds still for the +-- whole animation, or one number a frame when it does not. That fold is where +-- most of the size saving is -- a bone that only rotates costs two bytes for +-- each of its six other components. +local function writeTrackComponent(w, values, kind) + local isArray = type(values) == "table" + w:u8(isArray and 1 or 0) + if kind == "s" then + if isArray then + for i = 1, #values do w:i32(fixed(values[i])) end + else + w:i32(fixed(values)) + end + else + if isArray then + for i = 1, #values do w:i16(roundHalfEven(values[i])) end + else + w:i16(roundHalfEven(values)) + end + end +end + +-- Which animation each fixed battle context slot resolves to: entries 165 +-- upward of the species' own battle table, in slot order. An entry naming an +-- animation the species does not have is written as "none" rather than +-- clamped -- the mod would rather fall back than play the wrong clip. +function StadiumBuild.contextTable(rows, nAnims) + local ctx = {} + for i = 1, #StadiumBuild.CONTEXTS do + local row = rows[CTX_BASE + i - 1] + local ai = row and row[1] or nil + ctx[i] = (ai ~= nil and ai < nAnims) and ai or NONE16 + end + return ctx +end + +-- ------- naming the animations +-- +-- build.py's label_animations. The names are not read at runtime -- the mod +-- addresses animations by index through the move and context tables -- but +-- they are in the format, so they have to be produced the same way for the +-- oracle diff to mean anything. They also make a packed file readable in a +-- hex dump, which is worth the byte apiece. + +local function labelAnimations(data, rows, nAux) + local anims = data.anims + local n = #anims + local uses, moveUses = {}, {} + local auxOrder, auxCount = {}, {} + for i = 1, n do + uses[i], moveUses[i] = {}, 0 + auxOrder[i], auxCount[i] = {}, {} + end + for e = 0, rows.n - 1 do + local ai = rows[e][1] + if ai < n then + if e < N_MOVES then + moveUses[ai + 1] = moveUses[ai + 1] + 1 + elseif e >= CTX_BASE and e < CTX_BASE + #StadiumBuild.CONTEXTS then + local list = uses[ai + 1] + list[#list + 1] = StadiumBuild.CONTEXTS[e - CTX_BASE + 1] + end + local ax = rows[e][2] + if ax >= 0 and ax < nAux then + local counts, order = auxCount[ai + 1], auxOrder[ai + 1] + if counts[ax] == nil then + counts[ax] = 0 + order[#order + 1] = ax + end + counts[ax] = counts[ax] + 1 + end + end + end + + for i = 1, n do + -- sorted(set(uses)) -- the alphabetically first context is the fallback + -- name, so the ordering is part of the answer + local seen, ctx = {}, {} + for _, name in ipairs(uses[i]) do + if not seen[name] then + seen[name] = true + ctx[#ctx + 1] = name + end + end + table.sort(ctx) + local name = nil + for _, pref in ipairs(NAME_PREF) do + if seen[pref] then + name = pref + break + end + end + if not name then + if moveUses[i] > 0 then + name = "attack" + elseif ctx[1] then + name = ctx[1] + else + name = "anim" .. (i - 1) + end + end + anims[i].name = name + -- Counter.most_common(1): the highest count, and on a tie the one that + -- was inserted first + local best, bestN = -1, -1 + local order, counts = auxOrder[i], auxCount[i] + for _, ax in ipairs(order) do + if counts[ax] > bestN then + best, bestN = ax, counts[ax] + end + end + anims[i].aux = best + end + + local seenName = {} + for i = 1, n do + local base = anims[i].name + local k = seenName[base] or 0 + seenName[base] = k + 1 + if k > 0 then anims[i].name = base .. "_" .. (k + 1) end + end +end + +-- ------- the pack + +function StadiumBuild.pack(data, species, moveRows, ctx) + local w = newWriter() + local bones, prims = data.bones, data.prims + local textures, anims, aux = data.textures, data.anims, data.auxAnims + + local height, floorY, radius = stance(data) + + local idleIndex = ctx[1] -- CONTEXTS[1] is "idle" + local idle = (idleIndex ~= NONE16) and anims[idleIndex + 1] or nil + local static = idleIsBroken(data, idle) + + w:raw("DSM3") + w:u16(species) + w:u16(#bones) + w:u16(#prims) + w:u16(#textures) + w:u16(#anims) + w:u16(#aux) + w:f32(data.rootScale[1]) + -- 1 = hold the bind pose, never play an animation + w:u8(static and 1 or 0) + w:f32(height) + w:f32(floorY) + w:f32(radius) + + for m = 1, N_MOVES do + local row = moveRows[m] + w:u16((row and row[1] < #anims) and row[1] or NONE16) + end + for m = 1, N_MOVES do + local row = moveRows[m] + w:i16((row and row[2] >= 0 and row[2] < #aux) and row[2] or -1) + end + for i = 1, #ctx do w:u16(ctx[i]) end + + for i = 1, #bones do + local b = bones[i] + w:i16(b.parent) + for k = 1, 3 do w:i16(roundHalfEven(b.t[k])) end + for k = 1, 3 do w:i16(b.r[k]) end + for k = 1, 3 do w:i32(fixed(b.s[k])) end + end + + for i = 1, #prims do + local p = prims[i] + w:u16(p.tex) + -- the display list's own cull mode: 1024 is G_CULL_BACK + w:u8((p.cull and p.cull ~= 0) and 1 or 0) + w:u8((p.blend == "add") and 1 or 0) + w:i16(p.texAnim or -1) + -- sorted by the stream's own byte, which is what the reader keys on + local keys = {} + if p.texMap then + for k in pairs(p.texMap) do keys[#keys + 1] = k end + table.sort(keys) + end + w:u8(#keys) + for _, k in ipairs(keys) do + w:u8(k) + w:u16(p.texMap[k]) + end + local frames = p.fxFrames + w:u16(frames and #frames or 0) + if frames then + for k = 1, #frames do w:u16(frames[k]) end + end + local pos, uv, nrm, skin = p.pos, p.uv, p.nrm, p.skin + w:u16(p.nverts) + w:u16(p.nidx) + for k = 1, p.nverts do + w:i16(pos[k * 3 - 2]) + w:i16(pos[k * 3 - 1]) + w:i16(pos[k * 3]) + -- 1/512, which puts a texel of the largest texture in the set well + -- inside a step and still reaches the +-32 the wrapped coordinates of + -- some display lists run to + w:i16(roundHalfEven(uv[k * 2 - 1] * 512)) + w:i16(roundHalfEven(uv[k * 2] * 512)) + w:i8(roundHalfEven(nrm[k * 3 - 2] * 127)) + w:i8(roundHalfEven(nrm[k * 3 - 1] * 127)) + w:i8(roundHalfEven(nrm[k * 3] * 127)) + w:u8(skin[k]) + end + for k = 1, p.nidx do w:u16(p.idx[k]) end + end + + for i = 1, #textures do + local t = textures[i] + w:u16(t.w) + w:u16(t.h) + w:u32(#t.rgba) + w:raw(t.rgba) + end + + local REST = { t = { 0, 0, 0 }, r = { 0, 0, 0 }, s = { 1.0, 1.0, 1.0 } } + for i = 1, #anims do + local a = anims[i] + local name = a.name or "" + if #name > 255 then name = name:sub(1, 255) end + w:u8(#name) + w:raw(name) + w:u16(a.frames) + w:u16(a.loopStart or 0) + w:i16(a.aux or -1) + for bi = 1, #bones do + local tr = a.tracks[bi] + if not tr then + w:u8(0) + else + w:u8(1) + for _, key in ipairs({ "t", "r", "s" }) do + local comps = tr[key] + if comps == nil then + -- a bone the animation leaves at its rest value for this path: + -- written as three constants so the reader never has to branch on + -- a missing path + comps = bones[bi][key] or REST[key] + end + for c = 1, 3 do writeTrackComponent(w, comps[c], key) end + end + end + end + end + + for i = 1, #aux do + local a = aux[i] + w:u16(a.frames) + w:u16(a.loopStart or 0) + w:u16(#a.channels) + for _, ch in ipairs(a.channels) do + w:u16(ch.n) + for k = 1, ch.n do w:u16(ch[k]) end + end + end + + return w:bytes(), height, floorY, radius +end + +-- ------- one species, end to end + +-- The same three steps build.py takes: parse the fragment, label the +-- animations off the species' battle table, then hang the generated fire/gas +-- stand-ins on the bones the game's own effect callbacks hang off. +function StadiumBuild.species(rom, fileno) + local blob = rom:model(fileno) + if not blob then return nil, ("file %d is not in the archive"):format(fileno) end + local data, err = StadiumFragment.extract(blob, ("%d.bin"):format(fileno)) + if not data then return nil, err end + local species = data.species + local rows = rom:battleRows(species) + labelAnimations(data, rows, #data.auxAnims) + StadiumFx.attach(data, species) + + local moveRows = {} + for m = 1, N_MOVES do moveRows[m] = rows[m - 1] end + local ctx = StadiumBuild.contextTable(rows, #data.anims) + local bytes, height, floorY, radius = + StadiumBuild.pack(data, species, moveRows, ctx) + return { species = species, bytes = bytes, height = height, + floor = floorY, radius = radius, bones = #data.bones, + prims = #data.prims, anims = #data.anims, + warnings = data.warnings } +end + +-- ------- the stepped job +-- +-- `write(species, bytes)` is called for each finished pack and must answer +-- truthy; anything else stops the job with an error. Returning a job rather +-- than taking a callback for progress keeps the caller in charge of when work +-- happens, which is what lets a loading screen stay responsive. +function StadiumBuild.job(rom, write, count) + local total = count or StadiumRom.N_POKEMON + local n = rom:modelCount() + if total > n then total = n end + local job = { total = total, done = 0, bytes = 0, failed = {}, species = nil } + + function job:step() + if self.done >= self.total then return false end + local fileno = self.done + local ok, res, err = pcall(StadiumBuild.species, rom, fileno) + if ok and res then + local wrote, wErr = write(res.species, res.bytes) + if not wrote then + self.error = wErr or ("could not write species " .. res.species) + self.done = self.total + return false + end + self.bytes = self.bytes + #res.bytes + self.species = res.species + else + self.failed[#self.failed + 1] = fileno + self.lastError = ok and err or res + end + self.done = self.done + 1 + return self.done < self.total + end + + function job:progress() + if self.total <= 0 then return 1 end + return self.done / self.total + end + + return job +end + +return StadiumBuild diff --git a/lib/StadiumFragment.lua b/lib/StadiumFragment.lua new file mode 100644 index 0000000..9cf3565 --- /dev/null +++ b/lib/StadiumFragment.lua @@ -0,0 +1,1016 @@ +-- STADIUM battles: one FRAGMENT module -> geometry, textures, skeleton, +-- animations. +-- +-- A port of model_extract/pipeline/fragment.py, structure for structure and +-- name for name, so the two can be read side by side and diffed. The Python +-- is the reference implementation and stays the ORACLE: +-- tools/stadium_pack.py drives it over the same ROM and +-- tests/stadium_extract_test.lua requires the finished .dsm files to agree +-- byte for byte. That is the only way a port of this much numeric code can +-- be trusted -- reading it twice is not enough. +-- +-- ------- the three things it does +-- +-- THE GEO LAYOUT is a little bytecode: a tree of nodes with an open/close +-- stack, where some nodes are bones, some set the current material, and some +-- hand a display list to whichever bone is live. Walking it builds the +-- skeleton and decides which triangles belong to which bone. +-- +-- THE DISPLAY LISTS are F3DEX2, the N64's own graphics microcode. Only four +-- of its commands matter here -- load vertices, draw triangle(s), set the +-- geometry mode (which carries the cull bits), call/branch -- because +-- everything else is render state this rebuilds from the texture table +-- instead. +-- +-- THE ANIMATIONS are packed per-frame streams of 12- or 16-bit fields. The +-- game also has a hermite-keyframe mode (flags & 8); it is ported for +-- completeness but no animation of any of the 151 battle Pokemon uses it. +-- +-- ------- arithmetic, and why there are no bit operations here +-- +-- Every shift and mask is written as multiply/divide/modulo. Two reasons. +-- LuaJIT's `bit` library works on SIGNED 32-bit integers, so every value that +-- crosses 0x80000000 -- which pointers in this file constantly do -- would +-- need a conversion back, and each of those is a place to be wrong. And the +-- one shift that genuinely needs care (`bitfield` below) has to be exact to +-- 32 bits, which a double can do only if the value is reduced BEFORE it is +-- shifted up. Doing it in arithmetic makes that reduction visible instead of +-- hiding it behind an operator that silently truncates. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumFragment = {} + +local byte = string.byte +local char = string.char +local sub = string.sub +local concat = table.concat +local floor = math.floor + +-- Where the module is linked to run. Every pointer inside it is an address in +-- that space, so subtracting this turns one into a file offset. +local BASE = 0x8FF00000 + +-- Size of each geo-layout command, by opcode. A command this does not +-- understand is still stepped over correctly, which is what lets an unknown +-- one be a warning rather than the end of the walk. +local CMD_SIZES = { + [0x00] = 0x08, [0x01] = 0x04, [0x02] = 0x08, [0x03] = 0x08, [0x04] = 0x04, + [0x05] = 0x04, [0x06] = 0x04, [0x07] = 0x08, [0x08] = 0x0C, [0x09] = 0x04, + [0x0A] = 0x08, [0x0B] = 0x18, [0x0C] = 0x04, [0x0D] = 0x04, [0x0E] = 0x04, + [0x0F] = 0x04, [0x10] = 0x04, [0x11] = 0x04, [0x12] = 0x04, [0x13] = 0x08, + [0x14] = 0x0C, [0x15] = 0x0C, [0x16] = 0x04, [0x17] = 0x14, [0x18] = 0x08, + [0x19] = 0x08, [0x1A] = 0x04, [0x1B] = 0x10, [0x1C] = 0x10, [0x1D] = 0x1C, + [0x1E] = 0x08, [0x1F] = 0x18, [0x20] = 0x14, [0x21] = 0x10, [0x22] = 0x08, + [0x23] = 0x10, [0x24] = 0x04, [0x25] = 0x04, [0x26] = 0x14, +} + +StadiumFragment.CMD_SIZES = CMD_SIZES + +-- ------- rounding +-- +-- Python rounds half to EVEN, and the packer's numbers go through `round` +-- three times over (fold a track to a constant, quantise a scale to 16.16, +-- quantise a UV to 1/512). Rounding half away from zero instead would put +-- this one off by one wherever a value lands exactly on a boundary, and a +-- single byte is all it takes for the oracle diff to fail -- so it is worth +-- the six lines to do it the same way. + +local function roundHalfEven(x) + local f = floor(x) + local d = x - f + if d > 0.5 then return f + 1 end + if d < 0.5 then return f end + if f % 2 == 0 then return f end + return f + 1 +end + +local function roundTo(x, nd) + if nd == 0 then return roundHalfEven(x) end + local m = 10 ^ nd + return roundHalfEven(x * m) / m +end + +StadiumFragment.roundHalfEven = roundHalfEven +StadiumFragment.roundTo = roundTo + +-- Two's-complement reading of an n-bit field. +local function signed(v, bits) + local m = 2 ^ (bits - 1) + if v >= m then return v - m * 2 end + return v +end + +StadiumFragment.signed = signed + +-- The distinct values of an array, in the order they first appear. The Python +-- reached for a set here and that decided the order textures were registered +-- in -- see fragment.py's own `unique`. +local function unique(seq, n) + local seen, out, m = {}, {}, 0 + for i = 1, n or #seq do + local v = seq[i] + if v ~= nil and not seen[v] then + seen[v] = true + m = m + 1 + out[m] = v + end + end + return out, m +end + +-- ------- the module + +local Frag = {} +Frag.__index = Frag + +function Frag:u8(o) + return byte(self.d, o + 1) +end + +function Frag:s8(o) + local v = byte(self.d, o + 1) + if v >= 128 then return v - 256 end + return v +end + +function Frag:u16(o) + local a, b = byte(self.d, o + 1, o + 2) + return a * 256 + b +end + +function Frag:s16(o) + local a, b = byte(self.d, o + 1, o + 2) + local v = a * 256 + b + if v >= 32768 then return v - 65536 end + return v +end + +function Frag:u32(o) + local a, b, c, d = byte(self.d, o + 1, o + 4) + return ((a * 256 + b) * 256 + c) * 256 + d +end + +function Frag:s32(o) + local v = self:u32(o) + if v >= 2147483648 then return v - 4294967296 end + return v +end + +-- A pointer as a file offset, or nil for the null pointer. +function Frag:off(ptr) + if ptr == 0 then return nil end + return ptr - BASE +end + +function Frag:ptr(o) + return self:off(self:u32(o)) +end + +-- The entry stub ends with `lui rX, hi; addiu rX, rX, lo`, which is MIPS for +-- "load the address of the root struct". Finding that pair is how the root is +-- located without a symbol table. +function Frag:root() + for o = 0x20, 0x7C, 4 do + local w = self:u32(o) + if floor(w / 0x4000000) == 0x0F then -- lui + local reg = floor(w / 0x10000) % 0x20 + local w2 = self:u32(o + 4) + if floor(w2 / 0x4000000) == 0x09 -- addiu rX, rX, imm + and floor(w2 / 0x200000) % 0x20 == reg then + return self:u16(o + 2) * 65536 + self:s16(o + 6) - BASE + end + end + end + return nil +end + +-- A null-terminated run of pointers. +function Frag:ptrList(o) + local out, n = {}, 0 + while true do + local p = self:ptr(o) + if p == nil then return out, n end + n = n + 1 + out[n] = p + o = o + 4 + end +end + +-- `data` is one decompressed archive entry. +function StadiumFragment.open(data, name) + if type(data) ~= "string" or #data < 0x20 then + return nil, (name or "?") .. ": too short to be a module" + end + if sub(data, 9, 16) ~= "FRAGMENT" then + return nil, (name or "?") .. ": not a FRAGMENT module" + end + return setmetatable({ d = data, name = name or "" }, Frag) +end + +-- ------- walking the geo layout and running the display lists + +local Model = {} +Model.__index = Model + +local function newModel(frag) + local r = frag:root() + if not r then return nil, frag.name .. ": could not locate root struct" end + local geo = frag:ptr(r + 0x08) + local anims = frag:ptr(r + 0x0C) + local aux = frag:ptr(r + 0x10) + local m = setmetatable({ + f = frag, + species = frag:u16(r), + geoLayouts = geo and frag:ptrList(geo) or {}, + anims = anims and frag:ptrList(anims) or {}, + auxAnims = aux and frag:ptrList(aux) or {}, + textures = {}, -- { fmt, siz, w, h, texels, data } + tluts = {}, -- palettes: { count, data, dl } + bones = {}, -- { parent, boneId, flags, chan, t, r, s } + boneById = {}, + prims = {}, -- { tex, tlut, mat, texAnim, cull, verts, tris } + primsByKey = {}, + rootScale = { 1.0, 1.0, 1.0 }, + fx = {}, -- geo cmd 0x08 procedural effect nodes + warnings = {}, + }, Model) + return m +end + +function Model:readTextureTable(off, count) + local f = self.f + local t = self.textures + for i = 0, count - 1 do + local o = off + i * 0xC + t[#t + 1] = { + fmt = f:u8(o), siz = f:u8(o + 1), w = f:s16(o + 2), + h = f:u16(o + 4), texels = f:u16(o + 6), data = f:ptr(o + 8), + } + end +end + +-- Palettes reuse the texture-record layout: the count sits in the width +-- field, the palette data in the next word, and unk_08 is the display list +-- that loads it (src/12D80.c func_80015B20). The list is authoritative, so it +-- is run rather than trusted. +function Model:readTlutTable(off, count) + local f = self.f + for i = 0, count - 1 do + local o = off + i * 0xC + local rec = { count = f:u16(o + 2), data = f:ptr(o + 4), dl = f:ptr(o + 8) } + local dl = rec.dl + if dl ~= nil then + for _ = 1, 16 do + local w0, w1 = f:u32(dl), f:u32(dl + 4) + local op = floor(w0 / 0x1000000) + if op == 0xFD then -- G_SETTIMG + rec.data = f:off(w1) + elseif op == 0xF0 then -- G_LOADTLUT + rec.count = floor(w1 / 0x4000) % 0x400 + 1 + elseif op == 0xDF then + break + end + dl = dl + 8 + end + end + self.tluts[#self.tluts + 1] = rec + end +end + +-- The bone whose matrix is live. Mirrors gCurGraphNodeList in +-- src/geo_layout.c: the top of the stack is the slot the NEXT node command +-- writes to, so the node that owns the current one is the slot below +-- (func_80017AC4). +function Model:curBone() + local n = #self.stack + if n >= 2 then return self.stack[n - 1] end + return -1 +end + +function Model:build() + self.curTex = -1 + self.curTlut = -1 + self.curMat = nil + self.curTexAnim = -1 + self.stack = { -1 } + -- The RSP vertex cache persists ACROSS display lists: a bone's list often + -- preloads vertices that the next bone's list then indexes, which is how + -- these models get blended joints. Each slot remembers the bone whose + -- matrix was current when it was loaded. + self.vbuf = {} + if not self.geoLayouts[1] then + self.warnings[#self.warnings + 1] = "no geo layout" + return + end + self:walk(self.geoLayouts[1], 0) +end + +function Model:walk(o, depth) + local f = self.f + if depth > 32 or o == nil then return end + while true do + local cmd = f:u8(o) + local size = CMD_SIZES[cmd] + if size == nil then + self.warnings[#self.warnings + 1] = + ("unknown geo cmd 0x%02x at 0x%x"):format(cmd or -1, o) + return + end + if cmd == 0x01 or cmd == 0x04 then -- end / return + return + elseif cmd == 0x00 or cmd == 0x03 then -- branch (with return) + self:walk(f:ptr(o + 4), depth + 1) + elseif cmd == 0x02 then -- jump (no return) + o = f:ptr(o + 4) + if o == nil then return end + cmd = nil -- skip the o = o + size + elseif cmd == 0x05 then -- open node + local n = #self.stack + self.stack[n + 1] = self.stack[n] + elseif cmd == 0x06 then -- close node + self.stack[#self.stack] = nil + elseif cmd == 0x17 then -- model header + self:readTextureTable(f:ptr(o + 8), f:s16(o + 2)) + if f:ptr(o + 0xC) then + self:readTlutTable(f:ptr(o + 0xC), f:s16(o + 4)) + end + self.vtxBase = f:ptr(o + 0x10) + self.nVerts = f:s16(o + 6) + elseif cmd == 0x08 then -- effect callback + self.fx[#self.fx + 1] = { bone = self:curBone(), callback = f:u32(o + 4), + arg = f:ptr(o + 8) } + elseif cmd == 0x1C then -- uniform scale node + self.rootScale = { f:s32(o + 4) / 65536.0, f:s32(o + 8) / 65536.0, + f:s32(o + 0xC) / 65536.0 } + elseif cmd == 0x1D then -- bone / joint node + local idx = #self.bones -- 0-based, as the file + self.bones[idx + 1] = { + parent = self:curBone(), boneId = f:u8(o + 1), flags = f:u8(o + 2), + chan = f:s8(o + 3), + t = { f:s16(o + 4), f:s16(o + 6), f:s16(o + 8) }, + r = { f:s16(o + 0xA), f:s16(o + 0xC), f:s16(o + 0xE) }, + s = { f:s32(o + 0x10) / 65536.0, f:s32(o + 0x14) / 65536.0, + f:s32(o + 0x18) / 65536.0 }, + } + self.boneById[f:u8(o + 1)] = idx + self.stack[#self.stack] = idx + elseif cmd == 0x23 then -- set texture / material + self.curTex = f:s16(o + 8) + self.curTlut = f:s16(o + 0xA) + self.curMat = f:ptr(o + 4) + -- offset 0x02 is the texture-animation channel; -1 means static. + -- func_800176DC swaps this material's texture per frame out of the + -- auxiliary animation's stream. + self.curTexAnim = f:s16(o + 2) + elseif cmd == 0x22 then -- DL on current bone + self:runDL(f:ptr(o + 4), self:curBone(), 0) + elseif cmd == 0x1E then -- DL on named bone + local named = self.boneById[f:s16(o + 2)] + self:runDL(f:ptr(o + 4), named or self:curBone(), 0) + elseif cmd == 0x20 or cmd == 0x21 then -- DL + own transform + self:runDL(f:ptr(o + (cmd == 0x20 and 0x10 or 0xC)), self:curBone(), 0) + end + if cmd ~= nil then o = o + size end + end +end + +function Model:primFor(tex, tlut, mat, texAnim, cull) + local key = tex .. "," .. tlut .. "," .. tostring(mat) .. "," + .. texAnim .. "," .. cull + local p = self.primsByKey[key] + if p == nil then + p = { tex = tex, tlut = tlut, mat = mat, texAnim = texAnim, cull = cull, + verts = {}, nverts = 0, tris = {}, ntris = 0, remap = {} } + self.primsByKey[key] = p + self.prims[#self.prims + 1] = p + end + return p +end + +-- Bitwise AND and OR over the low `bits` bits, in arithmetic. See the module +-- header for why there is no `bit` library in here. +local function band(a, b, bits) + local r, p = 0, 1 + for _ = 1, bits do + if a % 2 == 1 and b % 2 == 1 then r = r + p end + a, b, p = floor(a / 2), floor(b / 2), p * 2 + end + return r +end + +local function bor(a, b, bits) + local r, p = 0, 1 + for _ = 1, bits do + if a % 2 == 1 or b % 2 == 1 then r = r + p end + a, b, p = floor(a / 2), floor(b / 2), p * 2 + end + return r +end + +-- One triangle out of the vertex cache and into a prim, deduplicating +-- vertices as it goes. +-- +-- A file-level function rather than a closure inside runDL: it is called +-- once per triangle -- some two hundred thousand times over the set -- and a +-- closure there would allocate one per display-list command. +-- +-- A triangle naming a cache slot that was never loaded is DROPPED, not +-- faulted. That happens where a display list indexes past what its own G_VTX +-- filled, which the hardware would read as stale cache; there is nothing +-- meaningful to draw. +-- +-- It is abandoned MID-TRIANGLE, exactly where the missing corner is found, +-- and the corners already walked keep the slots they were just given in the +-- vertex list. That looks like a detail and is not: those vertices stay in +-- the prim, so they shift every later vertex's index by one. Checking all +-- three corners up front instead -- which is what a careful reader writes -- +-- silently produces a different, equally plausible vertex list, and every +-- index in the file after that point moves. +local function emit(prim, vbuf, flip, ia, ib, ic) + local remap, verts = prim.remap, prim.verts + local tri = { 0, 0, 0 } + for k = 1, 3 do + local v = vbuf[k == 1 and ia or (k == 2 and ib or ic)] + if v == nil then return end + local key = v[1] .. "," .. v[2] .. "," .. v[3] .. "," .. v[4] .. "," + .. v[5] .. "," .. v[6] .. "," .. v[7] .. "," .. v[8] + .. "," .. v[9] .. "," .. v[10] + local j = remap[key] + if j == nil then + j = prim.nverts -- 0-based, as the file + remap[key] = j + prim.nverts = j + 1 + verts[j + 1] = v + end + tri[k] = j + end + if flip then tri[1], tri[3] = tri[3], tri[1] end + prim.ntris = prim.ntris + 1 + prim.tris[prim.ntris] = tri +end + +function Model:runDL(o, bone, depth) + if o == nil or depth > 8 then return end + local f = self.f + local vbuf = self.vbuf + local cull = 0x400 + while true do + local w0, w1 = f:u32(o), f:u32(o + 4) + local op = floor(w0 / 0x1000000) + o = o + 8 + if op == 0xDF then -- G_ENDDL + return + elseif op == 0xDE then -- G_DL + self:runDL(f:off(w1), bone, depth + 1) + if floor(w0 / 0x10000) % 256 ~= 0 then -- branch, not call + return + end + elseif op == 0x01 then -- G_VTX + local n = floor(w0 / 0x1000) % 256 + local v0 = floor((w0 % 0x1000) / 2) - n + local a = f:off(w1) + if a then + for i = 0, n - 1 do + local p = a + i * 0x10 + local slot = v0 + i + if slot >= 0 and slot < 64 then + -- s and t are S10.5 and kept RAW here; the /32 happens once, on + -- the way out, so that the dedup key below compares integers + vbuf[slot] = { f:s16(p), f:s16(p + 2), f:s16(p + 4), + f:s16(p + 8), f:s16(p + 10), + f:s8(p + 12), f:s8(p + 13), f:s8(p + 14), + f:u8(p + 15), bone } + end + end + end + elseif op == 0xD9 then -- G_GEOMETRYMODE + -- `cull = (cull & (w0 & 0xFFFFFF)) | w1`. + -- + -- Only bits 9 and 10 -- G_CULL_FRONT and G_CULL_BACK -- are ever read + -- out of this, so the whole word is kept to eleven bits and the AND and + -- OR done over those. Bits above that cannot influence bits 9 and 10 + -- under either operator, so nothing is lost and the two loops that used + -- to run 24 times each now run 11. + cull = bor(band(cull, w0 % 0x800, 11), w1 % 0x800, 11) + elseif op == 0x05 or op == 0x06 then -- G_TRI1 / G_TRI2 + local prim = self:primFor(self.curTex, self.curTlut, self.curMat, + self.curTexAnim, cull % 0x800 - cull % 0x200) + local flip = (floor(cull / 0x200) % 2 == 1) + and (floor(cull / 0x400) % 2 == 0) + emit(prim, vbuf, flip, + floor(floor(w0 / 0x10000) % 256 / 2), + floor(floor(w0 / 0x100) % 256 / 2), + floor(w0 % 256 / 2)) + if op == 0x06 then + emit(prim, vbuf, flip, + floor(floor(w1 / 0x10000) % 256 / 2), + floor(floor(w1 / 0x100) % 256 / 2), + floor(w1 % 256 / 2)) + end + end + -- everything else (SETTILE / sync / ...) is render state this rebuilds + -- from the texture table instead, so it is skipped + end +end + +-- CI4 selects a 16-entry block of the palette through the render tile's +-- palette field; read it out of the material display list's last G_SETTILE. +function Model:tilePalette(mat) + if mat == nil then return 0 end + local f = self.f + local pal = 0 + for _ = 1, 16 do + local w0, w1 = f:u32(mat), f:u32(mat + 4) + local op = floor(w0 / 0x1000000) + if op == 0xF5 and floor(w1 / 0x1000000) % 8 == 0 then -- render tile + pal = floor(w1 / 0x100000) % 16 + elseif op == 0xDF then + break + end + mat = mat + 8 + end + return pal +end + +-- ------- animations + +-- src/F420.c func_80010500: a signed `bits`-wide field at bit index*bits. +-- +-- C integer division truncates toward zero and Lua's floor() does not, which +-- only differs for a NEGATIVE index -- and a negative index is exactly what an +-- empty channel produces, so the truncating form is the one that matches the +-- hardware. +-- +-- The shift is the part that needs care. `(v << rem) & 0xFFFFFFFF` on a +-- 32-bit v would want 63 bits of intermediate, and a double holds 53 exactly. +-- Masking FIRST -- dropping the bits the shift would push out anyway -- keeps +-- the product under 2^32 and therefore exact. +local function bitfield(f, base, index, bits) + local bitpos = index * bits + local word + if bitpos >= 0 then + word = floor(bitpos / 16) + else + word = -floor(-bitpos / 16) + end + local rem = bitpos - word * 16 + local o = base + word * 2 + local v = f:u16(o) * 65536 + f:u16(o + 2) + local shift = rem % 32 + local keep = 2 ^ (32 - shift) + v = (v % keep) * 2 ^ shift + return signed(floor(v / 2 ^ (32 - bits)), bits) +end + +StadiumFragment.bitfield = bitfield + +local Anim = {} +Anim.__index = Anim + +local function newAnim(frag, off) + return setmetatable({ + f = frag, off = off, + flags = frag:u8(off), + startFrame = frag:u16(off + 4), + loopStart = frag:u16(off + 6), + nChannels = frag:u16(off + 8), + nFrames = frag:u16(off + 0xA), + chanTable = frag:ptr(off + 0xC), + scaleData = frag:ptr(off + 0x10), + rotData = frag:ptr(off + 0x14), + transData = frag:ptr(off + 0x18), + }, Anim) +end + +function Anim:chan(i) + local o = self.chanTable + i * 0xA + local f = self.f + return { nScale = f:u8(o), nRot = f:u8(o + 1), nTrans = f:u8(o + 2), + interp = f:u8(o + 3), oScale = f:u16(o + 4), + oRot = f:u16(o + 6), oTrans = f:u16(o + 8) } +end + +-- Packed per-frame streams (flags & 8 == 0), which is what every animation of +-- every battle Pokemon actually uses. +-- +-- A count of 0 means the component has no stream at all. The game's own index +-- arithmetic (offset + count - 1) then runs off the front of the array -- for +-- Tangela's idle the scale "array" is two entries long and the computed index +-- is 99 -- so an empty channel is read as "keep the bind-pose value", which is +-- what the nil return means to the caller. +function Anim:transPacked(c, frame) + if c.nTrans == 0 then return nil end + local wide = floor(self.flags / 4) % 2 == 1 + local bits = wide and 16 or 12 + if c.nTrans == 1 then + if wide then return c.oTrans + 0.0 end + return floor(signed(c.oTrans * 16 % 65536, 16) / 16) + 0.0 + end + local i = c.oTrans + (frame < c.nTrans - 1 and frame or c.nTrans - 1) + return bitfield(self.f, self.transData, i, bits) + 0.0 +end + +function Anim:rotPacked(c, frame) + if c.nRot == 0 then return nil end + if c.nRot == 1 then return signed(c.oRot * 16 % 65536, 16) end + local i = c.oRot + (frame < c.nRot - 1 and frame or c.nRot - 1) + return signed(bitfield(self.f, self.rotData, i, 12) * 16 % 65536, 16) +end + +function Anim:scalePacked(c, frame) + if c.nScale == 0 then return nil end + if c.nScale == 1 then return c.oScale / 1000.0 end + local i = c.oScale + (frame < c.nScale - 1 and frame or c.nScale - 1) + return self.f:s16(self.scaleData + i * 2) / 1000.0 +end + +-- Hermite keyframes (flags & 8). Ported for completeness: no animation of any +-- of the 151 battle Pokemon sets that flag, which was measured rather than +-- assumed. +function Anim:hermite(base, n, frame, wide) + local f = self.f + local stride = wide and 8 or 6 + local function key(i) + local o = base + i * stride + return f:s16(o), f:s16(o + 2), f:s16(o + 4), + wide and f:s16(o + 6) or f:s16(o + 4) + end + local k0t, k0v = key(0) + if k0t >= frame then return k0v + 0.0 end + local lt, lv = key(n - 1) + if frame >= lt then return lv + 0.0 end + local i = 0 + while i < n - 2 do + if frame < (key(i + 1)) then break end + i = i + 1 + end + local at, av, ao, aw = key(i) + local bt, bv, bo = key(i + 1) + local x = (frame - at) / 30.0 + local y = 30.0 / (bt - at) + local x2, x3 = x * x, x * x * x + local y2, y3 = y * y, y * y * y + return av * (2 * x3 * y3 - 3 * x2 * y2 + 1) + + bv * (-2 * x3 * y3 + 3 * x2 * y2) + + (wide and aw or ao) * (x3 * y2 - 2 * x2 * y + x) + + bo * (x3 * y2 - x2 * y) +end + +function Anim:transKey(c, frame) + if c.nTrans < 2 then return signed(c.oTrans, 16) + 0.0 end + return self:hermite(self.transData + c.oTrans * 2, c.nTrans, frame, + c.interp % 2 == 1) +end + +function Anim:rotKey(c, frame) + local deg + if c.nRot < 2 then + deg = signed(c.oRot, 16) / 10.0 + else + deg = self:hermite(self.rotData + c.oRot * 2, c.nRot, frame, + floor(c.interp / 2) % 2 == 1) / 10.0 + end + deg = deg % 360.0 + return floor(deg / 360.0 * 65536.0) +end + +function Anim:scaleKey(c, frame) + if c.nScale < 2 then return signed(c.oScale, 16) / 100.0 end + return self:hermite(self.scaleData + c.oScale * 2, c.nScale, frame, + floor(c.interp / 4) % 2 == 1) / 100.0 +end + +-- (translation, rotation, scale) for one bone at one frame. Components whose +-- channel carries no data fall back to the bone's bind value. +function Anim:sampleTrs(chanIndex, frame, bt, br, bs) + local base = chanIndex * 3 + if base < 0 or base + 2 >= self.nChannels then return nil end + local c1, c2, c3 = self:chan(base), self:chan(base + 1), self:chan(base + 2) + local t, r, s = {}, {}, {} + if floor(self.flags / 8) % 2 == 1 then + t[1], t[2], t[3] = self:transKey(c1, frame), self:transKey(c2, frame), + self:transKey(c3, frame) + r[1], r[2], r[3] = self:rotKey(c1, frame), self:rotKey(c2, frame), + self:rotKey(c3, frame) + s[1], s[2], s[3] = self:scaleKey(c1, frame), self:scaleKey(c2, frame), + self:scaleKey(c3, frame) + else + t[1], t[2], t[3] = self:transPacked(c1, frame), self:transPacked(c2, frame), + self:transPacked(c3, frame) + r[1], r[2], r[3] = self:rotPacked(c1, frame), self:rotPacked(c2, frame), + self:rotPacked(c3, frame) + s[1], s[2], s[3] = self:scalePacked(c1, frame), + self:scalePacked(c2, frame), self:scalePacked(c3, frame) + end + for k = 1, 3 do + if t[k] == nil then t[k] = bt[k] end + if r[k] == nil then r[k] = br[k] end + if s[k] == nil then s[k] = bs[k] end + end + return t, r, s +end + +-- Texture animation (src/18140.c). Same header shape as a skeletal animation, +-- but each channel is a per-frame stream of texture-table indices that +-- func_800176DC substitutes into a material. +local Aux = {} +Aux.__index = Aux + +local function newAux(frag, off) + return setmetatable({ + f = frag, + flags = frag:u8(off), + startFrame = frag:u16(off + 4), + loopStart = frag:u16(off + 6), + nChannels = frag:u16(off + 8), + nFrames = frag:u16(off + 0xA), + chanTable = frag:ptr(off + 0xC), + data = frag:ptr(off + 0x10), + }, Aux) +end + +-- func_80017540: index into the stream, clamped to the channel's length. +function Aux:sample(chan, frame) + if chan < 0 or chan >= self.nChannels or self.chanTable == nil then + return nil + end + local o = self.chanTable + chan * 4 + local count, base = self.f:u16(o), self.f:u16(o + 2) + if count == 0 then return nil end + local i = base + (frame < count and frame or count - 1) + return self.f:u8(self.data + i) +end + +function Aux:track(chan) + local n = self.nFrames > 1 and self.nFrames or 1 + local out = {} + for i = 0, n - 1 do out[i + 1] = self:sample(chan, i) end + return out, n +end + +-- ------- textures + +local function rgba5551(p) + return floor(floor(p / 2048) % 32 * 255 / 31), + floor(floor(p / 64) % 32 * 255 / 31), + floor(floor(p / 2) % 32 * 255 / 31), + (p % 2 == 1) and 255 or 0 +end + +-- (w, h, RGBA8 string) for the N64 texture formats these models use. +local function decodeTexture(f, tex, tlut, palette) + local w, h, fmt, siz, addr = tex.w, tex.h, tex.fmt, tex.siz, tex.data + local n = w * h + if n <= 0 or addr == nil then + return w, h, string.rep("\255\0\255\255", n > 0 and n or 0) + end + local d = f.d + local out = {} + + local function nibble(i) + local v = byte(d, addr + floor(i / 2) + 1) + if i % 2 == 1 then return v % 16 end + return floor(v / 16) + end + + if fmt == 0 and siz == 2 then -- RGBA16 (5/5/5/1) + for i = 0, n - 1 do + local a, b = byte(d, addr + i * 2 + 1, addr + i * 2 + 2) + out[i + 1] = char(rgba5551(a * 256 + b)) + end + elseif fmt == 0 and siz == 3 then -- RGBA32 + return w, h, sub(d, addr + 1, addr + n * 4) + elseif fmt == 2 then -- CI4 / CI8 + local pal, np = {}, 0 + if tlut ~= nil and tlut.data ~= nil then + local base = tlut.data + (siz == 0 and palette * 16 * 2 or 0) + np = (siz == 0) and 16 or 256 + for i = 0, np - 1 do + local a, b = byte(d, base + i * 2 + 1, base + i * 2 + 2) + pal[i + 1] = char(rgba5551(a * 256 + b)) + end + end + if np == 0 then + np = 256 + for i = 1, np do pal[i] = "\255\0\255\255" end + end + for i = 0, n - 1 do + local idx = (siz == 0) and nibble(i) or byte(d, addr + i + 1) + out[i + 1] = pal[idx % np + 1] + end + elseif fmt == 3 then -- IA16 / IA8 / IA4 + for i = 0, n - 1 do + local l, a + if siz == 2 then + local x, y = byte(d, addr + i * 2 + 1, addr + i * 2 + 2) + l, a = x, y + elseif siz == 1 then + local v = byte(d, addr + i + 1) + l, a = floor(v / 16) * 17, v % 16 * 17 + else + local v = nibble(i) + l, a = floor(floor(v / 2) * 255 / 7), (v % 2 == 1) and 255 or 0 + end + out[i + 1] = char(l, l, l, a) + end + elseif fmt == 4 then -- I8 / I4 + for i = 0, n - 1 do + local l = (siz == 1) and byte(d, addr + i + 1) or nibble(i) * 17 + out[i + 1] = char(l, l, l, 255) + end + else + for i = 0, n - 1 do out[i + 1] = "\255\0\255\255" end + end + return w, h, concat(out) +end + +StadiumFragment.decodeTexture = decodeTexture + +-- ------- the whole model + +-- Constant tracks collapse to a scalar; most channels never move, and that +-- fold is most of the reason the packed set is 34 megabytes rather than a +-- great deal more. +local function compress(values, n, nd) + local first = roundTo(values[1], nd) + for i = 2, n do + if roundTo(values[i], nd) ~= first then + local out = {} + for k = 1, n do out[k] = roundTo(values[k], nd) end + return out + end + end + return first +end + +-- Every distinct effect callback in the geo layout, once, in the order it +-- first appears -- see fragment.py's dedupe_fx for why the order is written +-- down rather than left to a hash table. +local function dedupeFx(nodes) + local seen, out = {}, {} + for i = 1, #nodes do + local node = nodes[i] + local key = node.bone .. "," .. node.callback .. "," .. tostring(node.arg) + if not seen[key] then + seen[key] = true + out[#out + 1] = { bone = node.bone, callback = node.callback, + arg = node.arg } + end + end + return out +end + +-- One decompressed archive entry -> the table StadiumBuild packs. Mirrors +-- fragment.extract, including which fields exist and what they are named. +function StadiumFragment.extract(data, name) + local frag, err = StadiumFragment.open(data, name) + if not frag then return nil, err end + local m, mErr = newModel(frag) + if not m then return nil, mErr end + m:build() + + local auxAnims = {} + for i = 1, #m.auxAnims do auxAnims[i] = newAux(frag, m.auxAnims[i]) end + + local texIndexMap, texOut = {}, {} + + local function register(texIdx, tlut, pal) + local key = texIdx .. "," .. tlut .. "," .. pal + local hit = texIndexMap[key] + if hit ~= nil then return hit end + if texIdx < 0 or texIdx >= #m.textures then return -1 end + local slot = #texOut -- 0-based, as the file + texIndexMap[key] = slot + local tl = (tlut >= 0 and tlut < #m.tluts) and m.tluts[tlut + 1] or nil + local w, h, rgba = decodeTexture(frag, m.textures[texIdx + 1], tl, pal) + texOut[slot + 1] = { index = texIdx, w = w, h = h, rgba = rgba } + return slot + end + + -- an animated material can swap to any texture its channel names, so all of + -- them have to be decoded up front + for _, p in ipairs(m.prims) do + if p.ntris > 0 then + local pal = m:tilePalette(p.mat) + register(p.tex, p.tlut, pal) + if p.texAnim >= 0 then + for _, a in ipairs(auxAnims) do + local tr, tn = a:track(p.texAnim) + local vals, vn = unique(tr, tn) + for i = 1, vn do register(vals[i], p.tlut, pal) end + end + end + end + end + + local prims = {} + for _, p in ipairs(m.prims) do + if p.ntris > 0 then + local pal = m:tilePalette(p.mat) + local ti = texIndexMap[p.tex .. "," .. p.tlut .. "," .. pal] or -1 + -- texture-table index -> slot in texOut, for the animated swap + local texMap = nil + if p.texAnim >= 0 then + for _, a in ipairs(auxAnims) do + local tr, tn = a:track(p.texAnim) + local vals, vn = unique(tr, tn) + for i = 1, vn do + local slot = texIndexMap[vals[i] .. "," .. p.tlut .. "," .. pal] + if slot ~= nil then + texMap = texMap or {} + texMap[vals[i]] = slot + end + end + end + end + local tw, th = 32, 32 + if ti >= 0 then + tw, th = m.textures[p.tex + 1].w, m.textures[p.tex + 1].h + end + local pos, uv, nrm, skin, idx = {}, {}, {}, {}, {} + for i = 1, p.nverts do + local v = p.verts[i] + pos[i * 3 - 2], pos[i * 3 - 1], pos[i * 3] = v[1], v[2], v[3] + uv[i * 2 - 1] = (v[4] / 32.0) / tw + uv[i * 2] = (v[5] / 32.0) / th + nrm[i * 3 - 2] = v[6] / 127.0 + nrm[i * 3 - 1] = v[7] / 127.0 + nrm[i * 3] = v[8] / 127.0 + skin[i] = v[10] + end + local ni = 0 + for i = 1, p.ntris do + local tri = p.tris[i] + idx[ni + 1], idx[ni + 2], idx[ni + 3] = tri[1], tri[2], tri[3] + ni = ni + 3 + end + prims[#prims + 1] = { + tex = ti, cull = p.cull, texAnim = p.texAnim, texMap = texMap, + pos = pos, uv = uv, nrm = nrm, skin = skin, nverts = p.nverts, + idx = idx, nidx = ni, + } + end + end + + local anims = {} + for i = 1, #m.anims do + local a = newAnim(frag, m.anims[i]) + local nf = a.nFrames > 1 and a.nFrames or 1 + local tracks = {} + for bi = 1, #m.bones do + local b = m.bones[bi] + local ch = b.chan + if ch >= 0 and a:sampleTrs(ch, 0, b.t, b.r, b.s) ~= nil then + local ts, rs, ss = {}, {}, {} + for k = 1, 3 do ts[k], rs[k], ss[k] = {}, {}, {} end + for fr = 0, nf - 1 do + local t, r, s = a:sampleTrs(ch, fr, b.t, b.r, b.s) + for k = 1, 3 do + ts[k][fr + 1], rs[k][fr + 1], ss[k][fr + 1] = t[k], r[k], s[k] + end + end + tracks[bi] = { + t = { compress(ts[1], nf, 3), compress(ts[2], nf, 3), + compress(ts[3], nf, 3) }, + r = { compress(rs[1], nf, 0), compress(rs[2], nf, 0), + compress(rs[3], nf, 0) }, + s = { compress(ss[1], nf, 5), compress(ss[2], nf, 5), + compress(ss[3], nf, 5) }, + } + end + end + anims[i] = { index = i - 1, frames = nf, flags = a.flags, + channels = a.nChannels, loopStart = a.loopStart, + tracks = tracks } + end + + local auxOut = {} + for i = 1, #auxAnims do + local a = auxAnims[i] + local chans = {} + for c = 0, a.nChannels - 1 do + local tr, tn = a:track(c) + tr.n = tn + chans[c + 1] = tr + end + auxOut[i] = { index = i - 1, frames = a.nFrames > 1 and a.nFrames or 1, + flags = a.flags, loopStart = a.loopStart, channels = chans } + end + + return { + species = m.species, + file = name, + rootScale = m.rootScale, + bones = m.bones, + textures = texOut, + prims = prims, + anims = anims, + auxAnims = auxOut, + fx = dedupeFx(m.fx), + warnings = m.warnings, + } +end + +return StadiumFragment diff --git a/lib/StadiumFx.lua b/lib/StadiumFx.lua new file mode 100644 index 0000000..1f60de4 --- /dev/null +++ b/lib/StadiumFx.lua @@ -0,0 +1,436 @@ +-- STADIUM battles: the generated fire and gas stand-ins. +-- +-- A port of model_extract/pipeline/effects.py, plus the bind-pose measurement +-- build.py sizes them against. +-- +-- IMPORTANT: nothing here is extracted game data. The real tail flame, mane +-- fire and gas are drawn by procedural callbacks that live in a different +-- fragment -- geo command 0x08 records an attachment point and +-- func_80014A60 calls node->unk_10, and the model file supplies only two +-- empty display lists plus zeroed scratch buffers for it to fill. Those +-- callbacks have not been ported, so the models genuinely contain no flame +-- mesh and no flame texture: Charmander's texture set is eyes, claws, teeth +-- and skin. +-- +-- What follows is an ORIGINAL, procedurally generated replacement -- looping +-- flipbook noise on a pair of crossed quads, anchored to the exact bone the +-- callback hangs off so it sits where the real effect would and follows the +-- animation. Seeds derive from the species number, so a given Pokemon always +-- generates the same flame. +-- +-- Which species get one is the game's own grouping: every species sharing a +-- callback shares an effect. +-- +-- 0x810000D8 Charmander, Charmeleon, Charizard, Magmar, Moltres tail flame +-- 0x81000108 Ponyta, Rapidash, Moltres's wings small flame +-- 0x810000E0 Gastly (only) gas cloud + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumFx = {} + +local floor = math.floor +local sqrt = math.sqrt +local sin, cos = math.sin, math.cos +local char = string.char +local concat = table.concat +local pi = math.pi + +local FIRE_TAIL = 0x810000D8 +local FIRE_SMALL = 0x81000108 +local AURA = 0x810000E0 + +-- Desired size as a fraction of the model's world-space height: length, width. +StadiumFx.SIZES = { + fire_tail = { 0.40, 0.22 }, + fire_small = { 0.075, 0.042 }, + gas = { 1.05, 1.05 }, +} + +-- ------- 32-bit exclusive-or, in arithmetic +-- +-- The generator below is an xorshift, so it needs a real 32-bit xor and a +-- real 32-bit wrap. Written out rather than taken from LuaJIT's `bit`, which +-- works in SIGNED 32-bit and would need converting back on every step -- see +-- the same note in StadiumFragment. + +local function bxor32(a, b) + local r, p = 0, 1 + for _ = 1, 32 do + local x, y = a % 2, b % 2 + if x ~= y then r = r + p end + a, b, p = floor(a / 2), floor(b / 2), p * 2 + end + return r +end + +-- ------- deterministic noise + +local Rng = {} +Rng.__index = Rng + +local function newRng(seed) + local s = seed % 0x100000000 + if s == 0 then s = 0x9E3779B9 end + return setmetatable({ s = s }, Rng) +end + +function Rng:next() + local x = self.s + x = bxor32(x, (x % 0x80000) * 0x2000) -- x ^= (x << 13) + x = bxor32(x, floor(x / 0x20000)) -- x ^= x >> 17 + x = bxor32(x, (x % 0x8000000) * 0x20) -- x ^= (x << 5) + self.s = x % 0x100000000 + return self.s +end + +function Rng:unit() + return self:next() / 0x100000000 +end + +-- A w-by-h lattice of unit noise, consumed row by row so the sequence -- and +-- therefore the texture -- is reproducible. +local function lattice(rng, w, h) + local g = {} + for y = 1, h do + local row = {} + for x = 1, w do row[x] = rng:unit() end + g[y] = row + end + return g +end + +local function smooth(t) + return t * t * (3 - 2 * t) +end + +-- Bilinear value noise on a torus, so the field tiles in both axes. +local function sample(grid, x, y) + local h = #grid + local w = #grid[1] + local fx0, fy0 = floor(x), floor(y) + local x0, y0 = fx0 % w, fy0 % h + local x1, y1 = (x0 + 1) % w, (y0 + 1) % h + local fx, fy = smooth(x - fx0), smooth(y - fy0) + local r0, r1 = grid[y0 + 1], grid[y1 + 1] + local a = r0[x0 + 1] + (r0[x1 + 1] - r0[x0 + 1]) * fx + local b = r1[x0 + 1] + (r1[x1 + 1] - r1[x0 + 1]) * fx + return a + (b - a) * fy +end + +-- Sum octaves of tileable noise. +local function fbm(grids, x, y, scale) + local total, amp, norm = 0.0, 1.0, 0.0 + for i = 1, #grids do + local f = scale * 2 ^ (i - 1) + total = total + sample(grids[i], x * f, y * f) * amp + norm = norm + amp + amp = amp * 0.5 + end + return total / norm +end + +-- Intensity -> RGBA, through a piecewise ramp. +local function ramp(stops, t) + if t < 0.0 then t = 0.0 elseif t > 1.0 then t = 1.0 end + for i = 1, #stops - 1 do + local a, b = stops[i], stops[i + 1] + if t <= b[1] then + local k = 0.0 + if b[1] ~= a[1] then k = (t - a[1]) / (b[1] - a[1]) end + return floor(a[2] + (b[2] - a[2]) * k), floor(a[3] + (b[3] - a[3]) * k), + floor(a[4] + (b[4] - a[4]) * k), floor(a[5] + (b[5] - a[5]) * k) + end + end + local last = stops[#stops] + return last[2], last[3], last[4], last[5] +end + +local FIRE_RAMP = { + { 0.00, 0, 0, 0, 0 }, + { 0.30, 120, 24, 8, 90 }, + { 0.52, 226, 78, 16, 205 }, + { 0.74, 252, 176, 44, 245 }, + { 1.00, 255, 246, 214, 255 }, +} + +local GAS_RAMP = { + { 0.00, 0, 0, 0, 0 }, + { 0.34, 52, 26, 78, 70 }, + { 0.60, 96, 52, 140, 140 }, + { 0.82, 148, 96, 196, 190 }, + { 1.00, 208, 176, 236, 215 }, +} + +local TRANSPARENT = char(0, 0, 0, 0) + +-- An upward-advected noise plume. Scrolling by an exact multiple of the +-- lattice over the frame count is what makes the loop seamless. +local function fireFrames(seed, w, h, frames, wisp) + wisp = wisp or 1.0 + local rng = newRng(seed) + local grids = { lattice(rng, 8, 8), lattice(rng, 16, 16), + lattice(rng, 32, 32) } + local out = {} + for f = 0, frames - 1 do + local t = f / frames + local buf = {} + for i = 1, w * h do buf[i] = TRANSPARENT end + for y = 0, h - 1 do + local v = y / (h - 1) -- 0 at the base, 1 at the tip + -- plume envelope: wide and hot at the base, pinched at the tip + local taper = 1.0 - v + if taper < 0.0 then taper = 0.0 end + taper = taper ^ 0.42 + for x = 0, w - 1 do + local u = (x / (w - 1)) * 2 - 1 -- -1 .. 1 across the flame + local denom = taper * 0.95 + if denom < 0.10 then denom = 0.10 end + local radial = 1.0 - (u < 0 and -u or u) / denom + if radial > 0 then + radial = radial ^ 0.7 + local n = fbm(grids, x / w, (y / h) - t, 3.0) + local lick = 0.55 + 0.75 * (n - 0.5) * wisp + local inten = radial * (0.55 + 0.8 * taper) * lick + inten = inten - 0.16 * v -- cool towards the tip + if inten > 0.02 then + local r, g, b, a = ramp(FIRE_RAMP, inten) + -- +Y in texture space is up + buf[(h - 1 - y) * w + x + 1] = char(r, g, b, a) + end + end + end + end + out[f + 1] = concat(buf) + end + return w, h, out +end + +-- Slow swirling haze that fades out towards the rim. +local function gasFrames(seed, w, h, frames) + local rng = newRng(seed) + local grids = { lattice(rng, 8, 8), lattice(rng, 16, 16), + lattice(rng, 32, 32) } + local out = {} + for f = 0, frames - 1 do + local t = f / frames + local buf = {} + for i = 1, w * h do buf[i] = TRANSPARENT end + local ang = t * 2 * pi + local ca, sa = cos(ang), sin(ang) + for y = 0, h - 1 do + for x = 0, w - 1 do + local dx = (x / (w - 1)) * 2 - 1 + local dy = (y / (h - 1)) * 2 - 1 + local d = sqrt(dx * dx + dy * dy) + if d < 1.0 then + local falloff = (1.0 - d) ^ 0.85 + -- rotate the sample point so the haze churns without popping + local sx = dx * ca - dy * sa + local sy = dx * sa + dy * ca + local n = fbm(grids, sx * 0.5 + 0.5, sy * 0.5 + 0.5 - t, 2.5) + local inten = falloff * (0.78 + 1.30 * (n - 0.44)) + if inten > 0.03 then + local r, g, b, a = ramp(GAS_RAMP, inten) + buf[y * w + x + 1] = char(r, g, b, a) + end + end + end + end + out[f + 1] = concat(buf) + end + return w, h, out +end + +-- Two quads at right angles, so the effect reads from any angle. `axis` picks +-- which bone-local direction the quad grows along: bone-local +X runs down the +-- limb, so a flame laid out along X comes out lying sideways, and 'y' is that +-- same quad turned a quarter left about Z, which stands it up. `centred` +-- straddles the origin instead of growing from it. +local function crossedQuads(bone, length, width, axis, centred) + local pos, uv, nrm, skin, idx = {}, {}, {}, {}, {} + local ST = { { 0, 0 }, { 1, 0 }, { 1, 1 }, { 0, 1 } } + local nv, ni = 0, 0 + for q = 0, 1 do + local base = nv + for k = 1, 4 do + local s, t = ST[k][1], ST[k][2] + local a = (s - 0.5) * width + local b = centred and (t - 0.5) * length or t * length + local px, py, pz + if axis == "x" then + if q == 0 then px, py, pz = b, a, 0.0 else px, py, pz = b, 0.0, a end + else -- (x, y) -> (-y, x) + if q == 0 then px, py, pz = -a, b, 0.0 else px, py, pz = 0.0, b, a end + end + pos[nv * 3 + 1], pos[nv * 3 + 2], pos[nv * 3 + 3] = px, py, pz + uv[nv * 2 + 1], uv[nv * 2 + 2] = s, 1.0 - t + if q == 0 then + nrm[nv * 3 + 1], nrm[nv * 3 + 2], nrm[nv * 3 + 3] = 0.0, 0.0, 1.0 + else + nrm[nv * 3 + 1], nrm[nv * 3 + 2], nrm[nv * 3 + 3] = 1.0, 0.0, 0.0 + end + skin[nv + 1] = bone + nv = nv + 1 + end + idx[ni + 1], idx[ni + 2], idx[ni + 3] = base, base + 1, base + 2 + idx[ni + 4], idx[ni + 5], idx[ni + 6] = base, base + 2, base + 3 + ni = ni + 6 + end + return { pos = pos, uv = uv, nrm = nrm, skin = skin, nverts = nv, + idx = idx, nidx = ni } +end + +-- ------- the bind pose these are sized against +-- +-- build.py's bind_extent, kept in its own 4x4 column-major convention rather +-- than folded into StadiumBuild's 3x4 walk. The two agree -- they are the +-- same skeleton -- but the effect sizes come out of THIS one's per-bone scale +-- measurement, and rewriting it into the other convention is exactly the kind +-- of change that moves a byte without anyone noticing. + +local function trs(t, r, s) + local function S(v) return sin(v / 32768 * pi) end + local function C(v) return cos(v / 32768 * pi) end + local sx, cx = S(r[1]), C(r[1]) + local sy, cy = S(r[2]), C(r[2]) + local sz, cz = S(r[3]), C(r[3]) + return { cy * cz * s[1], cy * sz * s[1], -sy * s[1], 0, + (sx * sy * cz - cx * sz) * s[2], (sx * sy * sz + cx * cz) * s[2], + sx * cy * s[2], 0, + (cx * sy * cz + sx * sz) * s[3], (cx * sy * sz - sx * cz) * s[3], + cx * cy * s[3], 0, + t[1], t[2], t[3], 1 } +end + +local function mul(a, b) + local r = {} + for c = 0, 3 do + for i = 1, 4 do + r[c * 4 + i] = a[i] * b[c * 4 + 1] + a[4 + i] * b[c * 4 + 2] + + a[8 + i] * b[c * 4 + 3] + a[12 + i] * b[c * 4 + 4] + end + end + return r +end + +-- (height of the bind pose, per-bone local scale). Height rather than the +-- largest dimension: sizing off the max would scale Moltres's flames to its +-- wingspan. +function StadiumFx.bindExtent(data) + local root = trs({ 0, 0, 0 }, { 0, 0, 0 }, data.rootScale) + local acc, uns, mats = {}, {}, {} + for i = 1, #data.bones do + local b = data.bones[i] + local p = b.parent + local pa = (p >= 0) and acc[p + 1] or { 1.0, 1.0, 1.0 } + local pu = (p >= 0) and uns[p + 1] or root + local u = mul(pu, trs({ b.t[1] * pa[1], b.t[2] * pa[2], b.t[3] * pa[3] }, + b.r, { 1, 1, 1 })) + local a = { pa[1] * b.s[1], pa[2] * b.s[2], pa[3] * b.s[3] } + local m = {} + for k = 1, 16 do m[k] = u[k] end + for k = 1, 4 do + m[k] = m[k] * a[1] + m[4 + k] = m[4 + k] * a[2] + m[8 + k] = m[8 + k] * a[3] + end + acc[i], uns[i], mats[i] = a, u, m + end + + local lo = { 1e9, 1e9, 1e9 } + local hi = { -1e9, -1e9, -1e9 } + for _, prim in ipairs(data.prims) do + local pos, skin = prim.pos, prim.skin + for i = 1, prim.nverts do + local m = mats[skin[i] + 1] + if m then + local x, y, z = pos[i * 3 - 2], pos[i * 3 - 1], pos[i * 3] + local wx = m[1] * x + m[5] * y + m[9] * z + m[13] + local wy = m[2] * x + m[6] * y + m[10] * z + m[14] + local wz = m[3] * x + m[7] * y + m[11] * z + m[15] + if wx < lo[1] then lo[1] = wx end + if wy < lo[2] then lo[2] = wy end + if wz < lo[3] then lo[3] = wz end + if wx > hi[1] then hi[1] = wx end + if wy > hi[2] then hi[2] = wy end + if wz > hi[3] then hi[3] = wz end + end + end + end + local extent = (lo[1] <= hi[1]) and (hi[2] - lo[2]) or 1.0 + + -- how much each bone scales its own local space, so an effect can divide it + -- back out and come out the size it asked for wherever it hangs + local scales = {} + for i = 1, #mats do + local m = mats[i] + scales[i] = sqrt(m[1] * m[1] + m[2] * m[2] + m[3] * m[3]) + end + return extent, scales +end + +-- ------- what a species gets + +-- Returns a list of { kind, bone, geo, w, h, frames }, or an empty list. +function StadiumFx.buildFor(species, fx, extent, boneScale) + local out = {} + for _, node in ipairs(fx) do + local cb, bone = node.callback, node.bone + if bone >= 0 and bone < #boneScale then + local k = boneScale[bone + 1] + if k == 0 then k = 1.0 end + if cb == FIRE_TAIL then + local fl, fw = StadiumFx.SIZES.fire_tail[1], StadiumFx.SIZES.fire_tail[2] + local w, h, fr = fireFrames(species * 7919 + 1, 32, 64, 8) + out[#out + 1] = { kind = "fire", bone = bone, w = w, h = h, frames = fr, + geo = crossedQuads(bone, extent * fl / k, + extent * fw / k, "y", false) } + elseif cb == FIRE_SMALL then + local fl, fw = StadiumFx.SIZES.fire_small[1], + StadiumFx.SIZES.fire_small[2] + local w, h, fr = fireFrames(species * 6271 + bone, 24, 40, 8, 1.25) + out[#out + 1] = { kind = "fire", bone = bone, w = w, h = h, frames = fr, + geo = crossedQuads(bone, extent * fl / k, + extent * fw / k, "y", false) } + elseif cb == AURA and species == 92 then -- Gastly only + local fl, fw = StadiumFx.SIZES.gas[1], StadiumFx.SIZES.gas[2] + local w, h, fr = gasFrames(species * 5237 + 3, 48, 48, 10) + out[#out + 1] = { kind = "gas", bone = bone, w = w, h = h, frames = fr, + geo = crossedQuads(bone, extent * fl / k, + extent * fw / k, "y", true) } + end + end + end + return out +end + +-- Append the generated prims and their flipbook textures to a model, exactly +-- as build.py's attach_effects does. Returns how many were made. +function StadiumFx.attach(data, species) + if not (data.fx and #data.fx > 0) then return 0 end + local extent, boneScale = StadiumFx.bindExtent(data) + local made = StadiumFx.buildFor(species, data.fx, extent, boneScale) + for _, e in ipairs(made) do + local first = #data.textures -- 0-based, as the file + for i = 1, #e.frames do + data.textures[first + i] = { index = -1, w = e.w, h = e.h, + generated = true, rgba = e.frames[i] } + end + local g = e.geo + local fxFrames = {} + for i = 1, #e.frames do fxFrames[i] = first + i - 1 end + data.prims[#data.prims + 1] = { + tex = first, cull = 0, texAnim = -1, texMap = nil, + generated = true, effect = e.kind, + blend = (e.kind == "fire") and "add" or "alpha", + fxFrames = fxFrames, + pos = g.pos, uv = g.uv, nrm = g.nrm, skin = g.skin, nverts = g.nverts, + idx = g.idx, nidx = g.nidx, + } + end + return #made +end + +return StadiumFx diff --git a/lib/StadiumInstall.lua b/lib/StadiumInstall.lua new file mode 100644 index 0000000..1314e4b --- /dev/null +++ b/lib/StadiumInstall.lua @@ -0,0 +1,261 @@ +-- STADIUM battles: finding the ROM, and building the models out of it once. +-- +-- The mod does not ship the Pokemon Stadium models and cannot: they are that +-- game's data. What it ships is the READER -- StadiumRom, StadiumFragment, +-- StadiumFx and StadiumBuild -- and the player supplies the cartridge, which +-- is exactly the arrangement this engine already has for the Game Boy ROM it +-- is a recompilation of (src/import/RomImporter.lua). +-- +-- So: drop a Pokemon Stadium (US) ROM in `baseroms/`, and the first time the +-- game runs with the mod on, the models are built. Once, on a loading screen, +-- in about ten seconds. After that the packs sit in the save directory and +-- the mod reads them like any other asset. +-- +-- ------- where "baseroms/" is +-- +-- One relative path, and it deliberately covers two different places at once, +-- because PhysFS searches the save directory AND the game folder under the +-- same names: +-- +-- * a folder install, or a checkout -- `baseroms/` next to main.lua, which +-- is also where the decompilation's own `make init` puts it +-- * a packaged or fused build, where the game folder is inside an archive +-- and cannot be written to -- `baseroms/` in the save directory, whose +-- absolute path this reports on screen so it can be found +-- +-- Any of `.z64`, `.n64` and `.v64` is accepted; StadiumRom normalises the +-- byte order on load. +-- +-- ------- what "installed" means +-- +-- A marker file next to the packs, holding the format magic, how many species +-- were written and the md5 of the ROM they came from. All three matter. The +-- magic catches a format change (the packs are rebuilt rather than read as +-- garbage), the count catches a build that was interrupted half way, and the +-- md5 catches the player swapping the ROM for a different revision. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumPack = V.require("StadiumPack") + +local StadiumInstall = {} + +-- Where a ROM is looked for, and where the built packs are kept. +StadiumInstall.ROM_DIR = "baseroms" +StadiumInstall.DIR = StadiumPack.CACHE_DIR +StadiumInstall.MARKER = StadiumInstall.DIR .. "/pack.info" + +-- Bumped whenever the .dsm format changes, so an old cache is rebuilt rather +-- than misread. Must track StadiumPack's magic. +StadiumInstall.FORMAT = "DSM3" + +StadiumInstall.COUNT = 151 + +-- Named ROM files, in the order the decompilation's own pipeline looks for +-- them, then any ROM at all sitting in the folder. +local NAMED = { + StadiumInstall.ROM_DIR .. "/baserom.z64", + StadiumInstall.ROM_DIR .. "/us/baserom.z64", + StadiumInstall.ROM_DIR .. "/baserom.n64", + StadiumInstall.ROM_DIR .. "/baserom.v64", +} + +local function fs() + return love and love.filesystem +end + +local function isFile(path) + local f = fs() + if not (f and f.getInfo) then return false end + local ok, info = pcall(f.getInfo, path, "file") + return (ok and info) and true or false +end + +-- The ROM's path on the PhysFS read path, or nil. +function StadiumInstall.romPath() + local f = fs() + if not f then return nil end + for _, path in ipairs(NAMED) do + if isFile(path) then return path end + end + local ok, items = pcall(f.getDirectoryItems, StadiumInstall.ROM_DIR) + if ok and items then + table.sort(items) + for _, name in ipairs(items) do + if name:lower():match("%.[nvz]64$") then + local path = StadiumInstall.ROM_DIR .. "/" .. name + if isFile(path) then return path end + end + end + end + return nil +end + +function StadiumInstall.romPresent() + return StadiumInstall.romPath() ~= nil +end + +-- Where to tell the player to put it. The save directory is the answer that +-- is always writable, and it is the one a packaged build needs. +function StadiumInstall.romHint() + local f = fs() + local base = (f and f.getSaveDirectory and select(2, pcall(f.getSaveDirectory))) + if type(base) ~= "string" then base = "the game folder" end + return base .. "/" .. StadiumInstall.ROM_DIR +end + +-- ------- the marker + +local function readMarker() + local f = fs() + if not (f and isFile(StadiumInstall.MARKER)) then return nil end + local ok, text = pcall(f.read, StadiumInstall.MARKER) + if not (ok and type(text) == "string") then return nil end + local format, count, md5 = text:match("^(%S+)%s+(%d+)%s*(%S*)") + if not format then return nil end + return { format = format, count = tonumber(count), md5 = md5 } +end + +-- Whether a complete, current set of packs is on disk. +local readyCache = nil + +function StadiumInstall.ready() + if readyCache ~= nil then return readyCache end + local m = readMarker() + readyCache = (m ~= nil and m.format == StadiumInstall.FORMAT + and m.count == StadiumInstall.COUNT) and true or false + return readyCache +end + +-- Whether a complete set came WITH the mod folder -- a developer checkout +-- that has run tools/stadium_pack.py. Never true of a released build, which +-- carries no models at all. +-- +-- Sampled at both ends of the dex rather than counted. The question being +-- asked is "did somebody run the packer here", not "is every one of the 151 +-- present"; a genuinely half-written folder is a case for the marker file, +-- which is what catches an interrupted RUNTIME build. +local function shipped() + local mod = V.mod + if not (mod and mod.read) then return false end + for _, dex in ipairs({ 1, 151 }) do + local ok, bytes = pcall(mod.read, mod, + ("%s/%03d.dsm"):format(StadiumPack.DIR, dex)) + if not (ok and type(bytes) == "string" and #bytes > 4) then return false end + end + return true +end + +-- Whether the STADIUM rungs can be offered at all: either the packs have been +-- built from the player's ROM, or the mod folder already carries a set. +function StadiumInstall.available() + if StadiumInstall.ready() then return true end + return shipped() +end + +-- Whether there is work to do: something to build from, and nothing usable +-- yet. +-- +-- A checkout that already carries a set is NOT pending. Building anyway would +-- be correct and would also mean a ten-second loading screen on the first run +-- of every checkout, to arrive at the files that were already sitting there. +function StadiumInstall.pending() + if StadiumInstall.available() then return false end + return StadiumInstall.romPresent() +end + +function StadiumInstall.forget() + readyCache = nil +end + +-- ------- building + +local job = nil +local status = { state = "idle", done = 0, total = StadiumInstall.COUNT } + +StadiumInstall.status = status + +local function writePack(species, bytes) + local f = fs() + if not f then return false, "no filesystem" end + local ok, err = f.write(("%s/%03d.dsm"):format(StadiumInstall.DIR, species), + bytes) + if not ok then return false, tostring(err) end + return true +end + +-- Open the ROM and start a stepped build. Returns false plus a reason when +-- there is nothing to build from. +function StadiumInstall.begin() + local f = fs() + if not f then return false, "no filesystem" end + local path = StadiumInstall.romPath() + if not path then return false, "no ROM in " .. StadiumInstall.ROM_DIR end + + local okRead, bytes = pcall(f.read, path) + if not (okRead and type(bytes) == "string") then + return false, "could not read " .. path + end + + local StadiumRom = V.require("StadiumRom") + local StadiumBuild = V.require("StadiumBuild") + local rom, err = StadiumRom.open(bytes) + if not rom then return false, tostring(err) end + if not rom:isExpectedUS() then + V.mod.log:warn("stadium: %s is md5 %s, not the US 1.0 ROM the model " + .. "offsets are keyed to -- building anyway", path, + tostring(rom:md5())) + end + + pcall(f.createDirectory, StadiumInstall.DIR) + job = StadiumBuild.job(rom, writePack, StadiumInstall.COUNT) + job.md5 = rom:md5() + status.state = "building" + status.done = 0 + status.total = job.total + status.error = nil + return true +end + +-- One species. Returns true while there is more to do. +function StadiumInstall.step() + if not job then return false end + local more = job:step() + status.done = job.done + status.species = job.species + if job.error then + status.state = "failed" + status.error = job.error + job = nil + return false + end + if not more then + local f = fs() + local wrote = #job.failed == 0 + if wrote and f then + pcall(f.write, StadiumInstall.MARKER, + ("%s %d %s\n"):format(StadiumInstall.FORMAT, job.total, + tostring(job.md5 or ""))) + readyCache = nil + StadiumPack.forget() + end + if not wrote then + status.state = "failed" + status.error = ("%d of %d models could not be built") + :format(#job.failed, job.total) + else + status.state = "done" + end + job = nil + return false + end + return true +end + +function StadiumInstall.cancel() + job = nil + status.state = "idle" +end + +return StadiumInstall diff --git a/lib/StadiumMon.lua b/lib/StadiumMon.lua new file mode 100644 index 0000000..7374aa9 --- /dev/null +++ b/lib/StadiumMon.lua @@ -0,0 +1,350 @@ +-- STADIUM battles: one Pokemon, standing on its tile. +-- +-- The side's live state -- which species is out, the rig posing it, which +-- animation the fight has asked for and how far through it is, and the +-- matrix that puts it on its cell at the right size facing the right way. +-- Stadium owns the pair of these; StadiumRig owns the arithmetic. +-- +-- ------- how big a Pokemon is +-- +-- The one genuinely invented number in this mode, and it is worth saying +-- why it is invented rather than measured. +-- +-- The flat 2D-3D mode has an exact answer: a full-size 56-pixel pic covers +-- one 16-pixel overworld square, so a canvas pixel is a fixed number of +-- world pixels and every species comes out at whatever its own artwork's +-- size implies (see BattleBillboard.FULL_W). The camera is then SOLVED to +-- make one square that big on screen (BattleCam). +-- +-- The Stadium models have no such anchor. Their units are the N64's, they +-- run from Caterpie at 9 units to Gyarados at 147 -- a sixteenfold spread, +-- where the Gen 1 pics span barely one and a half -- and the game they come +-- from framed each one with its own camera, which a fight staged on the +-- overworld cannot do because the two mons share a shot. +-- +-- Taken literally, that spread puts Caterpie at a couple of pixels on a +-- 144-pixel screen while Gyarados leaves the frame. So the range is +-- COMPRESSED rather than either honoured or discarded: a species is drawn +-- at REF_HEIGHT world pixels scaled by its own height over the set's +-- median, raised to SQUASH. At 1 that would be the raw sixteenfold spread; +-- at 0 every Pokemon would be the same size; at 0.55 the order and the +-- feel of the differences survive -- Onix and Gyarados tower, Diglett and +-- Caterpie are small enough to have to look for -- inside a range a shared +-- frame can hold. +-- +-- ------- and where its feet are +-- +-- The pack measures each model's lowest point against its own origin +-- (tools/stadium_pack.py's `stance`), and the answer splits the set in +-- three. 119 species sit within 5% of zero: the origin IS the floor, and +-- the game stood them on its field with it. A handful sit ABOVE it -- +-- Zubat, Magnemite, Geodude -- which is a hover the model is authored with. +-- The rest hang BELOW it -- Tentacruel, Gastly, Haunter, Weezing, Zapdos -- +-- which is a model centred on its origin rather than standing on it. +-- +-- So a model is stood on its own lowest point, and then given back as much +-- of its authored hover as the shot can hold -- HOVER_CAP of its own height, +-- no more. The middle group is unaffected either way, which is the check +-- that the rule is reading the data rather than correcting it. +-- +-- The cap is not tidiness. Stadium framed one Pokemon per camera and could +-- afford to hang Zubat three body-heights off the floor; this shot has the +-- foe's feet on GB row 56 of 144, so the same hover puts Zubat off the top +-- of the frame entirely -- which is exactly what it did before the cap. The +-- flat 2D-3D mode has the same constraint and answers it by bottom-aligning +-- every pic, hovering species included; this keeps the hover but spends +-- only the room there is. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local Mat4 = V.require("Mat4") +local StadiumPack = V.require("StadiumPack") +local StadiumRig = V.require("StadiumRig") + +local StadiumMon = {} +StadiumMon.__index = StadiumMon + +-- How tall a median Pokemon stands, in world pixels. +-- +-- Not picked by eye: it is what the FLAT mode already puts on those cells. +-- A full-size Gen 1 pic is 56 pixels for the foe and 64 for the player's +-- own, drawn with its feet on GB rows 56 and 96 of a 144-row frame -- so a +-- full-size mon covers 39% of the frame at the far cell and 44% at the near +-- one. Against the lens BattleCam solves (about 38 world pixels of frame at +-- the far cell, 30 at the near one, because the near one is closer) both of +-- those work out at roughly fourteen world pixels. +-- +-- So this is the number that makes a median Stadium model exactly as big as +-- the artwork it replaces, which is what keeps the composition the camera +-- was solved for. +StadiumMon.REF_HEIGHT = 14 + +-- The set's own median bind height, in game units (tools/stadium_pack.py +-- --report prints it). Only ever a reference point for the ratio above, so +-- a re-extraction that moved it slightly changes nothing but the middle of +-- the ladder. +StadiumMon.MEDIAN = 52.25 + +-- How much of the raw size spread survives. See the header. +StadiumMon.SQUASH = 0.5 + +-- And hard stops either end, because a compression is not a guarantee. The +-- ceiling is what keeps Onix and Gyarados inside a frame whose top edge is +-- only 56 GB rows above the foe's own feet: past about this they stop being +-- imposing and start being cropped. +StadiumMon.MIN_HEIGHT = 5 +StadiumMon.MAX_HEIGHT = 18 + +-- How much of an authored hover survives, as a fraction of the Pokemon's +-- own height. See the header: Stadium could hang a flier three body-heights +-- up because it framed one Pokemon at a time. +StadiumMon.HOVER_CAP = 0.5 + +-- The animation clock. Every animation in the set is authored at 30 fps +-- (model_extract/README.md), and the eyes run on their own counter at the +-- same rate. +StadiumMon.FPS = StadiumPack.FPS + +-- ------- the animation the fight is asking for +-- +-- Each entry says which context slot to look up, whether it loops, and +-- what it falls back to when the species has no animation in that slot. +local STATES = { + idle = { slot = "idle", loop = true }, + entrance = { slot = "entrance", loop = false, next = "idle" }, + hit = { slot = "hit", loop = false, next = "idle" }, + flinch = { slot = "flinch", loop = false, next = "idle", fallback = "hit" }, + faint = { slot = "faint", loop = false, hold = true }, + -- an attack names its animation outright (the move table decides), so it + -- has no slot of its own + attack = { loop = false, next = "idle" }, +} + +function StadiumMon.new(side) + return setmetatable({ + side = side, -- "player" or "enemy" + species = nil, -- the dex number currently modelled + model = nil, + rig = nil, + state = "idle", + anim = nil, -- index into model.anims + time = 0, -- seconds into it + loop = true, + hold = false, + aux = nil, -- the texture animation running alongside + visible = false, + scale = 1, -- the send-out grow, 1 the rest of the time + }, StadiumMon) +end + +function StadiumMon:release() + if self.rig then self.rig:release() end + self.rig, self.model, self.species = nil, nil, nil +end + +-- ------- which species this side is showing +-- +-- Returns true when the model is ready to draw. A species with no pack, or +-- one whose meshes would not build, answers false -- and Stadium then +-- leaves that side to the flat card, which is a per-POKEMON decline rather +-- than a per-battle one: a fight can perfectly well have a model on one +-- side and a pic on the other. +function StadiumMon:setSpecies(dex) + if dex == self.species then return self.rig ~= nil end + if self.rig then self.rig:release() end + self.rig, self.model, self.species = nil, nil, dex + if not dex then return false end + local model = StadiumPack.load(dex) + if not model then return false end + local rig = StadiumRig.new(model) + if not rig then return false end + self.model, self.rig = model, rig + -- a new Pokemon on the field opens on its standby loop; whoever sent it + -- out asks for the entrance a moment later + self.state, self.anim, self.time = nil, nil, 0 + self:play("idle") + return true +end + +-- ------- the state machine + +-- Which animation a context slot resolves to for this species, or nil. +function StadiumMon:slotAnim(name) + local model = self.model + local slot = model and StadiumPack.SLOT[name] + if not slot then return nil end + local index = model.ctx[slot] + if not index or index == StadiumPack.NONE then return nil end + return index + 1 +end + +-- Start a state. `animIndex` overrides the state's own slot lookup, which +-- is what an attack uses. +function StadiumMon:play(state, animIndex, auxIndex) + local model = self.model + if not model then return false end + local def = STATES[state] or STATES.idle + local index = animIndex + if not index and def.slot then index = self:slotAnim(def.slot) end + if not index and def.fallback then index = self:slotAnim(def.fallback) end + if not index then + -- the species has nothing for this; the standby loop is always there + if state == "idle" then index = 1 else return self:play("idle") end + end + local anim = model.anims[index] + if not anim then return false end + + self.state, self.anim, self.time = state, index, 0 + -- A species whose animations are corrupt at source stands in its BIND + -- pose and does not move. The state machine still runs -- the fight is + -- still asking for a hit or a faint, and something may want to know -- + -- but nothing is ever sampled, so the Pokemon simply stands there + -- looking like itself, which is the one thing the broken data cannot do. + if model.staticPose then self.anim = nil end + self.loop = def.loop and true or false + self.hold = def.hold and true or false + -- The eyes that go with it. Every skeletal animation carries the texture + -- animation the battle table most often set alongside it (the pack's own + -- `aux`), and a move may name a different one -- a hit that leaves the + -- Pokemon confused swaps the open eye for the dizzy swirl. + self.aux = auxIndex or anim.aux + return true +end + +-- Ask for a state, but never interrupt one that outranks it. A faint is +-- final, and a hit reaction landing on top of an attack the Pokemon is +-- halfway through reads as the attack being cancelled -- which, on the +-- receiving end of a two-hit turn, it is not. +local RANK = { idle = 0, entrance = 1, attack = 2, hit = 3, flinch = 3, + faint = 4 } + +function StadiumMon:request(state, animIndex, auxIndex) + if not self.model then return false end + local now = RANK[self.state] or 0 + local want = RANK[state] or 0 + if self.state == "faint" then return false end + -- an equal-ranked request RESTARTS: a second hit in a turn should play + -- the flinch again rather than be swallowed by the first + if want < now then return false end + return self:play(state, animIndex, auxIndex) +end + +-- The animation a move plays for this species, from the battle system's own +-- per-species table (model_extract's moves.json, packed into the .dsm). +-- `moveIndex` is the Gen 1 move id, which the engine's move defs carry as +-- `index` -- the same numbering, so no name mapping is needed. +function StadiumMon:attack(moveIndex) + local model = self.model + if not (model and moveIndex and moveIndex >= 1 + and moveIndex <= StadiumPack.N_MOVES) then + return false + end + local index = model.moveAnim[moveIndex] + if not index or index == StadiumPack.NONE then return false end + local aux = model.moveAux[moveIndex] + return self:request("attack", index + 1, + (aux and aux >= 0) and (aux + 1) or nil) +end + +-- ------- per frame + +function StadiumMon:update(dt) + local model = self.model + if not (model and self.anim) then return end + local anim = model.anims[self.anim] + if not anim then return end + self.time = self.time + (dt or 0) + if self.time >= anim.seconds and not self.loop then + if self.hold then + -- a faint stays down: hold the last frame rather than snapping back + -- to a standing pose the moment the animation runs out + self.time = math.max(0, anim.seconds - 1 / StadiumMon.FPS) + else + local nextState = (STATES[self.state] or {}).next or "idle" + self:play(nextState) + end + end +end + +-- How tall this species stands on the map, in world pixels. +function StadiumMon:worldHeight() + local model = self.model + local h = model and model.height or 0 + if not (h > 0) then return StadiumMon.REF_HEIGHT end + local k = (h / StadiumMon.MEDIAN) ^ StadiumMon.SQUASH + local out = StadiumMon.REF_HEIGHT * k + if out < StadiumMon.MIN_HEIGHT then out = StadiumMon.MIN_HEIGHT end + if out > StadiumMon.MAX_HEIGHT then out = StadiumMon.MAX_HEIGHT end + return out +end + +-- How wide this Pokemon stands, in world pixels -- the same scale +-- worldHeight is in, so a caller can size something to its footprint. +-- +-- Only STADIUM B asks: it needs to know how big a platform to put under a +-- mon, and "as tall as it is" is the wrong answer for a Snorlax, which is +-- half as tall as an Onix and three times as wide. +-- +-- The send-out grow is deliberately NOT folded in. A Pokemon scaling up out +-- of its ball should arrive on a platform that was already there, not one +-- that inflates under its feet. +function StadiumMon:worldRadius() + local model = self.model + if not model then return 0 end + local h = model.height or 0 + if not (h > 0) then return 0 end + return (model.radius or 0) * self:worldHeight() / h +end + +-- The model matrix: stand this Pokemon on world (x, groundY, z) facing +-- (faceX, faceZ), at whatever the send-out grow has done to its size. +-- +-- The vertices the rig writes are in the model's RAW units -- before the +-- model_root scale the game applies -- so the scale here carries that too, +-- and the floor offset is measured in the same raw units on the way in. +function StadiumMon:matrix(x, groundY, z, faceX, faceZ) + local model = self.model + if not model then return nil end + local root = model.rootScale + if not (root and root > 0) then root = 1 end + local k = root * self:worldHeight() / math.max(model.height, 1e-6) + k = k * (self.scale or 1) + -- stand it on its own lowest point, then give back as much of the + -- authored hover as the shot can hold (see the header) + local floor = model.floor or 0 + local hover = math.min(math.max(floor, 0), + StadiumMon.HOVER_CAP * math.max(model.height, 0)) + local lift = (floor - hover) / root + local yaw = 0 + if faceX and faceZ and (faceX ~= 0 or faceZ ~= 0) then + -- the card and the model share this convention: an unrotated model + -- faces +Z, which is map SOUTH, which is what "facing down" is in the + -- flat game (see Voxel3D's axis note) + yaw = math.atan2(faceX, faceZ) + end + self.yaw = yaw + return Mat4.mul( + Mat4.mul(Mat4.mul(Mat4.translate(x, groundY, z), Mat4.rotateY(yaw)), + Mat4.scale(k, k, k)), + Mat4.translate(0, -lift, 0)) +end + +-- Pose and skin for this frame. Separate from the draw because both the +-- SUN and the camera -- and, in a headset, both eyes -- want the same +-- skinned mesh, and skinning it once is the whole reason this is worth +-- doing on the CPU. +function StadiumMon:build() + if not (self.rig and self.model) then return false end + -- self.anim is nil for a static species, and pose() reads that as "the + -- bind pose", which is exactly what is wanted + self.rig:pose(self.anim, self.time * StadiumMon.FPS, self.loop) + self.rig:skin(self.yaw or 0) + -- no clock of its own: the texture animation rides the frame pose() just + -- resolved, which is what keeps a blink inside its standby loop and a + -- fainted Pokemon's eyes shut once it has stopped moving + self.rig:textures(self.aux) + return true +end + +return StadiumMon diff --git a/lib/StadiumPack.lua b/lib/StadiumPack.lua new file mode 100644 index 0000000..3285fa9 --- /dev/null +++ b/lib/StadiumPack.lua @@ -0,0 +1,553 @@ +-- STADIUM battles: reading one species' model off disk. +-- +-- `NNN.dsm` holds one Pokemon Stadium battle model. It is written by +-- StadiumBuild, out of the player's own copy of that ROM, the first time the +-- mod runs (see StadiumInstall) -- and by tools/stadium_pack.py, which is the +-- oracle that Lua path is tested against. This file is the other half of that +-- format and nothing else: bytes in, tables out. What the tables MEAN is +-- StadiumRig's business (posing a skeleton) and StadiumMon's (which animation +-- a fight is asking for). +-- +-- Three things shape it. +-- +-- BINARY, NOT LUA. A species is a couple of hundred kilobytes of numbers, +-- most of it animation, and a Lua source file of that is a parse the loader +-- would pay for on every boot whether a battle happened or not. A byte +-- string is read once, on the frame a fight starts, and only for the two +-- species actually fighting. +-- +-- LAZY ANIMATIONS. Geometry, bones and textures are decoded on load -- +-- they are small, and every one of them is needed the moment the mon +-- appears. The animations are not: a fight uses idle, an entrance and +-- whichever handful of attacks come up, out of the seven to twenty-one a +-- species carries. So the load pass SCANS the animation block, recording +-- where each one starts and skipping the rest, and a track is decoded the +-- first time something plays it. That turns a 200 KB decode into a 20 KB +-- one plus a few milliseconds spread over the fight. +-- +-- AN LRU OF FOUR. A model is shared by everything that draws that species +-- -- both sides of a mirror match, both VR eyes -- and kept for a few +-- battles after, because the next fight on the same route is very often +-- the same Pokemon. Four is enough for a wild fight (two) plus the +-- trainer's next two, and it bounds what the mode can hold to a few +-- megabytes. +-- +-- Everything is pcall-guarded and every failure answers nil: a missing +-- pack, a truncated file or a driver that will not make an image all end +-- at the same place, which is the flat 2D-3D card this mode falls back to +-- (see Stadium). + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumPack = {} + +local byte = string.byte +local floor = math.floor + +-- ------- where a pack comes from +-- +-- Two places, asked in this order. +-- +-- CACHE_DIR is in the save directory and is what actually ships: the mod +-- carries no models (they are Pokemon Stadium's data), so StadiumInstall +-- builds them out of the player's own ROM on first run and writes them here. +-- +-- DIR is inside the mod, and exists for a developer checkout that has run +-- tools/stadium_pack.py -- which is also how the oracle the Lua extractor is +-- tested against gets built. It is second because a locally built cache +-- should win over whatever a checkout happens to have lying around. +StadiumPack.CACHE_DIR = "dramatic_shape/stadium" +StadiumPack.DIR = "assets/stadium" + +local function readPack(species) + local rel = ("%s/%03d.dsm"):format(StadiumPack.CACHE_DIR, species) + if love and love.filesystem and love.filesystem.getInfo then + local okInfo, info = pcall(love.filesystem.getInfo, rel, "file") + if okInfo and info then + local ok, bytes = pcall(love.filesystem.read, rel) + if ok and type(bytes) == "string" and #bytes > 4 then return bytes end + end + end + local mod = V.mod + if not (mod and mod.read) then return nil end + local ok, bytes = pcall(mod.read, mod, + ("%s/%03d.dsm"):format(StadiumPack.DIR, species)) + if ok and type(bytes) == "string" and #bytes > 4 then return bytes end + return nil +end + +-- The battle system's context slots, in the order tools/stadium_pack.py +-- writes them -- slot 165 upward (see model_extract/manifest.json's +-- animationSlots). Indexed by POSITION, so this list is the format's +-- contract and the packer's CONTEXTS must stay identical to it. +StadiumPack.CONTEXT = { + "idle", "hit", "faint", "entrance", "reaction_169", "reaction_170", + "reaction_171", "reaction_172", "reaction_173", "reaction_174", + "struggle", "idle_alt", "faint_alt", "flinch", "reaction_179", + "reaction_180", "reaction_181", "reaction_182", "entrance_alt", + "idle_return", +} + +-- name -> slot position, for callers that ask by name +StadiumPack.SLOT = {} +for i, name in ipairs(StadiumPack.CONTEXT) do StadiumPack.SLOT[name] = i end + +StadiumPack.N_MOVES = 165 +StadiumPack.NONE = 0xFFFF + +-- The frame rate every animation in the set is authored at +-- (model_extract/README.md: keyframe times are frame / 30). +StadiumPack.FPS = 30 + +-- ------- readers +-- +-- One cursor threaded through by hand rather than an object: this runs over +-- a couple of hundred thousand values on the frame a battle starts, and a +-- method call per value is the difference between a hitch and no hitch. + +local function u8(s, p) return byte(s, p), p + 1 end + +local function u16(s, p) + local a, b = byte(s, p, p + 1) + return a + b * 256, p + 2 +end + +local function i16(s, p) + local a, b = byte(s, p, p + 1) + local v = a + b * 256 + if v >= 32768 then v = v - 65536 end + return v, p + 2 +end + +local function u32(s, p) + local a, b, c, d = byte(s, p, p + 3) + return a + b * 256 + c * 65536 + d * 16777216, p + 4 +end + +local function i32(s, p) + local v + v, p = u32(s, p) + if v >= 2147483648 then v = v - 4294967296 end + return v, p +end + +-- IEEE 754 single, by hand. LOVE has love.data.unpack, but this file reads +-- exactly four floats per model (the header's extents) and a hand decode +-- costs nothing while removing a version floor from the mod's whole +-- STADIUM path. +local function f32(s, p) + local b1, b2, b3, b4 = byte(s, p, p + 3) + local sign = 1 + if b4 >= 128 then sign, b4 = -1, b4 - 128 end + local expo = b4 * 2 + floor(b3 / 128) + local mant = (b3 % 128) * 65536 + b2 * 256 + b1 + if expo == 255 then + if mant == 0 then return sign * math.huge, p + 4 end + return 0, p + 4 + end + if expo == 0 then return sign * mant * 2 ^ -149, p + 4 end + return sign * (1 + mant / 8388608) * 2 ^ (expo - 127), p + 4 +end + +-- 16.16 fixed point, which is how bone scales are stored (they run from +-- about -31 to 100 across the set and a float would cost twice the bytes +-- for precision nothing can see). +local function fixed(s, p) + local v + v, p = i32(s, p) + return v / 65536, p +end + +-- ------- the load + +local function readHeader(s, p, model) + model.species, p = u16(s, p) + model.boneCount, p = u16(s, p) + model.primCount, p = u16(s, p) + model.texCount, p = u16(s, p) + model.animCount, p = u16(s, p) + model.auxCount, p = u16(s, p) + model.rootScale, p = f32(s, p) + -- a species whose standby loop is corrupt in the source extraction, and + -- which the mod therefore holds at its bind pose (see the packer's + -- idle_is_broken). Three of the 151. + local static + static, p = u8(s, p) + model.staticPose = static ~= 0 + model.height, p = f32(s, p) + model.floor, p = f32(s, p) + model.radius, p = f32(s, p) + + local moveAnim, moveAux, ctx = {}, {}, {} + for i = 1, StadiumPack.N_MOVES do moveAnim[i], p = u16(s, p) end + for i = 1, StadiumPack.N_MOVES do moveAux[i], p = i16(s, p) end + for i = 1, #StadiumPack.CONTEXT do ctx[i], p = u16(s, p) end + model.moveAnim, model.moveAux, model.ctx = moveAnim, moveAux, ctx + return p +end + +-- The bone tree, as flat parallel arrays: a rig walk touches every bone +-- every frame and an array of little tables would be a cache miss per bone +-- and a table per bone to collect. +local function readBones(s, p, model) + local n = model.boneCount + local parent, t, r, sc = {}, {}, {}, {} + for i = 1, n do + -- 0-based in the file, 1-based here, and 0 for "no parent" so the rig's + -- walk can test it without a sentinel comparison + local par + par, p = i16(s, p) + parent[i] = par + 1 + local b = (i - 1) * 3 + t[b + 1], p = i16(s, p) + t[b + 2], p = i16(s, p) + t[b + 3], p = i16(s, p) + r[b + 1], p = i16(s, p) + r[b + 2], p = i16(s, p) + r[b + 3], p = i16(s, p) + sc[b + 1], p = fixed(s, p) + sc[b + 2], p = fixed(s, p) + sc[b + 3], p = fixed(s, p) + end + model.parent, model.restT, model.restR, model.restS = parent, t, r, sc + return p +end + +-- One drawable piece: the triangles that share a texture and a cull mode. +-- +-- Positions and normals stay in BONE-LOCAL space, exactly as the display +-- list had them, because that is what makes the skinning a single matrix +-- multiply per vertex (every vertex in the set is rigidly bound to one bone +-- -- see model_extract/README.md) rather than a weighted blend. +local function readPrims(s, p, model) + local prims = {} + for i = 1, model.primCount do + local prim = {} + prim.tex, p = u16(s, p) + prim.tex = prim.tex + 1 + local cull, blend + cull, p = u8(s, p) + blend, p = u8(s, p) + prim.cull = cull ~= 0 + prim.additive = blend ~= 0 + prim.texAnim, p = i16(s, p) + + -- the texture-animation channel's value -> which texture to swap in. + -- Keyed by the stream's own byte, so the rig can look one up without + -- searching. + local mapN + mapN, p = u8(s, p) + if mapN > 0 then + local map = {} + for _ = 1, mapN do + local key, tex + key, p = u8(s, p) + tex, p = u16(s, p) + map[key] = tex + 1 + end + prim.texMap = map + end + + local fxN + fxN, p = u16(s, p) + if fxN > 0 then + local frames = {} + for k = 1, fxN do + frames[k], p = u16(s, p) + frames[k] = frames[k] + 1 + end + prim.fxFrames = frames + end + + local nv, ni + nv, p = u16(s, p) + ni, p = u16(s, p) + prim.vertCount, prim.indexCount = nv, ni + + -- five arrays rather than one array of vertices, for the same reason + -- the bones are flat: the skinning loop reads them in step and writes + -- one LOVE vertex row out + local px, py, pz = {}, {}, {} + local uv = {} + local nx, ny, nz = {}, {}, {} + local bone = {} + for k = 1, nv do + px[k], p = i16(s, p) + py[k], p = i16(s, p) + pz[k], p = i16(s, p) + local u, v + u, p = i16(s, p) + v, p = i16(s, p) + uv[k * 2 - 1], uv[k * 2] = u / 512, v / 512 + local a, b, c + a, p = u8(s, p) + b, p = u8(s, p) + c, p = u8(s, p) + if a >= 128 then a = a - 256 end + if b >= 128 then b = b - 256 end + if c >= 128 then c = c - 256 end + nx[k], ny[k], nz[k] = a / 127, b / 127, c / 127 + bone[k], p = u8(s, p) + bone[k] = bone[k] + 1 + end + prim.px, prim.py, prim.pz = px, py, pz + prim.uv = uv + prim.nx, prim.ny, prim.nz = nx, ny, nz + prim.bone = bone + + local idx = {} + for k = 1, ni do + idx[k], p = u16(s, p) + idx[k] = idx[k] + 1 + end + prim.index = idx + prims[i] = prim + end + model.prims = prims + return p +end + +-- The textures, kept as the raw RGBA8 they arrived as and turned into +-- images on first use. A species carries every frame of every blink and +-- every dizzy swirl; a fight that never shows one should not pay to +-- upload it. +-- +-- Raw rather than PNG, which is what DSM3 changed: an ImageData over these +-- bytes is a memcpy where a PNG is a decode on the frame a battle starts, +-- and -- the reason it was actually done -- uncompressed pixels are the same +-- pixels whichever side wrote them, so the Lua extractor's output can be +-- diffed against the Python packer's byte for byte. Two deflate +-- implementations need not agree; two arrays of pixels do. +local function readTextures(s, p, model) + local tex = {} + for i = 1, model.texCount do + local w, h, len + w, p = u16(s, p) + h, p = u16(s, p) + len, p = u32(s, p) + tex[i] = { w = w, h = h, rgba = s:sub(p, p + len - 1) } + p = p + len + end + model.textures = tex + return p +end + +-- How many bytes one animation's track block occupies, without decoding +-- any of it. This is the scan that makes lazy animations possible: nine +-- components a bone, each either one value or one a frame, and the only +-- thing that has to be READ is the byte that says which. +local COMP_BYTES = { 2, 2, 2, 2, 2, 2, 4, 4, 4 } -- t t t r r r s s s + +local function skipTracks(s, p, boneCount, frames) + for _ = 1, boneCount do + local present + present, p = u8(s, p) + if present ~= 0 then + for c = 1, 9 do + local kind + kind, p = u8(s, p) + p = p + COMP_BYTES[c] * (kind == 0 and 1 or frames) + end + end + end + return p +end + +local function readAnims(s, p, model) + local anims = {} + for i = 1, model.animCount do + local len + len, p = u8(s, p) + local name = s:sub(p, p + len - 1) + p = p + len + local frames, loopStart, aux + frames, p = u16(s, p) + loopStart, p = u16(s, p) + aux, p = i16(s, p) + anims[i] = { + name = name, frames = frames, loopStart = loopStart, + aux = aux >= 0 and (aux + 1) or nil, + seconds = frames / StadiumPack.FPS, + offset = p, -- where its tracks start; decoded later + } + p = skipTracks(s, p, model.boneCount, frames) + end + model.anims = anims + return p +end + +local function readAux(s, p, model) + local aux = {} + for i = 1, model.auxCount do + local frames, loopStart, chanN + frames, p = u16(s, p) + loopStart, p = u16(s, p) + chanN, p = u16(s, p) + local chans = {} + for c = 1, chanN do + local n + n, p = u16(s, p) + local stream = {} + for k = 1, n do stream[k], p = u16(s, p) end + chans[c] = stream + end + aux[i] = { frames = frames, loopStart = loopStart, channels = chans } + end + model.auxAnims = aux + return p +end + +-- ------- a track block, decoded on demand +-- +-- The shape a pose walk wants: `tracks[bone]` is either nil (this bone +-- holds its rest transform for the whole animation) or nine entries, each +-- either a number (constant) or an array of one value per frame. +-- +-- That fold is the source data's own, not something imposed here: a bone +-- that only rotates costs two bytes for each of its six other components, +-- and across the 151 species it is most of the reason the whole set is 24 +-- megabytes rather than a hundred. +function StadiumPack.tracks(model, index) + local anim = model.anims and model.anims[index] + if not anim then return nil end + if anim.tracks then return anim.tracks end + local s, p = model.bytes, anim.offset + if not (s and p) then return nil end + local frames = anim.frames + local out = {} + for b = 1, model.boneCount do + local present + present, p = u8(s, p) + if present ~= 0 then + local comps = {} + for c = 1, 9 do + local kind + kind, p = u8(s, p) + local read = (c >= 7) and fixed or i16 + if kind == 0 then + comps[c], p = read(s, p) + else + local arr = {} + for k = 1, frames do arr[k], p = read(s, p) end + comps[c] = arr + end + end + out[b] = comps + end + end + anim.tracks = out + return out +end + +-- One texture as a LOVE image, decoded on first ask. +function StadiumPack.image(model, index) + local slot = model.textures and model.textures[index] + if not slot then return nil end + if slot.image ~= nil then return slot.image or nil end + local ok, img = pcall(function() + local data = love.image.newImageData(slot.w, slot.h, "rgba8", slot.rgba) + local image = love.graphics.newImage(data) + -- N64 art at N64 resolution: nearest keeps the texels the size the + -- artist drew them, exactly as every other texture in this mode + image:setFilter("nearest", "nearest") + return image + end) + slot.image = (ok and img) or false + return slot.image or nil +end + +-- ------- the cache + +local cache = {} -- species -> model +local order = {} -- species, least recently used first +StadiumPack.KEEP = 4 + +local function touch(species) + for i = #order, 1, -1 do + if order[i] == species then table.remove(order, i) end + end + order[#order + 1] = species + while #order > StadiumPack.KEEP do + local drop = table.remove(order, 1) + local model = cache[drop] + cache[drop] = nil + if model and model.textures then + for _, slot in ipairs(model.textures) do + if slot.image and slot.image.release then + pcall(slot.image.release, slot.image) + end + end + end + end +end + +-- Whether a pack for this species is on disk at all. Cheap enough to ask +-- before a battle commits to the mode, and the honest test: a mod +-- installed without its assets folder must decline rather than error. +function StadiumPack.available(species) + if cache[species] then return true end + return readPack(species) ~= nil +end + +-- The model for a National Dex number (1..151), or nil. +function StadiumPack.load(species) + if not (species and species >= 1 and species <= 151) then return nil end + local hit = cache[species] + if hit ~= nil then + touch(species) + return hit or nil + end + + local bytes = readPack(species) + if not bytes then + cache[species] = false + return nil + end + + local ok, model = pcall(function() + if bytes:sub(1, 4) ~= "DSM3" then + error("not a DSM3 pack -- delete it and let the mod rebuild it", 0) + end + local m = { bytes = bytes } + local p = 5 + p = readHeader(bytes, p, m) + p = readBones(bytes, p, m) + p = readPrims(bytes, p, m) + p = readTextures(bytes, p, m) + p = readAnims(bytes, p, m) + readAux(bytes, p, m) + return m + end) + if not ok then + V.mod.log:warn("stadium: %03d.dsm did not read: %s -- that Pokemon " + .. "falls back to its flat pic", species, tostring(model)) + cache[species] = false + return nil + end + + cache[species] = model + touch(species) + return model +end + +-- Drop everything (hot reload, or a graphics context that went away). +function StadiumPack.invalidate() + for _, model in pairs(cache) do + if model and model.textures then + for _, slot in ipairs(model.textures) do + if slot.image and slot.image.release then + pcall(slot.image.release, slot.image) + end + slot.image = nil + end + end + end +end + +function StadiumPack.forget() + StadiumPack.invalidate() + cache, order = {}, {} +end + +return StadiumPack diff --git a/lib/StadiumRig.lua b/lib/StadiumRig.lua new file mode 100644 index 0000000..89c7220 --- /dev/null +++ b/lib/StadiumRig.lua @@ -0,0 +1,443 @@ +-- STADIUM battles: posing a skeleton and skinning it, on the CPU. +-- +-- One instance of this is one Pokemon standing on the map -- the meshes it +-- draws through and the scratch space its pose is computed in. The MODEL +-- (geometry, bones, animations, textures) is shared and read-only; this is +-- everything about it that is per-Pokemon and changes every frame. +-- +-- ------- why the CPU +-- +-- Because these models are tiny and the mod's shader already exists. A +-- battle model is 674 vertices on average and 1311 at the worst, of which +-- exactly two are on screen at a time -- so skinning them by hand costs +-- about two thousand vertex transforms a frame, which is less than the +-- grass pass does on an empty route. What it buys is that the finished +-- vertices go into Voxel3D's OWN vertex format, through Voxel3D's OWN +-- shader, and therefore get every single thing the rest of the diorama +-- gets for free: the depth buffer decides what is in front of what, the +-- sun pass throws a real shadow of the actual pose, the hour's tint lands +-- on it, the hit flash flattens it, and the tilt-shift and the +-- depth-of-field see it as part of the picture. A GPU skinning path would +-- have needed a second shader that then had to re-implement all of that, +-- and a second shadow shader beside it. +-- +-- It is also what makes the FORMAT work. Every vertex in the Stadium set is +-- rigidly bound to ONE bone with weight 1 (model_extract/README.md), so +-- skinning is a single matrix multiply per vertex with no blend -- and the +-- per-vertex `shade` Voxel3D wants, which no glTF has, is computed here +-- from the bone-local normal. +-- +-- ------- the two matrix chains +-- +-- The game keeps bone scale OUT of the matrix chain (func_800143C0): scale +-- accumulates in its own stack, a bone's local translation is +-- pre-multiplied by its parent's accumulated scale, and a bone's own +-- accumulated scale is applied to the finished matrix only at draw time. +-- glTF cannot express that -- its node scale propagates to children -- and +-- the reference export works around it by splitting every bone into two +-- nodes. +-- +-- Here it falls out naturally, as two arrays: +-- +-- pivot rotation and translation only. This is what a CHILD inherits, +-- and it is a pure rotation, which is also why the normals are +-- transformed with it rather than with the draw matrix. +-- draw the same matrix with the bone's accumulated scale applied on +-- the right, which is the one vertices go through. +-- +-- Folding the scale into the chain instead is the obvious mistake and it +-- applies every ancestor's scale once per generation. It is caught by the +-- suite: tools/stadium_pack.py measures the bind pose with this exact walk +-- and its answer matches the verified glTF export on all 151 species. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local Voxel3D = V.require("Voxel3D") +local StadiumPack = V.require("StadiumPack") + +local StadiumRig = {} +StadiumRig.__index = StadiumRig + +local sin, cos, floor = math.sin, math.cos, math.floor + +-- binary angle (32768 = pi) to radians +local ANG = math.pi / 32768 + +-- ------- how a surface is lit +-- +-- Voxel3D shades a face by its DIRECTION rather than by a light uniform: +-- every terrain and character mesh in this mode carries a per-vertex +-- `shade` baked from which way its face points, and the shadow map +-- multiplies on top of that (see Voxel3D.FACE_SHADE). A skinned model has +-- no fixed faces to bake, so the same answer is computed per vertex from +-- the posed normal -- and these four numbers are FACE_SHADE's own six +-- values, fitted: +-- +-- +Y up 1.00 -Y down 0.55 +X east 0.84 -X west 0.72 +-- +Z south 0.90 -Z north 0.68 +-- +-- so a Pokemon's flank catches the same southeastern sun the roof of the +-- house behind it does, and the two read as being in one picture. +local SHADE_BASE = 0.7725 +local SHADE_X = 0.06 +local SHADE_Y = 0.225 +local SHADE_Z = 0.11 + +-- ------- an instance + +-- `model` is a StadiumPack model. Returns nil where meshes cannot be made, +-- which is the same "no 3D" answer every other GPU object in this mod gives. +function StadiumRig.new(model) + if not (model and model.prims) then return nil end + if not (love.graphics and love.graphics.newMesh) then return nil end + + local self = setmetatable({ + model = model, + -- The two chains, flat: twelve numbers a bone, row-major 3x4. + -- + -- Named with the M rather than `pivot` and `draw` because an instance + -- field called `draw` shadows the DRAW METHOD through __index, and the + -- failure that causes is a nasty one: the shadow pass calls caster() + -- and keeps working, so a Pokemon casts a perfect animated shadow onto + -- ground it is not standing on. + pivotM = {}, + drawM = {}, + -- the accumulated scale, which is the third thing the game's own walk + -- carries and neither matrix can hold + accX = {}, accY = {}, accZ = {}, + parts = {}, + -- what the pose walk last answered, so a frame that neither moved the + -- animation nor turned the model can skip the whole thing + poseKey = nil, + }, StadiumRig) + + -- One mesh per primitive: a primitive is already "the triangles sharing + -- one texture", which is exactly one draw call's worth. + -- + -- "dynamic" rather than "static": every vertex is rewritten every frame + -- the pose changes, which is what the usage hint exists to say. + for i, prim in ipairs(model.prims) do + local rows = {} + local uv = prim.uv + for k = 1, prim.vertCount do + -- position and shade are filled by skin(); the texture coordinates + -- never change, so they are written once here + rows[k] = { 0, 0, 0, uv[k * 2 - 1], uv[k * 2], 1 } + end + local ok, mesh = pcall(love.graphics.newMesh, Voxel3D.FORMAT, rows, + "triangles", "dynamic") + if not ok then return nil end + pcall(mesh.setVertexMap, mesh, prim.index) + self.parts[i] = { mesh = mesh, rows = rows, prim = prim } + end + return self +end + +function StadiumRig:release() + for _, part in ipairs(self.parts or {}) do + if part.mesh and part.mesh.release then + pcall(part.mesh.release, part.mesh) + end + end + self.parts = {} +end + +-- ------- sampling one track +-- +-- `c` is the pack's own fold: a bare number when the component holds still +-- for the whole animation, or one value a frame when it does not. Two frame +-- indices and a blend come in because the caller has already resolved what +-- "between frame 12 and 13, three tenths of the way" means for THIS +-- animation's looping. + +local function sampleLinear(c, i0, i1, k) + if type(c) == "number" then return c end + local a = c[i0] + if k <= 0 then return a end + local b = c[i1] + if b == nil then return a end + return a + (b - a) * k +end + +-- The same, for a BINARY ANGLE, which wraps. Interpolating 32700 toward +-- -32700 the long way round spins the bone most of a full turn in one +-- frame; the short way is the one the eye expects and the one the game's +-- own player takes. +local function sampleAngle(c, i0, i1, k) + if type(c) == "number" then return c end + local a = c[i0] + if k <= 0 then return a end + local b = c[i1] + if b == nil then return a end + local d = b - a + if d > 32768 then d = d - 65536 elseif d < -32768 then d = d + 65536 end + return a + d * k +end + +-- ------- the pose +-- +-- `anim` is an index into model.anims (or nil for the bind pose), `frame` a +-- FLOAT frame in that animation's own 30 Hz timeline, and `wrap` whether +-- the far end joins back to loopStart (a standby loop) or holds on the last +-- frame (a faint). +function StadiumRig:pose(anim, frame, wrap) + local model = self.model + local n = model.boneCount + local tracks = anim and StadiumPack.tracks(model, anim) or nil + local frames = anim and model.anims[anim] and model.anims[anim].frames or 1 + + -- the two frames this instant falls between, and how far + local i0, i1, k = 1, 1, 0 + if tracks and frames > 1 then + local f = frame + if f < 0 then f = 0 end + local base = floor(f) + k = f - base + if base >= frames - 1 then + if wrap then + local loop = model.anims[anim].loopStart or 0 + base = base % frames + i0 = base + 1 + i1 = (base + 1 >= frames) and (loop + 1) or (base + 2) + else + i0, i1, k = frames, frames, 0 + end + else + i0, i1 = base + 1, base + 2 + end + if i0 > frames then i0 = frames end + if i1 > frames then i1 = frames end + end + + -- The frame this animation is actually SHOWING, after the wrap or the + -- hold, 0-based. Stashed rather than recomputed because the texture + -- animation is sampled at the very same frame (see textures) -- in the + -- game one counter drives both, and 73% of the paired animations in the + -- set are the same length as each other, which is what that looks like + -- from the outside. Two copies of this arithmetic would be two things to + -- keep in step; one number cannot drift from itself. + self.frameAt = i0 - 1 + + local parent = model.parent + local restT, restR, restS = model.restT, model.restR, model.restS + local pivot, drw = self.pivotM, self.drawM + local accX, accY, accZ = self.accX, self.accY, self.accZ + + for b = 1, n do + local o3 = (b - 1) * 3 + local tx, ty, tz, rx, ry, rz, kx, ky, kz + local comps = tracks and tracks[b] + if comps then + tx = sampleLinear(comps[1], i0, i1, k) + ty = sampleLinear(comps[2], i0, i1, k) + tz = sampleLinear(comps[3], i0, i1, k) + rx = sampleAngle(comps[4], i0, i1, k) + ry = sampleAngle(comps[5], i0, i1, k) + rz = sampleAngle(comps[6], i0, i1, k) + kx = sampleLinear(comps[7], i0, i1, k) + ky = sampleLinear(comps[8], i0, i1, k) + kz = sampleLinear(comps[9], i0, i1, k) + else + -- a bone this animation never touches keeps its rest transform + tx, ty, tz = restT[o3 + 1], restT[o3 + 2], restT[o3 + 3] + rx, ry, rz = restR[o3 + 1], restR[o3 + 2], restR[o3 + 3] + kx, ky, kz = restS[o3 + 1], restS[o3 + 2], restS[o3 + 3] + end + + local p = parent[b] + local pax, pay, paz = 1, 1, 1 + if p > 0 then pax, pay, paz = accX[p], accY[p], accZ[p] end + -- the parent's accumulated scale, applied to the CHILD's offset. This + -- is the whole of what the game does instead of propagating scale. + tx, ty, tz = tx * pax, ty * pay, tz * paz + + -- Rx * Ry * Rz in the game's own row-vector form (src/F420.c + -- func_8000F730), written out as the rows of a 3x3 + local ax, ay, az = rx * ANG, ry * ANG, rz * ANG + local sx, cx = sin(ax), cos(ax) + local sy, cy = sin(ay), cos(ay) + local sz, cz = sin(az), cos(az) + local m11, m12, m13 = cy * cz, sx * sy * cz - cx * sz, cx * sy * cz + sx * sz + local m21, m22, m23 = cy * sz, sx * sy * sz + cx * cz, cx * sy * sz - sx * cz + local m31, m32, m33 = -sy, sx * cy, cx * cy + + local o = (b - 1) * 12 + if p > 0 then + local q = (p - 1) * 12 + local a1, a2, a3, a4 = pivot[q + 1], pivot[q + 2], pivot[q + 3], pivot[q + 4] + local b1, b2, b3, b4 = pivot[q + 5], pivot[q + 6], pivot[q + 7], pivot[q + 8] + local c1, c2, c3, c4 = pivot[q + 9], pivot[q + 10], pivot[q + 11], pivot[q + 12] + pivot[o + 1] = a1 * m11 + a2 * m21 + a3 * m31 + pivot[o + 2] = a1 * m12 + a2 * m22 + a3 * m32 + pivot[o + 3] = a1 * m13 + a2 * m23 + a3 * m33 + pivot[o + 4] = a1 * tx + a2 * ty + a3 * tz + a4 + pivot[o + 5] = b1 * m11 + b2 * m21 + b3 * m31 + pivot[o + 6] = b1 * m12 + b2 * m22 + b3 * m32 + pivot[o + 7] = b1 * m13 + b2 * m23 + b3 * m33 + pivot[o + 8] = b1 * tx + b2 * ty + b3 * tz + b4 + pivot[o + 9] = c1 * m11 + c2 * m21 + c3 * m31 + pivot[o + 10] = c1 * m12 + c2 * m22 + c3 * m32 + pivot[o + 11] = c1 * m13 + c2 * m23 + c3 * m33 + pivot[o + 12] = c1 * tx + c2 * ty + c3 * tz + c4 + else + pivot[o + 1], pivot[o + 2], pivot[o + 3], pivot[o + 4] = m11, m12, m13, tx + pivot[o + 5], pivot[o + 6], pivot[o + 7], pivot[o + 8] = m21, m22, m23, ty + pivot[o + 9], pivot[o + 10], pivot[o + 11], pivot[o + 12] = m31, m32, m33, tz + end + + local ex, ey, ez = pax * kx, pay * ky, paz * kz + accX[b], accY[b], accZ[b] = ex, ey, ez + -- the bone's own accumulated scale, on the right: it scales the axes of + -- THIS bone's space and cannot reach the children, which is exactly the + -- game's draw-time application + drw[o + 1], drw[o + 2] = pivot[o + 1] * ex, pivot[o + 2] * ey + drw[o + 3], drw[o + 4] = pivot[o + 3] * ez, pivot[o + 4] + drw[o + 5], drw[o + 6] = pivot[o + 5] * ex, pivot[o + 6] * ey + drw[o + 7], drw[o + 8] = pivot[o + 7] * ez, pivot[o + 8] + drw[o + 9], drw[o + 10] = pivot[o + 9] * ex, pivot[o + 10] * ey + drw[o + 11], drw[o + 12] = pivot[o + 11] * ez, pivot[o + 12] + end +end + +-- ------- the skin +-- +-- Every vertex through its one bone's draw matrix, and its normal through +-- the same bone's pivot (a pure rotation, so the normal survives a +-- non-uniformly scaled bone -- which several species have). +-- +-- `yaw` is the model matrix's own turn, and it is folded in HERE rather +-- than left to the matrix because the shade has to be computed against the +-- WORLD normal: a Pokemon turned to face its opponent has a differently lit +-- flank than one facing the camera, and the sun does not turn with it. +function StadiumRig:skin(yaw) + local cy, sy = cos(yaw or 0), sin(yaw or 0) + local drw, piv = self.drawM, self.pivotM + for _, part in ipairs(self.parts) do + local prim, rows = part.prim, part.rows + local px, py, pz = prim.px, prim.py, prim.pz + local nx, ny, nz = prim.nx, prim.ny, prim.nz + local bone = prim.bone + for k = 1, prim.vertCount do + local o = (bone[k] - 1) * 12 + local x, y, z = px[k], py[k], pz[k] + local row = rows[k] + row[1] = drw[o + 1] * x + drw[o + 2] * y + drw[o + 3] * z + drw[o + 4] + row[2] = drw[o + 5] * x + drw[o + 6] * y + drw[o + 7] * z + drw[o + 8] + row[3] = drw[o + 9] * x + drw[o + 10] * y + drw[o + 11] * z + drw[o + 12] + local ax, ay, az = nx[k], ny[k], nz[k] + local wx = piv[o + 1] * ax + piv[o + 2] * ay + piv[o + 3] * az + local wy = piv[o + 5] * ax + piv[o + 6] * ay + piv[o + 7] * az + local wz = piv[o + 9] * ax + piv[o + 10] * ay + piv[o + 11] * az + -- the model matrix's yaw, by hand: (x, z) turned, y untouched + row[6] = SHADE_BASE + SHADE_X * (cy * wx + sy * wz) + SHADE_Y * wy + + SHADE_Z * (cy * wz - sy * wx) + end + pcall(part.mesh.setVertices, part.mesh, rows) + end +end + +-- ------- which texture each part wears this frame +-- +-- The eyes. A primitive whose display list carried geo command 0x23 with a +-- channel index has its texture REPLACED every frame from a stream of +-- texture-table indices (src/18140.c func_800176DC) -- which is how every +-- Pokemon in the game blinks, and how a confused one gets swirls. glTF has +-- no channel for that, so the .glb files carry only the first frame; the +-- pack carries the streams. +-- +-- `aux` is an index into model.auxAnims (the stream set) and `frame` its +-- own frame counter, which runs independently of the skeletal one. +-- The eyes, and everything else a material swaps per frame. +-- +-- Sampled at the SKELETAL animation's own frame -- the one pose() just +-- resolved -- and CLAMPED past the end of the stream rather than wrapped. +-- Both halves of that matter, and getting either wrong is visible. +-- +-- The frame is the skeleton's because in the game a single counter drives +-- both; the data says so plainly, since 507 of the 691 paired animations in +-- the set have a texture animation exactly as long as the skeletal one it +-- rides with. +-- +-- The clamp is what the game's own sampler does (func_80017540 indexes the +-- stream and holds the last entry past its end), and it is the whole +-- difference between a blink and a twitch. Rattata's standby loop is forty +-- frames and its blink is FIVE -- `6 8 7 8 6`, open through closed and back. +-- Wrapped on the blink's own length that plays six times a second, which is +-- what it looked like. Clamped, the eye blinks once at the top of the loop +-- and stays open for the remaining thirty-five frames, so it blinks about +-- once a second and a half. +function StadiumRig:textures(aux) + local model = self.model + local anim = aux and model.auxAnims and model.auxAnims[aux] or nil + local frame = self.frameAt or 0 + for _, part in ipairs(self.parts) do + local prim = part.prim + local index = prim.tex + if anim and prim.texAnim and prim.texAnim >= 0 and prim.texMap then + local stream = anim.channels[prim.texAnim + 1] + local n = stream and #stream or 0 + if n > 0 then + local at = frame + 1 + if at > n then at = n end + if at < 1 then at = 1 end + local mapped = prim.texMap[stream[at]] + if mapped then index = mapped end + end + end + part.texture = StadiumPack.image(model, index) + end +end + +-- ------- the draw +-- +-- `model` here is the MODEL MATRIX -- where this Pokemon stands, how big +-- and which way round -- and `sunModel` the transform the shadow pass drew +-- it with, which for these is the same matrix (unlike a character's leaning +-- card; see Voxel3D.draw). +-- +-- Seams off for the whole of it: the voxel wireframe draws the integer +-- planes of a mesh's own model space, and these vertices are in the N64's +-- own units where an integer plane means nothing (see VoxelGrid). Glass off +-- for the same reason the sprite passes turn it off -- the mask's +-- coordinates belong to the tileset atlas, not to a Pokemon's texture. +function StadiumRig:draw(matrix, pull) + Voxel3D.seams(false) + Voxel3D.glass(false) + local additive = nil + for _, part in ipairs(self.parts) do + if part.prim.additive then + -- held back to a second pass so the flames composite over the body + -- rather than depth-fighting it + additive = additive or {} + additive[#additive + 1] = part + elseif part.texture then + Voxel3D.draw(part.mesh, part.texture, matrix, pull) + end + end + if additive then + Voxel3D.blend("add") + for _, part in ipairs(additive) do + if part.texture then + Voxel3D.draw(part.mesh, part.texture, matrix, pull) + end + end + Voxel3D.blend(nil) + end + Voxel3D.glass(true) + Voxel3D.seams(true) +end + +-- The same geometry as the SUN sees it: no camera-ward pull (a trick for +-- the view's own depth buffer, which would drag a shadow off its owner) and +-- through the shadow pass's own draw call. The generated flame prims are +-- skipped -- a fire casts light, not a shadow. +function StadiumRig:caster(shadowMap, matrix) + for _, part in ipairs(self.parts) do + if part.texture and not part.prim.additive then + shadowMap.draw(part.mesh, part.texture, matrix) + end + end +end + +return StadiumRig diff --git a/lib/StadiumRom.lua b/lib/StadiumRom.lua new file mode 100644 index 0000000..e57493f --- /dev/null +++ b/lib/StadiumRom.lua @@ -0,0 +1,314 @@ +-- STADIUM battles: getting at the Pokemon Stadium ROM. +-- +-- Byte order, the archive the battle models are packed into, the Yay0 +-- decompressor that unwraps each one, and the per-species battle tables. It +-- is a port of model_extract/pipeline/rom.py, function for function, and the +-- Python remains the reference: tools/stadium_pack.py drives that side and +-- tests/stadium_extract_test.lua diffs this side's finished packs against it +-- byte for byte. +-- +-- ------- why this exists in Lua at all +-- +-- The mod cannot ship the models. They are ROM data, so what ships is the +-- READER, and the player supplies the ROM -- exactly the arrangement the +-- engine itself already has for the Game Boy ROM it is a recompilation of +-- (src/import/RomImporter.lua). Everything from `baserom.z64` to +-- `assets/stadium/NNN.dsm` therefore has to happen here, on the machine, in +-- Lua, with no Python and no build step. +-- +-- ------- what makes that tractable +-- +-- Three steps, and none of them needs a decompilation toolchain: +-- +-- 1. BYTE ORDER. The three N64 dump conventions differ by a swap that is +-- detected from the magic word and undone once, on load. +-- 2. THE ARCHIVE. The segment at 0x920000 is a count and a table of +-- (offset, size) records. No compression at that level, no names. +-- 3. Yay0. Nintendo's LZ variant: a bitstream where a 1 copies a literal +-- byte and a 0 pulls a (distance, length) pair out of a side table. +-- Thirty lines, and the same thirty lines the Python has. +-- +-- Verified in the Python by decompressing all 215 entries and diffing against +-- what the decompilation's own `make init` produces: 215/215 identical. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumRom = {} + +local byte = string.byte +local char = string.char +local concat = table.concat +local sub = string.sub +local floor = math.floor + +-- ROM offsets, from pokestadium-us.yaml by way of pipeline/rom.py. +StadiumRom.POKEMON_MODELS = 0x920000 -- archive of the 215 battle models +StadiumRom.BATTLE_DATA = 0x70D3A0 -- per-species battle tables +StadiumRom.MAIN_ROM = 0x1000 -- main code segment ... +StadiumRom.MAIN_VRAM = 0x80000400 -- ... and where it lands in RAM +StadiumRom.PTR_TABLE_VRAM = 0x80075BD0 -- D_80075BD0[species - 1] + +-- The revision every offset above is keyed to. A different ROM still runs -- +-- it may well be a regional variant with the same layout -- but the caller is +-- told, because "the models came out as garbage" and "that is not the ROM +-- this was written against" are the same fact and only one of them is useful. +StadiumRom.US_MD5 = "ed1378bc12115f71209a77844965ba50" + +-- The battle table's shape: 0xB90 bytes a species, as 0x10-byte entries. +-- Entries 0..164 are the moves (entry n drives move n + 1) and 165 up are the +-- fixed battle contexts. +StadiumRom.STRIDE = 0xB90 +StadiumRom.ENTRY = 0x10 +StadiumRom.N_MOVES = 165 + +-- How many of the archive's 215 models are the battle Pokemon. The rest are +-- props and trophies with no battle table. +StadiumRom.N_POKEMON = 151 + +-- ------- byte order +-- +-- .z64 is big-endian and native; .v64 has each pair of bytes swapped; .n64 +-- has each word reversed. `gsub` with a capture-reversing replacement does +-- either in one call through C rather than a Lua loop over 33 million bytes. + +local MAGIC_Z64 = "\128\055\018\064" +local MAGIC_V64 = "\055\128\064\018" +local MAGIC_N64 = "\064\018\055\128" + +-- Normalise a dump to .z64 order, or nil when it is not an N64 ROM at all. +function StadiumRom.normalise(bytes) + if type(bytes) ~= "string" or #bytes < 0x1000 then return nil end + local magic = sub(bytes, 1, 4) + if magic == MAGIC_Z64 then return bytes end + if magic == MAGIC_V64 then return (bytes:gsub("(.)(.)", "%2%1")) end + if magic == MAGIC_N64 then + return (bytes:gsub("(.)(.)(.)(.)", "%4%3%2%1")) + end + return nil +end + +-- ------- Yay0 +-- +-- The output has to be RANDOM ACCESS while it is being written -- a back +-- reference copies from what has already been produced, and overlapping runs +-- are legal and common -- so it is built in a flat table of byte values and +-- turned into a string at the end. +-- +-- The string.char conversion is the part that wants care: it is variadic and +-- has an argument limit, so the table is walked in blocks and the blocks +-- concatenated. Blocks of 4096 keep the call count and the intermediate +-- string count both low; the whole 151-model set converts in well under a +-- second on LuaJIT, which is what made an FFI buffer unnecessary here and +-- kept this module portable to any Lua the engine runs on. + +local CHUNK = 4096 + +-- LuaJIT keeps `unpack` global; 5.2+ moved it onto table. +local unpack = unpack or table.unpack + +local function bytesToString(out, n) + if n == 0 then return "" end + local parts, np = {}, 0 + local i = 1 + while i <= n do + local j = i + CHUNK - 1 + if j > n then j = n end + np = np + 1 + parts[np] = char(unpack(out, i, j)) + i = j + 1 + end + return concat(parts) +end + +-- Nintendo Yay0. Header: magic, decompressed size, link table offset, chunk +-- offset; then a bitstream read a word at a time. +function StadiumRom.yay0(src, base) + base = base or 0 + if sub(src, base + 1, base + 4) ~= "Yay0" then return nil, "not Yay0" end + local function be32(o) + local a, b, c, d = byte(src, base + o + 1, base + o + 4) + return ((a * 256 + b) * 256 + c) * 256 + d + end + local size = be32(4) + -- all three cursors are 1-based indices into `src`; the mask stream starts + -- immediately after the 16-byte header + local maskP = base + 0x10 + 1 + local linkP = base + be32(8) + 1 + local chunkP = base + be32(12) + 1 + + local out = {} + local pos = 0 -- bytes produced so far + local mask, bits = 0, 0 + + while pos < size do + if bits == 0 then + local a, b, c, d = byte(src, maskP, maskP + 3) + mask = ((a * 256 + b) * 256 + c) * 256 + d + maskP = maskP + 4 + bits = 32 + end + if mask >= 0x80000000 then + pos = pos + 1 + out[pos] = byte(src, chunkP) + chunkP = chunkP + 1 + else + local a, b = byte(src, linkP, linkP + 1) + linkP = linkP + 2 + local link = a * 256 + b + local dist = link % 0x1000 + local count = floor(link / 0x1000) + if count == 0 then + count = byte(src, chunkP) + 0x12 + chunkP = chunkP + 1 + else + count = count + 2 + end + -- overlapping runs are legal: copying one byte at a time from the + -- output as it grows is the behaviour, not a naive version of it + local copy = pos - dist + for _ = 1, count do + pos = pos + 1 + out[pos] = out[copy] + copy = copy + 1 + end + end + mask = (mask * 2) % 0x100000000 + bits = bits - 1 + end + + return bytesToString(out, size) +end + +-- Unwrap whatever container an asset arrived in. The model archive's entries +-- are PERS-SZP: an eight-byte magic plus a header size, wrapping a Yay0 +-- stream. +function StadiumRom.decompress(blob) + if sub(blob, 1, 8) == "PERS-SZP" then + local a, b, c, d = byte(blob, 9, 12) + local header = ((a * 256 + b) * 256 + c) * 256 + d + return StadiumRom.yay0(blob, header) + end + if sub(blob, 1, 4) == "Yay0" then return StadiumRom.yay0(blob, 0) end + return blob +end + +-- ------- the ROM + +local Rom = {} +Rom.__index = Rom + +-- `bytes` is the whole file. Returns the ROM, or nil plus why. +function StadiumRom.open(bytes) + local data = StadiumRom.normalise(bytes) + if not data then return nil, "not an N64 ROM (bad magic)" end + return setmetatable({ data = data }, Rom) +end + +function Rom:u8(o) + return byte(self.data, o + 1) +end + +function Rom:u32(o) + local a, b, c, d = byte(self.data, o + 1, o + 4) + if not d then return 0 end + return ((a * 256 + b) * 256 + c) * 256 + d +end + +function Rom:vramToRom(vram) + return StadiumRom.MAIN_ROM + (vram - StadiumRom.MAIN_VRAM) +end + +-- The md5 of the normalised image, or nil where LOVE's hash is not there +-- (the headless suite). Only ever used to tell the player which ROM they +-- gave us, never to refuse one. +function Rom:md5() + if self.hash ~= nil then return self.hash or nil end + local ok, hex = pcall(function() + local digest = love.data.hash("md5", self.data) + if type(digest) == "userdata" and digest.getString then + digest = digest:getString() + end + return love.data.encode("string", "hex", digest) + end) + self.hash = (ok and hex) or false + return self.hash or nil +end + +function Rom:isExpectedUS() + local hex = self:md5() + return hex == nil or hex == StadiumRom.US_MD5 +end + +-- ------- the archive +-- +-- Segments that hold many files start with +-- u32 tag, u32 0, u32 totalSize, u32 fileCount +-- followed by fileCount { u32 offset, u32 size, u32 pad[2] } records, all +-- relative to the start of the segment. +-- +-- Only the top three bytes of the first word are reliably zero: the model +-- archive puts a nonzero value in the low byte, which is the same quirk the +-- decompilation's own tools/unpack_asset.py works around. +-- +-- Returns a list of { start, size } rather than the bytes, so nothing is +-- copied until a caller actually wants a file. +function Rom:archive(off) + local tag = self:u32(off) + if (tag - tag % 256) ~= 0 or self:u32(off + 4) ~= 0 then return nil end + local count = self:u32(off + 12) + if count <= 0 or count >= 4096 then return nil end + local out = {} + for i = 0, count - 1 do + local rec = off + 0x10 + i * 0x10 + out[i + 1] = { start = off + self:u32(rec), size = self:u32(rec + 4) } + end + return out +end + +-- The entries of the battle-model archive, uncopied. +function Rom:models() + if not self.modelDir then + self.modelDir = self:archive(StadiumRom.POKEMON_MODELS) or {} + end + return self.modelDir +end + +function Rom:modelCount() + return #self:models() +end + +-- One model fragment, decompressed. `fileno` is 0-based, as in the Python and +-- in the source-file names: `N.bin` holds species N + 1. +function Rom:model(fileno) + local rec = self:models()[fileno + 1] + if not rec then return nil end + return StadiumRom.decompress(sub(self.data, rec.start + 1, + rec.start + rec.size)) +end + +-- ------- the per-species battle tables +-- +-- func_84302658 in src/fragments/62 DMAs 0xB90 bytes a species out of the +-- 0x70D3A0 segment, addressed through the D_80075BD0 pointer table. Byte 0 of +-- each 0x10-byte entry indexes that Pokemon's animation list and byte 1 its +-- auxiliary (texture) animation list. +-- +-- Returns a 0-based array-like table of { anim, aux }, aux 0xFF meaning none +-- and coming back as -1 -- the shape the packer writes. +function Rom:battleRows(species) + local ptrTable = self:vramToRom(StadiumRom.PTR_TABLE_VRAM) + local raw = self:u32(ptrTable + (species - 1) * 4) + local o = StadiumRom.BATTLE_DATA + raw % 0x1000000 + local rows = {} + local n = StadiumRom.STRIDE / StadiumRom.ENTRY + for e = 0, n - 1 do + local anim = self:u8(o + e * StadiumRom.ENTRY) + local aux = self:u8(o + e * StadiumRom.ENTRY + 1) + rows[e] = { anim, aux == 0xFF and -1 or aux } + end + rows.n = n + return rows +end + +return StadiumRom diff --git a/lib/StadiumScreen.lua b/lib/StadiumScreen.lua new file mode 100644 index 0000000..97a1e81 --- /dev/null +++ b/lib/StadiumScreen.lua @@ -0,0 +1,218 @@ +-- STADIUM battles: the one-time build, on screen. +-- +-- A pushed game state, so it draws in the Game Boy's own 160x144 and stops +-- everything under it -- which is what it should do, because it is doing real +-- work and the player should not be walking around while it happens. +-- +-- ------- why a species a frame +-- +-- A species takes roughly fifty milliseconds to extract, and there are 151 of +-- them. That is ten seconds, which has to go somewhere. Doing them one per +-- frame puts the whole cost on this screen where it is explained, keeps the +-- bar moving at a visible rate, and leaves the frame free to draw between +-- them. Batching more per frame would finish no sooner -- the work is the +-- same -- and would only make the bar jump. +-- +-- ------- what it says +-- +-- Which Pokemon it is on, by name. That is not decoration: it is the +-- difference between a progress bar the player trusts and one they suspect +-- has hung, and it costs one lookup a frame. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local StadiumInstall = V.require("StadiumInstall") + +local StadiumScreen = {} +StadiumScreen.__index = StadiumScreen + +-- The Game Boy frame this draws in. +local W, H = 160, 144 + +-- How long the finished message stays up before the screen retires itself. +StadiumScreen.HOLD = 1.1 + +local Font = nil +local function font() + if Font then return Font end + local ok, F = pcall(require, "src.render.Font") + if ok then Font = F end + return Font +end + +-- Black glyphs, because that is the only colour the Game Boy font sheets +-- have -- they are black on transparent, so setColor cannot lighten one. +-- Everything here is therefore laid out dark-on-light. +local function text(str, x, y) + local F = font() + if not F then return end + love.graphics.setColor(0, 0, 0, 1) + F.draw(str, math.floor(x), math.floor(y)) +end + +local function centred(str, y) + local F = font() + if not F then return end + text(str, (W - F.width(str)) / 2, y) +end + +-- ------- dex number -> the engine's own species key +-- +-- Built once, from the loaded data rather than from a list of names carried +-- here: a list would be a second place for the same 151 facts to live, and +-- would go stale against a mod that renames one. +local dexNames = nil + +local function speciesName(dex) + if not dex then return nil end + if not dexNames then + dexNames = {} + local ok, data = pcall(function() + return require("src.core.Game").data + end) + if ok and data and data.pokemon then + for key, def in pairs(data.pokemon) do + if type(def) == "table" and def.dex then dexNames[def.dex] = key end + end + end + end + return dexNames[dex] +end + +function StadiumScreen.new(game) + return setmetatable({ game = game, hold = 0, started = false }, StadiumScreen) +end + +-- Opaque: the loading screen owns the frame, so the map underneath is not +-- drawn and not paying for a render it cannot be seen through. +StadiumScreen.isOpaque = true + +function StadiumScreen:enter() + local ok, err = StadiumInstall.begin() + self.started = ok and true or false + if not ok then + StadiumInstall.status.state = "failed" + StadiumInstall.status.error = err + end +end + +function StadiumScreen:update() + local status = StadiumInstall.status + if status.state == "building" then + if not StadiumInstall.step() then + -- fell out of building: either finished or failed, both of which hold + -- for a moment so the player sees which + self.hold = 0 + end + return + end + self.hold = self.hold + 1 / 60 + -- a failure stays up longer, because it is the one the player has to read + local wait = (status.state == "failed") and StadiumScreen.HOLD * 4 + or StadiumScreen.HOLD + if self.hold >= wait then + if self.game and self.game.stack and self.game.stack:top() == self then + self.game.stack:pop() + end + end +end + +-- Let the player out of a build that has gone wrong, or that they would +-- rather not wait for. Cancelling leaves the packs unbuilt, so the STADIUM +-- rungs stay off the row until the next boot offers again -- which is +-- honest, and better than a half-built set. +function StadiumScreen:onKeyPressed(key) + if key == "escape" or key == "x" or key == "backspace" then + StadiumInstall.cancel() + if self.game and self.game.stack and self.game.stack:top() == self then + self.game.stack:pop() + end + return true + end + return false +end + +function StadiumScreen:draw() + local status = StadiumInstall.status + love.graphics.setColor(0.93, 0.94, 0.90, 1) + love.graphics.rectangle("fill", 0, 0, W, H) + + centred("POKEMON STADIUM", 24) + centred("BATTLE MODELS", 34) + + if status.state == "failed" then + centred("COULD NOT BUILD", 62) + local why = tostring(status.error or "unknown"):sub(1, 24) + centred(why, 76) + centred("STADIUM IS OFF", 96) + return + end + + local done = status.done or 0 + local total = status.total or StadiumInstall.COUNT + local frac = (total > 0) and (done / total) or 1 + if status.state == "done" then frac = 1 end + + -- the bar: a dark frame with a dark fill, so it reads on the light plate + local bx, by, bw, bh = 24, 66, W - 48, 9 + love.graphics.setColor(0.06, 0.05, 0.09, 1) + love.graphics.rectangle("fill", bx - 1, by - 1, bw + 2, bh + 2) + love.graphics.setColor(0.80, 0.80, 0.78, 1) + love.graphics.rectangle("fill", bx, by, bw, bh) + love.graphics.setColor(0.06, 0.05, 0.09, 1) + love.graphics.rectangle("fill", bx, by, math.floor(bw * frac + 0.5), bh) + + if status.state == "done" then + centred("READY", 84) + else + local name = speciesName(status.species) + centred(("%d/%d"):format(done, total), 84) + if name then centred(name, 96) end + centred("BUILDING FROM ROM", 112) + end + love.graphics.setColor(1, 1, 1, 1) +end + +-- ------- when this comes up +-- +-- The first frame the player is actually IN the world, rather than at boot. +-- Two reasons. The engine has its own launcher and ROM importer before the +-- game starts, and pushing over those would be fighting them for the screen. +-- And `Game.data` has to be loaded for the species names above to resolve. +-- +-- Asked once. If the player cancels, or there is no ROM, this does not come +-- back until the next run -- a loading screen that reappears every time you +-- step outside would be worse than no stadium models. +local asked = false + +function StadiumScreen.maybePush() + if asked then return false end + local ok, Game = pcall(require, "src.core.Game") + if not (ok and Game and Game.stack and Game.overworld) then return false end + if Game.stack:top() ~= Game.overworld then return false end + asked = true + if not StadiumInstall.pending() then + -- Say where to put a cartridge, ONCE, and only when there is nothing to + -- build from and nothing already built. The two STADIUM rungs are simply + -- absent in that case (ModSetting.setGate), which is the right thing for + -- a row to do and tells the player nothing about why -- and the answer + -- they need is an absolute path that depends on how the game was + -- installed, so it cannot be written into the options help text. + if not StadiumInstall.available() then + V.mod.log:info("stadium: no Pokemon Stadium ROM found, so the STADIUM " + .. "battle rungs are off. Put one (.z64/.n64/.v64) in " + .. "%s and restart.", StadiumInstall.romHint()) + end + return false + end + Game.stack:push(StadiumScreen.new(Game)) + return true +end + +-- named for the suite, which drives the screen without a boot +function StadiumScreen._reset() + asked = false +end + +return StadiumScreen diff --git a/lib/StadiumStage.lua b/lib/StadiumStage.lua new file mode 100644 index 0000000..12582cb --- /dev/null +++ b/lib/StadiumStage.lua @@ -0,0 +1,330 @@ +-- STADIUM B: the two discs the fight is staged on. +-- +-- The 3D-BTL row's fourth rung. Where STADIUM A puts the Pokemon Stadium +-- models on the MAP -- real ground, whatever the route happens to look like +-- -- this puts them on two platforms against the sky and draws no map at all. +-- +-- ------- why this is a rung and not a fix +-- +-- Staging on the map is the better picture when the map cooperates, and it +-- often does not. Half of Kanto's interiors are furniture; a cave floor can +-- be nothing but two-cell corridors; some maps have nowhere a fight can be +-- SEEN from a low camera and are declined outright (see BattleArena), which +-- drops the player back to the flat battle screen with no warning. And even +-- where a spot exists, the ground behind the foe is a hedge or a shop counter +-- rather than anything a battle wants behind it. +-- +-- Discs have none of those problems, because the stage is CARRIED rather than +-- found: it works on every map, in every building, at every step, and the +-- framing is the same every time. What it gives up is the thing STADIUM A is +-- for -- fighting somewhere real. +-- +-- ------- what stays +-- +-- The sky, and the light. A battle outdoors is under the hour's own sky, with +-- its bands and its sun or moon (Voxel3D.beginScene paints it when handed a +-- dressed one); a battle in a cave or a room is under that place's own void +-- and its own neutral light, exactly as the map itself would be. So the mode +-- is abstracted from the GROUND, not from the world -- walk into a cave at +-- midnight and the fight looks like a cave at midnight. +-- +-- And the framing. The camera, the pins, the HUDs, the text box, the move +-- animations and the depth of field are all identical, because every one of +-- them is hung off the arena's CELLS rather than off what is under them. That +-- is the same reason STADIUM A could be an option on the mode rather than a +-- second mode, and it is why this file is a few hundred lines and not a few +-- thousand. + +-- the mod namespace (see main.lua): V.require loads a sibling module +local V = ... + +local Mat4 = V.require("Mat4") +local Voxel3D = V.require("Voxel3D") + +local StadiumStage = {} + +local floor = math.floor +local sin, cos = math.sin, math.cos +local pi = math.pi + +-- ------- the shape of a disc +-- +-- Radius in world pixels, where a map cell is 16 and the two mons stand three +-- cells apart. +-- +-- A PLATFORM FOLLOWS WHAT STANDS ON IT rather than being one fixed size, +-- because the set's footprints run nearly tenfold: a Caterpie is under four +-- world pixels across and Moltres, wings out, is twenty-six. One radius for +-- both is either a dinner plate under the caterpillar or a doily under the +-- bird. +-- +-- RADIUS is the floor, and it is the number most species land on -- it is a +-- little over the map cell a Pokemon is sized to cover, which is the +-- proportion the Game Boy's own battle platforms have. PAD is the margin +-- around a mon that needs more than that, and MAX_RADIUS stops Moltres from +-- being handed something the frame cannot hold. +-- +-- These are the FULL radius, out to where the fade has finished; the solid +-- centre a Pokemon actually stands on is SOLID of it. PAD is sized so that a +-- mon's own footprint fits inside that centre rather than out over the +-- stipple -- 1.8 x 0.70 is a little over 1.25, so a big Pokemon still has +-- solid ground under its edges. +StadiumStage.RADIUS = 18 +StadiumStage.MAX_RADIUS = 34 +StadiumStage.PAD = 1.8 + +-- The platform for a mon of this footprint. `r` may be nil (nothing standing +-- there yet, which is every frame of the send-out before the model appears), +-- and then the platform is the plain one -- it has to be there BEFORE the +-- Pokemon lands on it. +function StadiumStage.radiusFor(r) + local want = (r or 0) * StadiumStage.PAD + if want < StadiumStage.RADIUS then return StadiumStage.RADIUS end + if want > StadiumStage.MAX_RADIUS then return StadiumStage.MAX_RADIUS end + return want +end + +-- Per-vertex shading, in the same terms StadiumRig lights the models with, so +-- a disc and the Pokemon standing on it agree about where the sun is. Fitted +-- to Voxel3D.FACE_SHADE's six values: the constant is the average, and each +-- axis term is half the spread between that axis's two faces. +local SHADE_BASE = 0.7725 +local SHADE_X = 0.06 +local SHADE_Y = 0.225 +local SHADE_Z = 0.11 + +local function shadeFor(nx, ny, nz) + local s = SHADE_BASE + nx * SHADE_X + ny * SHADE_Y + nz * SHADE_Z + if s < 0.30 then return 0.30 end + if s > 1.00 then return 1.00 end + return s +end + +-- ------- the texture +-- +-- The platform is a FLAT painted disc that fades out at its rim -- no rim +-- wall, no thickness, the whole thing carried in one texture on one quad +-- lying on the ground plane. That is what the Game Boy's own battle +-- platforms are, and it is what keeps the stage from competing with the +-- Pokemon standing on it. +-- +-- ------- why the fade is DITHERED +-- +-- The scene shader discards any texel under half alpha outright (it has to: +-- that is what keeps a sprite's transparent corners out of the depth buffer). +-- So a smooth alpha ramp does not fade -- it comes out as a hard circle cut +-- at wherever the ramp crosses 0.5, which is the one thing this must not be. +-- +-- The fade is therefore an ORDERED DITHER baked into the texture's alpha: +-- every texel is fully on or fully off, and the proportion that are on falls +-- away toward the rim. It is the same trick the sky already uses for its +-- bands (Sky.DITHER), it needs no shader change and so risks nothing in any +-- other pass, and on a mode built out of visible texels it reads as intended +-- rather than as a limitation. +-- +-- The COLOUR is deliberately neutral. Everything the shader does to it after +-- this is the environment's: Voxel3D.tint carries the hour outdoors and the +-- room's own flat light indoors, and the shadow pass darkens whatever the +-- Pokemon standing on it occludes. So one texture is a sunlit platform, a +-- dusk platform and a cave platform, without a variant for each. +StadiumStage.TEX = 128 + +-- Where the solid centre ends, as a fraction of the disc's radius. Inside +-- this everything is opaque; from here to the rim the dither thins out. +StadiumStage.SOLID = 0.76 + +local TOP = { 0.74, 0.71, 0.63 } +local TOP_ALT = { 0.67, 0.64, 0.57 } + +local texture = nil + +-- A small deterministic scatter, for the surface itself. Not a random one: an +-- authored constant that happens to look unpatterned is worth more here than +-- a seed, because it can never change under a different Lua. +-- +-- Quantised into blocks, so the surface reads as TEXELS rather than as noise. +-- Per-pixel it came out as a fine mottle that fought the dithered rim for +-- attention -- and the rim is the thing worth looking at. At this size the +-- grain is roughly the size of the voxels everywhere else in the mode. +StadiumStage.GRAIN = 4 + +local function grain(x, y) + local bx = (x - x % StadiumStage.GRAIN) / StadiumStage.GRAIN + local by = (y - y % StadiumStage.GRAIN) / StadiumStage.GRAIN + local v = (bx * 37 + by * 71 + ((bx * by) % 13) * 17) % 100 + return v < 34 +end + +-- The 8x8 ordered (Bayer) matrix, as thresholds in 0..63. Ordered rather than +-- random because a random dither crawls: this pattern is fixed in the +-- texture, so the fade holds still while the camera drifts across it. +local BAYER = { + { 0, 32, 8, 40, 2, 34, 10, 42 }, + { 48, 16, 56, 24, 50, 18, 58, 26 }, + { 12, 44, 4, 36, 14, 46, 6, 38 }, + { 60, 28, 52, 20, 62, 30, 54, 22 }, + { 3, 35, 11, 43, 1, 33, 9, 41 }, + { 51, 19, 59, 27, 49, 17, 57, 25 }, + { 15, 47, 7, 39, 13, 45, 5, 37 }, + { 63, 31, 55, 23, 61, 29, 53, 21 }, +} + +function StadiumStage.texture() + if texture ~= nil then return texture or nil end + local ok, img = pcall(function() + local n = StadiumStage.TEX + local data = love.image.newImageData(n, n) + local half = (n - 1) / 2 + local solid = StadiumStage.SOLID + for y = 0, n - 1 do + local dy = (y - half) / half + for x = 0, n - 1 do + local dx = (x - half) / half + local d = (dx * dx + dy * dy) ^ 0.5 + -- how much of this texel's neighbourhood should survive: everything + -- inside the solid core, nothing past the rim, and a smooth ramp + -- between the two that the dither turns into a stipple + local cover + if d <= solid then + cover = 1.0 + elseif d >= 1.0 then + cover = 0.0 + else + local t = (d - solid) / (1.0 - solid) + cover = 1.0 - t * t * (3 - 2 * t) -- smoothstep, falling + end + local threshold = (BAYER[y % 8 + 1][x % 8 + 1] + 0.5) / 64 + local a = (cover > threshold) and 1 or 0 + local c = grain(x, y) and TOP_ALT or TOP + data:setPixel(x, y, c[1], c[2], c[3], a) + end + end + local image = love.graphics.newImage(data) + -- nearest, like every other texture in this mode: the grain and the + -- stipple are both meant to read as texels. Clamped rather than + -- repeating now that one texture covers the whole disc. + image:setFilter("nearest", "nearest") + image:setWrap("clampzero", "clampzero") + return image + end) + texture = (ok and img) or false + return texture or nil +end + +-- ------- the mesh +-- +-- One quad, lying flat on the ground plane, spanning -1..1 in x and z with +-- the whole texture stretched across it. The DISC is the texture's business, +-- not the geometry's -- everything outside the painted circle is alpha the +-- shader discards -- which is what "a flat texture that fades out at the +-- edges" means and what makes this four vertices rather than a hundred and +-- fifty. +-- +-- Shaded as a face pointing straight up, because it is one. + +local mesh = nil + +local function build() + local s = shadeFor(0, 1, 0) + local verts = { + { -1, 0, -1, 0, 0, s }, + { 1, 0, -1, 1, 0, s }, + { 1, 0, 1, 1, 1, s }, + { -1, 0, 1, 0, 1, s }, + } + return Voxel3D.newMesh(verts, { 1, 2, 3, 1, 3, 4 }) +end + +function StadiumStage.mesh() + if mesh == nil then mesh = build() or false end + return mesh or nil +end + +function StadiumStage.invalidate() + if texture and texture.release then pcall(texture.release, texture) end + if mesh and mesh.release then pcall(mesh.release, mesh) end + texture, mesh = nil, nil +end + +-- How far under the ground plane the disc actually sits. A hair, and only so +-- that a flat-footed Pokemon's sole -- which is AT the ground plane -- is not +-- coplanar with it and left to the depth buffer's mercy. +StadiumStage.SINK = 0.06 + +-- Where one disc sits: centred on a cell, at the ground plane, so a Pokemon +-- placed at that same height stands ON it rather than in it. +function StadiumStage.matrix(x, groundY, z, radius) + radius = radius or StadiumStage.RADIUS + return Mat4.mul(Mat4.translate(x, groundY - StadiumStage.SINK, z), + Mat4.scale(radius, 1, radius)) +end + +-- The two platforms this frame, as (side, matrix) -- shared by the camera's +-- pass and the sun's, so the two can never disagree about where they are. +local function each(arena, groundY, fn) + local ok, Stadium = pcall(V.require, "Stadium") + for _, side in ipairs({ "enemy", "player" }) do + local cell = arena[side] + if cell then + local footprint = ok and Stadium and Stadium.footprint(side) or nil + fn(StadiumStage.matrix(cell[1], groundY, cell[2], + StadiumStage.radiusFor(footprint))) + end + end +end + +-- ------- the synthetic arena +-- +-- STADIUM B does not search the map, because it does not stand on it. The +-- arena is the same WIDE shape every other staged fight uses -- so the two +-- cells are three apart down the middle and BattleCam frames them exactly as +-- it always has -- just placed at a fixed spot rather than a found one. +-- +-- Away from the origin on purpose. The coordinates run through the camera +-- solve, the sun's frustum fit and the projection to Game Boy pixels, and +-- putting a stage at (0, 0) is the kind of thing that hides a sign error for +-- months. +StadiumStage.ORIGIN = { 16, 16 } + +function StadiumStage.arena(map) + local BattleArena = V.require("BattleArena") + local arena = BattleArena.at(StadiumStage.ORIGIN[1], StadiumStage.ORIGIN[2], + "wide") + if not arena then return nil end + -- the map is carried for its SKY and its palette only -- what kind of place + -- the fight is happening in -- never for its geometry + arena.map = map + arena.discs = true + return arena +end + +-- ------- the draws + +-- The discs, in the main pass. No wireframe: everything else in this frame is +-- built a unit per voxel and wears the seams that fall out of that, and a +-- disc is a turned solid with no grid to draw. +function StadiumStage.draw(arena, groundY) + if not (arena and arena.discs) then return end + local m = StadiumStage.mesh() + local tex = StadiumStage.texture() + if not (m and tex) then return end + Voxel3D.seams(false) + Voxel3D.glass(false) + each(arena, groundY, function(matrix) Voxel3D.draw(m, tex, matrix) end) + Voxel3D.glass(true) + Voxel3D.seams(true) +end + +-- And into the sun, so the two Pokemon put real shadows on the platforms they +-- are standing on. Without this the shadow map is empty where the discs are +-- and a mon casts onto nothing at all -- which, with no ground behind it +-- either, reads as the pair floating. +function StadiumStage.cast(shadowMap, arena, groundY) + if not (arena and arena.discs and shadowMap) then return end + local m = StadiumStage.mesh() + local tex = StadiumStage.texture() + if not (m and tex) then return end + each(arena, groundY, function(matrix) shadowMap.draw(m, tex, matrix) end) +end + +return StadiumStage diff --git a/lib/Voxel3D.lua b/lib/Voxel3D.lua index 5bee511..a15f265 100644 --- a/lib/Voxel3D.lua +++ b/lib/Voxel3D.lua @@ -1159,6 +1159,30 @@ function Voxel3D.seams(on) on and VoxelGrid.DARK or 0) end +-- ADDITIVE for the length of a draw, or nil to put the pass back the way +-- it was found. +-- +-- Exactly one thing asks for this: the flame and gas primitives on a +-- STADIUM battle model (Charmander's tail, Weezing's cloud -- see +-- StadiumRig). Those are light, not surface: they are drawn over a body +-- that is already in the depth buffer and they must ADD to it rather than +-- replace it, or the flame comes out as an opaque orange sticker. +-- +-- Depth WRITES go off with the blend, and for the usual reason -- a +-- translucent thing that wrote depth would punch whatever comes after it +-- out of the frame. The test stays on, so a flame behind a tree is still +-- behind the tree. +function Voxel3D.blend(mode) + if not active then return end + if mode == "add" then + pcall(love.graphics.setBlendMode, "add", "alphamultiply") + pcall(love.graphics.setDepthMode, "lequal", false) + else + pcall(love.graphics.setBlendMode, "alpha", "alphamultiply") + pcall(love.graphics.setDepthMode, "lequal", true) + end +end + -- Whether what is drawn next may consult the glass mask. false for the -- length of a sprite-sheet pass, true to put it back. -- diff --git a/lib/VoxelScene.lua b/lib/VoxelScene.lua index 0e76ef2..f7abea3 100644 --- a/lib/VoxelScene.lua +++ b/lib/VoxelScene.lua @@ -865,6 +865,16 @@ local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh, ShadowMap.draw(BattleBillboard.mesh(), card.tex, ShadowMap.snug(card.model)) end ShadowMap.sprites(false) + -- and the STADIUM models, outside the sprite flag and un-snugged, for + -- the reasons the flat battle pass gives (BattleScene.castShadows): + -- these are geometry, not cut-outs + pcall(function() + local stageArena, stageY = V.require("OverworldBattle").stage() + if stageArena and stageArena.discs then + V.require("StadiumStage").cast(ShadowMap, stageArena, stageY or 0) + end + V.require("Stadium").cast(ShadowMap) + end) ShadowMap.finish(sig) end @@ -1072,6 +1082,24 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor, eyes) Voxel3D.draw(BattleBillboard.mesh(), card.tex, card.model, BattleBillboard.PULL) end + -- and, on the STADIUM rungs, the models -- the same skinned meshes the + -- flat pass and the sun already used this frame, drawn again through + -- THIS eye. Unlike the cards there is nothing per-eye about them: a + -- model faces its opponent, not the viewer, so both eyes see the same + -- pose from their own seats, which is what makes it read as solid. + -- + -- On STADIUM B the platforms come with them. In a headset the world is + -- still drawn -- the player is standing IN it, which is the whole point + -- of the headset, so the rung's "no map" does not apply here -- and the + -- discs then read as a stage set down on the ground, which is what they + -- are. + pcall(function() + local stageArena, stageY = V.require("OverworldBattle").stage() + if stageArena and stageArena.discs then + V.require("StadiumStage").draw(stageArena, stageY or 0) + end + V.require("Stadium").draw(BattleBillboard.PULL) + end) if battleTex.flash then Voxel3D.flatten(nil) end -- and the MOVE ANIMATIONS, standing on the same arena: the -- engine's own effects layer on the plane through both cells diff --git a/main.lua b/main.lua index cc062c3..9fd4a6d 100644 --- a/main.lua +++ b/main.lua @@ -200,6 +200,14 @@ mod.content.render_pipelines:register("voxel", { -- and the whole battle. Ahead of the active() gate below, because a 3D -- battle does not require the free-roam mode to be switched on. OverworldBattle.update(dt) + -- The one-time build of the Pokemon Stadium battle models out of the + -- player's own ROM, if there is one to build from and it has not been + -- done (see StadiumInstall). Rides this hook for the same reason the + -- battle does -- it is the tick that runs whatever is on the stack -- and + -- asks exactly once, on the first frame the player is actually in the + -- world, so it is never fighting the engine's own launcher for the + -- screen. + pcall(function() V.require("StadiumScreen").maybePush() end) -- The horde, on the same always-running tick and for the same reason: -- it owns no pass of the frame, it is a MODE over the overworld, and -- it has to keep thinking while a warp's wipe covers the screen (the @@ -422,7 +430,15 @@ local SETTINGS = { -- decide nothing there and a dead switch on the menu reads as broken. { OverworldBattle.setting, "Fight on the map: the battle draws over the nearest clear ground, " - .. "shot over the shoulder with a slow parallax drift.", + .. "shot over the shoulder with a slow parallax drift. 2D-3D stands " + .. "the game's own pics up on their tiles. STADIUM A replaces them with " + .. "the Pokemon Stadium battle models, animated, playing the animation " + .. "the move being used actually calls for. STADIUM B stands those same " + .. "models on two discs against the sky instead of on the map, which " + .. "works everywhere -- including the caves and shop floors that have " + .. "nowhere to stage a fight. The STADIUM rungs only appear once the " + .. "models have been built: drop a Pokemon Stadium (US) ROM in the " + .. "baseroms folder and restart.", when = function() return not VR.enabled() end, full = true }, -- Only offered while a fight can actually be staged on the map: with 3D-BTL -- off the engine draws the classic screen, which is this row's ON already, @@ -496,7 +512,7 @@ mod.options:define(schema) -- 5 V-GRID toggle the wireframe (new) -- 6 T-SHIFT cycle the blur ladder (was 9) -- 7 V-CURVE cycle the horizon bend (new) --- 8 3D-BTL toggle overworld battles (new) +-- 8 3D-BTL cycle overworld battles (new) -- 9 WATER cycle the water reflections (new; 9 was T-SHIFT's old key) -- -- Only 6 arrives by the documented route. Game:keypressed answers the diff --git a/manifest.json b/manifest.json index bddd212..7b63f85 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,7 @@ { "id": "DRAMATIC_SHAPE", "name": "Dramatic Shape Voxel Mod", - "version": "1.5.5", + "version": "1.6.0", "api": 2, "entry": "main.lua", "profile": "content", @@ -15,6 +15,6 @@ "engine_internals" ], "affects_link": false, - "description": "A full 3D diorama overworld: extruded terrain, depth-buffered occlusion, voxel characters and a tilt-shift miniature pass -- and battles fought on the map itself, shot over the shoulder at the nearest clear ground with a slow parallax drift and a depth-of-field pass. Water reflects the sky, the sun, the moon and -- through a screen-space ray march -- the shoreline standing behind it. Registers two render pipelines and claims hotkeys 3, 5, 6, 7, 8 and 9 -- 3 and 5 displace the engine's TILT and GBC FX keys, both still reachable on the OPTIONS menu. Presentational only: it changes what a battle is drawn over, never where anybody stands.", + "description": "A full 3D diorama overworld: extruded terrain, depth-buffered occlusion, voxel characters and a tilt-shift miniature pass -- and battles fought on the map itself, shot over the shoulder at the nearest clear ground with a slow parallax drift and a depth-of-field pass. Water reflects the sky, the sun, the moon and -- through a screen-space ray march -- the shoreline standing behind it. The 3D-BTL row also offers two STADIUM rungs, which replace the flat battle pics with the Pokemon Stadium battle models -- all 151 species, animated, playing the animation the move being used calls for -- either on the map or on two discs against the sky; those need a Pokemon Stadium (US) ROM of your own dropped in a baseroms/ folder, and build themselves out of it on first run. Registers two render pipelines and claims hotkeys 3, 5, 6, 7, 8 and 9 -- 3 and 5 displace the engine's TILT and GBC FX keys, both still reachable on the OPTIONS menu. Presentational only: it changes what a battle is drawn over, never where anybody stands.", "github": "DramaticShape/DramaticShapeVoxelMod" } diff --git a/mod.card b/mod.card index d3ac85c..2b60209 100644 --- a/mod.card +++ b/mod.card @@ -10,7 +10,8 @@ return { changed = { "with VOXEL on, the overworld draws as 3D geometry instead of flat tiles", "occlusion comes from a depth buffer rather than a y-sort, so buildings really hide what is behind them", - "with 3D-BTL on, a battle draws over the map's nearest clear ground instead of over a white field", + "with 3D-BTL on 2D-3D, a battle draws over the map's nearest clear ground instead of over a white field", + "with 3D-BTL on STADIUM A or STADIUM B, the same fight is staged with the Pokemon Stadium battle models in place of the flat pics -- all 151 species, skinned and animated, playing the animation the move being used actually calls for. A stands them on the map; B stands them on two discs against the sky, which works on every map including the caves and shop floors that have nowhere to stage a fight", "the battle's text box and menu are frosted glass over that ground rather than an opaque white slab, on the same panels the HUDs sit on", "the map's NPCs are culled for the length of a battle, so the wipe plays over an empty map", "a battle's letterbox voids go black rather than white, because the battle canvas is no longer white", @@ -31,7 +32,8 @@ return { "V-GRID on hotkey 5 and V-CURVE on hotkey 7", "Q and E zoom whichever camera is in front of you -- the third-person boom, a staged battle's lens, or the engine's own survey zoom on an orbit rung -- alongside the mouse wheel, a two-finger pinch, and the pad's left and right stick clicks (out and in). 1ST claims none of them: the eye is in the player's head and there is no distance to change", "WATER on hotkey 9 (FULL / SKY / OFF, FULL by default): the water surface becomes a field of pixel-tall voxel columns rising and falling as waves, reflecting the sky, the sun, the moon and the cast standing beside it -- and, on FULL, the shoreline, trees and buildings behind it, by a screen-space ray march", - "3D-BTL on hotkey 8 (ON / OFF, on by default), battles fought on the world map", + "3D-BTL on hotkey 8 (2D-3D / STADIUM A / STADIUM B / OFF, 2D-3D by default), battles fought on the world map -- 2D-3D stands the game's own pics up on their tiles, and both STADIUM rungs replace them with the Pokemon Stadium battle models. The STADIUM rungs are only on the row once those models have been built (see below)", + "the STADIUM animations are driven from the fight: a move plays the animation that species' own battle table names for it (so DIG really does put Diglett into the ground), damage plays the hit reaction, fainting plays the faint and holds there, and a send-out plays the entrance. The eyes blink and go dizzy, and Charmander's tail flame and Weezing's gas are drawn over the body", "BACK SPRITES options row (OFF / ON, off by default), which keeps your own Pokemon on the battle menu in its classic slot while the foe stands out on the map", "VR options row (OFF / ON, off by default): PCVR through OpenXR on Windows -- the diorama as a head-tracked tabletop model presented at the rung's own angle and framing on the orbit rungs, life-size first person on 1ST, a staged battle snapping the headset (through a fade to black) into the flat game's own over-the-shoulder seat at life scale, a voxel Pokedex flush along the left controller in first person and in battles (menus, dialogs and the 2D battle screen on its screen; the diorama does without it), the sky and its sun and moon anchored in space (bands, GBC dither and twilight glow alike -- nothing in the sky reacts to the head), the floating panel wearing the GB frame near-square rather than the whole monitor-wide window (scaled into the headset, so the picture and its ratio are identical at every window size, fullscreen included), the window as mirror; needs a runtime (SteamVR/Oculus/WMR) and the mod on a real folder", "VR controllers (Touch/Index/WMR, rebindable in the runtime): left stick moves, A/B are A/B, either trigger is START, left stick click steps the VOXEL angle ladder exactly as the 3 key and SELECT do; in 1ST the right stick snap-turns 45 degrees a flick; in the diorama the right stick zooms and a squeezed grip drags the table's height; no controller button leaves VR -- that is the VR row's job", @@ -49,6 +51,9 @@ return { "WATER on FULL ray-marches the depth buffer per water pixel, so a map that is mostly sea costs real fill rate on a weak GPU -- SKY is the same look minus the ray march, and OFF is the flat water", "a screen-space reflection can only reflect what is in the frame: a tree just off the top edge is not in the water below it, and a ray that runs off the side fades into the sky rather than ending on a line", "a map with no 3x6 clearing falls back to a 1x4 one, and a map with neither draws the plain battle screen", + "the STADIUM rungs need the Pokemon Stadium battle models, and the mod ships none of them -- they are that game's data. Drop a Pokemon Stadium (US) ROM in a baseroms/ folder beside the game and the 151 models are built out of it on a loading screen the first time it runs, in about ten seconds, into the save directory; until then the two rungs are simply not on the row. Once built, a rung declines per POKEMON rather than per battle: a species with no pack, a standing substitute doll, and the trainer's own pic before the send-out each fall back to the flat card on that side alone, with the other side keeping its model", + "the STADIUM rungs size a Pokemon by its own model against the set's median, with the range compressed -- the authored heights span sixteenfold, from Caterpie to Gyarados, and a shared over-the-shoulder shot cannot hold that. The order and the feel of the differences survive; the literal ratios do not", + "three species -- Exeggutor, Tangela and Magmar -- have standby loops that are corrupt in the source extraction, and are held at their bind pose so they stand still rather than coming apart", "the arena is where the CAMERA goes -- nobody is moved, so a fight staged across the map is a shot of that ground, not a trip to it", "the battle backdrop renders at the GB's 160x144 to match the pics composited over it, so it is chunkier than the free-roam pass", "menus and cutscenes are unaffected -- outside a battle the mode only draws the free-roam overworld", @@ -71,6 +76,7 @@ return { }, credits = { { who = "pret/pokered", for_ = "the tile and sprite data the geometry is derived from" }, + { who = "the Pokemon Stadium decompilation effort", for_ = "the battle model format STADIUM's models are extracted from (see model_extract/)" }, { who = "The Khronos Group", for_ = "the OpenXR loader shipped unmodified in assets/vr (Apache-2.0; full license text alongside the DLL)" }, }, compat = { engine = ">=0.1.37 <2.0.0", modApi = 2 }, diff --git a/model_extract/README.md b/model_extract/README.md new file mode 100644 index 0000000..061e3d1 --- /dev/null +++ b/model_extract/README.md @@ -0,0 +1,168 @@ +# Pokemon Stadium (US) — battle model export + +All 151 battle Pokemon plus 64 other models from the same segment, in standard +formats. Regenerate straight from the ROM — stdlib only, no `make init`, no +splat, no crunch64: + +```bash +model_extract/pipeline/build.py +``` + +Put a US 1.0 ROM in [baseroms/](baseroms/) (`.z64`, `.n64` or `.v64`), or pass +`--rom=PATH`. See [pipeline/README.md](pipeline/README.md) for the module layout, +how the ROM is unpacked, and the generated-effects notes. + +``` +viewer.html browse everything in the browser — open it directly +manifest.json every model + what each of its animations is used for +moves.json all 165 moves + the animation each species plays for them +glb/025_pikachu.glb glTF 2.0 binary: mesh, skeleton, skin, animations, textures +glb/x152_model.glb non-Pokemon models from the same segment (props, trophies…) +textures/025_pikachu/ the same textures as loose PNGs, named _x.png +js/ viewer payloads, one per model, plus index.js and moves.js +``` + +`viewer.html` has a filterable picker for every model plus prev/next/random, a +**move picker** that jumps to whichever animation the current Pokemon plays for +that move, per-animation playback with a frame scrubber, an eye/texture-animation +selector, and texture/lighting/wireframe/skeleton toggles. It reads `js/`, not +`glb/`, because browsers block `fetch` of local files from `file://` — script +injection is what lets the page work when you just double-click it. + +Sizes: 73 MB `glb/`, 54 MB `js/`, 7.4 MB `textures/`. Two flags if you want less: +`--no-js` skips the viewer payloads and `viewer.html` (leaving the glTF export +alone), and `--manifest-only` rebuilds just `manifest.json`. + +`.glb` files are self-contained and open directly in Blender, Maya, Unity, Unreal, +three.js, Godot, Windows 3D Viewer, macOS Quick Look, and https://gltf-viewer.donmccurdy.com. +Source file `N.bin` holds species `N + 1`. + +## Conventions + +- Y up, +Z front, right-handed — glTF standard. +- Animations are authored at **30 fps**; keyframe times are `frame / 30`. +- Units are game units. Models are authored 10x and scaled down by the + `model_root` node, matching the geo layout's scale command. +- Textures are `CLAMP_TO_EDGE`, materials are `alphaMode: MASK` with cutoff 0.5 + (N64 RGBA5551 has one bit of alpha). `doubleSided` follows the display list's + cull mode. + +## Skeleton + +The game keeps bone scale *out* of the matrix chain (`func_800143C0` in +[src/12D80.c](../src/12D80.c)): scale accumulates in its own stack, a bone's local +translation is pre-multiplied by the parent's accumulated scale, and the +accumulated scale is applied to the rows of the finished world matrix only at +draw time. glTF node TRS instead propagates scale multiplicatively to children, +so a 1:1 node mapping would be wrong wherever a non-uniformly scaled bone has +descendants. + +Each game bone is therefore exported as two nodes: + +| node | role | +| --- | --- | +| `boneNN` | pivot: `translation = t * accScale(parent)`, `rotation = R`, scale 1 | +| `boneNN_scale` | leaf child holding `scale = accScale(bone)`, so it cannot propagate | + +The skin binds to the `boneNN_scale` nodes, whose world matrices then equal the +game's draw matrices exactly. Vertices are already in bone-local space and each is +rigidly bound to one bone, so all inverse bind matrices are identity. + +This was verified by parsing each exported `.glb` back and diffing every joint +matrix against a reference implementation of the game's own math, over the bind +pose and four sampled frames of every animation. Worst-case disagreement is +~1e-2 game units on models spanning 20–40 units, entirely from storing rotations +as spec-normalised `SHORT` quaternions. + +## Animation semantics + +Per-species battle data lives in `assets/us/70D3A0.bin`, 0xB90 bytes per species, +DMA'd into the battle system by `func_84302658` via the `D_80075BD0[species-1]` +pointer table. It is an array of 0x10-byte entries; byte 0 of each entry is an +index into that Pokemon's animation list and byte 1 indexes the auxiliary list: + +- **entries 0–164** — one per move, in the move ID order of + [oldnotes/stadium1/constants/move_constants.s](../oldnotes/stadium1/constants/move_constants.s). + Entry *n* gives the animation played when the Pokemon uses move *n + 1*. +- **entries 165+** — fixed battle contexts (idle, hit, faint, …). + +Every one of the 151 species' tables indexes only animations that exist in that +species' list, which is what confirms the layout. + +`manifest.json` reports, for each animation, the exact list of moves that trigger +it plus which context slots reference it. `moves.json` inverts that: every move, +and the animation each of the 151 species plays for it. + +One caveat when reading move data: the table is **dense**. Every species has a +row for every move, including moves it can never learn, and those unreachable +rows overwhelmingly point at the species' generic reaction animation — the same +one the `hit` slot uses. So "118 species play Thunderbolt" is an artifact, not a +fact about the game. `moves.json` marks each row with `differsFromDefault` and +gives a `speciesWithOwnAnimation` count per move; treat those as the signal. The `animationSlots` section carries an +`evidence` field per slot: + +- `code` — the battle code in `src/fragments/62` names the slot outright. +- `data` — inferred from what the referenced animation actually does, measured + across all 151 species. For example slot 167 is labelled `faint` because its + animation always ends far from the standing pose (the model drops to + 0.03–0.84x idle height, or leaves the frame entirely for fliers), while slot + 168's animation always ends at exactly idle height. + +`endBehavior` reports what the animation player does past the last frame +(`func_80016FBC`): every animation in the game wraps back to `loopStartFrame`, so +one-shots like `faint` are ended by the battle state machine switching animation, +not by the player clamping. glTF has no loop flag, so importers will loop clips by +default. + +The common layout, consistent across nearly every species: + +| animation | role | +| --- | --- | +| 0 | idle / standby loop (all 151 species) | +| 1 | second idle-length animation, rarely referenced by the context slots | +| 2 | hit / damage reaction (149–151 species across slots 166, 178–181) | +| 3 … n-3 | attack animations, selected per move | +| n-2 | faint (slots 167, 177) | +| n-1 | entrance / return-to-idle cycle (slots 168, 183) | + +## Texture animations (blinking, dizzy eyes) + +The second animation list in the model root is a *texture* animation, not a +skeletal one (`src/18140.c`). Geo command `0x23` carries a channel index at +offset `0x02`; when it is `>= 0`, `func_800176DC` replaces that material's +texture every frame from a per-frame stream of texture-table indices. + +Charmander's eyes are the clearest example — texture 2 is the open eye, 3 and 4 +are blink frames, and 5–7 are the dizzy swirl: + +| aux animation | frames | texture stream | +| --- | --- | --- | +| 0 | 10 | `2 2 3 3 4 4 4 3 3 2` — a blink | +| 2 | 122 | cycles `5 6 7` — confusion swirl | +| 4 | 18 | a slower blink | + +The viewer plays these. Each skeletal animation is paired with the texture +animation the battle table most often sets alongside it, and the `eyes` dropdown +overrides that. glTF 2.0 has no texture-swap animation channel, so this data +lives in `js/` and `moves.json` rather than the `.glb` — the `.glb` files carry +the first frame's texture on each material. + +## Known gaps + +- **Move effect visuals are not here.** Geo command `0x24` does not draw + anything: `func_80014CB8` just records an attachment point (an id plus a world + position) on the Pokemon, and the battle system spawns particles there. Ids + 1–14 are generic and used by nearly every species. So Charmander's tail flame, + beams, explosions and the like are drawn by the effect system in the battle + fragments and are not present in these model files — Charmander's texture set + contains eyes, claws, teeth and skin, and no flame. +- **The Poke Ball throw/open model was not found.** It is not in this segment, + no other `assets/us/**.bin` contains a model fragment, and scanning the ROM + ranges of fragments 62–64 for embedded model headers found none. What does + exist is Poke Ball *2D* artwork in fragment 29 + (`fragments/29/fragment29_unk_bin_*`, flagged in the splat yaml). The throw is + most likely built from raw display lists rather than a geo-layout model. +- Files 151–214 are exported as `x_model` with generic names. They are + props, trophies, minigame pieces and similar; only Surfing Pikachu (file 152, + the same 37-bone / 723-triangle rig as Pikachu) is named with confidence. They + carry no battle table, so their animations are left unnamed. diff --git a/model_extract/baseroms/.gitignore b/model_extract/baseroms/.gitignore new file mode 100644 index 0000000..0f17c87 --- /dev/null +++ b/model_extract/baseroms/.gitignore @@ -0,0 +1,5 @@ +baserom.z64 +*.z64 +*.n64 +*.v64 +*:Zone.Identifier diff --git a/model_extract/baseroms/README.md b/model_extract/baseroms/README.md new file mode 100644 index 0000000..21523cf --- /dev/null +++ b/model_extract/baseroms/README.md @@ -0,0 +1,25 @@ +# Put the ROM here + +`pipeline/build.py` looks for a Pokemon Stadium (US 1.0) ROM in this folder: + + model_extract/baseroms/baserom.z64 + +`.z64`, `.n64` and `.v64` byte orders are all accepted — the pipeline detects the +magic and normalises on load. Any ROM file dropped in this folder is picked up. + +Expected md5 of the US 1.0 ROM: `ed1378bc12115f71209a77844965ba50`. A different +ROM still runs, but the build prints a warning since the offsets are keyed to +this revision. + +Search order (first hit wins): + +1. `model_extract/baseroms/baserom.z64` +2. `model_extract/baseroms/us/baserom.z64` +3. `baseroms/us/baserom.z64` at the repo root — the location `make init` uses +4. any `*.z64` / `*.n64` / `*.v64` in this folder + +Or point at one explicitly: + + model_extract/pipeline/build.py --rom=/path/to/baserom.z64 + +The ROM is not included and is not tracked by git. diff --git a/model_extract/pipeline/README.md b/model_extract/pipeline/README.md new file mode 100644 index 0000000..ff9d9d4 --- /dev/null +++ b/model_extract/pipeline/README.md @@ -0,0 +1,93 @@ +# Export pipeline + +End-to-end: `baserom.z64` in, everything in `model_extract/` out. **Stdlib only** — +no `make init`, no splat, no crunch64, no build directory. + +```bash +model_extract/pipeline/build.py # finds the ROM automatically +model_extract/pipeline/build.py --rom=/path/to.z64 --out=/tmp/out +``` + +The ROM is looked for in `model_extract/baseroms/` first, so this folder stands +on its own; the repo's own `baseroms/us/` is the fallback. Search order: + +1. `model_extract/baseroms/baserom.z64` +2. `model_extract/baseroms/us/baserom.z64` +3. `baseroms/us/baserom.z64` at the repo root — where `make init` expects it +4. any `*.z64` / `*.n64` / `*.v64` sitting in `model_extract/baseroms/` + +`.z64`, `.n64` and `.v64` all work — the byte order is detected from the magic +and normalised on load. See [../baseroms/README.md](../baseroms/README.md). + +| flag | effect | +| --- | --- | +| `--only=3,91` | restrict to those model file numbers (fast iteration) | +| `--no-glb` | skip the glTF binaries and PNG dumps | +| `--no-js` | skip the viewer payloads and `viewer.html` | +| `--no-effects` | skip the generated fire/gas stand-ins | + +## Modules + +| file | does | +| --- | --- | +| `rom.py` | byte-order fixup (.z64/.v64/.n64), md5 check, archive unpacking, Yay0 and PERS-SZP decompression | +| `fragment.py` | FRAGMENT module → geo layout walk, F3DEX2 execution, textures, skeleton, animations | +| `battle.py` | per-species battle tables, move names, animation-context slot meanings | +| `glb.py` | glTF 2.0 binary writer | +| `effects.py` | **generated** fire/gas stand-ins (see below) | +| `build.py` | driver: ties it together, writes manifests | + +## Getting from ROM to models without the build system + +Three steps, all in `rom.py`: + +1. **Byte order.** `.z64` is native; `.v64` swaps byte pairs; `.n64` reverses + words. Detected from the magic and normalised on load. +2. **Archive.** The segment at `0x920000` starts with + `u32 tag, u32 0, u32 totalSize, u32 fileCount`, then one + `{u32 offset, u32 size, u32 pad[2]}` record per file. Only the top three + bytes of the first word are reliably zero — the model archive puts a nonzero + value in the low byte, which is the quirk `tools/unpack_asset.py` works + around too. +3. **Decompression.** Each entry is `PERS-SZP` (an 8-byte magic plus a header + size, wrapping a Yay0 stream). The Yay0 decoder is ~30 lines: a bitstream + where a 1 copies a literal byte and a 0 pulls a (distance, length) pair. + +Verified by decompressing all 215 entries and diffing against what +`make init` produces: **215/215 byte-identical**. + +The battle tables need one more hop — `D_80075BD0[species - 1]` lives in the main +code segment, so `Rom.vram_to_rom` converts `0x80075BD0` using the segment's +`start`/`vram` from the splat yaml. + +## Generated effects + +`effects.py` produces **original, procedurally generated** fire and gas. It is +not extracted game data, and everything it emits is tagged `generated: true` in +the manifest, the viewer payloads and the PNG filenames (`*_fx.png`). + +This exists because the real effects are not in the model files at all. Geo +command `0x08` attaches a callback (`func_80014A60` calls `node->unk_10`), and +the model supplies only two empty display lists and zeroed scratch buffers for +it to fill. The callback lives in another fragment and has not been ported, so +there is no flame mesh or flame texture to extract — Charmander's texture set is +eyes, claws, teeth and skin. + +The stand-ins are anchored to the exact bone the callback hangs off, so they sit +where the real effect would and follow the animation: + +| callback | species | stand-in | +| --- | --- | --- | +| `0x810000D8` | Charmander, Charmeleon, Charizard, Magmar, Moltres | tail/crest flame | +| `0x81000108` | Ponyta, Rapidash, Moltres wings | small flame | +| `0x810000E0` | Gastly (only) | gas cloud | + +Both are looping flipbooks built from tileable value noise, drawn on a pair of +crossed quads — glTF cannot billboard, so crossed quads are the portable way to +make them read from any angle. Sizes are expressed as a fraction of the model's +**height** and divided by the anchor bone's accumulated scale, so an effect comes +out the intended size wherever in the skeleton it hangs. Seeds derive from the +species number, so a given Pokemon always generates the same effect. + +In the viewer they draw in a second pass with depth writes off — additive for +fire, alpha for gas — and there is a *generated effects* toggle to hide them. diff --git a/model_extract/pipeline/battle.py b/model_extract/pipeline/battle.py new file mode 100644 index 0000000..9ed8ec3 --- /dev/null +++ b/model_extract/pipeline/battle.py @@ -0,0 +1,122 @@ +#!/usr/bin/env python3 +""" +Per-species battle data. + +`func_84302658` in src/fragments/62 DMAs a 0xB90-byte table per species out of +the 0x70D3A0 segment, addressed through the D_80075BD0 pointer table. It is an +array of 0x10-byte entries: byte 0 is an index into that Pokemon's animation +list, byte 1 indexes the auxiliary (texture) animation list. + + entries 0..164 one per move, so entry n drives move n + 1 + entries 165+ fixed battle contexts + +Every one of the 151 species' tables indexes only animations that species +actually has, which is what confirms the layout. +""" +import os +import struct + +STRIDE = 0xB90 +ENTRY = 0x10 +N_MOVES = 165 + +# `evidence` records how far each label can be trusted: +# code - the battle code in src/fragments/62 names the slot outright +# data - inferred from what the referenced animation does, measured over all +# 151 species +CONTEXT_SLOTS = { + 165: ('idle', 'code', + 'The standby loop. func_8432B0A4 restores this slot whenever the Pokemon ' + 'returns to neutral, and it resolves to animation 0 for all 151 species.'), + 166: ('hit', 'data', + 'Resolves to animation 2 for 149/151 species, the same animation slots ' + '178-181 use in the reaction paths.'), + 167: ('faint', 'data', + 'The referenced animation always ends far from the standing pose - the ' + 'model collapses to 0.03-0.84x its idle height, or leaves the frame ' + 'entirely for fliers.'), + 168: ('entrance', 'code+data', + 'The default slot in func_8430506C / func_8432AF70. The referenced ' + 'animation ends at exactly idle height, so it is a full cycle that ' + 'settles back into the standby pose.'), + 169: ('reaction_169', 'data', 'Resolves to the idle animation for 139/151 species.'), + 170: ('reaction_170', 'data', 'Split between the idle and hit animations.'), + 171: ('reaction_171', 'data', 'Resolves to the idle animation for 138/151 species.'), + 172: ('reaction_172', 'data', 'Resolves to the idle animation for 148/151 species.'), + 173: ('reaction_173', 'data', 'Resolves to the hit animation for 97/151 species.'), + 174: ('reaction_174', 'data', 'Resolves to the idle animation for 138/151 species.'), + 175: ('struggle', 'code', 'Passed as slot 0xAF to func_84305A74.'), + 176: ('idle_alt', 'code', + 'Substituted for the idle slot when battle flag 0x200 is set.'), + 177: ('faint_alt', 'data', 'Same animation as slot 167 for almost every species.'), + 178: ('flinch', 'code', + 'Used when the incoming move is one of the two listed in D_84384598.'), + 179: ('reaction_179', 'data', 'Resolves to the hit animation for all 151 species.'), + 180: ('reaction_180', 'data', 'Resolves to the hit animation for all 151 species.'), + 181: ('reaction_181', 'data', 'Resolves to the hit animation for all 151 species.'), + 182: ('reaction_182', 'data', + 'Resolves to animation 0 for 136 species and animation 1 for the other 15.'), + 183: ('entrance_alt', 'data', 'Same animation as slot 168 for every species.'), + 184: ('idle_return', 'code', 'Passed as slot 0xB8 to func_84305A74.'), +} + +MOVE_CONSTANTS = 'oldnotes/stadium1/constants/move_constants.s' + + +def load_move_names(repo_root='.'): + """Move IDs come from the repo's own extracted constants when available.""" + path = os.path.join(repo_root, MOVE_CONSTANTS) + names = {} + if os.path.exists(path): + for line in open(path, encoding='utf-8', errors='replace'): + # the file also carries an ABC_* section indexing moves alphabetically + # by their Japanese names; only the real move IDs are wanted + if ' EQU ' not in line or line.startswith('ABC_'): + continue + name, val = line.split(' EQU ') + val = val.split(';', 1)[0].strip() + if val: + names[int(val, 0)] = name.strip().replace('_', ' ').title() + return {i: names.get(i, f'Move {i}') for i in range(1, N_MOVES + 1)} + + +class BattleTables: + def __init__(self, rom): + from rom import BATTLE_DATA, PTR_TABLE_VRAM + self.rom = rom + self.base = BATTLE_DATA + self.ptr_table = rom.vram_to_rom(PTR_TABLE_VRAM) + + def offset(self, species): + raw = self.rom.u32(self.ptr_table + (species - 1) * 4) + return self.base + (raw & 0xFFFFFF) + + def rows(self, species): + """Returns [(animIndex, auxIndex)] for every entry, aux 0xFF -> -1.""" + o = self.offset(species) + out = [] + for e in range(STRIDE // ENTRY): + anim = self.rom.data[o + e * ENTRY] + aux = self.rom.data[o + e * ENTRY + 1] + out.append((anim, -1 if aux == 0xFF else aux)) + return out + + +SPECIES = {} +_NAMES = ( + "Bulbasaur Ivysaur Venusaur Charmander Charmeleon Charizard Squirtle Wartortle Blastoise " + "Caterpie Metapod Butterfree Weedle Kakuna Beedrill Pidgey Pidgeotto Pidgeot Rattata Raticate " + "Spearow Fearow Ekans Arbok Pikachu Raichu Sandshrew Sandslash NidoranF Nidorina Nidoqueen " + "NidoranM Nidorino Nidoking Clefairy Clefable Vulpix Ninetales Jigglypuff Wigglytuff Zubat " + "Golbat Oddish Gloom Vileplume Paras Parasect Venonat Venomoth Diglett Dugtrio Meowth Persian " + "Psyduck Golduck Mankey Primeape Growlithe Arcanine Poliwag Poliwhirl Poliwrath Abra Kadabra " + "Alakazam Machop Machoke Machamp Bellsprout Weepinbell Victreebel Tentacool Tentacruel Geodude " + "Graveler Golem Ponyta Rapidash Slowpoke Slowbro Magnemite Magneton Farfetchd Doduo Dodrio " + "Seel Dewgong Grimer Muk Shellder Cloyster Gastly Haunter Gengar Onix Drowzee Hypno Krabby " + "Kingler Voltorb Electrode Exeggcute Exeggutor Cubone Marowak Hitmonlee Hitmonchan Lickitung " + "Koffing Weezing Rhyhorn Rhydon Chansey Tangela Kangaskhan Horsea Seadra Goldeen Seaking " + "Staryu Starmie MrMime Scyther Jynx Electabuzz Magmar Pinsir Tauros Magikarp Gyarados Lapras " + "Ditto Eevee Vaporeon Jolteon Flareon Porygon Omanyte Omastar Kabuto Kabutops Aerodactyl " + "Snorlax Articuno Zapdos Moltres Dratini Dragonair Dragonite Mewtwo Mew").split() +for _i, _n in enumerate(_NAMES): + SPECIES[_i + 1] = _n diff --git a/model_extract/pipeline/build.py b/model_extract/pipeline/build.py new file mode 100644 index 0000000..38b0e9a --- /dev/null +++ b/model_extract/pipeline/build.py @@ -0,0 +1,345 @@ +#!/usr/bin/env python3 +""" +End-to-end export: baserom.z64 -> glb / textures / viewer payloads / manifests. + + model_extract/pipeline/build.py [--rom PATH] [--out DIR] [options] + +Stdlib only. Nothing here needs `make init`, splat or crunch64 -- the ROM is +read, decompressed and parsed directly. + +Options: + --no-js skip the viewer payloads and viewer.html + --no-glb skip the glTF binaries and PNG dumps + --no-effects skip the generated fire/gas stand-ins + --only N[,N] restrict to these model file numbers (for quick iteration) +""" +import base64 +import collections +import json +import math +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +REPO = os.path.abspath(os.path.join(HERE, '..', '..')) + +import battle +import effects as fx_gen +import fragment +import glb as glb_mod +import rom as rom_mod + +N_POKEMON = 151 +EXTRA_NAMES = {152: 'Surfing Pikachu'} # only the one identified with confidence + +# Where to look for the ROM, in order. model_extract/baseroms/ comes first so the +# folder can stand on its own; the repo's own baseroms/ is the fallback. +BASEROMS = os.path.join(os.path.dirname(HERE), 'baseroms') +ROM_CANDIDATES = [ + os.path.join(BASEROMS, 'baserom.z64'), + os.path.join(BASEROMS, 'us', 'baserom.z64'), + os.path.join(REPO, 'baseroms', 'us', 'baserom.z64'), +] + + +def find_rom(): + for p in ROM_CANDIDATES: + if os.path.exists(p): + return p + if os.path.isdir(BASEROMS): # any ROM dropped in the folder + for f in sorted(os.listdir(BASEROMS)): + if f.lower().endswith(('.z64', '.n64', '.v64')): + return os.path.join(BASEROMS, f) + return None + + +# --------------------------------------------------------------- bind extent + +def bind_extent(data): + """World-space bounding box of the bind pose, used to size the effects.""" + def trs(t, r, s): + S = lambda v: math.sin(v / 32768 * math.pi) + C = lambda v: math.cos(v / 32768 * math.pi) + sx, cx = S(r[0]), C(r[0]); sy, cy = S(r[1]), C(r[1]); sz, cz = S(r[2]), C(r[2]) + return [cy*cz*s[0], cy*sz*s[0], -sy*s[0], 0, + (sx*sy*cz-cx*sz)*s[1], (sx*sy*sz+cx*cz)*s[1], sx*cy*s[1], 0, + (cx*sy*cz+sx*sz)*s[2], (cx*sy*sz-sx*cz)*s[2], cx*cy*s[2], 0, + t[0], t[1], t[2], 1] + + def mul(a, b): + r = [0]*16 + for c in range(4): + for i in range(4): + r[c*4+i] = a[i]*b[c*4] + a[4+i]*b[c*4+1] + a[8+i]*b[c*4+2] + a[12+i]*b[c*4+3] + return r + + root = trs([0, 0, 0], [0, 0, 0], data['rootScale']) + acc, uns, mats = [], [], [] + for b in data['bones']: + pa = acc[b['parent']] if b['parent'] >= 0 else [1.0, 1.0, 1.0] + pu = uns[b['parent']] if b['parent'] >= 0 else root + u = mul(pu, trs([b['t'][k]*pa[k] for k in range(3)], b['r'], [1, 1, 1])) + a = [pa[k]*b['s'][k] for k in range(3)] + m = list(u) + for k in range(4): + m[k] *= a[0]; m[4+k] *= a[1]; m[8+k] *= a[2] + acc.append(a); uns.append(u); mats.append(m) + + lo = [1e9]*3; hi = [-1e9]*3 + for p in data['prims']: + for i, bi in enumerate(p['skin']): + m = mats[bi] + x, y, z = p['pos'][i*3:i*3+3] + w = (m[0]*x+m[4]*y+m[8]*z+m[12], m[1]*x+m[5]*y+m[9]*z+m[13], + m[2]*x+m[6]*y+m[10]*z+m[14]) + for k in range(3): + lo[k] = min(lo[k], w[k]); hi[k] = max(hi[k], w[k]) + # height, not the largest dimension: sizing off the max would scale Moltres' + # flames to its wingspan + extent = (hi[1] - lo[1]) if lo[0] <= hi[0] else 1.0 + # how much each bone scales its own local space, so effects can compensate + scales = [math.sqrt(m[0]*m[0] + m[1]*m[1] + m[2]*m[2]) for m in mats] + return extent, scales + + +# ------------------------------------------------------------ animation names + +# Which context name wins when several claim the same animation. The battle +# table points many slots at one clip, and these are the ones worth naming. +NAME_PREF = ['idle', 'hit', 'faint', 'entrance', 'struggle', 'flinch'] + + +def label_animations(data, rows, moves): + """Name each animation after what the battle table uses it for, and pair it + with the texture animation that table most often sets alongside it. + + Mutates `data['anims']`, giving each a `name` and an `aux`, and hands back + the per-animation context and move lists the manifest reports. Factored out + of main() because the mod's packer (tools/stadium_pack.py) has to label them + exactly the same way for its output to be comparable with the Lua extractor + that reads the same ROM at runtime. + """ + entries = [r[0] for r in rows] + aux = [r[1] for r in rows] + uses = [[] for _ in data['anims']] + move_uses = [[] for _ in data['anims']] + for e, ai in enumerate(entries): + if ai >= len(uses): + continue + if e < battle.N_MOVES: + move_uses[ai].append(moves[e + 1]) + elif e in battle.CONTEXT_SLOTS: + uses[ai].append(battle.CONTEXT_SLOTS[e][0]) + pairs = [collections.Counter() for _ in data['anims']] + for e, ai in enumerate(entries): + if ai < len(pairs) and 0 <= aux[e] < len(data['auxAnims']): + pairs[ai][aux[e]] += 1 + for i, a in enumerate(data['anims']): + ctx = sorted(set(uses[i])) + named = [n for n in NAME_PREF if n in ctx] + a['name'] = (named[0] if named else 'attack' if move_uses[i] + else ctx[0] if ctx else f'anim{i}') + a['aux'] = pairs[i].most_common(1)[0][0] if pairs[i] else -1 + seen = {} + for a in data['anims']: + n = seen.get(a['name'], 0) + seen[a['name']] = n + 1 + if n: + a['name'] = f'{a["name"]}_{n + 1}' + return uses, move_uses + + +def attach_effects(data, species, raw=False): + """Append generated fire/gas prims + their flipbook textures. + + `raw` matches fragment.extract's: the flipbook frames are already RGBA8, so + they are stored as-is rather than encoded, for the packer that wants pixels. + """ + if not data.get('fx'): + return 0 + extent, bone_scale = bind_extent(data) + made = fx_gen.build_for(species, data['fx'], extent, bone_scale) + for e in made: + first = len(data['textures']) + for i, frame in enumerate(e['frames']): + rec = dict(index=-1, w=e['w'], h=e['h'], generated=True) + if raw: + rec['rgba'] = frame + else: + rec['png'] = ('data:image/png;base64,' + base64.b64encode( + fragment.png(e['w'], e['h'], frame)).decode()) + data['textures'].append(rec) + g = e['geo'] + data['prims'].append(dict( + tex=first, cull=0, texAnim=-1, texMap={}, + generated=True, effect=e['kind'], + blend='add' if e['kind'] == 'fire' else 'alpha', + fxFrames=list(range(first, first + len(e['frames']))), + pos=g['pos'], uv=g['uv'], nrm=g['nrm'], skin=g['skin'], idx=g['idx'])) + return len(made) + + +# --------------------------------------------------------------------- main + +def main(argv): + args = {a.split('=')[0]: (a.split('=', 1)[1] if '=' in a else True) for a in argv} + rom_path = args.get('--rom') or find_rom() + outdir = args.get('--out') or os.path.join(REPO, 'model_extract') + want_js = '--no-js' not in args + want_glb = '--no-glb' not in args + want_fx = '--no-effects' not in args + only = {int(x) for x in args['--only'].split(',')} if '--only' in args else None + + if not rom_path or not os.path.exists(rom_path): + sys.exit('ROM not found. Put a Pokemon Stadium (US 1.0) ROM at\n' + f' {os.path.join(BASEROMS, "baserom.z64")}\n' + 'or pass --rom=PATH. Searched:\n ' + + '\n '.join(ROM_CANDIDATES)) + + print(f'reading {rom_path}') + rom = rom_mod.Rom(rom_path) + print(f' md5 {rom.md5}' + ('' if rom.is_expected_us else ' (NOT the expected US 1.0 ROM)')) + + blobs = rom_mod.pokemon_models(rom) + print(f' {len(blobs)} model fragments') + tables = battle.BattleTables(rom) + moves = battle.load_move_names(REPO) + + for sub in ('glb', 'textures', 'js'): + os.makedirs(os.path.join(outdir, sub), exist_ok=True) + + manifest = dict( + source='Pokemon Stadium (US) 1.0', romMd5=rom.md5, + generator='model_extract/pipeline/build.py', + coordinateSystem='Y up, +Z front, units are game units (models authored 10x, ' + 'baked into the model_root node scale)', + frameRate=30, + generatedEffects='Prims and textures tagged generated:true are NOT extracted ' + 'game data -- see pipeline/effects.py.', + animationSlots={str(k): dict(name=v[0], evidence=v[1], description=v[2]) + for k, v in battle.CONTEXT_SLOTS.items()}, + pokemon=[], extra=[]) + move_rows, anim_names, index, fx_count = {}, {}, [], 0 + + for fileno, blob in enumerate(blobs): + if only is not None and fileno not in only: + continue + try: + data = fragment.extract(blob, f'{fileno}.bin') + except Exception as exc: + print(f' skip {fileno}: {exc}') + continue + species = data['species'] + pokemon = fileno < N_POKEMON + + if pokemon: + rows = tables.rows(species) + uses, move_uses = label_animations(data, rows, moves) + slug = f'{species:03d}_{battle.SPECIES.get(species, str(species)).lower()}' + data['name'] = battle.SPECIES.get(species, f'#{species}') + move_rows[species] = [[rows[e][0], rows[e][1]] + for e in range(battle.N_MOVES)] + anim_names[species] = [a['name'] for a in data['anims']] + else: + slug = f'x{fileno:03d}_model' + data['name'] = EXTRA_NAMES.get(fileno, f'Model {fileno}') + for i, a in enumerate(data['anims']): + a['name'] = f'anim{i}' + a['aux'] = 0 if data['auxAnims'] else -1 + + nfx = attach_effects(data, species) if want_fx else 0 + fx_count += nfx + + pngs = [base64.b64decode(t['png'].split(',', 1)[1]) for t in data['textures']] + if want_glb: + with open(os.path.join(outdir, 'glb', slug + '.glb'), 'wb') as fp: + fp.write(glb_mod.build_glb(data, pngs)) + texdir = os.path.join(outdir, 'textures', slug) + os.makedirs(texdir, exist_ok=True) + for i, (t, p) in enumerate(zip(data['textures'], pngs)): + tag = '_fx' if t.get('generated') else '' + with open(os.path.join(texdir, f'{i:02d}_{t["w"]}x{t["h"]}{tag}.png'), 'wb') as fp: + fp.write(p) + if want_js: + with open(os.path.join(outdir, 'js', slug + '.js'), 'w') as fp: + fp.write('PKMN_LOAD(' + json.dumps(data, separators=(',', ':')) + ');\n') + + entry = dict( + species=species, name=data['name'], slug=slug, + group='pokemon' if pokemon else 'extra', + sourceFile=f'{fileno}.bin', glb=f'glb/{slug}.glb', + textureDir=f'textures/{slug}', + triangles=sum(len(p['idx']) // 3 for p in data['prims']), + vertices=sum(len(p['pos']) // 3 for p in data['prims']), + bones=len(data['bones']), textures=len(data['textures']), + generatedEffects=nfx, + animations=[dict( + index=i, name=a['name'], frames=a['frames'], + seconds=round(a['frames'] / 30.0, 3), + endBehavior='clamp' if (a['flags'] & 2) else 'wrap', + loopStartFrame=a['loopStart'], + **(dict(contexts=sorted(set(uses[i])), + moves=sorted(set(move_uses[i])), + moveCount=len(set(move_uses[i]))) if pokemon else {})) + for i, a in enumerate(data['anims'])]) + (manifest['pokemon'] if pokemon else manifest['extra']).append(entry) + index.append(dict(species=species, name=data['name'], slug=slug, + group=entry['group'], triangles=entry['triangles'], + bones=entry['bones'], animations=len(data['anims']))) + print(f' {slug:<22} {len(data["anims"]):2d} anims {entry["triangles"]:5d} tris' + + (f' +{nfx} effect' if nfx else '')) + + # ---- move index ------------------------------------------------------ + moves_out = [] + if move_rows: + default_anim = {p['species']: next( + (a['index'] for a in p['animations'] if 'hit' in a.get('contexts', [])), -1) + for p in manifest['pokemon']} + for mid in range(1, battle.N_MOVES + 1): + users, tally, ndiff = [], collections.Counter(), 0 + for sp in sorted(move_rows): + ai, ax = move_rows[sp][mid - 1] + name = anim_names[sp][ai] if ai < len(anim_names[sp]) else f'anim{ai}' + diff = ai != default_anim.get(sp, -1) + ndiff += diff + tally[name] += 1 + users.append(dict(species=sp, animation=ai, animationName=name, + aux=ax, differsFromDefault=diff)) + moves_out.append(dict( + id=mid, name=moves[mid], speciesWithOwnAnimation=ndiff, + animationNames=[dict(name=n, species=c) for n, c in tally.most_common()], + users=users)) + with open(os.path.join(outdir, 'moves.json'), 'w') as fp: + json.dump(dict(source=manifest['source'], note=( + 'Entry n of the per-species battle table (0-indexed) selects the ' + 'animation played when that Pokemon uses move n+1. The table is dense ' + '- every species has a row for every move, including moves it can ' + 'never learn - and those unreachable rows overwhelmingly point at the ' + 'species\' generic reaction animation. Use differsFromDefault.'), + moves=moves_out), fp, indent=1) + + with open(os.path.join(outdir, 'manifest.json'), 'w') as fp: + json.dump(manifest, fp, indent=2) + + if want_js: + with open(os.path.join(outdir, 'js', 'index.js'), 'w') as fp: + fp.write('window.PKMN_INDEX = ' + json.dumps(index, separators=(',', ':')) + ';\n') + if moves_out: + with open(os.path.join(outdir, 'js', 'moves.js'), 'w') as fp: + fp.write('window.PKMN_MOVES = ' + json.dumps( + [dict(id=m['id'], name=m['name'], + bySpecies={str(u['species']): [u['animation'], u['aux']] + for u in m['users']}) for m in moves_out], + separators=(',', ':')) + ';\n') + viewer_src = os.path.join(REPO, 'tools/model_viewer/viewer.html') + if os.path.exists(viewer_src): + with open(viewer_src) as s, open(os.path.join(outdir, 'viewer.html'), 'w') as d: + d.write(s.read()) + + print(f'\n{len(manifest["pokemon"])} Pokemon + {len(manifest["extra"])} other models' + f', {fx_count} generated effects') + + +if __name__ == '__main__': + main(sys.argv[1:]) diff --git a/model_extract/pipeline/effects.py b/model_extract/pipeline/effects.py new file mode 100644 index 0000000..d718f97 --- /dev/null +++ b/model_extract/pipeline/effects.py @@ -0,0 +1,225 @@ +#!/usr/bin/env python3 +""" +Generated stand-in effects. + +IMPORTANT: nothing in this file is extracted game data. The real tail flame, +mane fire and gas are drawn by procedural callbacks that live in another +fragment (geo command 0x08 -> func_80014A60 calls node->unk_10, and the model +file supplies only two empty display lists plus zeroed scratch buffers). Those +callbacks have not been ported, so the models genuinely contain no flame mesh +and no flame texture. + +What follows is an original, procedurally generated replacement: looping +flipbook textures plus a pair of crossed quads anchored to the bone the +callback hangs off. It is meant to make the models look right in the viewer, +and it is tagged `generated: true` everywhere it appears so it is never +mistaken for ripped content. +""" +import math + +# geo cmd 0x08 callback ids -> which effect to stand in for. The grouping is the +# game's own: every species sharing a callback shares an effect. +FIRE_TAIL = 0x810000D8 # Charmander, Charmeleon, Charizard, Magmar, Moltres +FIRE_SMALL = 0x81000108 # Ponyta, Rapidash, Moltres wings +AURA = 0x810000E0 # Gastly, Koffing, Weezing, Vaporeon, Articuno, Moltres + + +class Rng: + """Deterministic PRNG so a given species always generates the same effect.""" + + def __init__(self, seed): + self.s = seed & 0xFFFFFFFF or 0x9E3779B9 + + def next(self): + x = self.s + x ^= (x << 13) & 0xFFFFFFFF + x ^= x >> 17 + x ^= (x << 5) & 0xFFFFFFFF + self.s = x & 0xFFFFFFFF + return self.s + + def unit(self): + return self.next() / 0x100000000 + + +def _lattice(rng, w, h): + return [[rng.unit() for _ in range(w)] for _ in range(h)] + + +def _smooth(t): + return t * t * (3 - 2 * t) + + +def _sample(grid, x, y): + """Bilinear value noise on a torus, so the field tiles in both axes.""" + h, w = len(grid), len(grid[0]) + x0, y0 = int(math.floor(x)) % w, int(math.floor(y)) % h + x1, y1 = (x0 + 1) % w, (y0 + 1) % h + fx, fy = _smooth(x - math.floor(x)), _smooth(y - math.floor(y)) + a = grid[y0][x0] + (grid[y0][x1] - grid[y0][x0]) * fx + b = grid[y1][x0] + (grid[y1][x1] - grid[y1][x0]) * fx + return a + (b - a) * fy + + +def _fbm(grids, x, y, scale): + """Sum octaves of tileable noise.""" + total, amp, norm = 0.0, 1.0, 0.0 + for i, g in enumerate(grids): + f = scale * (2 ** i) + total += _sample(g, x * f, y * f) * amp + norm += amp + amp *= 0.5 + return total / norm + + +def _ramp(stops, t): + t = max(0.0, min(1.0, t)) + for i in range(len(stops) - 1): + a, b = stops[i], stops[i + 1] + if t <= b[0]: + k = 0.0 if b[0] == a[0] else (t - a[0]) / (b[0] - a[0]) + return tuple(int(a[1 + j] + (b[1 + j] - a[1 + j]) * k) for j in range(4)) + return tuple(stops[-1][1:]) + + +FIRE_RAMP = [ # intensity -> RGBA + (0.00, 0, 0, 0, 0), + (0.30, 120, 24, 8, 90), + (0.52, 226, 78, 16, 205), + (0.74, 252, 176, 44, 245), + (1.00, 255, 246, 214, 255), +] + +GAS_RAMP = [ + (0.00, 0, 0, 0, 0), + (0.34, 52, 26, 78, 70), + (0.60, 96, 52, 140, 140), + (0.82, 148, 96, 196, 190), + (1.00, 208, 176, 236, 215), +] + + +def fire_frames(seed, w=32, h=64, frames=8, wisp=1.0): + """Upward-advected noise plume. Scrolling by an exact multiple of the noise + lattice over the frame count makes the loop seamless.""" + rng = Rng(seed) + grids = [_lattice(rng, 8, 8), _lattice(rng, 16, 16), _lattice(rng, 32, 32)] + out = [] + for f in range(frames): + t = f / frames + buf = bytearray(w * h * 4) + for y in range(h): + v = y / (h - 1) # 0 at the base, 1 at the tip + # plume envelope: wide and hot at the base, pinched at the tip + taper = max(0.0, 1.0 - v) ** 0.42 + for x in range(w): + u = (x / (w - 1)) * 2 - 1 # -1 .. 1 across the flame + radial = (1.0 - min(1.0, abs(u) / max(0.10, taper * 0.95))) ** 0.7 + if radial <= 0: + continue + n = _fbm(grids, x / w, (y / h) - t, 3.0) + lick = 0.55 + 0.75 * (n - 0.5) * wisp + inten = radial * (0.55 + 0.8 * taper) * lick + inten -= 0.16 * v # cool towards the tip + if inten <= 0.02: + continue + r, g, b, a = _ramp(FIRE_RAMP, inten) + i = ((h - 1 - y) * w + x) * 4 # +Y in texture space is up + buf[i:i+4] = bytes((r, g, b, a)) + out.append(bytes(buf)) + return w, h, out + + +def gas_frames(seed, w=48, h=48, frames=10): + """Slow swirling haze that fades out towards the rim.""" + rng = Rng(seed) + grids = [_lattice(rng, 8, 8), _lattice(rng, 16, 16), _lattice(rng, 32, 32)] + out = [] + for f in range(frames): + t = f / frames + buf = bytearray(w * h * 4) + ang = t * 2 * math.pi + for y in range(h): + for x in range(w): + dx = (x / (w - 1)) * 2 - 1 + dy = (y / (h - 1)) * 2 - 1 + d = math.hypot(dx, dy) + if d >= 1.0: + continue + falloff = (1.0 - d) ** 0.85 + # rotate the sample point so the haze churns without popping + sx = dx * math.cos(ang) - dy * math.sin(ang) + sy = dx * math.sin(ang) + dy * math.cos(ang) + n = _fbm(grids, sx * 0.5 + 0.5, sy * 0.5 + 0.5 - t, 2.5) + inten = falloff * (0.78 + 1.30 * (n - 0.44)) + if inten <= 0.03: + continue + r, g, b, a = _ramp(GAS_RAMP, inten) + i = (y * w + x) * 4 + buf[i:i+4] = bytes((r, g, b, a)) + out.append(bytes(buf)) + return w, h, out + + +def crossed_quads(bone, length, width, axis='y', centred=False): + """Two quads at right angles so the effect reads from any angle -- the + portable stand-in for a billboard, since glTF cannot billboard. + + `axis` picks which bone-local direction the quad grows along. Bone-local +X + runs down the limb, so a flame laid out along X comes out lying sideways; + 'y' is that same quad rotated 90 degrees left about Z, which stands it up. + `centred` straddles the origin instead of growing from it.""" + pos, uv, nrm, skin, idx = [], [], [], [], [] + for q in range(2): + base = len(pos) // 3 + for (s, t) in ((0, 0), (1, 0), (1, 1), (0, 1)): + a = (s - 0.5) * width + b = (t - 0.5) * length if centred else t * length + if axis == 'x': + p = (b, a, 0.0) if q == 0 else (b, 0.0, a) + else: # (x, y) -> (-y, x) + p = (-a, b, 0.0) if q == 0 else (0.0, b, a) + pos += list(p) + uv += [s, 1.0 - t] + nrm += [0.0, 0.0, 1.0] if q == 0 else [1.0, 0.0, 0.0] + skin.append(bone) + idx += [base, base + 1, base + 2, base, base + 2, base + 3] + return dict(pos=pos, uv=uv, nrm=nrm, skin=skin, idx=idx) + + +# desired size as a fraction of the model's world-space extent +SIZES = { + 'fire_tail': (0.40, 0.22), # length, width + 'fire_small': (0.075, 0.042), + 'gas': (1.05, 1.05), +} + + +def build_for(species, fx, extent, bone_scale): + """Returns [{kind, bone, geo, w, h, frames}] for one model, or []. + + `extent` is the model's world-space size and `bone_scale[i]` how much bone i + already scales its local space; dividing by it keeps every effect the size we + asked for regardless of where in the skeleton it hangs.""" + out = [] + for node in fx: + cb, bone = node['callback'], node['bone'] + if bone < 0 or bone >= len(bone_scale): + continue + k = bone_scale[bone] or 1.0 + if cb == FIRE_TAIL: + fl, fw = SIZES['fire_tail'] + w, h, fr = fire_frames(species * 7919 + 1, 32, 64, 8) + geo = crossed_quads(bone, extent * fl / k, extent * fw / k, axis='y') + out.append(dict(kind='fire', bone=bone, geo=geo, w=w, h=h, frames=fr)) + elif cb == FIRE_SMALL: + fl, fw = SIZES['fire_small'] + w, h, fr = fire_frames(species * 6271 + bone, 24, 40, 8, wisp=1.25) + geo = crossed_quads(bone, extent * fl / k, extent * fw / k, axis='y') + out.append(dict(kind='fire', bone=bone, geo=geo, w=w, h=h, frames=fr)) + elif cb == AURA and species == 92: # Gastly only + fl, fw = SIZES['gas'] + w, h, fr = gas_frames(species * 5237 + 3, 48, 48, 10) + geo = crossed_quads(bone, extent * fl / k, extent * fw / k, axis='y', centred=True) + out.append(dict(kind='gas', bone=bone, geo=geo, w=w, h=h, frames=fr)) + return out diff --git a/model_extract/pipeline/fragment.py b/model_extract/pipeline/fragment.py new file mode 100644 index 0000000..f87850d --- /dev/null +++ b/model_extract/pipeline/fragment.py @@ -0,0 +1,735 @@ +#!/usr/bin/env python3 +""" +Model extraction: FRAGMENT module -> geometry, textures, skeleton, animations. + +Self-contained copy of tools/model_viewer/extract_model.py, taking raw bytes so +it can be fed straight from the ROM. See ../README.md for the format notes. +""" +import json, os, struct, sys, zlib + +BASE = 0x8FF00000 + +# ---------------------------------------------------------------- geo layout + +CMD_SIZES = { + 0x00:0x08, 0x01:0x04, 0x02:0x08, 0x03:0x08, 0x04:0x04, 0x05:0x04, 0x06:0x04, + 0x07:0x08, 0x08:0x0C, 0x09:0x04, 0x0A:0x08, 0x0B:0x18, 0x0C:0x04, 0x0D:0x04, + 0x0E:0x04, 0x0F:0x04, 0x10:0x04, 0x11:0x04, 0x12:0x04, 0x13:0x08, 0x14:0x0C, + 0x15:0x0C, 0x16:0x04, 0x17:0x14, 0x18:0x08, 0x19:0x08, 0x1A:0x04, 0x1B:0x10, + 0x1C:0x10, 0x1D:0x1C, 0x1E:0x08, 0x1F:0x18, 0x20:0x14, 0x21:0x10, 0x22:0x08, + 0x23:0x10, 0x24:0x04, 0x25:0x04, 0x26:0x14, +} + + +class Fragment: + def __init__(self, data, name=''): + self.d = data if isinstance(data, (bytes, bytearray)) else open(data, 'rb').read() + self.name = name if isinstance(data, (bytes, bytearray)) else str(data) + if self.d[8:0x10] != b'FRAGMENT': + raise ValueError(f'{self.name}: not a FRAGMENT module') + self.hdrSize, self.relocOff, self.sizeRom, self.sizeRam = struct.unpack_from('>4I', self.d, 0x10) + + def off(self, ptr): + return None if ptr == 0 else ptr - BASE + + def u8(self, o): return self.d[o] + def s8(self, o): return struct.unpack_from('>b', self.d, o)[0] + def u16(self, o): return struct.unpack_from('>H', self.d, o)[0] + def s16(self, o): return struct.unpack_from('>h', self.d, o)[0] + def u32(self, o): return struct.unpack_from('>I', self.d, o)[0] + def s32(self, o): return struct.unpack_from('>i', self.d, o)[0] + def ptr(self, o): return self.off(self.u32(o)) + + def root(self): + """The entry stub ends with `lui rX, hi; addiu rX, rX, lo` loading the root struct.""" + for o in range(0x20, 0x80, 4): + w = self.u32(o) + if (w >> 26) != 0x0F: # lui + continue + reg = (w >> 16) & 0x1F + w2 = self.u32(o + 4) + if (w2 >> 26) == 0x09 and ((w2 >> 21) & 0x1F) == reg: # addiu rX, rX, imm + return ((self.u16(o + 2) << 16) + self.s16(o + 6)) - BASE + raise RuntimeError('could not locate root struct') + + def ptr_list(self, o): + out = [] + while True: + p = self.ptr(o) + if p is None: + return out + out.append(p) + o += 4 + + +# --------------------------------------------------------------- F3DEX2 exec + +def signed(v, bits): + m = 1 << (bits - 1) + return (v ^ m) - m + + +class Model: + """Walks the geo layout, executes the display lists, accumulates draw data.""" + + def __init__(self, frag): + self.f = frag + r = frag.root() + self.species = frag.u16(r) + self.geoLayouts = frag.ptr_list(frag.ptr(r + 0x08)) + self.anims = frag.ptr_list(frag.ptr(r + 0x0C)) + self.auxAnims = frag.ptr_list(frag.ptr(r + 0x10)) + + self.textures = [] # {fmt, siz, w, h, texels, data} + self.tluts = [] # palettes: {count, data, dl} + self.bones = [] # {parent, boneId, chan, t, r, s} + self.boneById = {} + self.prims = [] # {tex, cull, verts:[...], tris:[...]} + self.primsByKey = {} + self.vtxBase = None + self.rootScale = [1.0, 1.0, 1.0] + self.fx = [] # geo cmd 0x08 procedural effect nodes + self.warnings = [] + + # ---- textures ------------------------------------------------------- + def read_texture_table(self, off, count): + f = self.f + for i in range(count): + o = off + i * 0xC + self.textures.append(dict( + fmt=f.u8(o), siz=f.u8(o + 1), w=f.s16(o + 2), + h=f.u16(o + 4), texels=f.u16(o + 6), data=f.ptr(o + 8))) + + def read_tlut_table(self, off, count): + """Palettes reuse the texture-record layout: the count sits in the width + field, the palette data in the next word, and unk_08 is the DL that loads + it (src/12D80.c func_80015B20). The DL is authoritative, so run it.""" + f = self.f + for i in range(count): + o = off + i * 0xC + rec = dict(count=f.u16(o + 2), data=f.ptr(o + 4), dl=f.ptr(o + 8)) + dl = rec['dl'] + if dl is not None: + for _ in range(16): + w0, w1 = struct.unpack_from('>II', f.d, dl) + op = w0 >> 24 + if op == 0xFD: # G_SETTIMG + rec['data'] = f.off(w1) + elif op == 0xF0: # G_LOADTLUT + rec['count'] = ((w1 >> 14) & 0x3FF) + 1 + elif op == 0xDF: + break + dl += 8 + self.tluts.append(rec) + + # ---- geo layout ----------------------------------------------------- + def build(self): + self.curTex = -1 + self.curTlut = -1 + self.curMat = None + self.curTexAnim = -1 + # Mirrors gCurGraphNodeList in src/geo_layout.c: stack[-1] is the slot the + # next node command writes to, and a node's parent -- and the bone whose + # matrix is live -- is the slot *below* it (func_80017AC4). + self.stack = [-1] + # The RSP vertex cache persists across display lists: a bone's list often + # preloads verts that the *next* bone's list then indexes, which is how + # these models get blended joints. Each slot remembers the bone whose + # matrix was current when it was loaded. + self.vbuf = [None] * 64 + self.walk(self.geoLayouts[0]) + + def walk(self, o, depth=0): + f = self.f + if depth > 32: + return + while True: + cmd = f.u8(o) + size = CMD_SIZES.get(cmd) + if size is None: + self.warnings.append(f'unknown geo cmd {cmd:#04x} at {o:#x}') + return + if cmd == 0x01 or cmd == 0x04: # end / return + return + if cmd in (0x00, 0x03): # branch (with return) + self.walk(f.ptr(o + 4), depth + 1) + elif cmd == 0x02: # jump (no return) + o = f.ptr(o + 4) + continue + elif cmd == 0x05: # open node + self.stack.append(self.stack[-1]) + elif cmd == 0x06: # close node + self.stack.pop() + elif cmd == 0x17: # model header + self.read_texture_table(f.ptr(o + 8), f.s16(o + 2)) + if f.ptr(o + 0xC): + self.read_tlut_table(f.ptr(o + 0xC), f.s16(o + 4)) + self.vtxBase = f.ptr(o + 0x10) + self.nVerts = f.s16(o + 6) + elif cmd == 0x08: # procedural effect callback + self.fx.append(dict(bone=self.curBone(), callback=f.u32(o + 4), + arg=f.ptr(o + 8))) + elif cmd == 0x1C: # uniform scale node + self.rootScale = [f.s32(o + 4) / 65536.0, f.s32(o + 8) / 65536.0, + f.s32(o + 0xC) / 65536.0] + elif cmd == 0x1D: # bone / joint node + idx = len(self.bones) + self.bones.append(dict( + parent=self.curBone(), boneId=f.u8(o + 1), flags=f.u8(o + 2), + chan=f.s8(o + 3), + t=[f.s16(o + 4), f.s16(o + 6), f.s16(o + 8)], + r=[f.s16(o + 0xA), f.s16(o + 0xC), f.s16(o + 0xE)], + s=[f.s32(o + 0x10) / 65536.0, f.s32(o + 0x14) / 65536.0, + f.s32(o + 0x18) / 65536.0])) + self.boneById[f.u8(o + 1)] = idx + self.stack[-1] = idx + elif cmd == 0x23: # set texture / material + self.curTex = f.s16(o + 8) + self.curTlut = f.s16(o + 0xA) + self.curMat = f.ptr(o + 4) + # offset 0x02 is the texture-animation channel; -1 means static. + # func_800176DC swaps this material's texture per frame from the + # auxiliary animation's channel stream. + self.curTexAnim = f.s16(o + 2) + elif cmd == 0x22: # display list on current bone + self.run_dl(f.ptr(o + 4), self.curBone()) + elif cmd == 0x1E: # display list on named bone + self.run_dl(f.ptr(o + 4), self.boneById.get(f.s16(o + 2), self.curBone())) + elif cmd in (0x20, 0x21): # display list + own transform + self.run_dl(f.ptr(o + (0x10 if cmd == 0x20 else 0xC)), self.curBone()) + o += size + + def curBone(self): + return self.stack[-2] if len(self.stack) >= 2 else -1 + + # ---- display lists -------------------------------------------------- + def run_dl(self, o, bone, depth=0): + if o is None or depth > 8: + return + f = self.f + vbuf = self.vbuf + cull = 0x400 + while True: + w0, w1 = struct.unpack_from('>II', f.d, o) + op = w0 >> 24 + o += 8 + if op == 0xDF: # G_ENDDL + return + if op == 0xDE: # G_DL + self.run_dl(f.off(w1), bone, depth + 1) + if (w0 >> 16) & 0xFF: # branch, not call + return + continue + if op == 0x01: # G_VTX + n = (w0 >> 12) & 0xFF + v0 = ((w0 & 0xFFF) >> 1) - n + a = f.off(w1) + for i in range(n): + p = a + i * 0x10 + if 0 <= v0 + i < len(vbuf): + vbuf[v0 + i] = ( + f.s16(p), f.s16(p + 2), f.s16(p + 4), # position + f.s16(p + 8) / 32.0, f.s16(p + 10) / 32.0, # s, t (S10.5) + f.s8(p + 12), f.s8(p + 13), f.s8(p + 14), # normal + f.u8(p + 15), # alpha + bone) # owning bone + continue + if op == 0xD9: # G_GEOMETRYMODE + cull = (cull & (w0 & 0xFFFFFF)) | w1 + continue + if op in (0x05, 0x06): # G_TRI1 / G_TRI2 + prim = self.prim_for(self.curTex, self.curTlut, self.curMat, + self.curTexAnim, cull & 0x600) + + def emit(a, b, c): + tri = [] + for idx in (a, b, c): + v = vbuf[idx] if idx < len(vbuf) else None + if v is None: + return + j = prim['_remap'].get(v) + if j is None: + j = len(prim['verts']) + prim['_remap'][v] = j + prim['verts'].append(v) + tri.append(j) + if (cull & 0x200) and not (cull & 0x400): + tri.reverse() + prim['tris'].append(tri) + + emit(((w0 >> 16) & 0xFF) // 2, ((w0 >> 8) & 0xFF) // 2, (w0 & 0xFF) // 2) + if op == 0x06: + emit(((w1 >> 16) & 0xFF) // 2, ((w1 >> 8) & 0xFF) // 2, (w1 & 0xFF) // 2) + continue + # everything else (SETTILE / sync / ...) is state we reconstruct + # from the texture table instead, so it is skipped. + + def prim_for(self, tex, tlut, mat, texAnim, cull): + key = (tex, tlut, mat, texAnim, cull) + p = self.primsByKey.get(key) + if p is None: + p = dict(tex=tex, tlut=tlut, mat=mat, texAnim=texAnim, cull=cull, + verts=[], tris=[], _remap={}) + self.primsByKey[key] = p + self.prims.append(p) + return p + + def tile_palette(self, mat): + """CI4 selects a 16-entry block of the TLUT via the render tile's palette + field; read it from the material display list's final G_SETTILE.""" + if mat is None: + return 0 + pal = 0 + for _ in range(16): + w0, w1 = struct.unpack_from('>II', self.f.d, mat) + op = w0 >> 24 + if op == 0xF5 and ((w1 >> 24) & 7) == 0: # G_SETTILE, render tile + pal = (w1 >> 20) & 0xF + elif op == 0xDF: + break + mat += 8 + return pal + + +# ---------------------------------------------------------------- animations + +def bitfield(f, base, index, bits): + """src/F420.c func_80010500: signed `bits`-wide field at bit index*bits. + + C integer division truncates toward zero; Python's floors. That only differs + for negative indices, which is exactly what an empty channel produces, so the + truncating form is used here to match the hardware.""" + bitpos = index * bits + word = bitpos // 16 if bitpos >= 0 else -((-bitpos) // 16) # C: trunc to zero + rem = bitpos - word * 16 # C: sign follows bitpos + o = base + word * 2 + v = (f.u16(o) << 16) | f.u16(o + 2) + v = (v << (rem & 31)) & 0xFFFFFFFF # MIPS masks the shift to 5 bits + return signed(v >> (32 - bits), bits) + + +class Animation: + """src/17300.c. Two sampling modes: packed per-frame streams (default) and + hermite keyframes (flags & 8).""" + + def __init__(self, frag, off): + f = self.f = frag + self.off = off + self.flags = f.u8(off) + self.startFrame= f.u16(off + 4) + self.loopStart = f.u16(off + 6) + self.nChannels = f.u16(off + 8) + self.nFrames = f.u16(off + 0xA) + self.chanTable = f.ptr(off + 0xC) + self.scaleData = f.ptr(off + 0x10) + self.rotData = f.ptr(off + 0x14) + self.transData = f.ptr(off + 0x18) + + def chan(self, i): + o = self.chanTable + i * 0xA + f = self.f + return dict(nScale=f.u8(o), nRot=f.u8(o + 1), nTrans=f.u8(o + 2), + interp=f.u8(o + 3), oScale=f.u16(o + 4), + oRot=f.u16(o + 6), oTrans=f.u16(o + 8)) + + # -- packed stream sampling (flags & 8 == 0) -------------------------- + # A count of 0 means the component has no stream at all. The game's index + # arithmetic (offset + count - 1) then runs off the front of the array -- for + # Tangela's idle the scale "array" is two entries long and the computed index + # is 99 -- so an empty channel is treated as "keep the bind-pose value". + def _trans_packed(self, c, frame): + if c['nTrans'] == 0: + return None + bits = 16 if (self.flags & 4) else 12 + if c['nTrans'] == 1: + return float(c['oTrans'] if (self.flags & 4) else signed((c['oTrans'] * 16) & 0xFFFF, 16) >> 4) + i = c['oTrans'] + min(frame, c['nTrans'] - 1) + return float(bitfield(self.f, self.transData, i, bits)) + + def _rot_packed(self, c, frame): + if c['nRot'] == 0: + return None + if c['nRot'] == 1: + return signed((c['oRot'] * 16) & 0xFFFF, 16) + i = c['oRot'] + min(frame, c['nRot'] - 1) + return signed((bitfield(self.f, self.rotData, i, 12) * 16) & 0xFFFF, 16) + + def _scale_packed(self, c, frame): + if c['nScale'] == 0: + return None + if c['nScale'] == 1: + return c['oScale'] / 1000.0 + i = c['oScale'] + min(frame, c['nScale'] - 1) + return self.f.s16(self.scaleData + i * 2) / 1000.0 + + # -- hermite keyframe sampling (flags & 8) ---------------------------- + def _hermite(self, base, n, frame, wide): + f = self.f + stride = 8 if wide else 6 + + def key(i): + o = base + i * stride + return (f.s16(o), f.s16(o + 2), f.s16(o + 4), + f.s16(o + 6) if wide else f.s16(o + 4)) + + k0 = key(0) + if k0[0] >= frame: + return float(k0[1]) + last = key(n - 1) + if frame >= last[0]: + return float(last[1]) + i = 0 + while i < n - 2: + if frame < key(i + 1)[0]: + break + i += 1 + a, b = key(i), key(i + 1) + x = (frame - a[0]) / 30.0 + y = 30.0 / (b[0] - a[0]) + x2, x3 = x * x, x * x * x + y2, y3 = y * y, y * y * y + return (a[1] * (2 * x3 * y3 - 3 * x2 * y2 + 1) + + b[1] * (-2 * x3 * y3 + 3 * x2 * y2) + + (a[3] if wide else a[2]) * (x3 * y2 - 2 * x2 * y + x) + + b[2] * (x3 * y2 - x2 * y)) + + def _trans_key(self, c, frame): + if c['nTrans'] < 2: + return float(signed(c['oTrans'], 16)) + return self._hermite(self.transData + c['oTrans'] * 2, c['nTrans'], frame, c['interp'] & 1) + + def _rot_key(self, c, frame): + if c['nRot'] < 2: + deg = signed(c['oRot'], 16) / 10.0 + else: + deg = self._hermite(self.rotData + c['oRot'] * 2, c['nRot'], frame, c['interp'] & 2) / 10.0 + deg %= 360.0 + return int(deg / 360.0 * 65536.0) + + def _scale_key(self, c, frame): + if c['nScale'] < 2: + return signed(c['oScale'], 16) / 100.0 + return self._hermite(self.scaleData + c['oScale'] * 2, c['nScale'], frame, c['interp'] & 4) / 100.0 + + def sample_trs(self, chanIndex, frame, bind=None): + """Returns (translation, rotation, scale) triples for one bone. Components + whose channel carries no data fall back to the bone's bind value.""" + base = chanIndex * 3 + if base < 0 or base + 2 >= self.nChannels: + return None + cs = [self.chan(base + i) for i in range(3)] + if self.flags & 8: + out = ([self._trans_key(c, frame) for c in cs], + [self._rot_key(c, frame) for c in cs], + [self._scale_key(c, frame) for c in cs]) + else: + out = ([self._trans_packed(c, frame) for c in cs], + [self._rot_packed(c, frame) for c in cs], + [self._scale_packed(c, frame) for c in cs]) + if bind is None: + bind = ([0, 0, 0], [0, 0, 0], [1.0, 1.0, 1.0]) + return tuple([v if v is not None else bind[k][i] for i, v in enumerate(comp)] + for k, comp in enumerate(out)) + + +class AuxAnimation: + """Texture animation (src/18140.c). Same header shape as the skeletal + animations, but each channel is a per-frame stream of texture-table indices + that func_800176DC substitutes into a material.""" + + def __init__(self, frag, off): + f = self.f = frag + self.flags = f.u8(off) + self.startFrame= f.u16(off + 4) + self.loopStart = f.u16(off + 6) + self.nChannels = f.u16(off + 8) + self.nFrames = f.u16(off + 0xA) + self.chanTable = f.ptr(off + 0xC) + self.data = f.ptr(off + 0x10) + + def sample(self, chan, frame): + """func_80017540: index into the stream, clamped to the channel length.""" + if not (0 <= chan < self.nChannels) or self.chanTable is None: + return None + o = self.chanTable + chan * 4 + count, base = self.f.u16(o), self.f.u16(o + 2) + if count == 0: + return None + i = base + (frame if frame < count else count - 1) + return self.f.u8(self.data + i) + + def track(self, chan): + n = max(1, self.nFrames) + return [self.sample(chan, i) for i in range(n)] + + +# ------------------------------------------------------------------ textures + +def rgba5551(p): + return (((p >> 11) & 0x1F) * 255 // 31, ((p >> 6) & 0x1F) * 255 // 31, + ((p >> 1) & 0x1F) * 255 // 31, 255 if (p & 1) else 0) + + +def decode_texture(f, tex, tlut=None, palette=0): + """Returns (w, h, RGBA8 bytes) for the N64 texture formats these models use.""" + w, h, fmt, siz, addr = tex['w'], tex['h'], tex['fmt'], tex['siz'], tex['data'] + out = bytearray(w * h * 4) + d = f.d + n = w * h + + def nibble(i): + return (d[addr + i // 2] >> (0 if i & 1 else 4)) & 0xF + + if fmt == 0 and siz == 2: # RGBA16 (5/5/5/1) + for i in range(n): + out[i*4:i*4+4] = bytes(rgba5551(struct.unpack_from('>H', d, addr + i * 2)[0])) + elif fmt == 0 and siz == 3: # RGBA32 + out[:] = d[addr:addr + n * 4] + elif fmt == 2: # CI4 / CI8 -> RGBA16 palette + pal = [] + if tlut is not None and tlut['data'] is not None: + base = tlut['data'] + (palette * 16 * 2 if siz == 0 else 0) + for i in range(16 if siz == 0 else 256): + pal.append(bytes(rgba5551(struct.unpack_from('>H', d, base + i * 2)[0]))) + if not pal: + pal = [b'\xff\x00\xff\xff'] * 256 + for i in range(n): + idx = nibble(i) if siz == 0 else d[addr + i] + out[i*4:i*4+4] = pal[idx % len(pal)] + elif fmt == 3: # IA16 / IA8 / IA4 + for i in range(n): + if siz == 2: + v = struct.unpack_from('>H', d, addr + i * 2)[0] + l, a = v >> 8, v & 0xFF + elif siz == 1: + v = d[addr + i] + l, a = (v >> 4) * 17, (v & 0xF) * 17 + else: + v = nibble(i) + l, a = ((v >> 1) * 255) // 7, 255 if (v & 1) else 0 + out[i*4:i*4+4] = bytes((l, l, l, a)) + elif fmt == 4: # I8 / I4 + for i in range(n): + l = d[addr + i] if siz == 1 else nibble(i) * 17 + out[i*4:i*4+4] = bytes((l, l, l, 255)) + else: + for i in range(n): # unsupported: magenta + out[i*4:i*4+4] = b'\xff\x00\xff\xff' + return w, h, bytes(out) + + +def png(w, h, rgba): + """Minimal PNG encoder (no PIL dependency).""" + raw = b''.join(b'\x00' + rgba[y*w*4:(y+1)*w*4] for y in range(h)) + + def chunk(tag, data): + c = tag + data + return struct.pack('>I', len(data)) + c + struct.pack('>I', zlib.crc32(c) & 0xFFFFFFFF) + + return (b'\x89PNG\r\n\x1a\n' + + chunk(b'IHDR', struct.pack('>IIBBBBB', w, h, 8, 6, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(raw, 9)) + + chunk(b'IEND', b'')) + + +# ---------------------------------------------------------------------- main + +def unique(seq): + """The distinct values of `seq`, in the order they first appear. + + Used where a set used to be. A set of small ints iterates in hash-slot + order, which is stable across runs but is neither insertion nor sort order + and is a CPython implementation detail -- and here it decided the order + textures get REGISTERED in, and so their indices in the packed file. Order + of appearance is a property of the data instead of the interpreter, which + is what lets the Lua extractor produce the same file. + """ + seen, out = set(), [] + for v in seq: + if v in seen: + continue + seen.add(v) + out.append(v) + return out + + +def dedupe_fx(nodes): + """The geo layout's effect callbacks, once each, IN THE ORDER THEY APPEAR. + + A geo layout can name the same callback on the same bone more than once + (the walk visits a subtree twice), so these have to be deduplicated, and it + used to be done by dropping them through a set. That was a real bug rather + than a style point: the set held tuples containing strings, so its iteration + order moved with PYTHONHASHSEED, and the generated flames of every species + carrying more than one -- Ponyta, Rapidash and Moltres -- came out in a + different order, with different seeds and therefore different pixels, on + different runs of the same build. + + Order of appearance is the game's own order, it is stable, and it is what + the Lua extractor can reproduce. + """ + seen, out = set(), [] + for node in nodes: + key = (node['bone'], node['callback'], node['arg']) + if key in seen: + continue + seen.add(key) + out.append(dict(node)) + return out + + +def extract(path, name=None, raw=False): + """`raw=True` carries each texture's decoded RGBA8 bytes as `rgba` instead + of encoding a PNG data URI into `png`. + + The viewer and the glTF export both want a PNG, so that stays the default. + The mod's own packer wants the pixels: it stores them uncompressed, so that + its Lua counterpart -- which has no zlib whose output is guaranteed to + agree with this one's byte for byte -- can be checked against it exactly. + """ + f = Fragment(path, name or str(path)) + m = Model(f) + m.build() + + import base64 + auxAnims = [AuxAnimation(f, o) for o in m.auxAnims] + + texIndexMap, texOut = {}, [] + + def register(texIdx, tlut, pal): + key = (texIdx, tlut, pal) + if key in texIndexMap: + return texIndexMap[key] + if not (0 <= texIdx < len(m.textures)): + return -1 + texIndexMap[key] = len(texOut) + tl = m.tluts[tlut] if 0 <= tlut < len(m.tluts) else None + w, h, rgba = decode_texture(f, m.textures[texIdx], tl, pal) + rec = dict(index=texIdx, w=w, h=h) + if raw: + rec['rgba'] = rgba + else: + rec['png'] = ('data:image/png;base64,' + + base64.b64encode(png(w, h, rgba)).decode()) + texOut.append(rec) + return texIndexMap[key] + + for p in m.prims: + if not p['tris']: + continue + pal = m.tile_palette(p['mat']) + register(p['tex'], p['tlut'], pal) + # An animated material can swap to any texture its channel names, so all + # of them have to be decoded up front. + if p['texAnim'] >= 0: + for a in auxAnims: + for t in unique(a.track(p['texAnim'])): + if t is not None: + register(t, p['tlut'], pal) + + prims = [] + for p in m.prims: + if not p['tris']: + continue + pos, uv, nrm, skin = [], [], [], [] + pal = m.tile_palette(p['mat']) + ti = texIndexMap.get((p['tex'], p['tlut'], pal), -1) + # texture-table index -> slot in texOut, for the animated swap + texMap = {} + if p['texAnim'] >= 0: + for a in auxAnims: + for t in unique(a.track(p['texAnim'])): + if t is not None and (t, p['tlut'], pal) in texIndexMap: + texMap[t] = texIndexMap[(t, p['tlut'], pal)] + tw, th = (m.textures[p['tex']]['w'], m.textures[p['tex']]['h']) if ti >= 0 else (32, 32) + for v in p['verts']: + pos += [v[0], v[1], v[2]] + uv += [v[3] / tw, v[4] / th] + nrm += [v[5] / 127.0, v[6] / 127.0, v[7] / 127.0] + skin.append(v[9]) + prims.append(dict(tex=ti, cull=p['cull'], texAnim=p['texAnim'], + texMap={str(k): v for k, v in sorted(texMap.items())}, + pos=pos, uv=uv, nrm=nrm, skin=skin, + idx=[i for t in p['tris'] for i in t])) + + def compress(values, nd): + """Constant tracks collapse to a scalar; most channels never move.""" + r = [round(v, nd) for v in values] + return r[0] if all(v == r[0] for v in r) else r + + anims = [] + for i, off in enumerate(m.anims): + a = Animation(f, off) + nf = max(1, a.nFrames) + tracks = [] + for b in m.bones: + ch = b['chan'] + bind = (b['t'], b['r'], b['s']) + if ch < 0 or a.sample_trs(ch, 0, bind) is None: + tracks.append(None) + continue + samples = [a.sample_trs(ch, fr, bind) for fr in range(nf)] + tracks.append(dict( + t=[compress([s[0][k] for s in samples], 3) for k in range(3)], + r=[compress([s[1][k] for s in samples], 0) for k in range(3)], + s=[compress([s[2][k] for s in samples], 5) for k in range(3)])) + anims.append(dict(index=i, frames=nf, flags=a.flags, + channels=a.nChannels, loopStart=a.loopStart, tracks=tracks)) + + auxOut = [] + for i, a in enumerate(auxAnims): + auxOut.append(dict(index=i, frames=max(1, a.nFrames), flags=a.flags, + loopStart=a.loopStart, + channels=[a.track(c) for c in range(a.nChannels)])) + + return dict( + species=m.species, + name=SPECIES.get(m.species, f'#{m.species}'), + file=os.path.basename(f.name), + rootScale=m.rootScale, + bones=[dict(parent=b['parent'], boneId=b['boneId'], chan=b['chan'], + flags=b['flags'], t=b['t'], r=b['r'], s=b['s']) for b in m.bones], + textures=texOut, + prims=prims, + anims=anims, + auxAnims=auxOut, + fx=dedupe_fx(m.fx), + warnings=m.warnings, + ) + + +SPECIES = {} +_NAMES = ( + "Bulbasaur Ivysaur Venusaur Charmander Charmeleon Charizard Squirtle Wartortle Blastoise " + "Caterpie Metapod Butterfree Weedle Kakuna Beedrill Pidgey Pidgeotto Pidgeot Rattata Raticate " + "Spearow Fearow Ekans Arbok Pikachu Raichu Sandshrew Sandslash NidoranF Nidorina Nidoqueen " + "NidoranM Nidorino Nidoking Clefairy Clefable Vulpix Ninetales Jigglypuff Wigglytuff Zubat " + "Golbat Oddish Gloom Vileplume Paras Parasect Venonat Venomoth Diglett Dugtrio Meowth Persian " + "Psyduck Golduck Mankey Primeape Growlithe Arcanine Poliwag Poliwhirl Poliwrath Abra Kadabra " + "Alakazam Machop Machoke Machamp Bellsprout Weepinbell Victreebel Tentacool Tentacruel Geodude " + "Graveler Golem Ponyta Rapidash Slowpoke Slowbro Magnemite Magneton Farfetchd Doduo Dodrio " + "Seel Dewgong Grimer Muk Shellder Cloyster Gastly Haunter Gengar Onix Drowzee Hypno Krabby " + "Kingler Voltorb Electrode Exeggcute Exeggutor Cubone Marowak Hitmonlee Hitmonchan Lickitung " + "Koffing Weezing Rhyhorn Rhydon Chansey Tangela Kangaskhan Horsea Seadra Goldeen Seaking " + "Staryu Starmie MrMime Scyther Jynx Electabuzz Magmar Pinsir Tauros Magikarp Gyarados Lapras " + "Ditto Eevee Vaporeon Jolteon Flareon Porygon Omanyte Omastar Kabuto Kabutops Aerodactyl " + "Snorlax Articuno Zapdos Moltres Dratini Dragonair Dragonite Mewtwo Mew").split() +for _i, _n in enumerate(_NAMES): + SPECIES[_i + 1] = _n + + +if __name__ == '__main__': + here = os.path.dirname(os.path.abspath(__file__)) + src = sys.argv[1] if len(sys.argv) > 1 else 'assets/us/pokemon_models/24.bin' + dst = sys.argv[2] if len(sys.argv) > 2 else os.path.join(here, 'model.js') + data = extract(src) + body = json.dumps(data, separators=(',', ':')) + with open(dst, 'w') as fp: + fp.write('window.PKMN_MODEL = ' + body + ';\n') + tris = sum(len(p['idx']) // 3 for p in data['prims']) + print(f"{data['name']} (#{data['species']}) bones={len(data['bones'])} prims={len(data['prims'])} " + f"tris={tris} textures={len(data['textures'])} anims={len(data['anims'])}") + print(f"frames per anim: {[a['frames'] for a in data['anims']]}") + if data['warnings']: + print('warnings:', data['warnings'][:5]) + print(f'wrote {dst} ({os.path.getsize(dst)/1024:.0f} KB)') diff --git a/model_extract/pipeline/glb.py b/model_extract/pipeline/glb.py new file mode 100644 index 0000000..ab83931 --- /dev/null +++ b/model_extract/pipeline/glb.py @@ -0,0 +1,274 @@ +#!/usr/bin/env python3 +""" +glTF 2.0 binary writer. + +Each game bone becomes two nodes -- a pivot carrying translation/rotation and a +leaf carrying the accumulated scale -- because the game keeps scale out of the +matrix chain while glTF propagates it to children. See ../README.md. +""" +import json +import math +import struct + +ND = 7 # decimals kept on node rest transforms + + +def quat_from_euler(r): + """The game's rotation is Rx*Ry*Rz in row-vector form (src/F420.c + func_8000F730); build that basis as glTF columns and convert.""" + sx, cx = math.sin(r[0] / 32768 * math.pi), math.cos(r[0] / 32768 * math.pi) + sy, cy = math.sin(r[1] / 32768 * math.pi), math.cos(r[1] / 32768 * math.pi) + sz, cz = math.sin(r[2] / 32768 * math.pi), math.cos(r[2] / 32768 * math.pi) + # rows of the game matrix become the columns of the glTF rotation + m = ((cy*cz, sx*sy*cz - cx*sz, cx*sy*cz + sx*sz), + (cy*sz, sx*sy*sz + cx*cz, cx*sy*sz - sx*cz), + (-sy, sx*cy, cx*cy)) + tr = m[0][0] + m[1][1] + m[2][2] + if tr > 0: + s = math.sqrt(tr + 1.0) * 2 + w = 0.25 * s + x = (m[2][1] - m[1][2]) / s + y = (m[0][2] - m[2][0]) / s + z = (m[1][0] - m[0][1]) / s + elif m[0][0] > m[1][1] and m[0][0] > m[2][2]: + s = math.sqrt(1.0 + m[0][0] - m[1][1] - m[2][2]) * 2 + w = (m[2][1] - m[1][2]) / s + x = 0.25 * s + y = (m[0][1] + m[1][0]) / s + z = (m[0][2] + m[2][0]) / s + elif m[1][1] > m[2][2]: + s = math.sqrt(1.0 + m[1][1] - m[0][0] - m[2][2]) * 2 + w = (m[0][2] - m[2][0]) / s + x = (m[0][1] + m[1][0]) / s + y = 0.25 * s + z = (m[1][2] + m[2][1]) / s + else: + s = math.sqrt(1.0 + m[2][2] - m[0][0] - m[1][1]) * 2 + w = (m[1][0] - m[0][1]) / s + x = (m[0][2] + m[2][0]) / s + y = (m[1][2] + m[2][1]) / s + z = 0.25 * s + n = math.sqrt(x*x + y*y + z*z + w*w) or 1.0 + return [x/n, y/n, z/n, w/n] + + +def pose(bones, sample_fn): + """Returns (pivotT, pivotQ, jointS) for every bone at one instant.""" + acc, pt, pq, js = [], [], [], [] + for i, b in enumerate(bones): + t, r, s = sample_fn(i, b) + pa = acc[b['parent']] if b['parent'] >= 0 else (1.0, 1.0, 1.0) + pt.append([t[0]*pa[0], t[1]*pa[1], t[2]*pa[2]]) + pq.append(quat_from_euler(r)) + a = (pa[0]*s[0], pa[1]*s[1], pa[2]*s[2]) + acc.append(a) + js.append(list(a)) + return pt, pq, js + + +# ------------------------------------------------------------------ glTF build + +class Glb: + def __init__(self): + self.buf = bytearray() + self.views = [] + self.accessors = [] + + def view(self, data, target=None): + while len(self.buf) % 4: + self.buf.append(0) + off = len(self.buf) + self.buf += data + v = dict(buffer=0, byteOffset=off, byteLength=len(data)) + if target: + v['target'] = target + self.views.append(v) + return len(self.views) - 1 + + def accessor(self, data, ctype, atype, count, target=None, + minmax=None, normalized=False): + a = dict(bufferView=self.view(data, target), componentType=ctype, + count=count, type=atype) + if normalized: + a['normalized'] = True + if minmax: + a['min'], a['max'] = minmax + self.accessors.append(a) + return len(self.accessors) - 1 + + def floats(self, values, atype, target=None, minmax=None): + n = {'SCALAR': 1, 'VEC2': 2, 'VEC3': 3, 'VEC4': 4, 'MAT4': 16}[atype] + return self.accessor(struct.pack(f'<{len(values)}f', *values), + 5126, atype, len(values) // n, target, minmax) + + def finish(self, gltf): + gltf['buffers'] = [dict(byteLength=len(self.buf))] + gltf['bufferViews'] = self.views + gltf['accessors'] = self.accessors + js = json.dumps(gltf, separators=(',', ':')).encode() + js += b' ' * (-len(js) % 4) + bin_ = bytes(self.buf) + b'\0' * (-len(self.buf) % 4) + return (struct.pack('= 0 else 0 + nodes[parent].setdefault('children', []).append(pivot_id[i]) + + # ---- textures / materials --------------------------------------------- + images, samplers, textures, materials = [], [], [], [] + if pngs: + samplers.append(dict(magFilter=9729, minFilter=9729, + wrapS=33071, wrapT=33071)) # LINEAR, CLAMP + for i, blob in enumerate(pngs): + images.append(dict(mimeType='image/png', + bufferView=g.view(blob), name=f'tex{i:02d}')) + textures.append(dict(sampler=0, source=i)) + + prims_out = [] + for p in data['prims']: + nv = len(p['pos']) // 3 + pos = [float(v) for v in p['pos']] + mn = [min(pos[k::3]) for k in range(3)] + mx = [max(pos[k::3]) for k in range(3)] + attrs = dict( + POSITION=g.floats(pos, 'VEC3', 34962, (mn, mx)), + NORMAL=g.floats([float(v) for v in p['nrm']], 'VEC3', 34962), + TEXCOORD_0=g.floats([float(v) for v in p['uv']], 'VEC2', 34962), + JOINTS_0=g.accessor( + struct.pack(f'<{nv*4}H', *[v for j in p['skin'] for v in (j, 0, 0, 0)]), + 5123, 'VEC4', nv, 34962), + WEIGHTS_0=g.floats([v for _ in range(nv) for v in (1.0, 0.0, 0.0, 0.0)], + 'VEC4', 34962), + ) + idx = g.accessor(struct.pack(f'<{len(p["idx"])}H', *p['idx']), + 5123, 'SCALAR', len(p['idx']), 34963) + blend = p.get('blend') + mat = dict( + name=f'mat{len(materials):02d}', + alphaMode='BLEND' if blend else 'MASK', + doubleSided=bool(blend) or not (p['cull'] & 0x400), + pbrMetallicRoughness=dict(metallicFactor=0.0, roughnessFactor=0.9), + ) + if blend: + # generated effects are unlit so they read as emissive fire/gas + mat['emissiveFactor'] = [1.0, 1.0, 1.0] + else: + mat['alphaCutoff'] = 0.5 + if p['tex'] >= 0: + mat['pbrMetallicRoughness']['baseColorTexture'] = dict(index=p['tex']) + if blend: + mat['emissiveTexture'] = dict(index=p['tex']) + materials.append(mat) + prims_out.append(dict(attributes=attrs, indices=idx, + material=len(materials) - 1)) + + skin_node = len(nodes) + nodes.append(dict(name=data['name'], mesh=0, skin=0)) + + ident = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] + gltf['skins'] = [dict(joints=joint_id, skeleton=0, + inverseBindMatrices=g.floats(ident * nb, 'MAT4'))] + gltf['meshes'] = [dict(name=data['name'], primitives=prims_out)] + + # ---- animations -------------------------------------------------------- + anims = [] + for a in data['anims']: + nf = a['frames'] + times = [round(fr / 30.0, 6) for fr in range(nf)] # authored at 30 fps + + def sample_fn(i, b, _a=a): + tr = _a['tracks'][i] + if not tr: + return b['t'], b['r'], b['s'] + pick = lambda c, fr: (c if isinstance(c, (int, float)) + else c[min(fr, len(c) - 1)]) + return ([pick(c, sample_fn.fr) for c in tr['t']], + [pick(c, sample_fn.fr) for c in tr['r']], + [pick(c, sample_fn.fr) for c in tr['s']]) + + seq_t = [[] for _ in range(nb)] + seq_q = [[] for _ in range(nb)] + seq_s = [[] for _ in range(nb)] + for fr in range(nf): + sample_fn.fr = fr + pt, pq, js = pose(bones, sample_fn) + for i in range(nb): + if seq_q[i] and sum(x*y for x, y in zip(seq_q[i][-1], pq[i])) < 0: + pq[i] = [-v for v in pq[i]] # keep quaternions continuous + seq_t[i].append(pt[i]); seq_q[i].append(pq[i]); seq_s[i].append(js[i]) + + channels, samplers_a = [], [] + cache = {} + + def time_accessor(keys): + if keys not in cache: + t = times if keys == nf else [times[0], times[-1]] + cache[keys] = g.floats(t, 'SCALAR', minmax=([t[0]], [t[-1]])) + return cache[keys] + + for i in range(nb): + for seq, path, node, dflt in ( + (seq_t[i], 'translation', pivot_id[i], nodes[pivot_id[i]]['translation']), + (seq_q[i], 'rotation', pivot_id[i], nodes[pivot_id[i]]['rotation']), + (seq_s[i], 'scale', joint_id[i], nodes[joint_id[i]]['scale'])): + const = all(v == seq[0] for v in seq) + # A constant channel can only be dropped when it already equals the + # node's rest value; otherwise the node would sit in its bind pose. + if const and [round(c, ND) for c in seq[0]] == dflt: + continue + if const: + seq = [seq[0], seq[0]] + time_acc = time_accessor(len(seq)) + flat = [c for v in seq for c in v] + if path == 'rotation': + out = g.accessor( + struct.pack(f'<{len(flat)}h', + *[max(-32768, min(32767, round(c * 32767))) + for c in flat]), + 5122, 'VEC4', len(seq), normalized=True) + else: + out = g.floats(flat, 'VEC3') + samplers_a.append(dict(input=time_acc, output=out, + interpolation='LINEAR')) + channels.append(dict(sampler=len(samplers_a) - 1, + target=dict(node=node, path=path))) + if channels: + anims.append(dict(name=a['name'], channels=channels, samplers=samplers_a)) + if anims: + gltf['animations'] = anims + + gltf['nodes'] = nodes + gltf['scenes'] = [dict(nodes=[0, skin_node])] + gltf['scene'] = 0 + if images: + gltf['images'] = images + gltf['samplers'] = samplers + gltf['textures'] = textures + gltf['materials'] = materials + return g.finish(gltf) + + diff --git a/model_extract/pipeline/rom.py b/model_extract/pipeline/rom.py new file mode 100644 index 0000000..404db6f --- /dev/null +++ b/model_extract/pipeline/rom.py @@ -0,0 +1,120 @@ +#!/usr/bin/env python3 +""" +Raw ROM access for the Pokemon Stadium (US) model export. + +Everything here is stdlib-only: byte-order fixup, the Yay0 decompressor, the +PERS-SZP wrapper the assets use, and the little archive format that packs many +files into one segment. That is all it takes to get from baserom.z64 to model +data, so the export does not need `make init`, splat or crunch64. +""" +import hashlib +import struct + +# ROM offsets taken from pokestadium-us.yaml. +POKEMON_MODELS = 0x920000 # archive of the 215 battle models +BATTLE_DATA = 0x70D3A0 # per-species battle tables, indexed by D_80075BD0 +MAIN_ROM = 0x1000 # main code segment ... +MAIN_VRAM = 0x80000400 # ... and where it lands in RAM +PTR_TABLE_VRAM = 0x80075BD0 # D_80075BD0[species - 1] -> offset into BATTLE_DATA + +US_MD5 = 'ed1378bc12115f71209a77844965ba50' + + +class Rom: + def __init__(self, path): + data = bytearray(open(path, 'rb').read()) + magic = struct.unpack_from('>I', data, 0)[0] + if magic == 0x37804012: # .v64, byte-swapped pairs + data[0::2], data[1::2] = data[1::2], data[0::2] + elif magic == 0x40123780: # .n64, word-reversed + data = bytearray(b''.join(data[i:i+4][::-1] for i in range(0, len(data), 4))) + elif magic != 0x80371240: # .z64, native big endian + raise ValueError(f'{path}: not an N64 ROM (magic {magic:#010x})') + self.data = bytes(data) + self.md5 = hashlib.md5(self.data).hexdigest() + + @property + def is_expected_us(self): + return self.md5 == US_MD5 + + def u32(self, o): + return struct.unpack_from('>I', self.data, o)[0] + + def vram_to_rom(self, vram): + return MAIN_ROM + (vram - MAIN_VRAM) + + # ---- archive --------------------------------------------------------- + def archive(self, off): + """Segments that hold many files start with + u32 tag, u32 0, u32 totalSize, u32 fileCount + followed by fileCount { u32 offset, u32 size, u32 pad[2] } records, + all relative to the start of the segment (tools/unpack_asset.py). + Only the top three bytes of the first word are reliably zero -- the + model archive puts a nonzero value in the low byte.""" + if (self.u32(off) & 0xFFFFFF00) != 0 or self.u32(off + 4) != 0: + return [self.data[off:]] + count = self.u32(off + 12) + if not 0 < count < 4096: + return [self.data[off:]] + out = [] + for i in range(count): + rec = off + 0x10 + i * 0x10 + start, size = self.u32(rec), self.u32(rec + 4) + out.append(self.data[off + start: off + start + size]) + return out + + +# ------------------------------------------------------------- decompression + +def yay0_decompress(src): + """Nintendo Yay0. Header: magic, decompressed size, link offset, chunk + offset; then a bitstream where a 1 copies one literal byte and a 0 pulls a + (distance, length) pair from the link table.""" + if src[:4] != b'Yay0': + raise ValueError('not Yay0') + size, link_off, chunk_off = struct.unpack_from('>3I', src, 4) + out = bytearray(size) + mask_p, link_p, chunk_p, pos = 0x10, link_off, chunk_off, 0 + mask, bits = 0, 0 + while pos < size: + if bits == 0: + mask = struct.unpack_from('>I', src, mask_p)[0] + mask_p += 4 + bits = 32 + if mask & 0x80000000: + out[pos] = src[chunk_p] + chunk_p += 1 + pos += 1 + else: + link = struct.unpack_from('>H', src, link_p)[0] + link_p += 2 + dist = link & 0x0FFF + count = link >> 12 + if count == 0: + count = src[chunk_p] + 0x12 + chunk_p += 1 + else: + count += 2 + copy = pos - dist - 1 + for _ in range(count): # overlapping runs are legal + out[pos] = out[copy] + pos += 1 + copy += 1 + mask = (mask << 1) & 0xFFFFFFFF + bits -= 1 + return bytes(out) + + +def decompress(blob): + """Unwrap whatever container an asset arrived in.""" + if blob[:8] == b'PERS-SZP': + header = struct.unpack_from('>I', blob, 8)[0] + return yay0_decompress(blob[header:]) + if blob[:4] == b'Yay0': + return yay0_decompress(blob) + return blob + + +def pokemon_models(rom): + """Returns the decompressed model fragments, indexed by file number.""" + return [decompress(b) for b in rom.archive(POKEMON_MODELS)] diff --git a/tests/dramatic_shape_test.lua b/tests/dramatic_shape_test.lua index 6c3c2ed..244e8ff 100644 --- a/tests/dramatic_shape_test.lua +++ b/tests/dramatic_shape_test.lua @@ -204,8 +204,19 @@ T.check(not pinnedIds["battleLayout"], T.eq(layoutGame.save.options.battleLayout, "og", "and a save that had WIDE is set to OG -- the only layout the shot composes in") +-- the STADIUM rung is still a staged fight, so it pins the layout exactly +-- as 2D-3D does: what changes on that rung is what stands on the cells, not +-- where the cells are or what screen they are composed for +Battles.setting:setValue("stadium", layoutGame) +T.eq(Battles.enabled(), true, "STADIUM stages the fight like 2D-3D does") +layoutGame.save.options.battleLayout = "wide" +Runtime.call("ui.options.rows", function(_, r) return r end, layoutGame, + { { id = "battleLayout" } }) +T.eq(layoutGame.save.options.battleLayout, "og", + "and pins BATTLE LAYOUT to OG the same way") + -- switching 3D-BTL off hands the row straight back, WIDE and all -Battles.setting:setIndex(2, layoutGame) +Battles.setting:setValue(false, layoutGame) T.eq(Battles.enabled(), false, "3D-BTL off") local handedBack = Runtime.call("ui.options.rows", function(_, r) return r end, layoutGame, @@ -235,7 +246,7 @@ T.eq(layoutGame.save.options.battleLayout, "wide", -- switch the row back on and the pin comes back with it, FULL or no FULL. -- (Arriving at FULL for real runs applyFull, which switches the row on -- so -- in the game the pin still follows the preset, by way of the row.) -Battles.setting:setIndex(1, layoutGame) +Battles.setting:setValue(true, layoutGame) Runtime.call("ui.options.rows", function(_, r) return r end, layoutGame, { { id = "battleLayout" } }) T.eq(layoutGame.save.options.battleLayout, "og", @@ -366,7 +377,7 @@ T.check(rowIndex(menu, "pipeline:tiltshift"), "T-SHIFT too") -- down than the player left it. do local Battles = run.loader.exports.DRAMATIC_SHAPE.lib.require("OverworldBattle") -Battles.setting:setIndex(2, menuGame) -- staged battles off +Battles.setting:setValue(false, menuGame) -- staged battles off menuGame.save.options.battleLayout = "wide" Pipelines.setLevel("voxel", 2) local layoutMenu = OptionsMenu.new(menuGame) @@ -408,9 +419,10 @@ T.eq(grid.value(), "OFF", "the grid starts off") T.eq(curve.label, "V-CURVE", "the curve row carries its label") T.eq(curve.value(), "OFF", "the curve starts off") T.eq(battles.label, "3D-BTL", "the overworld-battle row carries its label") -T.eq(battles.value(), "ON", - "overworld battles are on by default -- the mode's headline is the world " - .. "in 3D, and a battle is where the player spends half the game") +T.eq(battles.value(), "2D-3D", + "overworld battles are on by default, on the rung that stands the game's " + .. "own pics on the map -- the mode's headline is the world in 3D, and a " + .. "battle is where the player spends half the game") T.eq(backRow.label, "BACK SPRITES", "the back-pic row carries its label") T.eq(backRow.value(), "OFF", "and is off by default -- what the mode advertises is BOTH mons out on the " @@ -1124,11 +1136,131 @@ Game.keypressed(keyGame, "7") T.neq(Curve.setting:get(), curveBefore, "7 cycles V-CURVE") local Battles = run.loader.exports.DRAMATIC_SHAPE.lib.require("OverworldBattle") -T.eq(Battles.setting:get(), true, "3D-BTL starts on") +T.eq(Battles.setting:get(), true, "3D-BTL starts on 2D-3D") Game.keypressed(keyGame, "8") -T.eq(Battles.setting:get(), false, "8 toggles overworld battles off") +T.eq(Battles.setting:get(), "stadium", + "8 steps to STADIUM A -- one press off the default is the more elaborate " + .. "staged fight, not the absent one") Game.keypressed(keyGame, "8") -T.eq(Battles.setting:get(), true, "and back on") +T.eq(Battles.setting:get(), "stadiumB", + "again and it is STADIUM B, the discs") +Game.keypressed(keyGame, "8") +T.eq(Battles.setting:get(), false, "again and overworld battles are off") +Game.keypressed(keyGame, "8") +T.eq(Battles.setting:get(), true, "and the ladder wraps back to 2D-3D") + +-- ------- the eyes blink once a loop, not six times a second +-- +-- A texture animation is sampled at the SKELETAL animation's frame and HOLDS +-- its last entry past the end of its own stream, which is what the game's own +-- sampler does. Wrapping on the stream's length instead plays it over and +-- over: Rattata's standby loop is 40 frames and its blink is 5, so that came +-- out as six blinks a second. +-- +-- Driven through a stub rather than a real rig, because building one needs +-- meshes and there is no graphics context here -- and the rule under test is +-- pure index arithmetic that does not care. +;(function() + local Rig = run.loader.exports.DRAMATIC_SHAPE.lib.require("StadiumRig") + -- one prim on channel 0, whose stream values 6/7/8 map to textures 60/70/80 + local prim = { tex = 1, texAnim = 0, texMap = { [6] = 60, [7] = 70, + [8] = 80 } } + local model = { + prims = { prim }, + textures = { [1] = { w = 1, h = 1 }, [60] = { w = 1, h = 1 }, + [70] = { w = 1, h = 1 }, [80] = { w = 1, h = 1 } }, + -- Rattata's actual blink: open, half, closed, half, open + auxAnims = { { frames = 5, loopStart = 0, channels = { { 6, 8, 7, 8, 6 } } } }, + } + local part = { prim = prim } + local stub = setmetatable({ model = model, parts = { part } }, Rig) + + -- StadiumPack.image wants a real texture; what is asserted here is WHICH + -- index was chosen, so record it instead + local Pack = run.loader.exports.DRAMATIC_SHAPE.lib.require("StadiumPack") + local realImage = Pack.image + local picked + Pack.image = function(_, index) picked = index return nil end + + local function at(frame) + stub.frameAt = frame + stub:textures(1) + return picked + end + + T.eq(at(0), 60, "frame 0 of the blink is the open eye") + T.eq(at(1), 80, "frame 1 is half closed") + T.eq(at(2), 70, "frame 2 is shut") + T.eq(at(4), 60, "and frame 4 is open again -- one blink, five frames") + -- the whole point: frames 5..39 of the forty-frame idle are NOT a second + -- blink, they are the eye staying open + T.eq(at(5), 60, "frame 5, past the end of the blink, HOLDS the open eye") + T.eq(at(20), 60, "and so does frame 20") + T.eq(at(39), 60, "and frame 39, the last of the idle loop") + + Pack.image = realImage +end)() + +-- ------- the collapse waits for the HP bar +-- +-- onFaint fires the moment HP reaches zero, but the engine queues the visible +-- collapse behind the move animation and the bar drain -- seconds later. The +-- model has to wait for the same thing, or a Pokemon lies down while its own +-- health is still draining above it. `shownHP` is the engine's own bar +-- position, so this is the bar and not a guess at how long it takes. +;(function() + local Stad = run.loader.exports.DRAMATIC_SHAPE.lib.require("Stadium") + local ready, due = Stad._faintReady, Stad._faintStillDue + + T.eq(ready({ shownHP = 19, mon = { hp = 0 } }), false, + "a battler at 0 HP whose bar still reads 19 is NOT ready to collapse") + T.eq(ready({ shownHP = 1, mon = { hp = 0 } }), false, + "nor at one point left on the bar") + T.eq(ready({ shownHP = 0, mon = { hp = 0 } }), true, + "and is the moment the bar reaches zero") + T.eq(ready({ mon = { hp = 0 } }), true, + "a battler with no bar to drain collapses at once, rather than never") + T.eq(ready(nil), false, "and a battler that is gone is not ready") + + T.eq(due({ faintQueued = true, mon = { hp = 0 } }), true, + "a queued faint at 0 HP is still owed") + T.eq(due({ faintQueued = true, mon = { hp = 12 } }), false, + "one that has been healed since is not -- the debt is dropped, not paid " + .. "late at whoever is standing there") + T.eq(due({ mon = { hp = 0 } }), false, "and an unqueued battler owes nothing") +end)() + +-- ------- and the two STADIUM rungs are SKIPPED when the models are not there +-- +-- The mod ships no Pokemon Stadium data, so on a machine whose owner has not +-- supplied that ROM the row has two stops rather than four. Checked by gating +-- them off by hand rather than by hiding the packs, because what is being +-- tested is the ladder's behaviour and not the installer's. +;(function() + local gate = Battles.setting.gate + Battles.setting:setGate(function(value) + return value ~= "stadium" and value ~= "stadiumB" + end) + T.eq(Battles.setting:rungs(), 2, + "with no models built the 3D-BTL row offers two rungs, not four") + Battles.setting:setValue(true, Game) + Game.keypressed(keyGame, "8") + T.eq(Battles.setting:get(), false, + "and 8 steps straight past both STADIUM rungs to OFF") + Game.keypressed(keyGame, "8") + T.eq(Battles.setting:get(), true, "and back to 2D-3D") + + -- a save that CHOSE stadium before the ROM went missing reads as the + -- default, rather than as a mode with nothing behind it -- and the stored + -- value is left alone, so putting the ROM back restores the choice + Battles.setting.index = 2 + T.eq(Battles.setting:get(), true, + "a stored STADIUM with no models behind it reads as 2D-3D") + Battles.setting:setGate(gate) + T.eq(Battles.setting:get(), "stadium", + "and comes back the moment the models do") + Battles.setting:setValue(true, Game) +end)() -- ------- SELECT makes the same step the 3 key does -- @@ -2579,7 +2711,7 @@ T.eq(Battles.backPinned(), false, "so nothing is pinned to the menu") local backGame = { save = { options = { modOptions = {} } }, mods = { modOptions = {} } } -Battles.setting:setIndex(1, backGame) -- 3D-BTL on +Battles.setting:setValue(true, backGame) -- 3D-BTL on 2D-3D Battles.backSetting:setIndex(2, backGame) -- BACK SPRITES on T.eq(Battles.backPinned(), true, "switched on, the back pic is pinned") T.eq(backGame.save.options.modOptions.DRAMATIC_SHAPE.battleBack, true, @@ -2590,7 +2722,7 @@ T.eq(backGame.save.options.modOptions.DRAMATIC_SHAPE.battles, true, -- and it means nothing at all with staged battles off: there is no staged -- shot for a back pic to be pinned in front of, and the engine's own battle -- screen already draws exactly this -Battles.setting:setIndex(2, backGame) +Battles.setting:setValue(false, backGame) T.eq(Battles.backPinned(), false, "with 3D-BTL off the setting decides nothing, whatever it is left at") T.eq(Battles.backSetting:get(), true, "without being rewritten underneath") @@ -2606,7 +2738,7 @@ T.check(offIds["DRAMATIC_SHAPE:battles"], "3D-BTL itself is still offered") T.check(not offIds["DRAMATIC_SHAPE:battleBack"], "but BACK SPRITES is off the menu while there is no staged fight to be about") -Battles.setting:setIndex(1, backGame) +Battles.setting:setValue(true, backGame) local onRows = Runtime.call("ui.options.rows", function(_, r) return r end, backGame, { { id = "tilt" } }) local onAt = {} @@ -4929,6 +5061,106 @@ end)() T.eq(Gun.visible(), false, "and it is not drawn with the mode off") end)() +-- ------- STADIUM: the .dsm packs, and the rig that reads them +-- +-- Wrapped in its own scope for the same reason the horde block above is: +-- the main chunk is at Lua's 200-local ceiling, so a new top-level local +-- would refuse to compile. +-- +-- What this is really guarding is the FORMAT SEAM. tools/stadium_pack.py +-- writes those files and lib/StadiumPack.lua reads them, and the two agree +-- only by having been written to agree -- there is no schema between them. +-- A field inserted on one side and not the other slides every byte after it +-- and produces no error at all: the models load, the numbers are garbage, +-- and every Pokemon is silently scaled to nothing. That is exactly what +-- happened once during development, and the assertion that caught it is the +-- one below -- walk the bind pose with the REAL rig code and check it +-- against the header the packer wrote, which cannot agree by accident. +;(function() +local Pack = run.loader.exports.DRAMATIC_SHAPE.lib.require("StadiumPack") +local Rig = run.loader.exports.DRAMATIC_SHAPE.lib.require("StadiumRig") + +-- The packs are generated (tools/stadium_pack.py) and a checkout without +-- them is a legitimate state -- the mode declines per Pokemon. So the whole +-- block is skipped rather than failed when they are not there. +if not Pack.available(25) then + T.check(true, "stadium packs are not installed -- pack assertions skipped") + return +end + +local pikachu = Pack.load(25) +T.check(pikachu ~= nil, "a stadium pack loads") +T.eq(pikachu.species, 25, "and knows which species it is") +T.eq(pikachu.boneCount, 37, "Pikachu's rig is 37 bones, as the extract reports") +T.check(pikachu.rootScale > 0.09 and pikachu.rootScale < 0.11, + "the model_root scale came through as the 0.1 the geo layout sets") + +-- the battle system's own slot table: idle is animation 0 for all 151 +-- species (manifest.json's animationSlots calls that one `code` evidence) +T.eq(pikachu.ctx[Pack.SLOT.idle], 0, "the idle slot resolves to animation 0") +T.check(pikachu.ctx[Pack.SLOT.faint] ~= Pack.NONE, "and the faint slot resolves") +T.check(pikachu.ctx[Pack.SLOT.entrance] ~= Pack.NONE, "and the entrance slot") + +-- the move table is the Gen 1 move id, which is the engine's own `index` +T.eq(#pikachu.moveAnim, Pack.N_MOVES, "every move id has a row") +T.check(pikachu.moveAnim[85] ~= Pack.NONE, + "and THUNDERBOLT (move 85) names an animation Pikachu has") + +-- animations decode lazily; asking for one is what builds its tracks +local tracks = Pack.tracks(pikachu, 1) +T.check(type(tracks) == "table", "an animation's tracks decode on demand") +local animated = 0 +for b = 1, pikachu.boneCount do if tracks[b] then animated = animated + 1 end end +T.check(animated > 0 and animated <= pikachu.boneCount, + "and move a sane number of the rig's bones") + +-- THE SEAM. Walk the bind pose with the shipping rig code and measure it +-- the way tools/stadium_pack.py measured it. The packer's own answer was +-- checked against the reference glTF export on all 151 species, so +-- agreement here means the byte layout, the bone tree, the rotation basis +-- and the two-chain scale split all survived the trip into Lua. +local function bindExtent(model) + local rig = setmetatable({ + model = model, pivotM = {}, drawM = {}, accX = {}, accY = {}, accZ = {}, + parts = {}, + }, Rig) + rig:pose(nil, 0, false) + local drw = rig.drawM + local lo, hi = math.huge, -math.huge + for _, prim in ipairs(model.prims) do + for k = 1, prim.vertCount do + local o = (prim.bone[k] - 1) * 12 + local y = drw[o + 5] * prim.px[k] + drw[o + 6] * prim.py[k] + + drw[o + 7] * prim.pz[k] + drw[o + 8] + y = y * model.rootScale + if y < lo then lo = y end + if y > hi then hi = y end + end + end + return hi - lo, lo +end + +for _, dex in ipairs({ 25, 6, 95, 143 }) do + local model = Pack.load(dex) + if model then + local h, f = bindExtent(model) + -- a tenth of a game unit of slack: bone translations are stored as + -- integers and the packer measured in doubles + T.check(math.abs(h - model.height) < 0.5, + ("species %d: the rig's bind pose is the height the pack recorded " + .. "(walked %.2f, header %.2f)"):format(dex, h, model.height)) + T.check(math.abs(f - model.floor) < 0.5, + ("species %d: and its feet are where the pack put them"):format(dex)) + end +end + +-- the three species whose standby loop is corrupt in the source extraction +-- are marked to hold their bind pose instead of coming apart +T.eq(Pack.load(126).staticPose, true, + "Magmar is held at its bind pose -- its source animations are broken") +T.eq(pikachu.staticPose, false, "and a species with good data is not") +end)() + Pipelines.reset() run.release() diff --git a/tests/stadium_budget_test.lua b/tests/stadium_budget_test.lua new file mode 100644 index 0000000..10c5f90 --- /dev/null +++ b/tests/stadium_budget_test.lua @@ -0,0 +1,149 @@ +-- What the model build COSTS -- the numbers that decide whether it can run +-- on a phone. +-- +-- luajit mods/DramaticShapeVoxelMod/tests/stadium_budget_test.lua [--rom=PATH] +-- +-- Run from the PROJECT ROOT. +-- +-- ------- why this is a test and not a note +-- +-- The extraction is pure Lua on purpose -- no FFI, no native helper, no +-- second process -- specifically so it can run everywhere LOVE does, phones +-- included. That claim is about MEMORY as much as about which functions +-- exist: a desktop will not notice a transient peak that would have a mobile +-- OS kill the process, and the peak is not visible by reading the code. +-- +-- So this measures it, and fails if the two things that must stay bounded +-- stop being bounded: +-- +-- the WORKING SET must not grow with the number of species done, or the +-- build gets heavier the longer it runs and dies somewhere in the 140s +-- +-- the PEAK must stay under a budget a phone can be expected to have +-- spare, on top of a game that is already running +-- +-- The ROM itself is most of the floor and cannot be avoided -- the archive is +-- addressed by absolute offset -- so it is reported separately from the +-- per-species work built on top of it. + +local args = {} +for _, a in ipairs({ ... }) do + local k, v = a:match("^%-%-([%w_]+)=(.*)$") + if k then args[k] = v end +end + +local MOD = "mods/DramaticShapeVoxelMod" +local ROM = args.rom or (MOD .. "/model_extract/baseroms/us/baserom.z64") + +-- How much headroom the whole build may take on top of the ROM, in MB. Sized +-- against the smallest thing this is expected to run on rather than against +-- what is convenient: a mid-range phone from several years ago, with a game +-- already resident. +local PEAK_BUDGET_MB = 220 + +-- How much the working set may drift between the first ten species and the +-- last ten, in MB. Not zero -- species differ in size by a factor of ten, and +-- the collector is not obliged to run on any particular schedule -- but a +-- genuine leak shows up here as tens of megabytes. +local DRIFT_BUDGET_MB = 24 + +local loaded = {} +local V = {} +function V.require(name) + if loaded[name] == nil then + local chunk = assert(loadfile(MOD .. "/lib/" .. name .. ".lua")) + loaded[name] = chunk(V) + end + return loaded[name] +end +V.mod = { log = { warn = function() end, info = function() end } } + +local StadiumRom = V.require("StadiumRom") +local StadiumBuild = V.require("StadiumBuild") + +local function mb() + return collectgarbage("count") / 1024 +end + +-- A single collectgarbage() is not guaranteed to finish a cycle, and a +-- half-finished one reads tens of megabytes high -- which showed up here as +-- "settled" figures BELOW the baseline they were measured against. Run it +-- until the number stops moving. +local function settle() + local last = mb() + for _ = 1, 8 do + collectgarbage("collect") + local now = mb() + if now >= last - 0.05 then return now end + last = now + end + return mb() +end + +-- The baseline is taken BEFORE the ROM is read, or the file is already on the +-- heap when it is measured and the ROM appears to cost nothing. +local base = settle() + +local fp = io.open(ROM, "rb") +if not fp then + io.stderr:write("no ROM at " .. ROM .. "\n") + os.exit(2) +end +local romBytes = fp:read("*a") +fp:close() + +local rom = assert(StadiumRom.open(romBytes)) +local withRom = settle() + +local peak, settled = withRom, {} +local bytes = 0 +local t0 = os.clock() + +for fileno = 0, StadiumRom.N_POKEMON - 1 do + local res = assert(StadiumBuild.species(rom, fileno)) + bytes = bytes + #res.bytes + -- the live peak, before the collector has been asked for anything: this is + -- what the allocator actually had to find + local live = mb() + if live > peak then peak = live end + -- and the settled working set, which is what must not creep + settled[fileno + 1] = settle() +end + +local dt = os.clock() - t0 + +local function avg(from, to) + local sum = 0 + for i = from, to do sum = sum + settled[i] end + return sum / (to - from + 1) +end + +local first = avg(1, 10) +local last = avg(#settled - 9, #settled) +local drift = last - first + +io.write(("ROM %6.1f MB (the file, held for the whole build)\n") + :format(withRom - base)) +io.write(("peak working set %6.1f MB (over the ROM)\n"):format(peak - withRom)) +io.write(("settled, first 10 %6.1f MB\n"):format(first - withRom)) +io.write(("settled, last 10 %6.1f MB\n"):format(last - withRom)) +io.write(("drift %+6.1f MB (budget %.0f)\n") + :format(drift, DRIFT_BUDGET_MB)) +io.write(("total peak %6.1f MB (budget %.0f)\n") + :format(peak, PEAK_BUDGET_MB)) +io.write(("output %6.1f MB in %.1fs (%.0f ms a species)\n") + :format(bytes / 1e6, dt, dt * 1000 / StadiumRom.N_POKEMON)) + +local fail = false +if peak > PEAK_BUDGET_MB then + io.write(("FAIL peak %.1f MB is over the %.0f MB budget\n") + :format(peak, PEAK_BUDGET_MB)) + fail = true +end +if drift > DRIFT_BUDGET_MB then + io.write(("FAIL the working set grew %.1f MB across the run -- something is " + .. "being retained per species\n"):format(drift)) + fail = true +end +if fail then os.exit(1) end +io.write("PASS -- bounded working set, peak within budget\n") diff --git a/tests/stadium_extract_test.lua b/tests/stadium_extract_test.lua new file mode 100644 index 0000000..626d517 --- /dev/null +++ b/tests/stadium_extract_test.lua @@ -0,0 +1,128 @@ +-- The Lua ROM extractor, against the Python packer that is its oracle. +-- +-- luajit mods/DramaticShapeVoxelMod/tests/stadium_extract_test.lua \ +-- [--rom=PATH] [--oracle=DIR] [--only=25,6] [--out=DIR] +-- +-- Run from the PROJECT ROOT. Defaults: the ROM under +-- model_extract/baseroms/, the oracle in assets/stadium (whatever +-- tools/stadium_pack.py last wrote there). +-- +-- ------- what this is for +-- +-- lib/StadiumRom, StadiumFragment, StadiumFx and StadiumBuild are a port of +-- roughly fifteen hundred lines of dense numeric Python -- an F3DEX2 +-- interpreter, six texture codecs, a bit-packed animation sampler, a noise +-- generator and a binary writer. Reading a port of that twice does not +-- establish that it is right. Producing the same thirty-four megabytes, +-- byte for byte, does. +-- +-- It is also the guard on the two of them DRIFTING. The packer and the +-- extractor have to keep agreeing about the format forever, and a change to +-- one that is not made to the other shows up here as a differing offset +-- rather than as a Pokemon that renders as noise three months later. +-- +-- Headless: no LOVE, no graphics. Everything these four modules do is +-- arithmetic on strings. + +local args = {} +for _, a in ipairs({ ... }) do + local k, v = a:match("^%-%-([%w_]+)=(.*)$") + if k then args[k] = v else args[a:gsub("^%-%-", "")] = true end +end + +local MOD = "mods/DramaticShapeVoxelMod" +local ROM = args.rom or (MOD .. "/model_extract/baseroms/us/baserom.z64") +local ORACLE = args.oracle or (MOD .. "/assets/stadium") + +-- ------- the mod namespace, enough of it to load four modules + +local loaded = {} +local V = {} +function V.require(name) + if loaded[name] == nil then + local chunk = assert(loadfile(MOD .. "/lib/" .. name .. ".lua")) + loaded[name] = chunk(V) + end + return loaded[name] +end +V.mod = { log = { warn = function() end, info = function() end } } + +local StadiumRom = V.require("StadiumRom") +local StadiumBuild = V.require("StadiumBuild") + +-- ------- run + +local function readFile(path) + local fp = io.open(path, "rb") + if not fp then return nil end + local data = fp:read("*a") + fp:close() + return data +end + +local romBytes = readFile(ROM) +if not romBytes then + io.stderr:write("no ROM at " .. ROM .. "\n") + os.exit(2) +end + +local rom, err = StadiumRom.open(romBytes) +if not rom then + io.stderr:write("could not open ROM: " .. tostring(err) .. "\n") + os.exit(2) +end + +local only = nil +if args.only then + only = {} + for n in args.only:gmatch("%d+") do only[tonumber(n)] = true end +end + +local checked, matched, missing, failed = 0, 0, 0, 0 +local firstBad = nil +local t0 = os.clock() + +for fileno = 0, StadiumRom.N_POKEMON - 1 do + local ok, res = pcall(StadiumBuild.species, rom, fileno) + if not ok or not res then + -- res carries the message on the error path + io.write(("file %d: EXTRACT FAILED: %s\n"):format(fileno, tostring(res))) + failed = failed + 1 + elseif not only or only[res.species] then + checked = checked + 1 + if args.out then + local fp = io.open(("%s/%03d.dsm"):format(args.out, res.species), "wb") + if fp then fp:write(res.bytes) fp:close() end + end + local want = readFile(("%s/%03d.dsm"):format(ORACLE, res.species)) + if not want then + missing = missing + 1 + elseif want == res.bytes then + matched = matched + 1 + else + -- where, exactly: the first differing byte localises a format mistake + -- far faster than "the file is wrong" does + local at = nil + local n = math.min(#want, #res.bytes) + for i = 1, n do + if want:sub(i, i) ~= res.bytes:sub(i, i) then at = i break end + end + io.write(("%03d.dsm DIFFERS: %d bytes vs %d, first at %s\n") + :format(res.species, #res.bytes, #want, + at and ("offset " .. at) or "(one is a prefix)")) + if not firstBad then firstBad = res.species end + end + end +end + +io.write(("\n%d checked, %d identical, %d differ, %d oracle files missing, " + .. "%d extractions failed (%.1fs)\n") + :format(checked, matched, checked - matched - missing, missing, + failed, os.clock() - t0)) + +if matched == checked and failed == 0 and missing == 0 then + io.write("PASS -- the Lua extractor reproduces the packer exactly\n") + os.exit(0) +end +io.write("FAIL\n") +os.exit(1) diff --git a/tests/stadium_pack_probe.lua b/tests/stadium_pack_probe.lua new file mode 100644 index 0000000..fb1d273 --- /dev/null +++ b/tests/stadium_pack_probe.lua @@ -0,0 +1,115 @@ +-- Probe: read the .dsm packs back with the mod's OWN reader and print what +-- it made of them, so the Lua side can be diffed against the packer's +-- --report output. Headless -- no love.graphics, no meshes. +-- +-- luajit mods/DramaticShapeVoxelMod/tests/stadium_pack_probe.lua [dex ...] +-- +-- Run from the repository root. + +package.path = "./?.lua;./?/init.lua;" .. package.path + +local ROOT = "mods/DramaticShapeVoxelMod" + +-- the mod namespace lib/ modules expect (see main.lua), with just enough of +-- it for the two files under test +local V = {} +local modules = {} +V.mod = { + log = { + warn = function(_, fmt, ...) print("[warn] " .. fmt:format(...)) end, + info = function(_, fmt, ...) print("[info] " .. fmt:format(...)) end, + }, + read = function(_, rel) + local fp = io.open(ROOT .. "/" .. rel, "rb") + if not fp then return nil end + local bytes = fp:read("*a") + fp:close() + return bytes + end, +} +function V.require(name) + if modules[name] then return modules[name] end + local chunk = assert(loadfile(ROOT .. "/lib/" .. name .. ".lua")) + modules[name] = chunk(V) + return modules[name] +end + +-- StadiumRig pulls in Voxel3D, which needs love; the pose walk itself does +-- not, so the require is stubbed out to the one field it reads. +modules.Voxel3D = { FORMAT = {} } + +local Pack = V.require("StadiumPack") +local Rig = V.require("StadiumRig") + +local want = {} +for i = 1, #arg do want[#want + 1] = tonumber(arg[i]) end +if #want == 0 then want = { 25, 6, 130, 95, 50, 10, 143, 92, 41, 73 } end + +print(("%-4s %-6s %6s %6s %6s %8s %8s %8s %8s") + :format("dex", "bones", "prims", "anims", "tex", "root", "height", + "floor", "radius")) +for _, dex in ipairs(want) do + local m = Pack.load(dex) + if not m then + print(("%-4d -- did not load"):format(dex)) + else + print(("%-4d %-6d %6d %6d %6d %8.4f %8.2f %8.2f %8.2f") + :format(dex, m.boneCount, m.primCount, m.animCount, m.texCount, + m.rootScale, m.height, m.floor, m.radius)) + + -- the bind pose, walked by the REAL rig code on a bare instance (no + -- meshes, so no graphics context needed), measured the same way + -- tools/stadium_pack.py measures it. Agreement here means the byte + -- format, the bone tree, the rotation basis and the two-chain scale + -- split all survived the trip into Lua. + local rig = setmetatable({ + model = m, pivotM = {}, drawM = {}, accX = {}, accY = {}, accZ = {}, + parts = {}, + }, Rig) + local function boxAt(anim, frame, wrap) + rig:pose(anim, frame, wrap) + local drw = rig.drawM + local lo, hi = math.huge, -math.huge + for _, prim in ipairs(m.prims) do + for k = 1, prim.vertCount do + local o = (prim.bone[k] - 1) * 12 + local x, y, z = prim.px[k], prim.py[k], prim.pz[k] + local wy = drw[o + 5] * x + drw[o + 6] * y + drw[o + 7] * z + + drw[o + 8] + wy = wy * m.rootScale + if wy < lo then lo = wy end + if wy > hi then hi = wy end + end + end + return hi - lo, lo + end + + local h, f = boxAt(nil, 0, false) + print((" bind pose walked in Lua: height %8.2f floor %8.2f " + .. "(header says %8.2f / %8.2f)%s") + :format(h, f, m.height, m.floor, + (math.abs(h - m.height) < 0.5 + and math.abs(f - m.floor) < 0.5) and " OK" or " MISMATCH")) + + -- the animation tables, decoded lazily like the game does it + local idle = m.ctx[Pack.SLOT.idle] + local names = {} + for i, a in ipairs(m.anims) do names[i] = a.name end + print((" anims: %s"):format(table.concat(names, " "))) + print((" idle slot -> %s, entrance -> %s, faint -> %s") + :format(tostring(idle), tostring(m.ctx[Pack.SLOT.entrance]), + tostring(m.ctx[Pack.SLOT.faint]))) + local tracks = Pack.tracks(m, (idle or 0) + 1) + local animated = 0 + for b = 1, m.boneCount do if tracks and tracks[b] then animated = animated + 1 end end + print((" idle: %d frames, %d/%d bones animated") + :format(m.anims[(idle or 0) + 1].frames, animated, m.boneCount)) + -- the POSED extent, which is what actually gets drawn. Compare against + -- tools/stadium_pack.py's anim_sample, which was checked frame for + -- frame against the reference glTF export. + for _, fr in ipairs({ 0, 1, 5 }) do + local ah, af = boxAt((idle or 0) + 1, fr, true) + print((" idle frame %d: y %8.2f .. %8.2f"):format(fr, af, af + ah)) + end + end +end diff --git a/tests/stadium_shots.lua b/tests/stadium_shots.lua new file mode 100644 index 0000000..b1d9066 --- /dev/null +++ b/tests/stadium_shots.lua @@ -0,0 +1,294 @@ +-- Driver: screenshot a STADIUM battle -- the 3D-BTL row's third rung, where +-- the two Pokemon are the Pokemon Stadium battle models rather than the +-- game's own pics stood up on their tiles. +-- +-- What has to be looked at is a SPREAD OF SPECIES, because almost everything +-- that can go wrong here is per-model: how big it comes out (the size ladder +-- compresses a sixteenfold spread of authored heights -- see StadiumMon), +-- whether its feet are on the ground (the floor rule has to tell a hovering +-- Zubat from a Tentacruel centred on its own origin), whether the eyes +-- animate, and whether the species carries generated flame prims. So the +-- list below is deliberately awkward: the smallest and the largest in the +-- set, a hoverer, a floater, and the two species whose idle animation is +-- known to be wrong in the source data. +-- +-- SHOT_DIR=.scratchpad DS_STADIUM_DEBUG=1 \ +-- POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/stadium_shots.lua love . +-- +-- SHOT_DIR must already exist: the capture writes with io.open, which does +-- not create directories. +return function(game) + local U = dofile("tests/drivers/util.lua") + local DIR = os.getenv("SHOT_DIR") or ".scratchpad" + local Pokemon = require("src.pokemon.Pokemon") + local BattleState = require("src.battle.BattleState") + + local exports = game.mods and game.mods.exports + local lib = exports and exports.DRAMATIC_SHAPE and exports.DRAMATIC_SHAPE.lib + if not lib then + U.log("DRAMATIC_SHAPE is not loaded -- enable it and run again") + return + end + local Battles = lib.require("OverworldBattle") + local Stadium = lib.require("Stadium") + local Pack = lib.require("StadiumPack") + + local Install = lib.require("StadiumInstall") + + game.save.player.name = "RED" + + -- foe, and the player's own, chosen to put two different problems in one + -- frame wherever possible + local CASES = { + { "PIKACHU", "CHARIZARD" }, -- the reference pair; Charizard has flame + { "ONIX", "DIGLETT" }, -- the tallest against nearly the shortest + { "ZUBAT", "TENTACRUEL" }, -- hovers above its origin / hangs below it + { "GASTLY", "CATERPIE" }, -- a floater and the smallest in the set + { "EXEGGUTOR", "MAGMAR" }, -- both idle animations are wrong at source + { "GYARADOS", "SNORLAX" }, -- the two biggest bodies in the set + } + + -- ONTO THE MAP FIRST, before anything below waits on anything. + -- + -- The models are built out of the player's own ROM on first run, on a + -- loading screen, and that screen is pushed from the mod's update hook on + -- the first frame THE OVERWORLD IS THE TOP STATE (StadiumScreen.maybePush). + -- A driver that waits for the build before it has got the player onto a map + -- waits forever: the condition that starts the build is the very thing the + -- waiting is postponing. + -- DS_MAP puts the fight somewhere else. It exists for STADIUM B, whose + -- whole claim is that it carries its stage: the shot has to be checked in a + -- CAVE and in a SHOP as well as on a route, both because those are the + -- places the map-staged rungs decline, and because the rung is supposed to + -- take that place's own sky and light with it. + local MAP = os.getenv("DS_MAP") or "ROUTE_1" + local MX = tonumber(os.getenv("DS_X") or "") or 5 + local MY = tonumber(os.getenv("DS_Y") or "") or 8 + U.teleport(game, MAP, MX, MY, "down") + + -- Now wait it out, and say how long it took -- that number is what decides + -- whether the loading screen is acceptable rather than merely correct. + local waited, shotLoad = 0, false + while (Install.pending() or Install.status.state == "building") + and waited < 5400 do + if not shotLoad and Install.status.state == "building" + and (Install.status.done or 0) > 20 then + U.shot(game, ("%s/00_loading.png"):format(DIR)) + shotLoad = true + end + U.wait(10) + waited = waited + 10 + end + if waited > 0 then + U.log(("waited %d frames (%.1fs) for the model build -- %s") + :format(waited, waited / 60, tostring(Install.status.state))) + if Install.status.error then + U.log("build error: " .. tostring(Install.status.error)) + end + end + U.log(("rom present: %s, packs ready: %s, stadium available: %s") + :format(tostring(Install.romPresent()), tostring(Install.ready()), + tostring(Install.available()))) + + -- the rung under test, and the back pic OFF: BACK SPRITES would keep the + -- player's own side on the menu, which is exactly the half of the shot + -- this driver exists to look at + local RUNGS = { cards = true, a = "stadium", b = "stadiumB" } + local rung = RUNGS[os.getenv("DS_RUNG") or "a"] or "stadium" + Battles.setting:setValue(rung, game) + Battles.backSetting:setValue(false, game) + -- and PIN THE CLOCK. The hour multiplies everything in the shot -- the sky, + -- the tint, the weight of the shadows -- so a driver left on CYCLE + -- photographs a different scene every run, and two runs of it cannot be + -- compared. DS_TOD overrides for a deliberate look at dusk or night. + lib.require("DayNight").setting:setValue(os.getenv("DS_TOD") or "day", game) + U.log(("3D-BTL = %s, stadium enabled = %s, discs = %s") + :format(tostring(Battles.setting:get()), tostring(Stadium.enabled()), + tostring(Stadium.discs()))) + + -- did the models actually get built? one line rather than 151 silent + -- declines + local have, missing = 0, {} + for dex = 1, 151 do + if Pack.available(dex) then have = have + 1 + elseif #missing < 6 then missing[#missing + 1] = dex end + end + U.log(("stadium packs present: %d/151%s"):format( + have, #missing > 0 and (" (missing " .. table.concat(missing, ",") + .. "...)") or "")) + + -- let the neighbourhood's meshes land before the first fight, so the + -- opening frame is not the flat fallback + U.wait(90) + + -- ------- DS_BLINK: how often does the eye actually change? + -- + -- The texture animation rides the SKELETAL animation's frame and clamps + -- past the end of its own stream (StadiumRig.textures). Get either wrong + -- and a blink becomes a twitch: Rattata's standby loop is forty frames and + -- its blink is five, so wrapping on the blink's own length plays it six + -- times a second. + -- + -- Counted rather than looked at, because "too fast" is a RATE and a + -- screenshot has no rate in it. This walks the idle loop frame by frame and + -- reports how many times the eye texture changes per second. + if os.getenv("DS_BLINK") then + local Pack = lib.require("StadiumPack") + local Rig = lib.require("StadiumRig") + for _, dex in ipairs({ 19, 4, 1, 25 }) do + local model = Pack.load(dex) + local rig = model and Rig.new(model) + if rig then + local idle = model.ctx[Pack.SLOT.idle] + local anim = (idle ~= Pack.NONE) and (idle + 1) or nil + local rec = anim and model.anims[anim] + -- which prim carries the eye, and what it shows each frame + local seen, changes, last = {}, 0, nil + local SECONDS = 4 + for f = 0, SECONDS * Pack.FPS - 1 do + rig:pose(anim, f, true) + rig:textures(rec and rec.aux or nil) + local key = {} + for i, part in ipairs(rig.parts) do + if part.prim.texAnim and part.prim.texAnim >= 0 then + key[#key + 1] = i .. ":" .. tostring(part.texture) + end + end + key = table.concat(key, ",") + if last and key ~= last then changes = changes + 1 end + last = key + seen[key] = true + end + local looks = 0 + for _ in pairs(seen) do looks = looks + 1 end + local period = rec and (rec.frames / Pack.FPS) or 0 + U.log(("BLINK dex %3d: idle %s frames (%.2fs), aux %s frames -- " + .. "%d texture changes in %ds, %d distinct looks; the idle " + .. "loop comes round every %.2fs, so that is %.1f changes a " + .. "cycle") + :format(dex, tostring(rec and rec.frames), period, + tostring(rec and rec.aux + and model.auxAnims[rec.aux].frames), + changes, SECONDS, looks, period, + period > 0 and changes / (SECONDS / period) or 0)) + rig:release() + end + end + U.log("done -- " .. DIR) + return + end + + -- ------- DS_FAINT: does the collapse wait for the bar? + -- + -- The faint animation must not start until the foe's HP bar has finished + -- emptying: `onFaint` fires the instant HP reaches zero, but the engine + -- queues the visible collapse behind the move animation and the drain, and + -- a Pokemon that lies down while its own health is still draining above it + -- reads as a bug (see Stadium's faintReady). + -- + -- A TIMELINE rather than a screenshot, because what is being checked is an + -- ORDER: the frame the bar reaches zero against the frame the animation + -- changes. One printed line per frame settles that; two stills cannot. + if os.getenv("DS_FAINT") then + local Stadium2 = lib.require("Stadium") + game.save.party = { Pokemon.new(game.data, "CHARIZARD", 60) } + local battle = BattleState.newWild(game, "PIKACHU", 5) + battle.onFinish = function() end + game.overworld:pushBattle(battle) + U.wait(70) + for _ = 1, 40 do + if battle.phase == "menu" then break end + U.tap(game, "a") + U.wait(10) + end + U.tap(game, "a") + U.wait(12) + U.tap(game, "a") + + local barZeroAt, animAt, shot = nil, nil, false + for f = 1, 400 do + -- keep advancing the text, as a player would. Without this the queue + -- blocks on the damage message and the HP bar never drains at all -- + -- which is a perfectly good demonstration that the collapse now waits, + -- and no demonstration whatever that it eventually arrives. + if f % 20 == 0 then U.tap(game, "a") end + U.wait(1) + local foe = battle.enemy + local shown = foe and foe.shownHP + local anim = Stadium2.animOf and Stadium2.animOf("enemy") or nil + if f % 25 == 0 or (shown and shown <= 0 and not barZeroAt) then + U.log((" f=%3d phase=%s shownHP=%s hp=%s queued=%s anim=%s") + :format(f, tostring(battle.phase), tostring(shown), + tostring(foe and foe.mon and foe.mon.hp), + tostring(foe and foe.faintQueued), tostring(anim))) + end + if shown and shown <= 0 and not barZeroAt then barZeroAt = f end + if anim == "faint" and not animAt then animAt = f end + -- a still from the middle of the drain: the foe must still be standing + if shown and shown > 0 and not shot and barZeroAt == nil + and foe and foe.faintQueued then + U.shot(game, ("%s/faint_1_draining.png"):format(DIR)) + shot = true + end + if animAt and f > animAt + 20 then + U.shot(game, ("%s/faint_2_collapsed.png"):format(DIR)) + break + end + end + U.log(("FAINT: bar reached zero at frame %s, faint animation began at %s") + :format(tostring(barZeroAt), tostring(animAt))) + if barZeroAt and animAt then + U.log((animAt >= barZeroAt) + and " OK -- the collapse waits for the bar" + or " WRONG -- the collapse ran while the bar was still draining") + end + while game.stack:top() and game.stack:top() ~= game.overworld do + game.stack:pop() + end + U.wait(10) + U.log("done -- " .. DIR) + return + end + + for i, case in ipairs(CASES) do + local foe, mine = case[1], case[2] + local tag = ("%02d_%s_vs_%s"):format(i, mine:lower(), foe:lower()) + game.save.party = { Pokemon.new(game.data, mine, 40) } + + local battle = BattleState.newWild(game, foe, 30) + battle.onFinish = function() end + game.overworld:pushBattle(battle) + + -- The wipe, then the intro chatter, and -- the part that matters -- + -- far enough past it that the player's own Pokemon has been SENT OUT. + -- Before that the player's side is legitimately the trainer's back + -- sprite, with no Pokemon on the field to model at all; a shot taken + -- there looks exactly like a bug and is not one. + U.wait(70) + -- tap until the FIGHT menu is up, which is the first moment BOTH + -- Pokemon are on the field in their standby loop + for _ = 1, 40 do + if battle.phase == "menu" then break end + U.tap(game, "a") + U.wait(10) + end + U.wait(45) + U.shot(game, ("%s/%s_1_idle.png"):format(DIR, tag)) + + -- FIGHT -> the first move, which is where the attack animation is + U.tap(game, "a") + U.wait(12) + U.tap(game, "a") + U.wait(22) + U.shot(game, ("%s/%s_2_attack.png"):format(DIR, tag)) + U.wait(45) + U.shot(game, ("%s/%s_3_hit.png"):format(DIR, tag)) + + while game.stack:top() and game.stack:top() ~= game.overworld do + game.stack:pop() + end + U.wait(10) + end + + U.log("done -- " .. DIR) +end diff --git a/tools/stadium_pack.py b/tools/stadium_pack.py new file mode 100644 index 0000000..5e762ab --- /dev/null +++ b/tools/stadium_pack.py @@ -0,0 +1,572 @@ +#!/usr/bin/env python3 +"""Pack the Pokemon Stadium battle models into the mod's own .dsm format. + + tools/stadium_pack.py [--rom=PATH] [--out=assets/stadium] + [--only=25,6] [--report] + +Reads the ROM directly, through model_extract/pipeline -- the same modules, +in the same order, that lib/StadiumRom.lua and lib/StadiumFragment.lua port to +Lua so the mod can do this itself at runtime with no Python and no checked-in +extract. That parallel is the point of this tool now: it is the ORACLE the +Lua extractor is verified against (tests/stadium_extract_test.lua diffs all +151 files byte for byte), so anything that changes the bytes has to change on +both sides or the suite says so. + +The output is one file per species, `NNN.dsm`, holding geometry, the bone +tree, every animation, the textures and the battle system's own slot tables +(which animation each move plays, and which one each battle context asks +for). Nothing here is decoded at runtime beyond byte order: lib/ +StadiumPack.lua walks these files straight into arrays. + +Textures are stored as RAW RGBA8 rather than PNG, which is why the magic is +DSM3. Two reasons, and the second is the one that decided it. A PNG costs a +decode on the frame a battle starts, where an ImageData over the bytes costs +nothing. And PNG means zlib: Python's deflate and LOVE's are both valid and +need not agree byte for byte, so a packed PNG would make this file impossible +to check the Lua extractor against. Uncompressed pixels are the same pixels +whoever wrote them. + +Everything is little-endian, so the reader's byte pairs go (low, high). + + header + "DSM3" magic + u16 species, bones, prims, textures, anims, auxAnims + f32 rootScale the model_root's own scale + u8 staticPose 1 = never animate + f32 height, floor, radius the bind pose's extent, + in GAME units after + rootScale -- what the mod + sizes a mon on its tile by + u16 moveAnim[165] move id -> animation + i16 moveAux[165] move id -> texture anim + u16 ctxAnim[20] slot 165..184 -> animation + bones[] + i16 parent (-1 root) + i16 t[3] rest translation + i16 r[3] rest rotation, binary + angles (32768 = pi) + i32 s[3] rest scale, 16.16 fixed + prims[] + u16 texture + u8 cull 1 = cull back faces + u8 blend 1 = additive (fx flipbook) + i16 texAnimChannel (-1 none) + u8 texMapN, then texMapN * (u8 key, u16 texture) + u16 fxN, then fxN * u16 flipbook texture frames + u16 verts, indices + verts * (i16 x, y, z ; i16 u, v at 1/512 ; i8 nx, ny, nz ; u8 bone) + indices * u16 + textures[] + u16 w, h ; u32 length ; length RGBA8 bytes (= w * h * 4) + anims[] + u8 name length, then the name + u16 frames, loopStart ; i16 aux (-1 none) + bones * track: + u8 1 if this bone is animated at all, else 0 + when animated, nine components in order tx ty tz rx ry rz sx sy sz, + each u8 kind (0 constant, 1 one value a frame) + then 1 or `frames` values -- i16 for t and r, i32 16.16 for s + auxAnims[] + u16 frames, loopStart, channels + channels * (u16 length, then that many u16 texture-table indices) + +Stdlib only, like the extraction pipeline it drives. +""" + +import math +import os +import struct +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +MOD = os.path.dirname(HERE) +PIPELINE = os.path.join(MOD, 'model_extract', 'pipeline') +sys.path.insert(0, PIPELINE) + +import battle # noqa: E402 (needs PIPELINE on the path first) +import build # noqa: E402 +import fragment # noqa: E402 +import rom as rom_mod # noqa: E402 + +# The battle system's fixed context slots, in slot order from 165. Names are +# manifest.json's own (animationSlots); the mod indexes this list by position, +# so the ORDER is the contract and must match lib/StadiumPack.lua's CONTEXT. +CONTEXTS = [ + 'idle', 'hit', 'faint', 'entrance', 'reaction_169', 'reaction_170', + 'reaction_171', 'reaction_172', 'reaction_173', 'reaction_174', + 'struggle', 'idle_alt', 'faint_alt', 'flinch', 'reaction_179', + 'reaction_180', 'reaction_181', 'reaction_182', 'entrance_alt', + 'idle_return', +] + +N_MOVES = 165 +NONE16 = 0xFFFF + +# How many battle Pokemon the model archive holds, and where the fixed context +# slots start in a species' battle table (entries 0..164 are the moves). +N_POKEMON = 151 +CTX_BASE = 165 + + +# --------------------------------------------------------------- bind extent + +def quat_basis(r): + """The game's rotation as a 3x3, rows first (src/F420.c func_8000F730). + + Rx*Ry*Rz in row-vector form -- the same basis model_extract/pipeline/ + glb.py converts to a quaternion, kept as a matrix here because that is + what the runtime builds too. + """ + sx, cx = math.sin(r[0] / 32768 * math.pi), math.cos(r[0] / 32768 * math.pi) + sy, cy = math.sin(r[1] / 32768 * math.pi), math.cos(r[1] / 32768 * math.pi) + sz, cz = math.sin(r[2] / 32768 * math.pi), math.cos(r[2] / 32768 * math.pi) + return ((cy * cz, sx * sy * cz - cx * sz, cx * sy * cz + sx * sz), + (cy * sz, sx * sy * sz + cx * cz, cx * sy * sz - sx * cz), + (-sy, sx * cy, cx * cy)) + + +def mat_mul(a, b): + """3x4 (rotation rows plus a translation column) times the same.""" + out = [] + for r in range(3): + row = [] + for c in range(3): + row.append(sum(a[r][k] * b[k][c] for k in range(3))) + row.append(sum(a[r][k] * b[k][3] for k in range(3)) + a[r][3]) + out.append(tuple(row)) + return tuple(out) + + +def rest_sample(bones): + def sample(i): + b = bones[i] + return b['t'], b['r'], b['s'] + return sample + + +def anim_sample(bones, anim, frame): + """The bone TRS this animation holds at `frame`, rest where it is silent.""" + tracks = anim['tracks'] + + def component(comps, i, fallback): + if comps is None: + return fallback + c = comps[i] + if isinstance(c, list): + return c[frame % len(c)] if c else fallback + return c + + def sample(i): + b = bones[i] + tr = tracks[i] if i < len(tracks) else None + if not tr: + return b['t'], b['r'], b['s'] + return ([component(tr.get('t'), k, b['t'][k]) for k in range(3)], + [component(tr.get('r'), k, b['r'][k]) for k in range(3)], + [component(tr.get('s'), k, b['s'][k]) for k in range(3)]) + return sample + + +def bind_matrices(bones, sample=None): + """Every bone's draw matrix at one instant, as 3x4 rows. + + The game keeps bone scale out of the matrix chain: it accumulates in its + own stack, a bone's local translation is pre-multiplied by the PARENT's + accumulated scale, and the bone's own accumulated scale is applied to the + finished matrix at draw time. This is that, and it is the same walk + lib/StadiumRig.lua does per frame. + + Two chains, and the distinction is the whole point: `pivot` is the + rotation/translation chain a CHILD inherits, and the draw matrix is that + with the bone's own accumulated scale applied on the right. Folding the + scale into the chain instead would apply every ancestor's scale twice -- + which is exactly the multiplicative propagation glTF has and the game + does not (see model_extract/README.md's two-node export). + """ + sample = sample or rest_sample(bones) + pivot, draw, acc = [], [], [] + for i, b in enumerate(bones): + bt, br, bs = sample(i) + p = b['parent'] + pa = acc[p] if p >= 0 else (1.0, 1.0, 1.0) + pm = pivot[p] if p >= 0 else ((1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0)) + t = [bt[i2] * pa[i2] for i2 in range(3)] + rot = quat_basis(br) + local = tuple((rot[r][0], rot[r][1], rot[r][2], t[r]) for r in range(3)) + m = mat_mul(pm, local) + a = tuple(pa[i2] * bs[i2] for i2 in range(3)) + acc.append(a) + pivot.append(m) + # scale on the right: the bone's own space, so it cannot reach children + draw.append(tuple((m[r][0] * a[0], m[r][1] * a[1], m[r][2] * a[2], + m[r][3]) for r in range(3))) + return draw + + +def pose_box(data, mats): + """The axis-aligned box the whole model occupies under `mats`, in game + units after the model_root scale.""" + root = data['rootScale'][0] + lo = [1e30, 1e30, 1e30] + hi = [-1e30, -1e30, -1e30] + for prim in data['prims']: + pos, skin = prim['pos'], prim['skin'] + for i in range(len(skin)): + m = mats[skin[i]] + x, y, z = pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2] + for a in range(3): + v = (m[a][0] * x + m[a][1] * y + m[a][2] * z + m[a][3]) * root + lo[a] = min(lo[a], v) + hi[a] = max(hi[a], v) + return lo, hi + + +def stance(data): + """(height, floor, radius): how tall the mon is, where its lowest point + sits relative to the model's own origin, and how wide it is -- all in + game units after the model_root scale. + + Measured on the BIND POSE, which is the one pose in the set that can be + trusted for this. Two things recommend it. It reproduces the verified + glTF export bit for bit on all 151 species, so it is measuring the same + skeleton the reference implementation agreed with; and it is immune to + the animation quirks a handful of species carry (Exeggutor's idle throws + limbs hundreds of units off the body from frame 1 on, and Magmar's does + something similar) -- quirks that would otherwise decide how big every + OTHER frame of those species is drawn. + + The floor is the interesting number, and it reads cleanly: 119 of the + 151 sit within 5% of zero, which says the model origin IS where the game + stands a Pokemon on its field. Every species that does not is one that + hovers -- Zubat, Magnemite and Geodude float above their origin, + Tentacruel, Gastly, Haunter, Weezing and Zapdos hang below it. What the + mod does with that is a placement decision and lives in StadiumMon. + """ + lo, hi = pose_box(data, bind_matrices(data['bones'])) + if lo[0] > hi[0]: + return 0.0, 0.0, 0.0 + return hi[1] - lo[1], lo[1], max(hi[0] - lo[0], hi[2] - lo[2]) / 2 + + +def idle_is_broken(data, idle): + """Whether this species' standby loop is corrupt in the source data. + + A handful of species come out of the extraction with animations that + throw bones hundreds of units off the body -- Exeggutor, Tangela and + Magmar, whose channel streams the game's own index arithmetic evidently + reads differently from the way the exporter does. Played, they look + like a Pokemon coming apart; the mod would rather stand them still. + + The test is deliberately narrow, because "differs from the bind pose" is + NOT brokenness. It is asked only of the STANDBY loop, which is the one + animation that is supposed to stay where it is -- a faint is meant to + end far from the standing pose and an attack is meant to lunge -- and it + wants both a large size blow-up and real drift, or an enormous amount of + one. Dewgong is what calibrates it: its idle is 2.4x its own bind pose + because the BIND is the collapsed one, and it drifts barely at all, so + it must not be caught. + """ + if idle is None: + return False + bones = data['bones'] + lo, hi = pose_box(data, bind_matrices(bones)) + span = hi[1] - lo[1] + if span <= 0: + return False + worst_h, worst_drift = 1.0, 0.0 + for frame in range(0, idle['frames'], 3): + flo, fhi = pose_box(data, bind_matrices(bones, + anim_sample(bones, idle, frame))) + worst_h = max(worst_h, (fhi[1] - flo[1]) / span) + worst_drift = max(worst_drift, abs(flo[1] - lo[1]) / span, + abs(fhi[1] - hi[1]) / span) + return ((worst_h > 2.5 and worst_drift > 1.5) + or worst_drift > 2.0 or worst_h > 3.4) + + +# --------------------------------------------------------------------- write + +class Writer: + def __init__(self): + self.parts = [] + + def raw(self, b): + self.parts.append(b) + + def u8(self, v): + self.parts.append(struct.pack(' hi else v) + + +def fixed(v): + """16.16, which holds every bone scale in the set (-31 .. 100) exactly + enough that a rounded one is invisible.""" + return clamp(int(round(v * 65536)), -2**31, 2**31 - 1) + + +def write_track_component(w, values, kind): + """One component of one bone's t/r/s in one animation. + + `values` is the js payload's own shape: a bare number when the component + holds still for the whole animation, or one number a frame when it does + not. That fold is where most of the size saving is -- a bone that only + rotates costs two bytes for each of its six other components. + """ + array = isinstance(values, list) + w.u8(1 if array else 0) + seq = values if array else [values] + if kind == 's': + for v in seq: + w.i32(fixed(v)) + else: + for v in seq: + w.i16(int(round(v))) + + +def context_table(rows, n_anims): + """Which animation each fixed battle context slot resolves to. + + Entries 165 upward of the species' own battle table, in slot order, which + is exactly what CONTEXTS lists. An entry naming an animation the species + does not have is written as "none" rather than clamped: the mod would + rather fall back than play the wrong clip. + """ + ctx = [NONE16] * len(CONTEXTS) + for i in range(len(CONTEXTS)): + e = CTX_BASE + i + ai = rows[e][0] if e < len(rows) else None + if ai is not None and ai < n_anims: + ctx[i] = ai + return ctx + + +def pack(data, species, move_rows, ctx): + w = Writer() + bones, prims = data['bones'], data['prims'] + textures, anims, aux = data['textures'], data['anims'], data['auxAnims'] + + height, floor, radius = stance(data) + + idle_index = ctx[CONTEXTS.index('idle')] + idle = anims[idle_index] if idle_index != NONE16 else None + static = idle_is_broken(data, idle) + + w.raw(b'DSM3') + for v in (species, len(bones), len(prims), len(textures), len(anims), + len(aux)): + w.u16(v) + w.f32(data['rootScale'][0]) + # 1 = hold the bind pose, never play an animation (see idle_is_broken). + # Immediately after rootScale, which is where the format table above says + # it is and where lib/StadiumPack.lua reads it. + w.u8(1 if static else 0) + w.f32(height) + w.f32(floor) + w.f32(radius) + + rows = move_rows or [] + for m in range(N_MOVES): + row = rows[m] if m < len(rows) else None + w.u16(row[0] if row and row[0] < len(anims) else NONE16) + for m in range(N_MOVES): + row = rows[m] if m < len(rows) else None + w.i16(row[1] if row and 0 <= row[1] < len(aux) else -1) + for v in ctx: + w.u16(v) + + for b in bones: + w.i16(b['parent']) + for v in b['t']: + w.i16(round(v)) + for v in b['r']: + w.i16(v) + for v in b['s']: + w.i32(fixed(v)) + + for p in prims: + w.u16(p['tex']) + # the display list's own cull mode: 1024 is G_CULL_BACK + w.u8(1 if p.get('cull') else 0) + w.u8(1 if p.get('blend') == 'add' else 0) + w.i16(p.get('texAnim', -1)) + tex_map = p.get('texMap') or {} + w.u8(len(tex_map)) + for key, tex in sorted(tex_map.items(), key=lambda kv: int(kv[0])): + w.u8(int(key)) + w.u16(tex) + frames = p.get('fxFrames') or [] + w.u16(len(frames)) + for f in frames: + w.u16(f) + pos, uv, nrm, skin, idx = (p['pos'], p['uv'], p['nrm'], p['skin'], + p['idx']) + n = len(skin) + w.u16(n) + w.u16(len(idx)) + for i in range(n): + w.i16(pos[i * 3]) + w.i16(pos[i * 3 + 1]) + w.i16(pos[i * 3 + 2]) + # 1/512, which puts a texel of the largest texture in the set + # well inside a step and still reaches the +-32 the wrapped + # coordinates of some display lists run to + w.i16(round(uv[i * 2] * 512)) + w.i16(round(uv[i * 2 + 1] * 512)) + w.i8(round(nrm[i * 3] * 127)) + w.i8(round(nrm[i * 3 + 1] * 127)) + w.i8(round(nrm[i * 3 + 2] * 127)) + w.u8(skin[i]) + for v in idx: + w.u16(v) + + for t in textures: + rgba = t['rgba'] + w.u16(t['w']) + w.u16(t['h']) + w.u32(len(rgba)) + w.raw(rgba) + + for a in anims: + name = (a.get('name') or '')[:255].encode('utf8') + w.u8(len(name)) + w.raw(name) + w.u16(a['frames']) + w.u16(a.get('loopStart', 0)) + w.i16(a.get('aux', -1)) + tracks = a['tracks'] + for bi in range(len(bones)): + tr = tracks[bi] if bi < len(tracks) else None + if not tr: + w.u8(0) + continue + w.u8(1) + for key in ('t', 'r', 's'): + comps = tr.get(key) + if comps is None: + # a bone the animation leaves at its rest value for this + # path: written as three constants so the reader never + # has to branch on a missing path + rest = {'t': [0, 0, 0], 'r': [0, 0, 0], + 's': [1.0, 1.0, 1.0]}[key] + src = bones[bi][key] if key in bones[bi] else rest + comps = list(src) + for c in comps: + write_track_component(w, c, key) + + for a in aux: + w.u16(a['frames']) + w.u16(a.get('loopStart', 0)) + chans = a['channels'] + w.u16(len(chans)) + for ch in chans: + w.u16(len(ch)) + for v in ch: + w.u16(v) + + return w.bytes(), (height, floor, radius) + + +# ---------------------------------------------------------------------- main + +def build_one(blob, fileno, tables, moves): + """One model fragment -> the payload `pack` takes. + + The same three steps build.py takes for a Pokemon, in the same order: + parse the fragment, label the animations off the species' battle table, + then hang the generated fire/gas stand-ins on the bones the game's own + effect callbacks hang off. + """ + data = fragment.extract(blob, '%d.bin' % fileno, raw=True) + species = data['species'] + rows = tables.rows(species) + build.label_animations(data, rows, moves) + build.attach_effects(data, species, raw=True) + data['name'] = battle.SPECIES.get(species, '#%d' % species) + return data, species, rows + + +def main(argv): + args = {a.split('=')[0]: (a.split('=', 1)[1] if '=' in a else True) + for a in argv} + out = args.get('--out') or os.path.join(MOD, 'assets', 'stadium') + only = ({int(x) for x in args['--only'].split(',')} + if '--only' in args else None) + + rom_path = args.get('--rom') or build.find_rom() + if not rom_path or not os.path.exists(rom_path): + print('ROM not found. Put a Pokemon Stadium (US 1.0) ROM at\n %s\n' + 'or pass --rom=PATH.' + % os.path.join(build.BASEROMS, 'baserom.z64'), file=sys.stderr) + return 1 + + rom = rom_mod.Rom(rom_path) + if not rom.is_expected_us: + print('warning: md5 %s is not the expected US 1.0 ROM' % rom.md5, + file=sys.stderr) + blobs = rom_mod.pokemon_models(rom) + tables = battle.BattleTables(rom) + moves = battle.load_move_names(os.path.join(MOD, 'model_extract')) + + os.makedirs(out, exist_ok=True) + total, report, statics = 0, [], [] + for fileno in range(min(N_POKEMON, len(blobs))): + data, species, rows = build_one(blobs[fileno], fileno, tables, moves) + if only and species not in only: + continue + move_rows = [[rows[m][0], rows[m][1]] for m in range(N_MOVES)] + blob, extent = pack(data, species, move_rows, + context_table(rows, len(data['anims']))) + if blob[4 + 12 + 4] == 1: + statics.append(species) + path = os.path.join(out, '%03d.dsm' % species) + with open(path, 'wb') as fp: + fp.write(blob) + total += len(blob) + report.append((species, data['name'], len(blob), extent, + len(data['bones']), len(data['prims']), + len(data['anims']))) + + print('%d models, %.1f MB -> %s' % (len(report), total / 1e6, out)) + if statics: + print('held at the bind pose (corrupt standby loop in the source): %s' + % ', '.join(str(x) for x in statics)) + if '--report' in args: + report.sort(key=lambda r: -r[3][0]) + print('%-4s %-12s %9s %8s %8s %6s %6s %5s' + % ('#', 'name', 'bytes', 'height', 'floor', 'bones', 'prims', + 'anims')) + for r in report[:10] + report[-5:]: + print('%-4d %-12s %9d %8.2f %8.2f %6d %6d %5d' + % (r[0], r[1], r[2], r[3][0], r[3][1], r[4], r[5], r[6])) + heights = sorted(r[3][0] for r in report) + print('height: min %.2f median %.2f max %.2f' + % (heights[0], heights[len(heights) // 2], heights[-1])) + return 0 + + +if __name__ == '__main__': + sys.exit(main(sys.argv[1:]))