Implementing the Tachyon Pet for Codex

Tachyon began with a small request: create a desktop pet resembling a technological limulus, or horseshoe crab. The design came back as a compact cyber creature with graphite armor, cyan sensor eyes, mechanical legs, and a cable-like tail. Cute, specific, and apparently determined to teach me more about sprite atlases than I had planned to learn.

The first design image was only a reference. Codex needed a package containing metadata and a binary spritesheet, so I turned the concept into pet.json plus spritesheet.webp. That sounded like the easy part. This was optimistic in the way that labeling a folder FINAL is optimistic.

The package worked, except for the working part

The first package used a legacy atlas with eight columns and nine animation rows. When I loaded it in the desktop app, an upgrade button appeared because the current pet format expected two additional rows for sixteen look directions and a manifest declaring sprite version 2.

The obvious plan was to preserve the existing nine rows, add the two directional rows, update the manifest, and go home with the quiet satisfaction of somebody who had changed one integer. Visual inspection ruined this excellent plan.

The old atlas had real defects. Some frames crossed cell boundaries, so the renderer sliced Tachyon into unrelated upper and lower fragments during animation. A contact sheet also exposed detached effects, incomplete bodies, inconsistent proportions, and poses that did not match their named states. The jump sometimes began with two tails and never convincingly left the ground. The waiting animation looked more like a jump. Running barely moved. Looking directions changed the character's scale and perspective. It was a remarkably efficient collection of problems for one small crustacean.

This mattered because an atlas can have the expected outer dimensions and still be wrong inside. The renderer does not understand that a tail continued into the neighboring cell for artistic reasons. It sees a grid, extracts rectangles, and displays exactly the fragments I gave it (with the calm professionalism of a machine documenting my mistake).

Rebuilding around visual invariants

The repair became a full atlas pass rather than a schema upgrade. I treated the good running-right sequence as the reference for Tachyon's proportions and cyan body details, then rebuilt running-left from that reference. The jump became visibly airborne without the second tail. Waiting became a restrained bob instead of an accidental launch, while the generic running state gained actual motion.

The look-direction frames needed their own correction. They were scaled down to match the normal character proportions and kept within the same visual identity. The acceptable failed animation stayed. Waving and review were retained, while their unused cells were cleared. The final run also cleared every unused sprite cell to full transparency, removing invisible pixel data that validation had flagged.

That last point is less cosmetic than it sounds. Transparent pixels can still carry RGB values, and unused atlas cells can still contain non-transparent debris. Neither necessarily shows up in a casual preview, but both make a poor asset contract. A sprite sheet is not only the character one can see. It is also the geometry, padding, alpha channel, and boring empty regions around it.

The repaired package was reported as a 1536 by 2288 RGBA WebP, arranged as an 8 by 11 atlas. The package iteration was called Tachyon v3, but the sprite schema remained version 2. Those are separate version numbers: one describes my third pass over the artifact, while the other tells the desktop loader which atlas contract to use.

The deliberately boring manifest

After all that visual work, the final readable contract is pleasantly small:

{
  "id": "tachyon_v2",
  "displayName": "Tachyon",
  "description": "A compact cyber horseshoe crab with armored graphite plating, cyan sensor eyes, tiny mechanical legs, and a segmented cable-like tail.",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}

The manifest names the pet, preserves its visual brief, declares the sprite contract, and points at the binary asset. The complexity belongs in the atlas, but the atlas is only trustworthy after both mechanical validation and visual review. Dimensions caught the format. Contact sheets and animation previews caught the character being bisected, duplicated, resized, and occasionally asked to jump without jumping.

This is still a short implementation story, even after the repair, because the useful result is not proportional to the number of paragraphs I can force out of it. I built a recognizable Codex pet, rebuilt its broken atlas, validated the package, and stopped before the manifest became a small constitution. Given my usual instincts around configuration files, that last part may be the most surprising result.

If you want to inspect the small constitution I heroically avoided writing, Tachyon is waiting in its repository with all body parts now assigned to the correct frames.