prometeu-studio/docs/compiler/pbs/agendas/18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md

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