Wolfenstein Modloader Buy me a coffeeKaffee spendieren

Wiki / Research briefsForschungsaufträge

Research brief: Entitypipe

OpenOffen Original page in the GitHub wikiOriginalseite im GitHub-Wiki

In plain wordsIn einfachen Worten

This page is the task description given to a research worker, not a result. The goal for Wolfenstein II: The New Colossus is a custom map on existing level geometry: read a map's entity file, change enemies, pickups, lights, triggers or the spawn point, rebuild the archive and verify it. The brief lists what is already solved, what must be proven, and what the worker must not touch.

  • Source map: the Gestapo office (c2v1) from DLC 2; its entity file is plain text.
  • Required: a byte-exact round-trip over every entity file, and edits that change only the intended bytes.
  • At least three distinct changes a player would notice, each listed with its entity name.
  • The checker must reject a broken block, a dangling reference and a duplicate name.
  • No install and no game launch; the result must be labelled "structurally valid, runtime unconfirmed".

Diese Seite ist die Aufgabenstellung für einen Forschungs-Worker, kein Ergebnis. Ziel für Wolfenstein II: The New Colossus ist eine eigene Karte auf vorhandener Level-Geometrie: die Entity-Datei einer Karte lesen, Gegner, Pickups, Lichter, Trigger oder den Startpunkt ändern, das Archiv neu bauen und prüfen. Das Briefing nennt, was schon gelöst ist, was bewiesen werden muss und was der Worker nicht anfassen darf.

  • Ausgangskarte: das Gestapo-Büro (c2v1) aus DLC 2; seine Entity-Datei ist reiner Text.
  • Gefordert: ein byte-genauer Roundtrip über jede Entity-Datei und Änderungen, die nur die beabsichtigten Bytes betreffen.
  • Mindestens drei verschiedene Änderungen, die man als Spieler bemerkt, jeweils mit Entity-Namen aufgelistet.
  • Der Prüfer muss einen kaputten Block, einen ins Leere zeigenden Verweis und einen doppelten Namen ablehnen.
  • Keine Installation und kein Spielstart; das Ergebnis muss als „strukturell gültig, im Spiel unbestätigt“ gekennzeichnet sein.

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-entitypipe-a1; task entitypipe; implement. Read .agent-cache/WORKER.md. Bus: python "%USERPROFILE%/.claude/skills/agent-cache-orchestrator/scripts/acbus.py" Parallel: w-meshfmt-a1 (geometry), w-cmfmt-a1 (collision), w-matpipe-a1 (surfaces), w-mapmanifest-a1 (streaming). You own placement and authoring.

Objective

You are the one worker on this wave whose result can be PLAYABLE without any further format being cracked - so treat that as the goal, not a side effect.

Build the authoring pipeline for a custom map on existing geometry: read a retail map's .entities, change it meaningfully, rebuild the bundle, verify it. Concretely, produce a map that differs from retail in ways a player would notice: enemy placement and counts, item and weapon pickups, lights, triggers, spawn point. That is what "custom map" means for most id Tech games that ship without an editor, and everything needed for it is already solved.

What is already solved - build directly on it

  • wolfsdk/idclwrite.py - container writer, round-trips retail archives BYTE-IDENTICALLY (3/3), 6/6 negative controls, finalize() recomputes every hash. Independently re-verified by the master today.
  • The other master (codex/Astra) already proved ONE authored entity change survives a bundle build: a cyan lobby light at 8.72,-192.97,1.32 in re_probes/map_alias_v3/bundle_headerfixed/ - READ IT AS A REFERENCE, do not modify it, it is their only copy. Their docs/tnc_astra_findings_20260923.md documents the alias/MRL work.
  • re_probes/idclwriter/chunk_22.resources is that same bundle with its four stale entry hashes repaired (7127/7127). Read-only for you.
  • The .entities file is a compfile and is TEXT - compfile:maps/game/dlc/ c02/c2v1_custom.entities, 256319 bytes uncompressed. That is your input.
  • tools/entities.py (part 1 entity work) and tools/build_entities_mod.py exist - read them, reuse what fits.

Sources / starting points

  • Retail source map: <Steam library>/.../dlc/dlc_2/base/chunk_22.resources (c2v1, Gestapo Office). READ ONLY.
  • re_probes/agent_reports/{small_custom_map,idclwriter,execcarrier}.md
  • docs/karten.md, docs/kiscule.md (2408 script files, 205 node types - scripted events live there), docs/moddingflaeche-tnc.md.
  • The entity grammar is id Tech 6 and close to Doom 2016's .entities. Public knowledge is a legitimate starting point, but VERIFY every claim against the actual file - do not import assumptions.

Ownership

tools/build_custom_map.py (new - the pipeline), tools/probe_entitypipe.py (new - checks), re_probes/entitypipe/ (new dir, the built map), and re_probes/agent_reports/entitypipe.md. Everything else is read-only: wolfsdk/*, other workers' tools, dlc_4, re_probes/{map_alias_v3,idclwriter,execcarrier,cfilekey}/.

Forbidden / do not touch

Do not install into the game folder and do not launch the game. The user runs installs themselves, in a five-minute window. No writes to "%USERPROFILE%/Saved Games". No pip install. Do not edit any other worker's files, docs/*, or config.json.

Hard constraints

Python 3.11, stdlib only. Reproducible from the command line.

Acceptance criteria

  • A parser/serializer for .entities with a byte-exact round-trip on the real file: read it, write it back unchanged, get identical bytes. Without that, an edit is guesswork. State it as n/n over every compfile entity file you can find, not just one.
  • Surgical edits: changing one property must leave every other byte untouched. Prove it with a diff, the way the part-1 decl editor does.
  • A built map bundle under re_probes/entitypipe/ containing at least three DISTINCT, player-visible changes (not just a light), each listed in the report with its entity name and what a player would see.
  • It must pass tools/probe_datahash.py n/n and tools/probe_idclhash.py OK.
  • Negative controls: a malformed entity block, a dangling entity reference and a duplicate entity name must each be REJECTED by your checker. A checker that accepts everything measures nothing.
  • A five-line runbook at the end of the report: install, launch, what to look for, how to tell it worked, uninstall.

Verification expectations

Nothing offline proves the map loads. Say "structurally valid by these checks, runtime unconfirmed". Be especially careful with entity references: a spawn that names a non-existent entityDef will not be caught by any hash check but will break the map.

Failure honesty

If the entities file turns out to be a compiled/binary form rather than the text it appears to be, say so immediately with evidence. If a change class (e.g. adding a new enemy rather than moving an existing one) needs an asset that is not in the map's chunk, name that dependency rather than shipping a map that will fail to resolve it.

Coordination / deliverable

Checkpoint at milestones. Publish a bus fact when the entities round-trip is byte-exact, and again when the bundle verifies - the other four workers are building the pieces that will eventually plug into YOUR pipeline. Concise German report in re_probes/agent_reports/entitypipe.md. Finish the bus task.