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