feat: SWF-to-PNG extraction pipeline + de-SWF roadmap

- extract-ui-pngs.sh: batch-exports all 377 Windows64 SWFs via ffdec
  (50,077 PNGs: bitmaps, shapes, sprite frames, named by export symbol)
- tools/DumpLayout.java: dumps per-SWF layout JSON (exports, imports,
  sprite display lists with matrices and instance names)
- docs/UI-DESWF-ROADMAP.md: phased plan to replace Iggy with a PNG-based
  iggy-shim, scene by scene
This commit is contained in:
2026-07-07 03:15:35 -05:00
parent ad758d6ce5
commit 354ca1702b
4 changed files with 212 additions and 0 deletions

7
.gitignore vendored
View File

@@ -17,3 +17,10 @@ sdktools.nupkg
*.pdb
screenshots/
proof*.png
# extraction outputs (regenerate with extract-ui-pngs.sh)
ui-png/
ui-png-test/
ffdec.zip
ffdec/
tools/*.class

57
docs/UI-DESWF-ROADMAP.md Normal file
View File

@@ -0,0 +1,57 @@
# De-SWF Roadmap: replacing Iggy/Flash UI with PNG-based UI
## Where the UI actually lives
The game's UI stack has three layers:
1. **C++ game code** (~100 `UIScene_*` classes + `UIController`) — owns all game
logic, pushes state into the flash scenes every frame via
`IggyPlayerCallMethodRS` ("SetHealth", "SetFood", ...) and receives button
events back through external-function callbacks. **240 distinct Iggy API
symbols** are referenced by game code.
2. **Iggy runtime** (`iggy_w64.dll`, closed-source RAD middleware) — a Flash
player: parses SWFs, runs AS3, renders via a `gdraw` D3D11 backend (which IS
open source, in-tree).
3. **SWF assets** (377 files for Windows64) —
- *skin SWFs* (~35): the actual art (bitmaps with export names like
`Health_Full`, `hotbar_item_selected`)
- *scene SWFs* (~340 = ~70 scenes × 480/720/1080/Split/Vita variants):
AS3 "document classes" (`fourj.documents.Hud` etc.) that build the
display tree from imported skin symbols and expose the setter methods
C++ calls.
## What this repo already extracts
- `extract-ui-pngs.sh` → `ui-png/<swf>/…` — **all 50k bitmaps/shapes/sprite
frames as PNGs** (named by export symbol where available)
- `tools/DumpLayout.java` → `ui-layout/<swf>.json` — stage size, export/import
tables, sprite display lists (depth/matrix/instance names, per frame)
- AS3 logic is decompilable per scene with ffdec
(`java -jar ffdec/ffdec.jar -export script out scene.swf`)
## Replacement strategy (phased, shippable at every step)
**Phase 1 — asset liberation (DONE)**: every piece of UI art exists as a PNG
with its layout metadata. Reskinning no longer requires Flash tooling.
**Phase 2 — `iggy-shim` skeleton**: an open-source drop-in replacement for
`iggy_w64.dll`'s C API (the 240-symbol subset the game uses). Scenes become
data: PNG atlas + JSON (from Phase 1) + a small per-scene C++ "document class"
replacing the AS3 one. Renders through the same open `gdraw_d3d11` path (which
DXVK/MoltenVK already runs on mac). Ship criteria: HUD renders via shim while
all other scenes still go through real Iggy (both runtimes coexist — the shim
only claims scenes that have been ported).
**Phase 3 — scene-by-scene port**: HUD → pause/death menus → inventory →
containers → settings → edge cases (keyboard, store, DLC). ~70 scenes. Each is
mechanical: read its decompiled AS3, re-express as a C++ document class over
the shim's display-tree API.
**Phase 4 — remove Iggy**: when every scene is ported, drop `iggy_w64.dll`,
the SWFs, and the `.arc` loader; assets ship as PNG/JSON directly.
## Effort honesty
Phase 2 is 1–2 solid weeks of work; Phase 3 is the long tail (an hour to a day
per scene, ~70 scenes). The result is a fully native, moddable, PNG-based UI —
and it removes the last closed-source blocker to a truly native macOS binary.

28
extract-ui-pngs.sh Executable file
View File

@@ -0,0 +1,28 @@
#!/usr/bin/env bash
# Extract every bitmap/shape/sprite from the Windows64 UI SWFs into PNGs.
# Output: ui-png/<swf-name>/{<id>_<name>.png, shapes/, sprites/}
set -euo pipefail
GAME_DIR="${GAME_DIR:-$HOME/neoLegacy/build/windows64-clang-mac/Minecraft.Client}"
OUT_DIR="${OUT_DIR:-$HOME/neoLegacy-mac/ui-png}"
FFDEC_JAR="${FFDEC_JAR:-$HOME/neoLegacy-mac/ffdec/ffdec.jar}"
JOBS="${JOBS:-8}"
mkdir -p "$OUT_DIR"
export FFDEC_JAR OUT_DIR
extract_one() {
local swf="$1"
local name
name="$(basename "$swf" .swf)"
local dest="$OUT_DIR/$name"
mkdir -p "$dest"
java -jar "$FFDEC_JAR" -export image,shape,sprite "$dest" "$swf" >/dev/null 2>&1 \
|| echo "FAILED: $swf"
}
export -f extract_one
find "$GAME_DIR/Common/Media" "$GAME_DIR/Windows64Media/Media" -name "*.swf" -print0 |
xargs -0 -n1 -P "$JOBS" bash -c 'extract_one "$0"'
echo "done: $(find "$OUT_DIR" -name '*.png' | wc -l | tr -d ' ') PNGs from $(ls "$OUT_DIR" | wc -l | tr -d ' ') SWFs"

120
tools/DumpLayout.java Normal file
View File

@@ -0,0 +1,120 @@
import com.jpexs.decompiler.flash.SWF;
import com.jpexs.decompiler.flash.tags.*;
import com.jpexs.decompiler.flash.tags.base.*;
import com.jpexs.decompiler.flash.types.*;
import java.io.*;
import java.util.*;
/**
* Dumps a SWF's UI structure as JSON: header, exported/imported symbols,
* and per-sprite display lists (placements with matrices and instance names).
* Usage: DumpLayout <swf-file> (JSON on stdout)
*/
public class DumpLayout {
static String esc(String s) {
if (s == null) return "";
return s.replace("\\", "\\\\").replace("\"", "\\\"").replace("\n", "\\n").replace("\r", "");
}
static String matrixJson(MATRIX m) {
if (m == null) return "null";
return String.format(Locale.US,
"{\"tx\":%.2f,\"ty\":%.2f,\"sx\":%.4f,\"sy\":%.4f,\"rot\":%b}",
m.translateX / 20.0, m.translateY / 20.0,
m.hasScale ? m.getScaleXFloat() : 1.0f,
m.hasScale ? m.getScaleYFloat() : 1.0f,
m.hasRotate);
}
static void dumpPlacements(Iterable<Tag> tags, StringBuilder sb) {
boolean first = true;
int frame = 0;
sb.append("[");
for (Tag t : tags) {
if (t instanceof ShowFrameTag) { frame++; continue; }
if (t instanceof PlaceObjectTypeTag) {
PlaceObjectTypeTag p = (PlaceObjectTypeTag) t;
if (!first) sb.append(",");
first = false;
sb.append(String.format(Locale.US,
"{\"frame\":%d,\"depth\":%d,\"charId\":%d,\"name\":\"%s\",\"matrix\":%s}",
frame, p.getDepth(), p.getCharacterId(),
esc(p.getInstanceName()), matrixJson(p.getMatrix())));
}
}
sb.append("]");
}
public static void main(String[] args) throws Exception {
SWF swf = new SWF(new FileInputStream(args[0]), false);
StringBuilder sb = new StringBuilder();
sb.append("{");
sb.append(String.format(Locale.US,
"\"file\":\"%s\",\"width\":%.0f,\"height\":%.0f,\"fps\":%.1f,",
esc(new File(args[0]).getName()),
swf.displayRect.getWidth() / 20.0, swf.displayRect.getHeight() / 20.0,
swf.frameRate));
// exported symbols (name -> charId)
sb.append("\"exports\":{");
boolean first = true;
for (Tag t : swf.getTags()) {
if (t instanceof ExportAssetsTag) {
ExportAssetsTag e = (ExportAssetsTag) t;
for (int i = 0; i < e.tags.size(); i++) {
if (!first) sb.append(",");
first = false;
sb.append("\"").append(esc(e.names.get(i))).append("\":").append(e.tags.get(i));
}
}
if (t instanceof SymbolClassTag) {
SymbolClassTag s = (SymbolClassTag) t;
for (int i = 0; i < s.tags.size(); i++) {
if (!first) sb.append(",");
first = false;
sb.append("\"").append(esc(s.names.get(i))).append("\":").append(s.tags.get(i));
}
}
}
sb.append("},");
// imports (runtime skin dependencies)
sb.append("\"imports\":[");
first = true;
for (Tag t : swf.getTags()) {
if (t instanceof ImportAssets2Tag) {
ImportAssets2Tag imp = (ImportAssets2Tag) t;
for (int i = 0; i < imp.tags.size(); i++) {
if (!first) sb.append(",");
first = false;
sb.append(String.format("{\"url\":\"%s\",\"name\":\"%s\",\"charId\":%d}",
esc(imp.url), esc(imp.names.get(i)), imp.tags.get(i)));
}
}
}
sb.append("],");
// sprites with display lists
sb.append("\"sprites\":{");
first = true;
for (Tag t : swf.getTags()) {
if (t instanceof DefineSpriteTag) {
DefineSpriteTag sp = (DefineSpriteTag) t;
if (!first) sb.append(",");
first = false;
sb.append("\"").append(sp.spriteId).append("\":{\"frames\":")
.append(sp.frameCount).append(",\"places\":");
dumpPlacements(sp.getTags(), sb);
sb.append("}");
}
}
sb.append("},");
// main timeline
sb.append("\"timeline\":");
dumpPlacements(swf.getTags(), sb);
sb.append("}");
System.out.println(sb);
}
}