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

113 lines
5.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.