lesson added
This commit is contained in:
+84
@@ -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.
|
||||||
+112
@@ -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.
|
||||||
@@ -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": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user