Files
Aidem-Media-DLL-Analysis/docs/tracker.md
T
Patryk GenschandClaude Opus 5.5 e03037647e data: extract 33 scene modules and the Wojna Trojańska engine (68 builds)
The DLL collection gains every WORLD/KOLOROWANKA variant, MATRIX, QMAN
(TEST), INERTIA and BOARD, plus the later PIKLIB72 build from Wojna
Trojańska, taken from the game discs. All 68 builds re-extracted; engine
snapshots are unchanged except the Piklib 6.1 switch dispatch. Roadmap,
batch results and docs follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 21:38:11 +01:00

8.9 KiB

Atlas API — tracker silników i bibliotek

Atlas łączy snapshoty oryginalnych DLL z rejestracjami MethodSpec w Rex-EMoolator. Nie uruchamia emulatora ani binarek. Nie utożsamia wykrycia metody z poprawną implementacją.

Uruchomienie

Z katalogu tego repozytorium, z zainstalowanymi zależnościami .[api]:

.venv/bin/python -m ams.serve_tracker \
  --emulator-root /ścieżka/do/Rex-EMoolator

Otwórz http://127.0.0.1:8766/ui/tracker.html. Command Center ma odnośnik do Atlasu. GET /tracker oraz GET /tracker?download=1 udostępniają te same dane jako JSON. Snapshoty z bazy i jawnie wskazanego katalogu są łączone i deduplikowane po SHA DLL. Bez SHA używany jest identyfikator snapshotu, jawnie niebędący tożsamością binarki. Katalog snapshotów jest przeszukiwany rekurencyjnie. Wyniki batcha mają pierwszeństwo przed starszymi snapshotami tego samego SHA; konflikt jest widoczny w uwagach, a dane nie są automatycznie scalane. Launcher domyślnie wczytuje data/binary-inventory.json, aby pokazać pokrycie zbioru DLL. Filtr rodziny i wariantu ogranicza dowody oryginału; nadal pokazuje sumę metod API z oznaczeniem „nieustalone” dla braku obserwacji w wybranym zakresie.

Eksport bez serwera:

.venv/bin/python -m ams.tracker snapshots/batch/*.snapshot.json snapshots/*.snapshot.json \
  --emulator-root /ścieżka/do/Rex-EMoolator \
  --reviews tracker-reviews.json --out /tmp/tracker.json

Atlas odczytuje snapshoty z dysku przy każdym pobraniu katalogu. Command Center, diff i eksport zgodności korzystają z bazy SQLite; nowe wyniki można do niej dodać poleceniem .venv/bin/python -m ams.api.importer snapshots/batch/*.snapshot.json.

Interpretacja

  • Zarejestrowana: znaleziono wpis MethodSpec, bez oceny poprawności.
  • Podejrzenie stubu: heurystyka wykryła wyjątek lub komunikat o braku implementacji. Może dotyczyć tylko gałęzi; wymaga przeglądu.
  • Brak rejestracji: adapter nie znalazł wpisu; dynamiczny dispatcher może obsługiwać metodę inaczej.
  • Zaimplementowana / przegląd ASM / test zachowania: aktualne deklaracje przeglądu obejmują wszystkie obserwowane warianty danej pary typ/metoda.
  • Nieustalone w oryginale: brak obserwacji, nigdy dowód nieobecności.

Licznik to pary typ/metoda. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Metody bazowe CMC_Runner (SEND, CLONE, …) są w zakresie * raz; typy wskazują go polem inherits. Zakres @ to instrukcje @IF/@LOOP/… (runner typu 0), porównywane z CodeParser.dispatchSpecialCall. Typy bez rozpoznanych metod pozostają widoczne. Roadmapę braków emulatora per zakres generuje python -m ams.roadmap tracker.json -o docs/roadmap.md (metody z sygnaturą, stuby, eventy i pola bez literału, z rodzinami silnika, w których DLL dana pozycja występuje). Z --usage data/script-usage.json każda luka ma liczbę gier i miejsc w ich skryptach, luki są w tej kolejności, a raport dodaje tabelę priorytetów i listę użyć spoza znanego API oryginału. Typ → runner pochodzi z runner_map snapshotu (fabryka w 7.1+, konstruktory klas w 6.1); bez niego z nazwy klasy, oznaczone jako wnioskowane. Metoda wspólnego runnera, którą oryginał pomija dla danego typu warunkiem obj.getType(), nie jest temu typowi przypisana; pusta implementacja wirtualna jest oznaczona jako brak efektu. Sygnatury (typy argumentów i wyniku) są odczytane z ciała metody i mogą być sumą wariantów (int/string). Eventy typu pochodzą z jego vtable (type_events) albo z listy najbliższej klasy w łańcuchu konstruktorów. Po stronie emulatora liczy się literał nazwy: w klasie typu (emitted), w Variable.java (emitted_base), w innym kodzie bez przypisania do typu (engine_literal); not_found znaczy tylko, że literału nie ma. Pola typu pochodzą z jego łańcucha konstruktorów (type_fields) albo z pól jego klasy i jej baz. Po stronie emulatora: klucz ":NAME" w gałęzi typu w CNVParser.createVariable lub odczyt atrybutu (getAttribute, getAttributeInHierarchy, attributes().get) w klasie typu (read), w Variable.java (read_base), gdzie indziej (engine_literal). Alias BOOL jest łączony z BOOLEAN, INT z INTEGER; nazwy metod są normalizowane do uppercase. ID metody pozostaje lokalne dla konkretnej klasy i binarki. Relacje dziedziczenia pochodzą wyłącznie ze snapshotu, nie są zgadywane z innej wersji.

Adapter rozpoznaje bieżący wzorzec rejestracji Java; nie jest ogólnym parserem języka Java. Komentarze i literały nie tworzą fałszywych wpisów, nawiasy są dopasowywane leksykalnie. Własne dispatchery GROUP / INSTANCE są oznaczone do przeglądu. Celowe no-op nie są automatycznie stubami.

Użycie w skryptach gier

.venv/bin/python -m ams.usage "/Users/genszu/Gry Aidem Media" -o data/script-usage.json   # ~10 s dla 51 obrazów
.venv/bin/python -m ams.usage GRA.iso -o /tmp/usage.json --dump /tmp/skrypty              # także zdekodowane skrypty (UTF-8)

Katalog z obrazami daje jedno wydanie na obraz, a tytułem jest folder obrazu, więc kilka wydań jednej gry liczy się jako jedna gra. Katalog bez obrazów jest jednym wydaniem z luźnych skryptów. Obrazy czyta 7-Zip: bsdtar nie widzi plików na części płyt (Aladyn, Pinokio, Piotruś Pan, Wojna Trojańska). CNV/DEF/CLASS są deszyfrowane jak w ScriptDecypher emulatora; SEQ opisuje sekwencje, nie obiekty skryptu, i jest pomijany. Rodzina silnika pochodzi z DLL silnika na płycie. Gry od 6.1 wzwyż mają skrypty wprost na płycie; w instalatorach (MSI/CAB/PMG) są tylko starsze silniki albo wydania w Unity.

NAZWA^METODA( liczy się dla typu z deklaracji NAZWA:TYPE=: najpierw z tego samego pliku, potem z całego wydania, jeśli wszystkie deklaracje się zgadzają. NAZWA_N to kopia CLONE, NAZWA_CURSOR to kursor bazy NAZWA, a RANDOM/MOUSE/KEYBOARD/SYSTEM to obiekty globalne (jak BuiltinVariableProvider). Obiekt z KLASA^NEW("NAZWA") jest instancją (INSTANCE): jego metody to zachowania ze skryptu klasy, nie API silnika. *ZMIENNA^METODA( liczy się jako dynamic dla typów obiektów, których nazwy wydanie przypisuje do ZMIENNA (:VALUE=, ^SET("…")). Reszta ($N, THIS, nazwy niezadeklarowane lub niejednoznaczne) zostaje pod unresolved per nazwa metody. Roadmapa przypisuje ją zakresowi, który jako jedyny ma tę metodę (albo *). Do listy „spoza API” trafiają tylko użycia bezpośrednie. Liczby to miejsca w skryptach, nie wykonania.

Dowody poprawności

tracker-reviews.json jest wersjonowanym rejestrem przeglądów; początkowo pustym. Ekstrakcja rejestracji silników, WORLD i KOLOROWANKA nie wypełnia go automatycznie. Każdy wpis wymaga pól tekstowych:

Pole Znaczenie
type, method Para API
binary_sha256, rva Dokładna binarka i adres względny, np. 0xc950
emulator_commit, body_sha256, source_tree_sha256 Rewizja i hashe z eksportu trackera
kind asm lub runtime
verdict matches, partial, differs
reviewer, date Autor i data przeglądu
notes, evidence Zakres porównania i odnośnik do trwałego dowodu/testu

matches oznacza świadomą ocenę całej metody dla wskazanego wariantu; dla sprawdzenia pojedynczego przypadku użyj partial. Sam adres lub dekompilat nie wystarcza do takiej oceny. Zmiana commita lub dowolnego źródła Java w core/src unieważnia przegląd konserwatywnie (także zmiana helpera). Można zachować historyczne wpisy dla starszych rewizji. Sprzeczne, zduplikowane przeglądy tej samej pary i rewizji są odrzucane. Adresy impl_addr, case_addr, registration_addr w snapshotach są VA, nie RVA. Należy odjąć potwierdzoną bazę obrazu przed zapisaniem rva.

Kolejka dalszej analizy

.venv/bin/python -m ams.inventory /Users/genszu/_dll_repository \
  --snapshots snapshots --out data/binary-inventory.json

Manifest zachowuje wszystkie ścieżki identycznych DLL i proponuje pliki wynikowe po pełnym SHA. Nie uruchamia analiz. Klasyfikacja nazw wymaga przeglądu przy przemianowanych DLL. Starsze Pikliby są wyłączone z zakresu, Sekai oznaczone jako zależność natywna. Moduły sceny (WORLD, KOLOROWANKA, MATRIX, QMAN, INERTIA, BOARD) są w repozytorium DLL od 2026-10-28 i wyciąga je ten sam batch co silniki; ich typy mają w trackerze pochodzenie module (runner instalowany przez obiekt modułu).

Kolejka wszystkich unikalnych silników: batch.md. Statyczne dowody pluginów: WORLD i KOLOROWANKA.

Pozostałe etapy: uzupełnienie niepełnych mapowań klas, dziedziczenia, pól i zdarzeń; rozstrzygnięcie podwójnej rejestracji WORLD.SETPOSITION; analiza natywnego Sekai; porównanie zachowania i rejestracja przeglądów. Historyczny snapshot 7.1 bez SHA pozostaje oznaczony jako nieustalony; nowe ekstrakcje mają pełną tożsamość DLL. Istniejący ogólny pipeline acquire(directory) nadal wybiera jeden silnik — do masowej analizy służy ams.acquire.batch.