96 lines
2.9 KiB
Markdown
96 lines
2.9 KiB
Markdown
# 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.
|