Chronologia

Technical notes and supporting artifacts from a demoscene reverse-engineering scratch project.

Contents

New or materially revised analysis files identify the model used for that analysis or revision:

Analysis model: <actual model identifier and reasoning level>
Last edited: YYYY-MM-DD

The value comes from the active session or runtime and must not be copied from an older article or template. If it cannot be verified, the file says Analysis model: not recorded. Existing untouched analyses retain their historical metadata.

If the user reports a model selection that is not exposed by the runtime, record it as user-reported attribution rather than verified runtime identity. Do not guess a reasoning level. The current review's user-reported selection is GPT-6 Astra; preserve the original analysis-model credits separately.

Use the UTC calendar date of the material revision for Last edited. Add or update it whenever an analysis changes materially so the age of its technical pass is visible without consulting Git history.

Project quality guidance lives in analysis-quality-notes.md. It records the current evidence bar, media policy, preflight command, and hosting boundary.

Runtime Capture Strategy

When an analysis needs visual backfill, capture the full demo run and normally add one Runtime Capture section to the analysis. That section should document the emulator/version, date, configuration, timing zero point, and whether timestamps are capture stream timestamps or in-demo cues. Split or relocate the runtime material when the demo or evidence clearly reads better another way.

The installed DOSBox-X build has no warning-only or --no-warnings switch. For non-visual automated diagnostics, its built-in -silent switch plus stdout/stderr redirection to an ignored .codex/tmp/ log suppresses routine console chatter. In this build -silent also selects dummy video, so do not use it for a run that must be seen or captured: launch normally and redirect both output streams to the ignored log instead. Keep that log for failed runs, but do not stream routine SDL, XKB, EGL, keyboard-layout, or code-page warnings into the working console. Use dummy host audio as described below.

Choose representative frames from the whole run rather than only the first successful screen: title/setup moments, major effect changes, distinctive objects/scenes, and late-run states that help someone remember what the demo looked like. Captions should include exact timestamps and enough visual context to connect the screenshots back to the technical analysis.

Current scope focus: review mid-1990s classics, starting with Dope and Cyboman, then other productions of that era, including Orange. Treat the existing analyses as strong work to verify against binaries and runtime evidence; change claims only when the evidence warrants it. Vector Balls is not a priority beyond completing confirmed fixes. Earlier 1990/1991 productions remain useful material, but no longer define the active queue. Lead with how the recovered effect works and how its authored controls produce the visible changes. Keep verification counts and provenance notes subordinate to that explanation; an isolated kernel test is not an end-to-end analysis. Prefer a materially deeper pass over an existing article to a shallow new catalogue entry; add a new production when its binary and runtime evidence support the same code-first depth. The user also requests a small selection of the strongest Amiga classics, starting with Desert Dream; prioritize deep review rather than broad Amiga catalogue expansion. Use Pouet, Demozoo, and Scene.org as the normal source chain: Pouet for candidate selection and public context, Demozoo for structured metadata/credits/results, and Scene.org/archive mirrors for the actual release files when available. Enough cracktros for now; do not add more cracktro passes unless explicitly requested.

Use short GIFs when the important evidence is temporal rather than static. Good candidates include tunnel fly-throughs, palette or color-cycle loops, wipes/collapses, bouncing or rotating objects, scrollers, and keyed interactive gates. The site should not rely on visitors clicking separate video links to understand a demo: put the useful motion or still evidence inline in the article and, when useful, on the front-page card. Do not make animation a quota item: if still frames explain the code path better, use still frames and say why. Real runtime/video-derived animation is preferred when it is available and technically relevant; keep its native or technically appropriate cadence, including high frame rates for intricate motion. Public screenshot-sequence GIFs assembled from unrelated stills are allowed as lively overview/index material, but those should be paced slowly, about one frame per second, so they read as evidence slides rather than fake motion. Non-H.264 silent clips are acceptable only when GIF is genuinely a bad fit. Do not add new H.264 encodes unless explicitly requested; existing published media remains site content and should not be removed just for codec cleanup.

Audio policy: music and other demo audio are opt-in only. Do not make demo audio audible during analysis, emulation, capture, preview, or verification unless the user explicitly asks for it. If emulated audio hardware is needed as an internal timing source, keep host output dummy/muted while preserving the guest timing path. Published page media should remain silent unless explicitly requested.

Preview policy: diagnostic contact sheets, timestamp atlases, and other multi-frame proof sheets are useful internal evidence, but front-page previews must be one untiled still or one continuous animation. If a preview appears multiplied while the main view is correct, treat the preview as wrong and do not publish it until it has been checked separately.

Keep screenshot hashes out of rendered analysis pages. Store the images under images/, list the asset family in this README when useful, and rely on the site-wide click-to-zoom viewer for full-window inspection of small old-school frames.

Workflow note: after finishing and deploying one coherent analysis pass, keep going to the next suitable target in the same priority thread instead of stopping arbitrarily. If the user interrupts with comments or corrections, incorporate the direction and then continue the active queue unless they explicitly say to pause or stop. Pause only for a real blocker, conflicting local changes, or an explicit user stop.

Parallel-analysis note: the user permits subagents whenever they materially help a demo pass. Split independent questions such as renderer loops, player or IRQ code, segment lifecycle, and media concordance; keep delegated work read-only unless a disjoint edit is explicitly useful. The primary analysis must reconcile contradictory findings against the binary before publication, especially when a parser result controls screenshot attribution.

Inner-loop depth note: the original purpose of this project is to recover the frame loop, not merely name an effect. For each major renderer, record exact loop bounds, record strides, fixed-point formats, table roles, clipping or culling, projection, sorting, rasterization/blitting, buffer/page cadence, hardware ports, and old-frame cleanup where the binary permits it. Vector-ball and vector-object passes need particular care: separate orthographic from perspective projection, pre-shifted sprites from generated circles, point sort from face sort, line walking from span filling, and selective restoration from whole-page clearing. Put normalized pseudocode beside the relevant offsets. Do not analyze only the headline draw loop: recover the supporting setup, transform, sort, clip, draw, cleanup, and presentation loops, including their shared state and hand-off points. When an older article stops at a visual label or broad architectural summary, prefer revisiting it until this complete frame path is explained. Correction passes must preserve or increase this mechanism-level depth.

VGA feedback note: a guest-RAM dump's physical A0000 region may not be the emulator's video backing store. Verify the actual backing layout before calling those bytes captured history. Keep an original-kernel prediction from supplied pixels distinct from an observed complete-frame RGB match.

Non-blocking issue note: if something looks wrong but does not block the current demo pass, make a concise note in the relevant work log or README and continue to another suitable demo. Do not stop just to ask unless continuing would risk corrupting existing work, publishing misleading media, or overwriting unrelated local changes.

Update timestamp note: every demo card touched by a new analysis pass should get a machine-readable data-updated timestamp, and every visible update/work log entry should use an exact local timestamp with timezone. This keeps the front page sortable/groupable by most recent work later, instead of relying on file order or vague date text.

Group tag note: when the production has an obvious group or artist attribution, add a machine-readable data-groups attribute to the touched front-page card using stable lowercase tokens separated by spaces. Examples: data-groups="cubic-team seen" or data-groups="orange". Do this alongside data-updated so group filtering/sorting can be added later without re-reading every card.

Release year note: every front-page card must also carry a machine-readable data-year attribute. Use the four-digit production release year rather than an archive-upload or later re-release year. A space-separated pair is allowed only when the analysis documents a genuine unresolved date conflict, for example data-year="1989 1990".

Front-page filter note: typed filtering matches identity fields: visible title, data-groups, URL slug words, and data-year. Descriptive prose is not indexed, which keeps incidental technical terms from producing noisy results. The year combobox is populated from data-year and combines with the typed filter, so a year works even when the visible description abbreviates it as TG95 or omits it entirely.

Lesson from the Dragnet and Fistro passes: for one-static-scene or near-static productions, do not force a fake tour of effects. Use one clean full-frame reference, deliberate detail crops, and timestamped frames only where the text, foreground objects, palette, or scroller actually changes. State plainly when those frames come from public video or screenshot references rather than local emulator capture.

Quality bar note: use sea-robot-of-love-analysis.md as a good current model for the balance of depth and media. Live reference: https://demo2.jeskola.net/sea-robot-of-love-analysis.html . The technical analysis should carry the piece; screenshots, GIFs, and cards should make the argument easier to follow and more inviting, not replace the code/runtime reasoning.

Code-to-commentary rule for future demo analyses: target at least 80% concrete code work and at most 20% contextual or visual commentary in the main technical body. Concrete code work means quoted and annotated disassembly, reconstructed C or precise pseudocode, data structures, addresses, constants, control flow, and instruction-by-instruction inner-loop analysis. Offset lists, archive inventories, screenshots, and prose claims about what code does do not count as code. Put the relevant instructions or reconstruction next to each conclusion. If the executable cannot be recovered or unpacked far enough to meet this bar, state that boundary explicitly instead of padding the article with visual prose.

Primary editorial objective, especially for early 1990/1991 demos: reconstruct the actual frame machinery, not merely the name or appearance of an effect. A deep pass should follow setup into the steady-state inner loops and document the handoffs between table or object update, transform, ordering, clipping or phase handling, draw, erase/background repair, hardware timing, and presentation. Treat that end-to-end inner-loop account as the normal stopping criterion for an analysis pass: identifying an effect, naming its helper, or matching a screenshot is useful evidence, but is not by itself a finished dissection. For every major visible effect, the article should answer what one complete steady-state iteration reads, changes, draws, restores, waits for, and presents, with exact bounds and data hand-offs wherever the recovered binary permits it. The inner-loop acceptance test is concrete: identify the entry conditions and active buffers; recover the state-record layout and units; name every nested loop with its iteration count, pointer stride, and important branch; calculate common-path and conditional read/write or plot counts where they clarify the work; follow intermediate data into the next routine; and close the lifecycle through clipping, erase or background repair, retrace/timer gating, page or buffer selection, and the final visible presentation. Distinguish measured runtime behavior, instruction-backed conclusions, and bounded inference. If a binary prevents one of these recoveries, state the exact missing boundary instead of silently replacing it with effect-level commentary. For vector balls and other vector objects, recover the object/point records, coordinate and rotation arithmetic, projection and depth policy, visible-size or shade selection, plot/blit kernel, clipping bounds, and old-pixel cleanup where the binary permits it. Prefer making an existing early article reach this standard before adding another shallow catalogue entry.

Visual-ownership check: before describing a visible object as a live renderer, prove whether its pixels come from object records, generated geometry, a packed full-frame sequence, a static plane, or a separately composited overlay. Tie every article image and front-page preview to that exact ownership boundary; do not use a visually similar frame as evidence for a different inner loop.

Future analysis standard, derived from the stronger deep-dive passes: do not stop at archive inventory, screenshots, or visual commentary. A proper demo analysis should normally include these layers, in the order that best fits the production:

When a pass has visuals and resource notes but no function-level or mechanism-level evidence, treat it as incomplete and return to the binary before moving on.

Runtime-backed completion gate: do not call a demo pass complete merely because its card has a GIF or its article has a static disassembly. Unless a direct run is genuinely impossible and the failure boundary is documented, the public article should include direct silent runtime evidence from the exact release, a timed authored-route account, runtime-to-code concordance, and an observed exit or explicit held/failed boundary. Prefer stills, GIFs, or non-H.264 silent clips for new media. Keep tiled/contact-sheet material diagnostic-only; the public preview is one untiled frame or one continuous animation. Verify both article and card at desktop and phone widths before deployment.

Scope note: the backlog also includes very small intros, including 16-byte, 32-byte, 64-byte, and similar size-coded productions. These should be analyzed when they fit the active priority band, with quick byte-level code explanations instead of the larger-demo loader/resource structure.

Animation restraint note: do not slide into adding GIFs everywhere. Add animation only when motion is technically explanatory or materially improves the analysis: palette cycling, tunnels, object rotation, feedback, scrollers, camera/floor motion, or staged transitions where stills hide the mechanism. Visually rich articles such as sea-robot-of-love-analysis.md can be fine without extra animation if the stills and analysis already carry the point. Sparse one-frame-per-second screenshot-sequence GIFs are useful as overview or index material when the source is just a set of stills. Do not impose that rate on real effect captures; use the timing that makes the actual animation legible.

Current writeups:

Supporting files:

Local Codex transcript logs are intentionally ignored because they can contain chat text, credentials, and deployment details that do not belong in git.

Method

The analyses combine public production metadata, archive inspection, binary layout notes, static disassembly, and runtime captures where practical. They are not source-level reconstructions unless explicitly stated in a file.

For DOS productions, the workflow usually involved unpacking archives, inspecting MZ/EXE structure, running under DOSBox-X when useful, carving guest RAM, and disassembling recovered code. For the N64 intro, the workflow used V64 to Z64 byte-order conversion and direct MIPS/N64 hardware register inspection.

Process Notes

Deployment

This directory is mirrored to DreamHost under:

/home/demobot/demo2.jeskola.net

The sync intentionally excludes local VCS and IDE state:

.git/
.vs/
logs/
.playwright-cli/
.codex/
.agents/
output/
tools/
.htaccess

Do not modify, overwrite, or delete the remote .htaccess during deploys. Rsync commands should exclude .htaccess so DreamHost/Apache behavior remains owned by the server-side configuration.

Deployment should stay fast and proportional:

  1. For each completed demo/article commit, run the relevant local render/audit, commit, make a remote backup of the files that commit changes, then rsync those exact files before continuing to the next demo. The workspace may be mounted through a shared filesystem that reports regular files as mode 770; always use --no-perms --omit-dir-times when syncing to the web root. After the bounded sync, set only the uploaded regular files to mode 644. Do not let archive-mode rsync replace the server's file or directory permissions.
  2. After rsync, do a small smoke check: touched page(s) return 200, touched asset(s) return 200, and protected support directories still return 403.
  3. Use the full browser verification loop only when the change touches routing, sorting, front-page JavaScript, preview selection, or another browser-specific behavior.
  4. Do not turn routine deploys into extended investigation passes. If rsync and the smoke checks pass, continue with the demo work.

After deploy, keep support directories non-web-readable and asset directories non-listable:

chmod 700 .codex .vs logs output .playwright-cli tools 2>/dev/null || true
chmod 711 images videos 2>/dev/null || true

Then verify directory URLs such as /images/, /videos/, /.codex/, and /tools/ return 403, while known article/image/video files still return 200.