88 lines
2.6 KiB
Markdown
88 lines
2.6 KiB
Markdown
# 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/register 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”.
|