DPS PolyAsset

POLYASSET

Make your game's assets smaller by making them stranger.

================================================================

WHAT IT IS

================================================================

polyasset is a command-line tool that converts your game's art

and audio into formats that fit the data better than PNG and WAV

do - and it always leaves a normal PNG or WAV beside each one, so

your game still works if a decoder never loads.

It also ships the browser decoders. You get a small JavaScript

file per format; the tool wires it into your page.

Nothing is one-way. Every house format has a twin. If you stop

using polyasset tomorrow, you delete the odd files and keep the

twins, and nothing breaks.

================================================================

THE IDEA

================================================================

Most game art is stored in formats designed for photographs.

Game art is usually not photographs. It is tiles that repeat,

sprites that share a palette, sounds built from the same short

grain, and grids of numbers pretending to be pictures.

When you store the repetition instead of the pixels, the files

get much smaller - and, more usefully, they get *meaningful*.

  Tile Ledger (.tld)    Two identical 8x8 cells become one tile

                        and an index. A tileset collapses to

                        almost nothing.

  Sprite Ledger (.sld)  A family of sprites shares one tile

                        dictionary and one exact palette. One

                        file instead of three hundred.

  Grain Ledger (.gld)   A hoofbeat that is the same 40 ms twelve

                        times becomes one grain and a sequence.

  Voice Ledger (.vld)   Dialogue tokenised at the phrase level,

                        with each line bound to the character who

                        says it and the event that fires it. Game

                        chatter has a tiny vocabulary and a huge

                        line count, so a bank ends up smaller

                        than its own plain text.

  N-Dim Cube (.ndc)     A PNG is rank 2 and a WAV is rank 1. This

                        is rank n, with named dimensions and real

                        OLAP verbs - for the data your game

                        actually queries.

  DOI / DOA             House still-image and 4-bit ADPCM audio

                        containers, both decodable in a page.

It also reads and writes a shelf of real published formats: QOI,

AutoCAD DXF R12, HP-GL plotter paths, ASCII STL, ILBM, and the

id-era set (Quake MDL, MD2, SPR, WAL, .map).

================================================================

THE RULE IT ENFORCES ON YOU

================================================================

A format has to earn its place. The tool has a verb for this and

it is not decoration:

  polyasset gameplay

      Did the house formats reach PLAY, or only the attract

      screen? It scans for decoder call-sites in your game code

      and gives a verdict. A convert that writes .tld files and a

      splash page that prints "form: .tld" next to a PNG thumb is

      a demonstration, not an asset pipeline.

  polyasset budget

      Your file-count and byte ceilings, what is spending them,

      and the compression options in the order worth reaching

      for. Useful anywhere, essential if you are shipping to a

      host with limits.

  polyasset realitycheck

      Where your claims and your files disagree.

Conversions that lose are reported as losses. Photographic

stills do not tokenise; the tool says so rather than shipping a

bigger file and calling it a win.

================================================================

USAGE

================================================================

  polyasset doctor

      Environment and project report. Run this first.

  polyasset inventory --path . --write

      What unusual formats you have, how many, how big, and what

      each one is for. Writes a table into your README or roadmap

      between marker comments, so it regenerates instead of

      rotting.

  polyasset convert --path .

      Convert what wins. Twins always emitted.

  polyasset bank <folder>

      Point it at a folder of small-palette sprites and get one

      Sprite Ledger sharing a dictionary.

  polyasset budget --path . --write

      Ceilings and recommendations.

  polyasset gameplay --path .

      The did-it-reach-play verdict.

  polyasset graft --path .

      Copy the browser decoders into your web root and wire them

      into your page.

  polyasset create / invent

      Generate seeded house and retro assets from nothing prior -

      useful for placeholders that are not programmer-art grey.

================================================================

WHAT YOU NEED

================================================================

Python 3.9+. That is the base install and it covers the house

formats, the ledgers, the id-era set and the vector formats.

Optional external converters unlock extra lanes (ffmpeg, libwebp,

oxipng, flac). `polyasset doctor` reports which it found and

skips the rest cleanly.

================================================================

WHO IT IS FOR

================================================================

People shipping web games to a host with a size or file-count

cap, and anyone who would rather their asset pipeline be

legible than magic. Every format has a written spec in specs/,

every decoder fits on a page or two, and the tool will tell you

when an idea did not work.

Not a texture compressor for 3D pipelines - if you want

Basis/KTX2, use those. This is for 2D game data, tiles, sprite

corpora, short audio, dialogue banks, and structured grids.

================================================================

LICENCE

================================================================

MIT.

Built alongside real shipped games, which is why the docs are

blunt about what lost.