prometeu-studio/discussion/workflow/plans/PLN-0083-rgba8888-glyph-payload-emission-and-sizes.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0083	studio-packer-rgba8888-asset-pipeline	RGBA8888 Glyph Payload Emission and Size Accounting	done	2026-05-23	2026-05-23	DEC-0037	packer assets-pa glyph-bank rgba8888

Objective

Change packer glyph-bank runtime payload emission from RGB565 palette bytes to RGBA8888 palette bytes while keeping GLYPH/indexed_v1 and the fixed 64-palette model.

Background

DEC-0037 requires GLYPH/indexed_v1 to retain its format name and indexed model but emit RGBA8888 palette entries. Current payload emission in FileSystemPackerWorkspaceService writes RGB565 bytes, reserves index 0, and uses color-key bytes.

Scope

Included

• Update glyph-bank payload palette byte emission.
• Update measured payload size and decoded-size accounting.
• Remove RGB565 palette constants and palette color-key bytes from emission.
• Keep scene palette_id payload semantics unchanged.

Excluded

• Palette model extraction changes covered by PLN-0082.
• Read/detail projection changes covered by PLN-0084.
• Variable palette count.

Execution Steps

Step 1 - Update glyph payload constants and formulas

What: Change palette entry width from 2 bytes to 4 bytes.

How: Introduce clear constants for palette count, colors per palette, and RGBA bytes per color. Use 64 * 16 * 4 for palette block size.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java

Step 2 - Emit RGBA8888 palette bytes

What: Write each palette color as runtime RGBA channel bytes.

How: Replace RGB565 little-endian writes with four byte writes in R, G, B, A order derived from the canonical rgba8888 integer value.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java

Step 3 - Remove reserved color-key emission

What: Stop writing a synthetic color-key value at palette index 0.

How: Remove GLYPH_BANK_COLOR_KEY_RGB565 and any emission path that fills index 0 with magenta. Emit declared RGBA values for index 0 like every other index.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java

Step 4 - Update declared palette lookup

What: Read rgba8888 from declared pipeline metadata.

How: Replace originalArgb8888/convertedRgb565 lookup paths with rgba8888. Ensure empty or malformed rgba8888 is structural failure where emission requires a palette.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java

Step 5 - Keep scene payload stable

What: Preserve scene palette_id layout.

How: Do not change writeSceneBankPayload except compile fixes caused by shared helper changes. Scene tile records continue carrying palette_id as an index into the referenced glyph palette.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java

Test Requirements

Unit Tests

• Add or update tests asserting glyph payload size includes a 4096-byte palette block.
• Assert emitted palette bytes for a known RGBA value, including alpha.
• Assert index 0 emits declared RGBA data, not magenta.

Integration Tests

• Update workspace build tests that read build/assets.pa and assert glyph-bank offsets/sizes.

Manual Verification

• Search production packer code for GLYPH_BANK_COLOR_KEY_RGB565, convertedRgb565, RGB565 palette byte writes, and hard-coded 2048.

Acceptance Criteria

• Glyph payloads keep GLYPH/indexed_v1.
• Glyph palette blocks are 4096 bytes.
• Palette entries are emitted as RGBA bytes in runtime channel order.
• No synthetic magenta/color-key value is emitted.
• Size and decoded-size metadata match the new payload length.
• Scene palette_id payload shape is unchanged.

Dependencies

• Depends on PLN-0082.
• Should run before tests/fixture conformance in PLN-0085.

Risks

• Updating size formulas without updating emitted bytes, or vice versa, will corrupt payload slicing in assets.pa.
• Accidental scene payload edits could widen the change beyond DEC-0037.