120 lines
3.4 KiB
Markdown
120 lines
3.4 KiB
Markdown
# Mental Model: Assets Workspace
|
|
|
|
## Why This Workspace Exists
|
|
|
|
The `Assets` workspace is not a nicer file browser.
|
|
|
|
It exists to make the packer model understandable and usable from the Studio.
|
|
|
|
That means the workspace must help a contributor answer questions like:
|
|
|
|
- What is the managed asset here?
|
|
- Where does it live?
|
|
- Which files belong to it?
|
|
- What does it produce toward the runtime?
|
|
- Is it managed, orphaned, preload-marked, or diagnostically unhealthy?
|
|
|
|
If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model.
|
|
|
|
## The Core Shift
|
|
|
|
The key shift is:
|
|
|
|
- not `file-first`
|
|
- but `asset-first`
|
|
|
|
An asset may contain many files.
|
|
|
|
Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity.
|
|
|
|
So the workspace is designed to feel like:
|
|
|
|
- a structured asset navigator,
|
|
- plus a didactic explanation surface for the currently selected asset.
|
|
|
|
## Why It Is Still Path-Aware
|
|
|
|
`Asset-first` does not mean `filesystem-blind`.
|
|
|
|
People still organize projects by directories.
|
|
|
|
They still need to know:
|
|
|
|
- where the asset root lives;
|
|
- which broader folder group it belongs to;
|
|
- how to reason about the project layout.
|
|
|
|
That is why the workspace remains `path-aware`.
|
|
|
|
The important nuance is:
|
|
|
|
- path is supporting context
|
|
- asset identity is primary
|
|
|
|
## What The Left Side Teaches
|
|
|
|
The left-side navigator is a custom `Asset Tree` / `Asset Navigator`.
|
|
|
|
It teaches the model visually:
|
|
|
|
- groups may reflect location or parent folders,
|
|
- asset nodes are the real unit of navigation,
|
|
- icons and badges tell the story quickly,
|
|
- orphan and managed assets can coexist without becoming ambiguous.
|
|
|
|
This is better than a raw file tree because the user learns the packer model by looking at the navigation itself.
|
|
|
|
## What The Main Area Teaches
|
|
|
|
The selected asset view is intentionally structured in a fixed order:
|
|
|
|
1. `Summary`
|
|
2. `Runtime Contract`
|
|
3. `Inputs / Preview`
|
|
4. `Diagnostics`
|
|
5. `Actions`
|
|
|
|
That order matters.
|
|
|
|
It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do.
|
|
|
|
That is a teaching sequence, not just a layout sequence.
|
|
|
|
## Why Preview Matters
|
|
|
|
Preview is not decorative.
|
|
|
|
Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project.
|
|
|
|
Examples:
|
|
|
|
- an image bank should let the user inspect images and palettes;
|
|
- an audio asset should let the user inspect sound inputs;
|
|
- text-like artifacts should be inspectable as text when that helps understanding.
|
|
|
|
This makes the workspace feel grounded in real project materials while still preserving an asset-first model.
|
|
|
|
## What To Avoid
|
|
|
|
Common mistakes:
|
|
|
|
- turning the workspace into a raw filesystem explorer with extra badges;
|
|
- making path the true identity instead of the asset;
|
|
- showing only diagnostics and forgetting the actual asset model;
|
|
- treating orphan as if it meant broken;
|
|
- hiding runtime-facing information behind technical dumps.
|
|
|
|
## Practical Read Order
|
|
|
|
Read these together:
|
|
|
|
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
|
2. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
|
3. [`../../packer/learn/mental-model-packer.md`](../../packer/learn/mental-model-packer.md)
|
|
|
|
That path explains:
|
|
|
|
- what the packer believes,
|
|
- how the Studio presents it,
|
|
- and how the user should reason about asset operations.
|