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.

2.9 KiB Raw Blame History