updated packer specs

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent f27b28c516
commit e3389e78b6
10 changed files with 951 additions and 0 deletions
+7
View File
@@ -45,3 +45,10 @@ If content grows, prefer:
- and consolidation of duplicated explanations.
The goal is a maintainable learning surface, not a passive archive.
## Current Learning Path
Start here:
1. [`mental-model-packer.md`](./mental-model-packer.md)
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
@@ -0,0 +1,95 @@
# Asset Identity and Runtime Contract
This document explains the point that is easiest to get subtly wrong:
- `asset_id` is the stable artifact identity;
- `asset_name` is still a logical code-facing reference.
If you flatten those two concepts into one, the architecture starts drifting immediately.
## The Stable Side: `asset_id`
`asset_id` is allocated by the packer registry.
It is stable within the project and appears in runtime-facing artifacts.
Why this matters:
- preload uses `asset_id`;
- artifact identity survives move and rename;
- build outputs remain structurally stable even when authoring layout changes.
`asset_id` is the answer to:
> “Is this the same asset as before?”
## The Logical Side: `asset_name`
`asset_name` remains useful because game-facing code and runtime APIs still refer to assets by name in normal flows.
Why this matters:
- authors need a readable label;
- game code usually references assets semantically, not by integer literal;
- runtime lookup still uses names in parts of the current operational surface.
`asset_name` is the answer to:
> “What do humans and source code call this asset?”
## Why Not Use Only One Of Them?
If you use only `asset_name`:
- rename becomes identity breakage;
- preload/bootstrap integrity becomes fragile;
- build artifacts depend too much on mutable author intent.
If you use only `asset_id` everywhere today:
- source code becomes less ergonomic;
- authoring workflows become harder to read;
- the current runtime/game-facing API model would need stronger compile-time lowering infrastructure.
So the current architecture intentionally keeps both:
- stable identity for artifacts;
- logical naming for authoring and API usage.
## What Actually Happens In The Artifact?
The runtime-facing asset table carries both:
- `asset_id`
- `asset_name`
But they play different roles.
`asset_id`:
- defines stable identity;
- is used for preload/bootstrap integrity.
`asset_name`:
- stays in the table as descriptive/API-facing metadata;
- supports name-based lookup where that still exists.
## Why This Is Still Not The End Of The Story
There is still an open language/toolchain question:
- should source-level asset references remain name-based forever?
- or should the compiler eventually lower known references to stable IDs or resource handles?
That is a separate problem from the packer artifact identity model.
It belongs to language/frontend and runtime API design, not to the core packer identity rules.
## Practical Rule
When reading or implementing packer behavior, use this checklist:
- if the question is about stable artifact identity, think `asset_id`;
- if the question is about source naming or human-facing lookup, think `asset_name`;
- if the question is about preload/bootstrap correctness, prefer `asset_id`;
- if the question is about runtime/game API ergonomics, `asset_name` may still be intentionally present.
+87
View File
@@ -0,0 +1,87 @@
# Packer Mental Model
The packer is not a cartridge shipper, not a runtime reader, and not a random file janitor.
It is the system that turns an asset workspace into stable asset artifacts.
The easiest way to understand it is through five questions.
## 1. What is the unit of management?
The unit is the managed asset root.
One managed asset:
- lives in one asset root directory;
- has one anchor `asset.json`;
- may include many internal files as inputs.
This is why an atlas, image bank, or grouped sound bundle can still be one asset.
The managed asset is the output unit, not each source file.
## 2. Where is the source of truth?
There are two different truths for two different jobs:
- `assets/.prometeu/index.json` tells the packer which assets are officially managed;
- each `asset.json` tells the packer what that asset declares locally.
This split matters.
Without it, copy/move/adopt flows become ambiguous very quickly.
## 3. What is the difference between `asset_id` and `asset_name`?
They are not the same thing.
`asset_id` is the stable identity.
It survives moves and renames.
`asset_name` is the logical reference label.
It is the thing source code and runtime-facing APIs may still use today.
That means:
- renaming `asset_name` is not an identity change;
- but it can still be an API-visible change.
This is the most important distinction to keep in your head while reading the packer and runtime contracts.
## 4. What is the runtime-facing artifact?
`assets.pa`.
That is the artifact the runtime reads.
It is authoritative for runtime-facing asset metadata.
Companion JSON files exist for Studio and tooling, but they do not replace the contract inside `assets.pa`.
## 5. Why is determinism so important?
Because the packer is not just a converter.
It is part of the contract chain between authoring, Studio, shipping, and runtime.
If equivalent inputs can produce different outputs accidentally, then:
- debugging becomes harder;
- caching becomes unreliable;
- artifact review gets noisy;
- runtime compatibility becomes more fragile.
That is why the packer decisions keep preferring:
- explicit declaration over inference;
- stable identity over convenience;
- canonical serialization over incidental serializer behavior;
- preview/apply over silent mutation.
## How To Read The Packer Specs
Use this order:
1. domain and boundary
2. workspace and identity
3. asset declaration
4. build artifacts
5. diagnostics and Studio integration
6. versioning and trust
That sequence moves from “what the packer is” to “how it behaves” to “how it stays safe over time”.