Files
prometeu-studio/discussion/lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md
bquarkz 38f201a9c9
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
lesson added
2026-11-06 02:35:19 +00:00

5.6 KiB
Raw Permalink Blame History

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
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 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.pbs and ../ai-first-smoke/ACCEPTANCE.md, relative to the Studio checkout.