5.6 KiB
id, ticket, title, created, tags
| id | ticket | title | created | tags | ||||
|---|---|---|---|---|---|---|---|---|
| LSN-0102 | sample-project-sdk-refresh | Refreshing Samples Without Changing Their Identity | 2026-11-05 |
|
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 retains RGB565 palette arithmetic while constructing current Color values explicitly:
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 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 and fragments launcher 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 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 and fragments guide.
- First playable Pong.
- External local smoke source and guide:
../ai-first-smoke/src/main.pbsand../ai-first-smoke/ACCEPTANCE.md, relative to the Studio checkout.