updated packer specs
This commit is contained in:
@@ -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.
|
||||
@@ -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”.
|
||||
Reference in New Issue
Block a user