04-decisions.md · non-normative

04 — Art Decisions

Nine decisions binding on the art documents, settled so that asset production can proceed without each sprite re-litigating them.

D-1 to D-6 are six questions the art documents carried as open conflicts. Raised by the team producing the first asset bundle, who were right that these determine what files should exist and therefore belong before more polishing rather than after.

D-7 was raised later, by the team generating sprites from these documents, and is a different kind of item. It is not a conflict between two documents but an arithmetic consequence of two requirements that are each individually correct — a consequence neither document noticed it had written, and which made every detail layer in the roster impossible to draw.

D-8 and D-9 came out of building the verifier D-7 asked for and then running it over the delivered bundle. Both are about the same discovery: the art was never drawn to these rules. D-8 settles what happens to the four gun tubes; D-9 settles what happens to cell geometry generally, and records one wrong inference in full so it is not made again.

Status: Draft v0.1 · Owner: unassigned · Depends on: 00-art-direction.md, 01-units.md, 02-terrain.md, 03-ui-effects.md, docs/spec/04-ui-ux.md (UX-440)

Each decision below is binding on the art documents, and each names the requirements that must change to match. Where a decision was accepted as proposed it says so; where it was amended, the amendment and its reason are recorded, because a decision without its reasoning becomes a fossil the moment someone asks why.

D-1 · Counting cues are exempt from the interior-mark cap

Accepted as proposed. A repeated identity group — five road wheels, seven, a battery of barrels, a run of gun ports — counts as one semantic feature against the foundation's four-ink-shape cap (ART-080), not as one shape per element.

Rationale: the cap exists to stop a 128 px cell turning to mush, and the thing that causes mush is four unrelated marks competing for attention. A regular repeated run does not compete with itself — the eye reads "tracked vehicle, many wheels" as a single percept and then counts, which is exactly the identity cue the unit document is buying. Treating each wheel as a shape would forbid the cue that distinguishes Armour from Heavy Armour, which is not a trade the cap was ever meant to make.

Guard, added rather than assumed. The exemption applies only where the group actually reads as a group: elements MUST be uniform in size and shape, evenly spaced, and aligned on a common axis. An irregular scatter of similar marks is clutter wearing a counting cue's clothes and takes the full four-shape cap. A group MUST also survive the Chip-tier reduction as a texture rather than as countable elements — if it reads as noise at 8 CSS px, the count was never legible and the cue is not earning its complexity.

Changes: 00-art-direction.md ART-080 gains the exemption and its guard. 01-units.md §7.3's "6–12 discrete shapes" review row is reconciled against it — that row was the visible symptom of this conflict.

D-2 · Infantry is base-only; Armour is the detail-layer example

Accepted as proposed. Infantry ships with no detail layer. The foundation's worked example in §7 moves to Armour.

Rationale: Infantry is the style plate and the simplest silhouette in the roster, which is precisely what makes it the wrong teaching case for a feature about material and articulation — a shaded rifle teaches nothing and the sprite is better without it. Armour is the canonical case: tracks and road wheels are mechanical articulation that is genuinely not identity, so deleting the detail layer leaves a correct and recognisable counter, which is the test ART-125 sets for whether a detail layer is legitimate at all.

Changes: 00-art-direction.md §7 is rewritten end to end around Armour — the prompt, the layer split table, the reduction, and the cell placement. ART-490's style-plate discipline is unaffected: Infantry remains the style plate, because a style reference wants the simplest, most typical silhouette. The plate and the worked example are now deliberately different sprites, and the foundation must say so, since an earlier draft conflated them.

D-3 · File naming is <id>.png and <id>__<variant>.png

Accepted as proposed, and partly already done. Unit source and master files are infantry.png, submarine__submerged.png, armour_detail.png.

Rationale: the foundation's unit.infantry.normal.png carries a redundant unit. prefix inside a units directory and a .normal segment meaning "no variant", which is a value that exists only to avoid being absent. The shorter form is what 01-units.md, the delivered metadata and every atlas already use.

Changes: 00-art-direction.md §9's tree is corrected (done). The remainder of that document must be swept for the old form — it appears in prose, in the gen.json sidecar description, in the packer contract and in ART-550's worked commands. "Reconcile completely" is the requirement: a naming convention that holds in one section and not another is worse than either convention alone.

D-4 · Masters are re-rendered, never upscaled — and where they cannot be, the 128 px file is the record

Amended. The proposal was to restore 512 × 512 masters even though the artwork is procedurally constructed. Restoring masters is right; producing them by upscaling is not.

The rule. A 512 px master MUST contain information the 128 px delivered cell does not. It is therefore produced in exactly one of two ways:

  1. Re-rendered from the source that constructed it — the script, the vector, or the geometry that drew the sprite — at 512 px. This is a real master: it has true curves, and a later edit at 512 reduces cleanly.
  2. Kept from generation, where the sprite came from an image model, per ART-280.

A master MUST NOT be produced by upscaling a 128 px raster. Where neither route is available — the construction is not reproducible and no larger original exists — the 128 px file is the artwork of record, art/master/ legitimately has no entry for that sprite, and art/README.md says so for that sprite by name.

Rationale: an upscaled master is worse than an absent one. It has the size, the location and the filename of an artwork of record while containing not one pixel of additional information, so every downstream decision that assumes headroom — a hand edit at 512, a higher-DPI tier, a print asset — silently gets a blurred 128 px image instead. The absence of a master is a fact someone can act on; a fake master is a fact that lies. This is the same failure the specification has already been bitten by twice: a requirement that looks like engineering while encoding nothing.

Consequence for the delivered bundle. Its unit art was constructed deterministically. If that construction is reproducible, re-render at 512 and populate art/master/. If it is not, the current art/README.md deviation note stands and is the correct outcome, not a gap to paper over.

Changes: 00-art-direction.md ART-280 gains the re-render-or-absent rule.

D-5 · Chip and Strategic tiers are drawn at runtime

Accepted as proposed. The authored Chip and Strategic PNGs are replaced by code that draws them, per ART-390.

Rationale: both tiers carry short text labels and demand exact placement at 32 px and 16 px, which are the two things generated and hand-placed raster art gets wrong most reliably. Drawing them also makes them correct by construction for a modded unit set and for a translated label — neither of which a shipped raster can be, and both of which MOD-430 requires.

Sequencing. The delivered rasters stay until the drawing code exists — deleting working assets before their replacement runs would trade a deviation for a hole. They are marked as bootstrap under D-6 and removed in the same change that lands the code.

D-6 · Committed atlases are a labelled bootstrap

Accepted as proposed. The packed atlases in art/atlas/ are temporary. When the packer exists, they move to build/atlas/ as derived and gitignored, reproducible from art/src/ alone.

Added: they must be labelled, not merely intended to be temporary. art/atlas/README.md MUST state that these files are generated output committed as a bootstrap, MUST NOT be hand-edited, and MUST NOT be treated as a source of truth. A generated file sitting in a source tree with nothing saying so is one that gets hand-patched by someone fixing a sprite in a hurry, and the patch is then lost the first time the packer runs.

Rationale for committing them at all: the alternative is gitignoring artefacts nobody can currently regenerate, which leaves a teammate unable to load anything. Correct in principle, useless in practice, and this project's shared state is the server rather than a local build.

D-7 · Linear detail qualifies on its own three tests, not on the area floor

Accepted as proposed. ART-155 rule 4's 12 cell px minimum in a detail region's smaller dimension is the right test for an area feature and is unchanged for one. It is the wrong test for a linear feature, and a separate test now governs those.

The problem, stated as the arithmetic that produced it. ART-050 requires a closed 8 cell px ink contour around every silhouette. A gun tube is part of the silhouette and projects into void, so that contour runs down both of its long edges. ART-155 rule 4 then requires whatever is left between them to be at least 12 cell px in its smaller dimension. So:

8 px contour  +  12 px minimum detail region  +  8 px contour  =  28 cell px minimum tube thickness

28 cell px is 7 CSS px on a tank whose whole painted width is 70–78 px — roughly a third the height of the hull, and a barrel nobody would draw or accept. All four detail layers the roster delivers (field_gun, armour, heavy_artillery, heavy_armour) are gun tubes, so all four were arithmetically dead: not "expensive", not "a trade-off", but forbidden by two requirements that had never been read against each other.

Rationale: the two floors were written for area features — a helmet, a canopy, a hatch, a panel of material — where the smaller dimension is what a reader has to resolve and 12 cell px is honestly the floor of resolvability. A linear feature is a different object. Its thinness is the point: a gun tube that is not thin is not a gun tube, and the thing that makes it legible is its length and its straightness, which the eye reads long before it resolves the width. Applying an area test to a linear feature does not measure it conservatively, it measures the wrong quantity, and it happens to return "forbidden" for every instance of the class. That is the signature of a category error rather than a strict rule.

The two categories

Area detail keeps ART-155 rule 4 exactly as written: at least 12 cell px in its smaller dimension. Nothing about it changes.

Linear detail qualifies on three tests, and all three MUST hold:

Test Floor Measured
Visible width ≥ 4 cell px across the detail region itself — the authored colour left between the contours, not the projection's outside thickness
Length ≥ 24 cell px along the region's long axis
Aspect ratio ≥ 4 : 1 length : visible width

The aspect test is not redundant with the other two. Without it, a 24 × 20 cell px patch passes both floors and is an area feature wearing a linear feature's numbers; the ratio is what makes "linear" mean something a reader can check rather than a label an author applies.

The narrow-linear-projection exception to the contour

A projection that qualifies as linear detail MAY carry a 2 cell px ink contour on each exposed side in place of ART-050's 8, subject to a minimum 8 cell px total silhouette thickness for the projection. At the floor that is 2 + 4 + 2 = 8 cell px, which is the thinnest such projection that can exist at all.

The 8 cell px is not an arbitrary floor invented to make the arithmetic work. It is ART-040's existing silhouette minimum — no part of a silhouette may be thinner than 8 cell px — restated as the constraint on the projection. The exception therefore meets the general rule rather than carving underneath it, which is the whole reason it is defensible. An exception that had needed a 6 cell px projection would be asking for a hole in ART-040, and would have to be argued there instead.

The contour is narrower, never absent. ART-050's "closed and unbroken" is untouched: a qualifying projection is contoured on every exposed side, all the way to where it meets the mass it projects from.

The base test still governs

The base MUST remain complete and identifiable with the detail layer deleted. This is ART-155 rule 1 and ART-255 check 11, it is the existing test for whether a detail layer is legitimate at all, and D-7 does not touch it. A projection that only reads as itself once its authored colour is present has not qualified for a thinner contour — it has failed the prior question. Delete the layer and the tube must still be a tube.

The prohibition, which is what stops this becoming a licence

The exception is NOT available to decorative lines, panel seams, panel lines, rivets, tread links, hatch outlines, grille slots, bore lines drawn as surface marks, or any other surface marking. It is available only to a projection: a part of the silhouette itself, contoured on its exposed sides, with void on the other side of that contour.

This is a prohibition and not a guideline, and it is stated that way deliberately. ART-080 and ART-155 rule 4 have been holding one line since the first draft — that fine surface detail is mush at every tier this game draws, costs a texture page and buys a smudge — and D-7 hands an author a 4 cell px minimum width. Without the prohibition, every rivet and every panel seam in the roster can be drawn as "linear detail 4 px wide and 24 px long", the four-shape cap becomes unenforceable, and the silhouette discipline the whole style rests on collapses in one revision. The width relaxation buys exactly one thing — a projection thin enough to be a gun tube — and it buys nothing else.

What this makes drawable, checked rather than assumed

All four tubes were measured against the new geometry before this decision was recorded as implemented, because "the rule now permits it" and "the sprite now works" are different claims. ART-445 of 01-units.md carries the working; the result:

Cell Run Thickness Visible detail Aspect
field_gun ≥ 24 px 8 px 4 px ≥ 6.0 : 1 clears, on the floor of every test
armour 36 px 12 px 8 px 4.5 : 1 clears with margin
heavy_artillery ≥ 52 px 16 px 12 px ≥ 4.3 : 1 clears
heavy_armour ≥ 44 px 12 px 8 px ≥ 5.5 : 1 clears at 12 px only

All four clear the 8 cell px thickness floor, and they clear it trivially — ART-440 of that document already forbade any part of any silhouette from being thinner than 8 px, so no tube in the roster could have been thinner than the exception's minimum even before the exception existed. That is the same observation as "the floor is ART-040", arriving from the roster side.

Two things the check turned up that assuming would have missed:

The alpha-bleed rule is unaffected, and here is why

ART-230 floods the base's transparent RGB with INK and calls it exactly correct rather than a tolerable approximation. That claim rests entirely on ART-050: because the contour is closed, every pixel at the silhouette boundary is known to be ink, so continuing ink outward continues the artwork instead of guessing at it. A 2 cell px contour is still ink. The boundary pixel along a qualifying projection is an ink pixel exactly as it was, the guarantee is a statement about the value at the boundary and not about the width of the band behind it, and ART-230 is consequently untouched. The same holds for ART-210 of 01-units.md, which reaches the flood value from the same premise.

Known risk, named with a check rather than solved

A 2 cell px contour is 0.5 CSS px at the Close tier — a Close cell is 128 cell px shown at 32 CSS px. On the wire that is half a device pixel at DPR 1, one at DPR 2, one and a half at DPR 3. At DPR 1 the dark edge may alias away entirely, leaving the tube's authored colour floating on the terrain with no ink separating it — which is the precise failure ART-050 exists to prevent, arriving at the one place the contour was thinned.

This is not solved here. It is recorded as a risk with a named check, so that it is found on the first qualifying sprite rather than after twenty-six:

Render a qualifying narrow linear projection at DPR 1, DPR 2 and DPR 3, over the lightest and the darkest terrain, and confirm the contour survives at each. This is an explicit item in the contact-sheet review, not a thing to notice later.

If it fails at DPR 1, the honest responses are to thicken the projection so the contour can be wider, or to accept the tube untinted on that target and let the detail atlas be dropped — which ART-125 already permits and already has a fallback for. What must not happen is that the check is skipped and the answer is discovered in a bug report.

Changes.

00-art-direction.md: three new requirements, taken next to the rule they amend — ART-157 the two categories and the three linear tests, ART-158 the narrow-linear- projection contour exception with its alpha-bleed confirmation and its DPR risk, ART-159 the prohibition. ART-050 gains a pointer to ART-158, so a reader of the contour requirement alone is not misled about uniformity. ART-155 rule 4 splits into area and linear and defers to ART-157. ART-225 rule 2 and ART-255 check 10 stop naming a fixed 8-px contour band and take the contour weight that applies to the boundary they are measuring. §7's 28 cell px block, its layer-split table, its step 4b hand step and §7.4's placement table are re-derived. §8's checklist boxes change, and gain the DPR item.

01-units.md: ART-445 is new, stating the geometry at the drawing board, checking all four tubes against it, and carrying the DPR review obligation into the contact sheet of ART-1170 of 02-terrain.md. ART-435's "adopted without variation" splits into a weight variation and a closure exception, and its note on what the contour costs the four explicit cells is rewritten; ART-440's "an 8 px feature is contour and nothing else" is no longer true and is corrected; ART-245 and ART-247's closing rationale point at ART-445; ART-580's explicit-cell hand pass and §7.3's contour row follow; the verifier under ART-590 gains a note about these four cells — since superseded, because that note predicted a failure which measurement disproved, and ART-590 has been rebuilt to derive the contour band from the boundary rather than from one erosion depth (open question 4). §8's four explicit subsections gain a Tube geometry paragraph each — the first statement of tube thickness anywhere in that document. Open question 11 closes on viability, and questions 9, 14 and 16 are corrected where they cited the withdrawn arithmetic.

No requirement is renumbered. ART-157, ART-158, ART-159 and ART-445 are unused IDs taken next to the requirements they sit with, per the constraint in open question 3 below.

D-8 · The four gun tubes are re-authored as true projections

Decision. field_gun, armour, heavy_artillery and heavy_armour are re-authored so that each gun tube is an actual narrow linear projection — silhouette geometry with void immediately above and below its exposed run — to the figures §8 of 01-units.md already states. Each cell's <asset>.gen.json declaration lands with the redrawn art. This closes open question 4.

Why the delivered cells needed it. None of the four contains a projection. Every tube is drawn as a stripe inside a larger FIELD mass, its detail region sitting 8–20 cell px from the nearest background with material on both sides. That is ART-159's "bore line drawn as a mark on a surface", which is denied ART-158's narrower contour by name; and as a plain area region it is 4–5 cell px across against ART-155 rule 4's 12 cell px floor. The four cells conform to neither rule. They also never failed the contour check that a previous draft of this document predicted they would — measured, all four pass at 100.0 % INK — because a stripe deep inside a mass never touches the contour band at all. The prediction and the defect were both about a projection that was never drawn.

The targets are unchanged and need no revision. They are the Tube geometry paragraph in each of §8's four explicit subsections, stated as total thickness / visible detail width / exposed run:

Cell Total Visible Run Aspect
field_gun 8 px 4 px ≥ 24 px ≥ 6.0 : 1
armour 12 px 8 px 36 px 4.5 : 1
heavy_artillery 16 px 12 px ≥ 52 px ≥ 4.3 : 1
heavy_armour 12 px — not 16 8 px ≥ 44 px ≥ 5.5 : 1

What the delivered art missed is not these numbers. It is ART-158's first sentence: a projection reaches out from the mass with void on the far side of its contour. A barrel drawn inside the hull satisfies every figure in that table and is still not a projection.

Three alternatives were considered and rejected. Widen the detail regions to 12 cell px is the 28 px barrel D-7 exists to escape, arriving by another road. Grant surface marking a bounded exception of its own is precisely what ART-159 was written to refuse, and the reasoning there is unchanged. Cut the delivered raster was tried, not assumed: clearing the mass above and below armour's barrel until it projects — cut at x = 84, 12 px tube over a 36 px run, contour repainted from the new boundary — produces a projection that passes every geometric test and destroys the unit. The delivered silhouette is one solid mass from x = 17 to x = 120; the barrel has void above it but hull below, so the only way to give it void on both sides is to remove hull, and the hull is where the identity lives. Ink runs across the road-wheel row fell from 12 to 9 — wheels deleted — against an Accept line requiring exactly five road wheels. The sprite was restored. This is authoring work, not surgery.

The declaration follows the art, never precedes it. ART-585 validates a declaration against the geometry actually present, so one written against today's rasters is correctly rejected — ART-159: only N % of the run has void on both far sides.

Delivered. Bundle v3 re-authored all 25 cells from the locked geometry rather than patching the prototype, and the four tubes are now real projections. Measured here rather than taken on trust:

Cell Angle Total Visible Run Aspect Target
field_gun −16.3° 9 4 32 8.00 : 1 8 / 4 / ≥ 24
armour 0.0° 12 8 37 4.63 : 1 12 / 8 / 36
heavy_artillery −23.2° 16 (median) 12 65 5.42 : 1 16 / 12 / ≥ 52
heavy_armour −1.0° 12 8 45 5.63 : 1 12 / 8 / ≥ 44

armour holds 12.0 px across all 37 buckets without variance; heavy_artillery runs 3–23 px across its declared region because that region also spans the muzzle brake, which ART-445 measures as an area region rather than part of the linear one — its tube proper is 16.2 px at the median.

The declarations are load-bearing, which was checked by removing them. With the four gen.json files deleted the same cells fail at 84–91 % INK on ART-435 and report 119–360 detail pixels on the contour: the tubes genuinely depend on ART-158’s 2 px weight rather than merely being declared to. The counting cues survived the re-authoring — armour reads 5 road-wheel ink runs and heavy_armour 7, which is what their Accept lines require and what the cut-the-raster experiment destroyed.

D-9 · Cell geometry holds; the delivered 25 are concepts, not a baseline

Decision, in four parts.

  1. The 8 px frame band of ART-300 is a hard constraint. No sprite is clipped to satisfy it. Cells are re-authored so the completed contour finishes inside the live box.
  2. The per-domain bbox limits of ART-350 hold provisionally. In particular the air height is not expanded: the y = 24–80 footprint is an intentional class cue, and the delivered aircraft simply were not drawn to it — they were authored nearly full-cell.
  3. The 88 px land width ceiling is not changed on the current evidence. Before it is: author fresh conforming Close cells for infantry, heavy_armour, heavy_artillery, carrier and heavy_bomber, and run the badge and identity-core contact sheet at 32 CSS px. If the large ground units are materially cramped at that size, test a land-only 96 px ceiling. The live box is not globally relaxed to 112 px.
  4. The original 25 sprites are source and reference concepts, not geometry the verifier is expected to grandfather. No exemption table is added for them.

A measurement, and what it does not show. Running ART-590's full check set over the delivered bundle reports findings on 20 of 25 cells: 11 place art inside the frame band — cruiser 601 px, carrier 519 px — and 16 fall outside the loosest bbox bounds, mostly on height at 82–111 px.

An earlier reading of this document offered that as evidence the bounds themselves were the more likely defect, on the reasoning that a rule two thirds of a roster fails is usually the wrong rule. That inference was wrong, and it is recorded because it is the tempting one. The counts are accurate but they were measured against the original prototype bundle, which predates the stabilised ART-300/ART-350 geometry — the cruiser 601 and carrier 519 figures reproduce exactly from it. A failure rate against art that was never drawn to the rule is evidence about the art, and says nothing whatever about the rule. Deciding a constraint is broken because non-conforming input disagrees with it is how a live box quietly becomes whatever was drawn last.

Open questions

  1. Is the bundle's unit construction reproducible? D-4 turns entirely on this and only the team that produced it can answer. If yes, art/master/ fills at 512 px and the deviation in art/README.md closes. If no, that deviation is permanent for those sprites and any future sprite still owes a master under ART-280.

  2. Who owns the Chip and Strategic drawing code? D-5 assigns the outcome but not the home. It is client rendering, so 04-ui-ux.md is the natural owner, but the glyph atlas it needs for labels is an art asset. The split wants stating before either side assumes the other has it.

  3. The cross-document requirement-ID collision is still open. ART-605 names a different requirement in each art document. Every citation across these four files — including the ones this decision record just added — is ambiguous until one renumbering pass fixes all four together.

  4. D-7 breaks the roster verifier’s contour check. Closed by D-8, which re-authors the four cells as true projections, and by the boundary-derived contour band now in ART-590. The prediction this question carried — that the four cells would fail a check they conformed to — was wrong on both halves: they pass at 100.0 % INK, and they conform to ART-445 nowhere, because none of them contains a projection. D-8 records the evidence, the rejected alternatives, and the geometry targets.

  5. ART-595's ownership threshold is unreachable with the seat pairs the spec prints, and the delivered art cannot certify against it. Raised by the team producing bundle v3 and confirmed here by measurement. The requirement asks for a whole-cell RMSE above 0.25 between two seat pairs at an 8 × 8 reduction. The delivered 25 cells score 0.086 to 0.146, and the ceiling is structural rather than a matter of drawing harder:

    Quantity Value
    Separation between the two foreground (INK) colours 0.435
    Separation between the two background (FIELD) colours 0.087
    Fraction of the 8 × 8 cell that must be full foreground to reach 0.25 0.330

    The two printed seat pairs have nearly identical backgrounds, so FIELD carries almost no signal and effectively only INK separates the seats — while ART-240 caps interior INK at 8–35 %. A cell would have to be a third solid ink across the whole square, transparent margins included, to clear 0.25. ART-240 and ART-595 cannot both be satisfied as written, and no amount of re-authoring closes it.

    Three candidates, none taken here: renormalise the RMSE over the painted support rather than the whole cell, which the v3 bundle records as passing all 25 cells; lower the threshold to something the ink budget can actually reach; or choose seat pairs whose backgrounds differ, so FIELD carries signal too — which is the change that would make the measurement mean what UX-440 intended, since a viewer reads the mass before the marks. The human read test of ART-610 is unaffected and still required either way.

    The new ART-225 contour check reports one further defect in two of them: field_gun and heavy_artillery each place a single detail pixel at depth 8, on the innermost pixel of the contour band. It is a hair, it is real, and re-authoring resolves it.

Built from source 7f764a6c1ff9 · VERSION.json