Diff gains a type_events axis keyed by (script type, event). The tracker lists each type's original events (vftable list, or the nearest class list up the constructor chain for Piklib 6.1) and where the emulator names them: the type's class, Variable.java or other engine code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.3 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.
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.
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.
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 /ścieżka/do/_dll_repository \
/ścieżka/do/World.dll /ścieżka/do/Kolorowanka.dll \
--snapshots snapshots --out /tmp/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.
Kolejka wszystkich unikalnych silników: batch.md. Statyczne dowody pluginów: WORLD i KOLOROWANKA.
Pozostałe etapy: uogólnienie ekstrakcji pluginów na kolejne warianty; 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.