Files

Patryk Gensch 4542763936 Add Command Center web UI (no build step)

Static HTML/CSS/JS served by FastAPI (mounted at /ui, / redirects there),
talking to the existing JSON API — no node/npm, no bundler.

- games/versions sidebar with A/B version selectors
- visual 4-axis diff (types/methods/events/fields, +/- struct_layout) with
  +/-/~ rows, per-axis counts, class (owner) filter, moved-methods section
- single-snapshot browser (tabs + live filter)
- app.py mounts StaticFiles(html=True) last so API routes win; / -> /ui/

Smoke-tested live on uvicorn: /, /ui/ and assets serve 200; UI wiring drives
the same /games and /diff endpoints verified end-to-end. app.js passes
`node --check`.

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

2026-05-30 23:37:03 +02:00

4.0 KiB

Raw Blame History

aidem_media_playground

Narzędzie do analizy różnicowej silników gier Aidem Media (Piklib / BlooMoo). Cel: katalog gier (z ISO/ZIP), wersje silnika z hashami, oraz ekstrakcja i porównywanie "powierzchni silnika" — typów, metod, eventów i pól klas CMC_* — między wersjami.

Status

Faza 1: ekstraktor snapshot.json z Ghidry (walidacja na golden pair PIKLIB8 ↔ bloomoo). Infrastruktura (FastAPI + worker + DB + front) dochodzi dopiero, gdy format snapshotu będzie sprawdzony na realnych binariach.

Architektura (docelowa)

Modularny monolit + worker. Backend Python/FastAPI tylko zleca, wersjonuje i diffuje. Cała ekstrakcja żyje w workerze = Ghidra headless + ten skrypt, bo wymaga dostępu do call-grafu, referencji i vtable. Worker emituje snapshot.json, monolit go konsumuje.

Front (centrum dowodzenia) ─ FastAPI (katalog/hashe/diff) ─ PostgreSQL
                                   │ kolejka
                              Worker: Ghidra headless + extract_engine_surface.py

Zasada ekstrakcji

Ekstrakcja stoi na kotwicach semantycznych (cele wywołań, referowane literały stringów, immediaty PUSH), a nie na tekście dekompilatu. Dzięki temu jeden skrypt działa na MSVC6 (Piklib) i MSVC8 (BlooMoo) mimo różnego kodu wynikowego.

Co	Kotwica w Ghidrze	Status
Typy	`CMC_ObjectsContainer::resolve`: `operator==("NAME")` → `operator_new(SIZE)` → `CMC_X::CMC_X`	✅ (+ `dispatch_addr`, `via_module_iface`)
Metody	`CMC_*_Runner::prepareMthHashSet`: `CInteger(id)` + `CStringHashCode("NAME")` + `CHashtable::put`	✅ (+ `method_inheritance`)
Eventy	`CMC_*::getBehavioursList`: lista literałów `CXString`	✅ (lista per klasa, bez dziedziczenia)
Pola (skryptowe)	ctory `CMC_*`: literały czytane przez `CMElement::getProperty<T>Value` → nazwa + typ pola (FPS, PRELOAD, VISIBLE…)	✅ (+ `field_inheritance`)
Layout C++ (bonus)	ctory `CMC_*`: store'y `this+offset` przez P-code (rozmyte, `is_vtable`)	✅ pod `struct_layout`

Uruchomienie ekstraktora

W GUI Ghidry (najszybciej do walidacji): skopiuj ghidra_scripts/extract_engine_surface.py do swojego katalogu skryptów (Script Manager → Manage Script Directories), otwórz program, uruchom skrypt. Wynik trafi do <NazwaProgramu>.snapshot.json w katalogu roboczym Ghidry.

Headless (tryb docelowy):

analyzeHeadless <projDir> <projName> -process PIKLIB8.dll \
    -postScript extract_engine_surface.py "$(pwd)/snapshots/PIKLIB8.snapshot.json"

Diff engine (CLI)

python -m ams OLD.snapshot.json NEW.snapshot.json [--owner CMC_Animo] \
    [--only types,methods,events,fields,layout] [--json]

Porównuje dwa snapshoty po 4 osiach (added/removed/changed) + wykrywa metody przeniesione w hierarchii. Oś struct_layout jest sensowna tylko między wersjami tego samego kompilatora.

Backend (FastAPI + katalog)

Modularny monolit nad SQLAlchemy — domyślnie SQLite (zero setupu), gotowy pod Postgres przez DATABASE_URL. Pełny snapshot trzymany jest w bazie verbatim; diff czyta go z powrotem przez ams.diff.

pip install -e ".[api,dev]"                       # zależności
python -m ams.api.importer --game "Reksio i UFO" snapshots/PIKLIB8.dll.snapshot.json
uvicorn ams.api.app:create_app --factory --reload  # serwer

Endpointy: POST/GET /games, POST/GET /snapshots (import deduplikowany po sha256), GET /diff?old=&new=[&owner=], GET /health. Testy: pytest (11, w tym integracyjne na golden pair).

Front — Command Center

Po starcie serwera otwórz http://127.0.0.1:8000/ (/ → /ui/). Statyczny UI bez build-stepu (czysty HTML/CSS/JS w ams/api/static/, serwowany przez FastAPI): lista gier/wersji, wybór dwóch wersji (A/B), wizualny diff po 4 osiach z filtrem klasy i przeglądarka pojedynczej powierzchni.

Format snapshotu

schema_version, binary{name,sha256,engine,compiler,factory_addr}, oraz listy types / methods / events / fields. Diff = operacje na zbiorach dwóch snapshotów.

4.0 KiB Raw Blame History