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