diff --git a/discussion/lessons/DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md b/discussion/lessons/DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md new file mode 100644 index 00000000..10fe319c --- /dev/null +++ b/discussion/lessons/DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md @@ -0,0 +1,84 @@ +--- +id: LSN-0101 +ticket: pong-playable-test-project +title: Pong as the First Playable Studio Game +created: 2026-11-05 +tags: [studio, pbs, game, pong] +--- + +## Context and result + +Owner: **studio/project PBS**. DSC-0101 / DEC-0085 / PLN-0163 delivered +[Pong](../../../test-projects/pong/README.md) in a project created by the user +through Studio. It is a bounded first game originating from the broader AGD-0088 +discussion. After this delivery, the user explicitly abandoned AGD-0088 / DSC-0086 +on 2026-11-05. Its unfinished qualification matrix is no longer active work; +additional games or renewed qualification require a separate request and discussion. + +The implementation is in Studio commit `b2410e6e`. It preserves app ID 1508740446 +and supplies one player against a slower deterministic CPU, first to five points, +with menu, serve, play, pause and result states. Existing Color/Gfx and Pad/Button +APIs provide rendering and input. It needs no authored art, audio, persistence, +engine change or runtime repository write. + +## Keep the first game small and inspectable + +The [saved source](../../../test-projects/pong/src/main.pbs) separates input, +state transitions, simulation and drawing. The 480×270 display has an explicit +court boundary. The player moves four pixels per tick; the CPU moves two and +tracks the ball only after it enters the CPU's half. + +Ball positions use integer quarter pixels. Four bounded substeps advance one game +tick; the maximum horizontal movement per substep is 1.75 pixels, below the +eight-pixel paddle width. Collision checks require an incoming ball, restore its +position outside the paddle and choose a bounded outgoing angle from the impact +offset. A goal returns immediately after scoring, preventing a second score in +the same tick. + +One state branch executes per frame. Held Up/Down move the paddle; pressed +A/Start/B drive transitions. Pausing returns before physics. Resume restores the +prior phase. A new match clears both scores and resets positions; reaching five +enters the result state. These properties can be reviewed directly without an +additional game framework. + +## Execution evidence and its limits + +Studio saved-source diagnostics returned no diagnostics and a Studio build +succeeded during implementation. That access used an adapter script, which the +user rejected as an adequate test of native Studio tooling. A working transport +does not establish native tool registration or complete Studio authoring coverage. +The acquired agent task was released; the agent started no headless game process. + +The user's first Play attempt reported a missing runtime setting. After updating +Studio, the user reported Pong running successfully. No runtime code fix was +needed. Housekeeping also observed a complete newer build at 17:12:51 UTC on +2026-11-05. Its hashes are retained in the shared +[build observation](../DSC-0102-sample-project-sdk-refresh/evidence/build-artifacts.json). + +The user subsequently identified these deliveries as already executed and +concluded. This closes the first-game delivery. Pause, scoring and reset were +reviewed in source; no individual live input replay, full-match trace, captured +frame or native MCP authoring qualification is claimed. The user's subsequent +abandonment of the parent discussion preserves these evidence limits and the +completed Pong delivery without carrying forward the unfinished qualification +as active work. + +## Pitfalls + +- Treating all platform capabilities as prerequisites for the first small game. +- Conflating a successful Studio build, a user Play report and a scripted runtime + trace. Each establishes a different part of the result. +- Replacing unavailable native tools with a custom transport and describing that + route as native connector validation. +- Reading an old draft handoff as the final state after the user has built and + played the project. Reconcile saved artifacts and later feedback before cleanup. +- Restarting a rally when resuming or applying one input edge to multiple states. + +## References + +- Retired delivery artifacts: DSC-0101, DEC-0085 and PLN-0163. +- [Controls and Studio workflow](../../../test-projects/pong/README.md). +- [Source exports](../../../test-projects/pong/src/mod.barrel). +- [Sample compatibility refresh](../DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md). +- [Sprite animation and shared authoring](../DSC-0098-pbs-core-sprite-animation/LSN-0100-sprite-animation-and-shared-authoring.md) + is a separate capability; this primitive-rendered game does not qualify it. diff --git a/discussion/lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md b/discussion/lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md new file mode 100644 index 00000000..3e850dc7 --- /dev/null +++ b/discussion/lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md @@ -0,0 +1,112 @@ +--- +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. diff --git a/discussion/lessons/DSC-0102-sample-project-sdk-refresh/evidence/build-artifacts.json b/discussion/lessons/DSC-0102-sample-project-sdk-refresh/evidence/build-artifacts.json new file mode 100644 index 00000000..6c198a38 --- /dev/null +++ b/discussion/lessons/DSC-0102-sample-project-sdk-refresh/evidence/build-artifacts.json @@ -0,0 +1,199 @@ +{ + "observed_utc": "2026-11-05T17:36:00+00:00", + "owner": "studio/project PBS", + "discussions": [ + "DSC-0101", + "DSC-0102" + ], + "studio_implementation_commit": "b2410e6edcd66d6ca66b1fc845244e1f38595247", + "observation_method": "Read existing saved files and emitted build artifacts during housekeeping; no build or game process was launched by this observation.", + "evidence_limits": [ + "Artifacts establish emitted compile/pack output, not a clean diagnostics transcript or a complete runtime behavioral trace.", + "No native MCP operation log or headless input replay is supplied for the observed builds.", + "The user reported Pong running after updating Studio; per-control runtime scenarios are not individually recorded.", + "The sibling ai-first-smoke is outside the Studio Git repository; its local edits are not included in the Studio commit." + ], + "projects": [ + { + "root_relative_to_studio": "../ai-first-smoke", + "app_id": 691820361, + "sources": [ + { + "path": "../ai-first-smoke/src/main.pbs", + "bytes": 1110, + "modified_utc": "2026-11-05T16:35:33+00:00", + "sha256": "97455d44b39084e56f05eaf760389f0ab8e28e944fed049b0204f018025d43c9" + }, + { + "path": "../ai-first-smoke/src/mod.barrel", + "bytes": 47, + "modified_utc": "2026-09-29T11:14:06+00:00", + "sha256": "6acc9d676668c7fa935ef33e5d8487ac70d664154dc5851a46737c8b29f62129" + } + ], + "artifacts": [ + { + "path": "../ai-first-smoke/build/program.pbx", + "bytes": 11523, + "modified_utc": "2026-11-05T17:12:14+00:00", + "sha256": "dde90da091ad14badd97082ece694dd596d39219849f9fdc43c9a06469532832" + }, + { + "path": "../ai-first-smoke/build/assets.pa", + "bytes": 63, + "modified_utc": "2026-11-05T17:12:14+00:00", + "sha256": "dc609689d0e1a6ea46b27133bab5851e9f9a8b5f0cb6503bf3503c9afb48a276" + }, + { + "path": "../ai-first-smoke/build/manifest.json", + "bytes": 227, + "modified_utc": "2026-11-05T17:12:14+00:00", + "sha256": "28744a0734a0f7e701d79e91b7e8117c4c38bf2b926a99f78f66ca918965fdd3" + } + ], + "all_outputs_newer_than_saved_sources": true, + "packed_asset_ids": [], + "preloads": [] + }, + { + "root_relative_to_studio": "test-projects/fragments", + "app_id": 477476525, + "sources": [ + { + "path": "test-projects/fragments/src/main.pbs", + "bytes": 4868, + "modified_utc": "2026-11-05T16:25:53+00:00", + "sha256": "418a2edade2170d9e903ea1c1ca60d870419659560c5b2644290e4f8245befe8" + }, + { + "path": "test-projects/fragments/src/mod.barrel", + "bytes": 23, + "modified_utc": "2026-04-10T05:09:46+00:00", + "sha256": "013d9824a525aa8f78d878c16a71c8f461abc867fdcb2700f6b1684d5dce5977" + } + ], + "artifacts": [ + { + "path": "test-projects/fragments/build/program.pbx", + "bytes": 15954, + "modified_utc": "2026-11-05T17:12:32+00:00", + "sha256": "09e0f4059861b2951579b18c15b32016a13b87aa45aeca5a121e5f5211ff223a" + }, + { + "path": "test-projects/fragments/build/assets.pa", + "bytes": 63, + "modified_utc": "2026-11-05T17:12:33+00:00", + "sha256": "dc609689d0e1a6ea46b27133bab5851e9f9a8b5f0cb6503bf3503c9afb48a276" + }, + { + "path": "test-projects/fragments/build/manifest.json", + "bytes": 222, + "modified_utc": "2026-11-05T17:12:33+00:00", + "sha256": "90b2d02f3cf4f7cdda4216ec1264d93595ff3a5b57bb3f51042378f14ccad10b" + } + ], + "all_outputs_newer_than_saved_sources": true, + "packed_asset_ids": [], + "preloads": [] + }, + { + "root_relative_to_studio": "test-projects/main", + "app_id": 377753220, + "sources": [ + { + "path": "test-projects/main/src/main.pbs", + "bytes": 2193, + "modified_utc": "2026-11-05T16:25:53+00:00", + "sha256": "20219dd7b340bbb3d750d684e108cefa75e65a4c10f171fb7b42fedf98b71d9f" + }, + { + "path": "test-projects/main/src/mod.barrel", + "bytes": 23, + "modified_utc": "2026-04-10T05:09:46+00:00", + "sha256": "013d9824a525aa8f78d878c16a71c8f461abc867fdcb2700f6b1684d5dce5977" + } + ], + "artifacts": [ + { + "path": "test-projects/main/build/program.pbx", + "bytes": 14000, + "modified_utc": "2026-11-05T17:12:40+00:00", + "sha256": "dec3519f6699895e8bf511c73841272e9164b0b34f420ef871ae53f02241fa59" + }, + { + "path": "test-projects/main/build/assets.pa", + "bytes": 108383, + "modified_utc": "2026-11-05T17:12:40+00:00", + "sha256": "6b9788cf67350691e8e35c40f8dc40975f7acda5467b99fd6177c318cdaeed5f" + }, + { + "path": "test-projects/main/build/manifest.json", + "bytes": 1319, + "modified_utc": "2026-11-05T17:12:40+00:00", + "sha256": "36c2761bf293cdd318189bdfb991cc837807bb3fdf5b43bcba5d915a788b3fe7" + } + ], + "all_outputs_newer_than_saved_sources": true, + "packed_asset_ids": [ + 15, + 17, + 18 + ], + "preloads": [ + { + "asset_id": 15, + "slot": 0 + }, + { + "asset_id": 17, + "slot": 1 + }, + { + "asset_id": 18, + "slot": 0 + } + ] + }, + { + "root_relative_to_studio": "test-projects/pong", + "app_id": 1508740446, + "sources": [ + { + "path": "test-projects/pong/src/main.pbs", + "bytes": 9008, + "modified_utc": "2026-11-05T16:05:30+00:00", + "sha256": "4552610167814b961596e3720d2f1fef11f4e1635324331df2ed3bc26db0620a" + }, + { + "path": "test-projects/pong/src/mod.barrel", + "bytes": 47, + "modified_utc": "2026-11-05T16:05:30+00:00", + "sha256": "6acc9d676668c7fa935ef33e5d8487ac70d664154dc5851a46737c8b29f62129" + } + ], + "artifacts": [ + { + "path": "test-projects/pong/build/program.pbx", + "bytes": 31912, + "modified_utc": "2026-11-05T17:12:51+00:00", + "sha256": "302f9d82420fcb9f2f535b6344ee1f6d1f5e5de6a23666a64fb697c1a0117914" + }, + { + "path": "test-projects/pong/build/assets.pa", + "bytes": 63, + "modified_utc": "2026-11-05T17:12:51+00:00", + "sha256": "dc609689d0e1a6ea46b27133bab5851e9f9a8b5f0cb6503bf3503c9afb48a276" + }, + { + "path": "test-projects/pong/build/manifest.json", + "bytes": 218, + "modified_utc": "2026-11-05T17:12:51+00:00", + "sha256": "da1c35e4861d8f9fdb2b9a66a8170c83e4bb103c0f4b8359727f17d6dc0fe2d0" + } + ], + "all_outputs_newer_than_saved_sources": true, + "packed_asset_ids": [], + "preloads": [] + } + ] +}