prometeu-studio/docs/packer/learn/mental-model-packer.md

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”.