113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
---
|
||
id: LSN-0102
|
||
ticket: sample-project-sdk-refresh
|
||
title: Refreshing Samples Without Changing Their Identity
|
||
created: 2026-11-05
|
||
tags: [studio, pbs, samples, packer]
|
||
---
|
||
|
||
## Context and result
|
||
|
||
Owner: **studio/project PBS**, with existing compiler/SDK and Packer contracts as
|
||
dependencies. DSC-0102 / DEC-0086 / PLN-0164 refreshed `test-projects/main`,
|
||
`test-projects/fragments` and the sibling `../ai-first-smoke`. Pong gameplay was
|
||
preserved. Studio changes are in commit `b2410e6e`; the sibling is outside this
|
||
Git repository and its changes remain local.
|
||
|
||
The maintenance preserved application and asset identities, image/palette data,
|
||
sample geometry, user configuration and archived cartridge binaries. No SDK or
|
||
runtime source changed. The durable lesson is to repair API and lifecycle usage
|
||
while retaining each demonstration's original behavior.
|
||
|
||
## Translate the old representation explicitly
|
||
|
||
The smoke sample now imports Pad/Button and uses `Pad.down(Button.Left)` and the
|
||
other held directions. It combines direction changes before clamping, so opposite
|
||
directions cancel even at an edge. It retains the 16×16 blue square at (232,127),
|
||
normal speed one, B-held speed three, bounds x=0..464/y=0..254 and its label.
|
||
Its obsolete runtime path was replaced with the valid installation already
|
||
selected for the test projects. Native connector guidance replaces token copying.
|
||
|
||
The [fragments sample](../../../test-projects/fragments/src/main.pbs) retains
|
||
RGB565 palette arithmetic while constructing current Color values explicitly:
|
||
|
||
```text
|
||
r5 = (value / 2048) % 32
|
||
g6 = (value / 32) % 64
|
||
b5 = value % 32
|
||
Color.rgb(r5 * 255 / 31, g6 * 255 / 63, b5 * 255 / 31)
|
||
```
|
||
|
||
The helper uses long channel arithmetic required by the current API. Geometry
|
||
remains a 320×180 logical field with eight-pixel cells; changing the color carrier
|
||
does not require changing the effect or its coordinate system.
|
||
|
||
## Use the assets and lifecycle the project already owns
|
||
|
||
The [main sample](../../../test-projects/main/src/main.pbs) uses its existing
|
||
preloads: asset 15 in glyph slot 0, asset 17 in glyph slot 1 and asset 18 in scene
|
||
slot 0. It binds the preloaded scene during Frame, checks status and retries on a
|
||
later frame if binding fails. Init resets state. Touch-driven sprite frames,
|
||
camera motion and input examples remain.
|
||
|
||
Only the missing atlas and empty sound registration were excluded from build.
|
||
Their registrations and IDs remain intact. Removing identities or inventing new
|
||
assets would have turned a compatibility repair into a content migration.
|
||
|
||
The [main launcher](../../../test-projects/main/run.sh) and
|
||
[fragments launcher](../../../test-projects/fragments/run.sh) resolve their own
|
||
project directory, require the complete current build and select the configured
|
||
runtime. An explicit environment override is honored; the existing symlink is an
|
||
unset-setting fallback. A configured invalid runtime fails clearly. Launching the
|
||
current build avoids copying only some files into an obsolete cartridge directory.
|
||
Cache ignore rules were added; previously tracked caches were preserved.
|
||
|
||
## Reconcile the latest evidence before housekeeping
|
||
|
||
The commit recorded successful shell syntax, JSON, asset identity/image
|
||
preservation and whitespace checks, and accurately reported build/pack verification
|
||
as pending at that time. Later review found complete output sets newer than the
|
||
changed sources for all four projects on 2026-11-05:
|
||
|
||
| Project | Program emitted (UTC) | Program bytes | App ID |
|
||
| --- | --- | ---: | ---: |
|
||
| ai-first-smoke | 17:12:14 | 11,523 | 691820361 |
|
||
| fragments | 17:12:32 | 15,954 | 477476525 |
|
||
| main | 17:12:40 | 14,000 | 377753220 |
|
||
| Pong | 17:12:51 | 31,912 | 1508740446 |
|
||
|
||
Every set contains `program.pbx`, `assets.pa` and `manifest.json`. Main's manifest
|
||
contains exactly its active assets/preloads 15, 17 and 18. The
|
||
[artifact observation](evidence/build-artifacts.json) retains timestamps and hashes
|
||
of saved sources and emitted files without committing generated cartridges.
|
||
|
||
The user identified the deliveries as already executed and concluded. Housekeeping
|
||
therefore reconciles the stale plans with completed implementation, current build
|
||
outputs and that feedback. These observations do not establish who invoked each
|
||
build or supply a clean language-query transcript. The user's explicit live-game
|
||
report covers Pong; smoke controls and sample preservation were reviewed in source.
|
||
No per-sample runtime trace, native MCP session or exhaustive UI qualification is
|
||
claimed. Retaining these limits keeps closure evidence useful for future work.
|
||
|
||
## Pitfalls
|
||
|
||
- Passing packed RGB565 integers into a current RGBA API without conversion.
|
||
- Binding a preloaded scene at the wrong lifecycle phase.
|
||
- Loading an atlas that is absent while the required banks are already preloaded.
|
||
- Deleting asset identities to suppress diagnostics instead of correcting build
|
||
inclusion for unavailable content.
|
||
- Launching old bytecode beside new metadata, or silently ignoring an invalid
|
||
configured runtime in favor of another installation.
|
||
- Treating a sibling directory as part of the current commit.
|
||
- Keeping a plan open solely because its earlier pending-build note was never
|
||
reconciled with newer outputs and user feedback.
|
||
|
||
## References
|
||
|
||
- Retired maintenance artifacts: DSC-0102, DEC-0086 and PLN-0164.
|
||
- [Main guide](../../../test-projects/main/README.md) and
|
||
[fragments guide](../../../test-projects/fragments/README.md).
|
||
- [First playable Pong](../DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md).
|
||
- External local smoke source and guide: `../ai-first-smoke/src/main.pbs` and
|
||
`../ai-first-smoke/ACCEPTANCE.md`, relative to the Studio checkout.
|