ASCII Visual Engine

Two users. The app author needs a canvas animating in a few lines and a way to reach deeper only when they need to. The look author needs to describe a visual in a file they can read, tweak, and share, without touching engine code. Both need it to hold 60 frames per second on an ordinary laptop.

Engine or product? The demo could have become the app, with its own chrome, routing, and controls. I kept it a harness. The library ships no UI, hosts own the shell, and the harness exists to test the engine and show what it does. The public surface had grown past a hundred methods because every host need was met by adding one, so 0.3.0 put a small facade on top rather than removing anything underneath: app authors see a dozen methods, look authors see nested presets where every group is optional, and the full engine stays reachable for whoever needs it.

Frame pipeline

• Patterns write the base brightness field.
• Motion behaviors blend by weight and priority and move the field.
• Simulations and live sources layer on top; a source in mask mode cuts the finished frame to its shape.
• Effects and post passes (feedback, smear, displacement, threshold, dither, scanline) reshape it.
• The glyph language maps brightness and role to characters; a renderer draws the grid.

Systems

• Typed event bus for notes, controls, presets, morphs, and custom events.
• Plugin manager with pattern, effect, input, renderer, and utility types; every input device goes through one dispatch path and one mapper.
• Multi layer compositing with blend modes and masks.
• Named random streams behind a seed, and a fixed timestep, so the same take renders the same frames.
• Frame profiler, quality presets with adaptive mode, object pooling, glyph cache, dirty region rendering.
• Preset validation at load; scene documents for save and restore.

The target machine is a laptop driving a screen at 1080p, sometimes 4K, and the plan was to add a WebGL renderer when Canvas 2D ran out. It never did. The first measurement at 1920x1080 put three hero looks at 18 to 20 milliseconds a frame. Retina scaling behind a context transform, and a draw loop that sets the fill style once per brightness level instead of once per cell, brought all six to between 3 and 12. With the budget met, WebGL moved from next to demand driven, and the stub came out of the harness. The frame budget is re-measured and recorded with each release.

By September the engine existed in three places: the local tree with new validation and a reshaped demo, GitHub with CI and snapshot tests, and a copy vendored into a platform monorepo that had grown host driven methods for color, glyph override, and bass driven scale. Version 0.2.0 folded all three back into one branch with every test passing, and set the rule that hosts pin a git tag instead of carrying a copy.

The day Plantasonic went live, two of its five worlds went black about two seconds in while the engine still reported 60 frames per second. The host's adapter was passing a control value of NaN from an audio level read before the analyser had data, and one NaN cell reached the renderer's bucket lookup and threw every frame. The fix in 0.4.1 was not one guard but a boundary: every number that enters the engine is checked and a bad one is ignored with a warning that names it, the renderer treats a NaN cell as dark, and every preset is now run for four seconds in the test suite with the assertion that every cell stays finite. The warnings named the host's three bad controls the same afternoon.

The grid abstraction earned its keep: every feature since the first release, including morphing, input takes, and text as a mask, slotted in as a stage that reads and writes the same cells. The facade and the nested preset shape should have come first; a flat 59 field preset and a 105 method class were the honest cost of adding features one host at a time, and 0.3.0 paid it. The other lesson is about boundaries. A library that takes numbers from hosts has to assume some of them are wrong, and it took a live host to make that concrete.