A resource viewer from the first day

A resource viewer is a small program that opens the player's copy of the game and shows every file: what it is, what the project's decoders make of it, and the bytes nobody understands yet. Build it at the start of a project, right after the inventory, and grow it with every format. It gives the person directing the work a way to check a decoder by looking at its output. It gives an agent the same output as files it can read: a manifest, pictures and a coverage count.

Two worked examples exist. Un-Banished has a viewer for models, textures, sound and dialogs (apps/viewer in https://github.com/tanepiper/unbanished). The Frontier: Elite II project has a viewer for MZ overlays, packed pictures, MIDI songs, the original sound driver's music and the 3D model tables (apps/viewer in https://github.com/tanepiper/frontier-decompile).

Why it pays

• A picture shows a wrong decoder at once. A width one byte too small slants the image. A wrong palette turns faces green. A wrong vertex layout explodes a model. A table of numbers hides all three.
• The person directing the work can verify content. They need not read the decoder. They open the viewer and say "the 40th icon is the scanner" or "that ship is inside out".
• An agent can verify content. A viewer that writes a manifest and pictures to files lets an agent compare a decoder's output with a capture of the original (re-verify), count what is decoded, and find the files it has not looked at.
• It keeps the unknown in view. Every file is listed, decoded or not. Files that show only as hex are the open questions, and their count goes down as the project goes on.
• The decoders are proved again. The viewer calls the same readers the port uses, on every file of the player's copy, every time it starts.

Two stages

Stage	When	What	Tool
Catalogue	Day one, after re-inventory	A static HTML page and a JSON manifest: every file, its kind and entropy, a hex view, the result of every Python decoder, and the pictures a decoder returns	tools/formats/catalog.py
Project viewer	When the port has its first reader, usually within the first week	An app in the port's language that uses the port's own readers: pictures, sound, 3D, text, hex, natively and in the browser	the re-browse skill

The catalogue needs no code beyond the decoders written for validate.py:

python3 tools/formats/catalog.py game derived/catalog \
    --decoder '*.dat=decoders/units.py' --decoder '*.pic=decoders/picture.py' \
    --palette game/GAME.PAL
open derived/catalog/index.html

A decoder shows pictures when it defines images(result), returning (label, width, height, pixels) with one palette index per byte. The summary line ("12 of 47 files decode completely (31% of 2,345,678 bytes); 1 fails; 34 have no decoder") is the format coverage of the project. Write it into docs/CHECKLIST.md when it changes.

What the project viewer shows

Kind of file	View	How it is checked
Executables, overlays, libraries	Headers, sections or segments, relocations, imports and exports, the overlay or module tables the program uses, the strings	Against peinfo.py, dosinfo.py and the Ghidra export
Pictures, sprites, fonts	Every entry drawn with its header fields; zoom; transparency shown	Against a capture of the original's screen (re-observe)
Palettes	The 256 colours as swatches	Against a dump of the DAC or a screenshot
Sound and music	Events, instruments, waveforms; playback	Against a recording of the original (re-verify)
3D models	The model drawn, turned with the mouse; the header, the vertex list and the drawing commands; where a walk of the commands stopped	Against a capture of the model in the game
Text and scripts	Strings with their offsets; message tables; control codes made visible	Against the screen where the game shows them
Maps, levels, saves	A drawing of the map or a tree of the save's fields	Against the game's own display of the same data
Anything not understood	Hex, and an entropy strip (binview.py)	It stays listed until it is decoded

Show the evidence in the viewer. Name the original routine that reads each format, and mark what is inferred or assumed (a palette chosen because the game sets its own at run time, derived vertices placed without the game's camera). A viewer that hides its guesses misleads the person who checks it.

How to build it

• Keep the readers in the port. The viewer calls the same reader crate or module as the port. It never has a decoder of its own. A fix to a reader then fixes the game and the viewer together.
• Share the host code. Window, audio output, loading the player's files and browser glue belong in one shared crate or module that the game and the viewer both use. Do not copy them into the viewer.
• Read the player's own copy, locally. Natively from the game folder. In the browser from a file picker, or from a local development server that serves the ignored game-data/ folder to 127.0.0.1 only. Nothing is uploaded and nothing is bundled.
• Run where the port runs. If the port builds for the browser, the viewer does too. People can then check content without a build environment.
• Give agents a way in. A command-line mode that writes what a view shows to files: a picture per entry, a manifest with each file's decode status, a frame of a model. An agent reads those. It cannot read a window.
• Mark the viewer's own choices. Playback of a song on a different synthesiser, a camera, flat shading: each is a Deviation: comment, so the ledger shows the viewer is not the game.
• Fail visibly. A reader error is shown on the file's page with the offset where it stopped. The viewer never stops because one file is wrong.

When to update it

• After each new decoder (re-format): add the view, then re-run the catalogue for coverage.
• Before porting a system that draws or plays something: look at its data in the viewer first.
• When a check against the original fails: open the data in the viewer before reading code.

Pitfalls

• The game's palette is often set at run time. A viewer that guesses a palette must say so. Take it from a capture, a screenshot file the game wrote, or the code that sets it.
• Drawing is not the game's renderer. A viewer that draws a model with its own camera and shading shows the geometry. It does not prove the port's renderer. Compare the port's frames with the original's (re-verify).
• A viewer can hide a short read. Show whether every byte of a file was consumed, as validate.py does. A picture can look right while the decoder skips a field.
• The output holds game material. Keep the catalogue and extracted pictures in ignored folders (derived/). Never commit them. Screenshots are always fine: copy the ones a document or the site uses out of derived/, compress them (WebP) and commit them.