Files
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

90 lines
8.9 KiB
Markdown

# 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]`:
```sh
.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:
```sh
.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
```sh
.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
```sh
.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](batch.md). Statyczne dowody pluginów: [WORLD](world-analysis.md) i [KOLOROWANKA](kolorowanka-pilot.md).
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`.