116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# Asset References in Game Code - Names vs Compile-Time Lowering Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## Purpose
|
|
|
|
Define how game code should reference assets over time:
|
|
|
|
- by logical `asset_name`,
|
|
- by compile-time lowering to stable `asset_id`,
|
|
- or through a more structured resource model inspired by engines that expose named resources while compiling them to stable internal handles.
|
|
|
|
## Domain Owner
|
|
|
|
`docs/compiler/pbs`
|
|
|
|
This is primarily a language/frontend and game-facing API question.
|
|
It depends on packer and runtime contracts, but it should be owned here because it affects source authoring, compile-time semantics, and generated runtime calls.
|
|
|
|
## Context
|
|
|
|
The current runtime still exposes game-facing asset operations by name.
|
|
|
|
Examples in `../runtime` today:
|
|
|
|
- graphics/runtime calls receive `asset_name`;
|
|
- audio/runtime calls receive `asset_name`;
|
|
- the runtime internally maps `asset_name -> asset_id` for normal asset use;
|
|
- preload/bootstrap was recently tightened around stable `asset_id`.
|
|
|
|
At the same time, the packer model already distinguishes:
|
|
|
|
- `asset_id` as stable artifact identity;
|
|
- `asset_name` as logical code-facing reference label.
|
|
|
|
This leaves an open architectural question:
|
|
|
|
Should game code continue to use strings/names directly forever, or should the compiler eventually lower asset references to more stable runtime-facing identifiers?
|
|
|
|
## Upstream Inputs
|
|
|
|
From packer decisions:
|
|
|
|
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../../../packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
|
|
- [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../../../packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md)
|
|
|
|
From runtime:
|
|
|
|
- `preload` now resolves by `asset_id`;
|
|
- asset APIs used by game/runtime code still resolve by `asset_name`;
|
|
- `asset_table` carries both `asset_id` and `asset_name`.
|
|
|
|
## Core Questions
|
|
|
|
1. Should source code asset references remain name-based in the long term?
|
|
2. Should the compiler resolve known asset references at compile time and lower them to `asset_id`?
|
|
3. If compile-time lowering exists, what happens for dynamic/late-bound asset names?
|
|
4. Should PBS expose a first-class resource handle abstraction instead of raw string references?
|
|
5. What compatibility and tooling story do we want for rename of `asset_name`?
|
|
6. How much runtime lookup by name is acceptable once asset identity is already stable in packer/runtime artifacts?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Keep source and runtime calls name-based.
|
|
|
|
### Option B
|
|
|
|
Keep source authoring name-based, but lower resolvable references to `asset_id` at compile time.
|
|
|
|
### Option C
|
|
|
|
Introduce a richer resource abstraction in the language/toolchain, with compile-time or build-time resolution to stable handles under the hood.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A is simple and close to the current runtime, but keeps rename fragility and runtime lookup cost.
|
|
- Option B preserves authoring ergonomics while improving runtime determinism for static references.
|
|
- Option C could be the strongest long-term model, but it is also the most invasive and requires coordinated language, compiler, packer, and runtime work.
|
|
|
|
## Recommendation
|
|
|
|
Do not change the language surface blindly.
|
|
|
|
Recommended sequence:
|
|
|
|
1. preserve `asset_name` as the current source-level reference model;
|
|
2. evaluate compile-time lowering for statically known references as a separate capability;
|
|
3. only introduce a richer resource abstraction if the language ergonomics and tooling story justify the additional complexity.
|
|
|
|
This keeps current code understandable while leaving room to remove fragile runtime string lookup from hot paths later.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Source-level asset reference model for PBS.
|
|
2. Whether compile-time lowering to `asset_id` should exist.
|
|
3. Boundaries between static references and dynamic references.
|
|
4. Rename/refactor expectations in Studio and compiler diagnostics.
|
|
5. Relationship between source references, packer outputs, and runtime lookup.
|
|
|
|
## Expected Spec Material
|
|
|
|
- PBS asset reference model spec or section.
|
|
- Compiler lowering rules for asset references.
|
|
- Diagnostics/refactoring behavior for asset rename.
|
|
- Cross-reference to packer/runtime asset identity contracts.
|
|
|
|
## Non-Goals
|
|
|
|
- Defining every asset-related syscall in detail.
|
|
- Redesigning the entire runtime asset manager.
|
|
- Solving preload layout or `assets.pa` packing rules here.
|