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