---
id: PLN-0083
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Glyph Payload Emission and Size Accounting
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
  - DEC-0037
tags:
  - 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

- [x] Glyph payloads keep `GLYPH/indexed_v1`.
- [x] Glyph palette blocks are 4096 bytes.
- [x] Palette entries are emitted as RGBA bytes in runtime channel order.
- [x] No synthetic magenta/color-key value is emitted.
- [x] Size and decoded-size metadata match the new payload length.
- [x] 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`.