updated packer agendas
This commit is contained in:
+45
-1
@@ -2,7 +2,9 @@
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
Closed
|
||||
|
||||
Resolved by [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -28,6 +30,12 @@ Important example:
|
||||
- one `asset.json` describes the whole managed asset and its final packed output;
|
||||
- the internal source files are inputs of that asset, not separate assets unless explicitly modeled that way.
|
||||
|
||||
The runtime-facing extraction path also depends on codec information.
|
||||
Because codec affects how runtime opens, decodes, or materializes payload bytes, codec must be explicit in the asset contract rather than hidden inside format naming.
|
||||
|
||||
Preload intent is also asset-level information.
|
||||
Each managed asset should carry an explicit entry indicating whether it participates in preload, so preload inclusion is declared intentionally rather than inferred indirectly later in the pipeline.
|
||||
|
||||
## Source Sections
|
||||
|
||||
- `5.3 Asset Types (Bank Targets)`
|
||||
@@ -44,6 +52,8 @@ Important example:
|
||||
5. Is `type` the bank target, the user-facing kind, or both?
|
||||
6. How should packer version output formats independently from registry and descriptor schemas?
|
||||
7. How should one `asset.json` declare many internal inputs that together form one virtual asset, such as an atlas plus palettes?
|
||||
8. Should codec be part of `output.format`, or a separate explicit field in the output contract?
|
||||
9. How should each asset declare preload intent so the packer can materialize runtime preload entries deterministically?
|
||||
|
||||
## Options
|
||||
|
||||
@@ -75,6 +85,38 @@ Also adopt this modeling direction:
|
||||
- many internal source files may feed that single managed output;
|
||||
- atlas/image-bank style assets should be modeled as one asset with many inputs rather than many implicit sibling assets.
|
||||
|
||||
Also adopt this output-contract direction:
|
||||
|
||||
- `output.format` identifies the semantic/runtime format contract;
|
||||
- `output.codec` identifies how payload bytes are stored for extraction/materialization;
|
||||
- codec must remain explicit because it affects runtime extraction behavior;
|
||||
- codec should not be smuggled into format naming when it represents a distinct storage concern.
|
||||
|
||||
Also adopt this preload direction:
|
||||
|
||||
- each managed asset must expose an explicit preload-related declaration entry;
|
||||
- preload participation must be declared, not inferred from ad hoc conventions;
|
||||
- packer build must use that declaration to decide whether preload data is emitted into the runtime-facing artifact contract.
|
||||
- `preload.enabled` should be the required runtime-relevant boolean;
|
||||
- richer packer-side preload metadata may exist, but it must not change runtime behavior until separately specified.
|
||||
|
||||
Current recommended shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"preload": {
|
||||
"enabled": true,
|
||||
"policy": "boot_critical"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Direction:
|
||||
|
||||
- `enabled` is the normative yes/no input for runtime preload emission;
|
||||
- optional fields such as `policy` are packer-side hints for Studio, diagnostics, planning, or future evolution;
|
||||
- packer-side preload hints must not silently alter the current runtime-facing preload contract.
|
||||
|
||||
## Expected Decisions to Produce
|
||||
|
||||
1. Common `asset.json` schema boundary.
|
||||
@@ -82,6 +124,8 @@ Also adopt this modeling direction:
|
||||
3. Versioning strategy for asset format specs.
|
||||
4. Rules for defaults and explicit materialization.
|
||||
5. Multi-input asset declaration model for atlas, bank, and similar grouped assets.
|
||||
6. Explicit separation between output format and codec in the asset contract.
|
||||
7. Asset-level preload declaration model.
|
||||
|
||||
## Expected Spec Follow-up
|
||||
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
Closed
|
||||
|
||||
Resolved by [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -67,36 +69,87 @@ From `../runtime/docs/runtime/specs/15-asset-management.md`:
|
||||
|
||||
These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.
|
||||
|
||||
For this agenda, the intended direction is:
|
||||
|
||||
- `assets.pa` is the authoritative runtime-facing artifact;
|
||||
- `build/asset_table.json` is a companion tooling artifact derived from the same build result;
|
||||
- runtime must not depend on `build/asset_table.json` as its primary source of truth.
|
||||
|
||||
Current runtime code now resolves preload by `asset_id`, but game-facing runtime APIs still refer to assets by `asset_name`.
|
||||
Therefore this agenda distinguishes:
|
||||
|
||||
- `asset_id` as stable artifact identity for preload/bootstrap and asset-table integrity;
|
||||
- `asset_name` as logical API-level identifier used by game/runtime-facing calls today.
|
||||
|
||||
This agenda does not introduce a second runtime-only asset identity.
|
||||
The `asset_id` emitted by the packer is the same `asset_id` used in the runtime-facing artifact contract.
|
||||
|
||||
## Key Questions
|
||||
|
||||
1. How should the packer spec mirror the already normative `assets.pa` v1 envelope from runtime specs 13 and 15?
|
||||
2. Which fields in `asset_table.json` are still tooling-only if the runtime-facing contract lives primarily inside `assets.pa`?
|
||||
3. Is asset order always `asset_id` order, or can format-specific constraints override it?
|
||||
2. Which fields in `build/asset_table.json` are companion tooling data versus runtime-facing contract data?
|
||||
3. Should global asset packing order be deterministic by `asset_id`, or influenced by usage and format-specific heuristics?
|
||||
4. How should alignment be expressed and validated?
|
||||
5. What exactly counts as determinism for virtual asset pipelines?
|
||||
6. Which inferred values must be written back versus only emitted in build outputs?
|
||||
7. Which packer-side metadata is intentionally excluded from the runtime-facing contract?
|
||||
8. How should packer document `preload` lifecycle and `offset` semantics so they match runtime reader behavior?
|
||||
9. How should per-asset preload declarations be transformed into the `preload` section of `assets.pa` deterministically?
|
||||
10. How should the packer preserve both `asset_id` integrity and `asset_name` lookup semantics in runtime-facing artifacts?
|
||||
11. Should `asset_table` be modeled as a deterministically ordered asset list that preserves packer `asset_id` values end-to-end?
|
||||
12. Which envelope fields are runtime-validated versus emitted only for Studio/tooling use?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
Keep `assets.pa` simple and push structure into `asset_table.json`.
|
||||
Keep `assets.pa` as the authoritative autocontained runtime-facing artifact and emit `build/asset_table.json` as a derived companion artifact for Studio and tooling.
|
||||
|
||||
### Option B
|
||||
|
||||
Embed more self-description into `assets.pa` itself.
|
||||
Keep runtime-facing structure split across `assets.pa` and `build/asset_table.json`.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A keeps runtime payload compact and keeps metadata easier to evolve.
|
||||
- Option A matches the current draft direction and reduces double-modeling.
|
||||
- Option B may help standalone introspection, but it risks splitting authority across two artifacts.
|
||||
- Option A matches the runtime specs already in force.
|
||||
- Option A keeps runtime authority in one artifact and prevents contract drift.
|
||||
- Option A still allows rich tooling through a derived companion file.
|
||||
- Option B risks splitting authority across artifacts and making runtime/tooling divergence easier.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM slice structure.
|
||||
Adopt Option A with these fixed directions:
|
||||
|
||||
- `assets.pa` is the authoritative runtime-facing artifact;
|
||||
- the `assets.pa` header is the authoritative runtime-facing descriptor;
|
||||
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and builder/tooling integration;
|
||||
- global packing order is deterministic by increasing `asset_id`;
|
||||
- preload emission is derived deterministically from per-asset `preload.enabled`;
|
||||
- alignment exists only when explicitly required by spec;
|
||||
- offsets are always relative to the payload region, never to the start of the full file;
|
||||
- checksum is not part of the baseline `assets.pa` envelope contract.
|
||||
|
||||
Also adopt this performance direction:
|
||||
|
||||
- usage-based hot-first packing is not part of the baseline contract;
|
||||
- deterministic stable ordering is preferred over heuristic physical reordering;
|
||||
- future locality optimization may be introduced only through an explicit later decision and spec, not as an implementation shortcut now.
|
||||
|
||||
Also adopt this identity direction:
|
||||
|
||||
- runtime-facing preload entries should migrate to stable `asset_id` instead of mutable `asset_name`;
|
||||
- runtime-facing preload/bootstrap integrity should treat `asset_id` as primary identity;
|
||||
- `asset_name` remains present in `asset_table` as logical descriptive and API-facing metadata used by current runtime/game-facing calls;
|
||||
- `asset_table` should be generated deterministically on every build from the current managed asset set;
|
||||
- `asset_table` should be emitted as a deterministically ordered list of asset entries;
|
||||
- the runtime-facing `asset_id` is exactly the stable `asset_id` allocated by the packer registry;
|
||||
- stable cross-build identity comes from `asset_id`, not from table position;
|
||||
- rename of `asset_name` is therefore an API-visible/content-visible change, but not an identity change.
|
||||
|
||||
Also adopt this companion-artifact direction:
|
||||
|
||||
- `build/asset_table.json` should mirror the runtime-facing header data 1:1 for debugging and inspection;
|
||||
- if richer tooling artifacts are needed, they should be emitted as separate files instead of overloading `build/asset_table.json`.
|
||||
|
||||
## Expected Decisions to Produce
|
||||
|
||||
@@ -106,6 +159,11 @@ Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM
|
||||
4. Materialization requirements for inferred values.
|
||||
5. Runtime-facing artifact contract and reader expectations.
|
||||
6. Packer-side restatement of the runtime-owned `assets.pa` envelope and slice semantics.
|
||||
7. Deterministic mapping from asset declarations to runtime preload data.
|
||||
8. Explicit exclusion of usage-based packing heuristics from the baseline contract.
|
||||
9. Migration of preload/bootstrap integrity toward `asset_id`-based identity while preserving `asset_name` as current API-facing metadata.
|
||||
10. Deterministically ordered `asset_table` preserving packer `asset_id` values end-to-end.
|
||||
11. Separation between runtime-validated envelope fields and non-envelope tooling concerns.
|
||||
|
||||
## Expected Spec Follow-up
|
||||
|
||||
|
||||
Reference in New Issue
Block a user