Wolfenstein Modloader Buy me a coffeeKaffee spendieren

Wiki / Research briefsForschungsaufträge

Research brief: Mapmanifest

OpenOffen Original page in the GitHub wikiOriginalseite im GitHub-Wiki

In plain wordsIn einfachen Worten

Task description for custom maps in Wolfenstein II (TNC): what does a map need to know about a new object so that the game actually loads it? The worker is asked to study the map resource list, the streaming data, the visibility and shadow data, and the enemy navigation mesh. For each, the question is whether it can be written new or must be reused unchanged.

  • A DLC map (c2v1) is made of many placed pieces, e.g. 2,795 collision and 955 model entries, not one big world file.
  • Writing archives is already solved and reproduces originals byte-identical.
  • Deliverable: the smallest set of edits needed to add one new asset to an existing map.
  • The map resource list must be read and written back byte-exact for every copy found.
  • Being listed in a manifest does not prove the game loads it; that needs a test in the game.

Aufgabenbeschreibung zu eigenen Karten in Wolfenstein II (TNC): Was muss eine Karte über ein neues Objekt wissen, damit das Spiel es tatsächlich lädt? Der Worker soll die Ressourcenliste der Karte, die Streaming-Daten, die Sichtbarkeits- und Schattendaten sowie das Navigationsnetz der Gegner untersuchen. Für jeden Teil ist die Frage, ob er neu geschrieben werden kann oder unverändert wiederverwendet werden muss.

  • Eine DLC-Karte (c2v1) besteht aus vielen platzierten Teilen, z. B. 2.795 Kollisions- und 955 Modell-Einträgen, nicht aus einer großen Weltdatei.
  • Das Schreiben von Archiven ist schon gelöst und reproduziert Originale byte-gleich.
  • Ergebnis: die kleinste Menge an Änderungen, um einer bestehenden Karte ein neues Asset hinzuzufügen.
  • Die Ressourcenliste der Karte muss bei jeder gefundenen Kopie byte-genau gelesen und zurückgeschrieben werden.
  • In einer Liste zu stehen beweist nicht, dass das Spiel es lädt; dafür braucht es einen Test im Spiel.

Technical detailsTechnische Details

Der technische Teil ist auf Englisch – so, wie er im Wiki steht. Unterstrichene Begriffe haben eine Erklärung auf Deutsch.

Worker w-mapmanifest-a1; task mapmanifest; research. Read .agent-cache/WORKER.md. Bus: python "%USERPROFILE%/.claude/skills/agent-cache-orchestrator/scripts/acbus.py" Parallel: w-meshfmt-a1, w-cmfmt-a1, w-entitypipe-a1, w-matpipe-a1. You own the layer that decides what a map even consists of.

Objective

The other four workers can author assets. You answer the question that decides whether an authored asset ever reaches the player: what does a map need to know about an asset so the engine loads it?

Specifically:

  1. file:generated/buildgame/<map>.mapresources - what is in it, and is it the authoritative list of a map's assets? If we add a model/cm/image to a map chunk without listing it there, does it resolve?
  2. staticStreamTree and modelstream - the streaming layer. What decides that a model's data is fetched when the player walks into a room?
  3. pvs and staticShadowGeom - visibility and shadow precomputation. If a new object is not in them, is it invisible, unshadowed, or harmless?
  4. hknavmesh - navigation. Can enemies path at all if it is unchanged, and what happens to an AI that walks into newly added geometry?

For each: can it be authored/extended, or must it be reused as-is? A precise "reuse only" answer is just as valuable as an authoring recipe, because it tells the other workers where the walls are.

What is already solved - context you need

  • Container writing is finished and master-verified: wolfsdk/idclwrite.py round-trips retail archives BYTE-IDENTICALLY, finalize() fixes all hashes.
  • A map's composition, measured on dlc_2/base/chunk_22.resources (c2v1): cm 2795, image 1462, model 955, material 388, modelAsset 253, modelstream 249, sound 183, entityDef 78, extkisclule 68, md6Def 31, compfile 9, file 12. So there is NO monolithic world blob - a map is placed instances plus this manifest/streaming layer, which is why your piece matters so much.
  • re_probes/agent_reports/small_custom_map.md lists exactly these as the unrewritten cross-references and calls them the real blocker for a new map ID. That report is your starting point - it already named the problem, you answer it.
  • re_probes/agent_reports/idclwriter.md established that dep+0x18 in dependency records is NOT a general mirror of +0x60 (only 233 of 3741 resolvable dep_type=2 records carry it) - dependency records are subtler than they look, and they are part of your territory.

Sources / starting points

  • re_probes/runtime_87400/module.bin - read-only capture of the RUNNING, unpacked executable (file offset == RVA, sections in manifest.json, .pdata for function bounds). Today five formats fell to reading loaders in it.
  • docs/ladepfade.md (load paths), docs/streamed.md, docs/karten.md, docs/dlcmod.md, re_probes/agent_reports/{dlc_primary,loose_assets, map_selection}.md.
  • tools/streamed.py, tools/dlcinfo.py, tools/dlcmod.py - read-only.
  • Retail corpus READ ONLY: /steamapps/common/Wolfenstein.II.The.New.Colossus
  • capstone 5.0.7 vendored: PYTHONPATH=re_probes/python_deps

Ownership

tools/probe_mapmanifest.py (new), re_probes/mapmanifest/ (new dir), re_probes/agent_reports/mapmanifest.md (new). Everything else read-only.

Forbidden / do not touch

No game launch, no process attach, no writes under the Steam install or "%USERPROFILE%/Saved Games". Do not edit wolfsdk/, docs/, config.json, or any other worker's file. No pip install.

Hard constraints

Python 3.11, stdlib plus vendored capstone. Reproducible from the command line.

Acceptance criteria

  • .mapresources parsed with a byte-exact round-trip, n/n over every map's copy you can reach (there are many - use them all, it is the cheapest corpus here).
  • For each of the four questions: an answer backed by either a code path (with RVA and xref chain) or a measurement over the corpus with counts. "Probably" is not an answer; "unresolved, here is exactly what I tried" is.
  • A single clear deliverable the other workers can act on: the minimum set of manifest/streaming edits required to add one new asset to an existing map. If some part of that set is not authorable, say which and what it costs.
  • Negative controls: your parser must reject a truncated manifest and one with a count that disagrees with its entries.

Verification expectations

Every important assurance needs a check that can fail. Keep "listed in the manifest" and "actually loaded at runtime" apart - you cannot show the second offline, and you should say so.

Failure honesty

If PVS/navmesh turn out to be precomputed structures that cannot be regenerated, that is a major, useful finding: it would mean authored geometry is limited to places where being outside the precomputed sets is harmless. Quantify it if you can - e.g. what a retail map does with objects that are not in the PVS.

Coordination / deliverable

Checkpoint at milestones. Publish bus facts early and often here - the other four workers are authoring assets that may or may not need your manifest edits, and they would rather know at 30% than at the end. Concise German report in re_probes/agent_reports/mapmanifest.md. Finish the bus task.