updated packer agendas
This commit is contained in:
+115
@@ -0,0 +1,115 @@
|
||||
# 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.
|
||||
@@ -10,6 +10,7 @@ Closed agendas are moved to `docs/pbs/agendas/archive`.
|
||||
2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md`
|
||||
3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
|
||||
4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
5. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
Reference in New Issue
Block a user