feat(3d): ship threed_basic v1 milestone - #57
Open
wh000wh000 wants to merge 39 commits into
Open
Conversation
added 30 commits
August 6, 2026 17:13
Add the frozen classifier/GDD contract for a minimal three.js archetype while preserving every existing Phaser route. Includes regression fixtures for explicit 3D, 2D platformer, and 2D top-down prompts.
Provide the core3d skeleton, threed_basic gameplay layer, pinned npm lockfile, and builder-facing manuals. The template keeps DOM lifecycle screens and the three-key ESC fallback while limiting assets to the existing image pipeline.
Keep the player on authored floor patches and outside explicit static obstacle circles without introducing a physics dependency. Substepped resolution prevents high-delta tunnelling and the self-check covers road, obstacle, and slide behavior.
Teach the builder to preserve the pure XZ resolver, explicit collision radii, and v1 no-physics boundary so generated games consume the new capability instead of bypassing it.
The three.js renderer sizes from its container and never consumes the inherited 2D reference dimensions. Removing the unused leaves gives both standalone core3d and threed_basic a zero-dead-config baseline.
Generated v1.1 code duplicated fog, pickup, and count values. Make the builder keep one canonical path per runtime value, remove superseded aliases, and record the leaf-to-consumer map in GDD completion notes.
The universal GDD reminder contradicted threed_basic zero-dead-config rules by forbidding deletion of inherited fields. Keep the Phaser reminder unchanged while requiring consumed, single-source leaves for 3D.
A generated v1.3 game shipped teleport and time mutation hooks solely to make verification easy. Freeze the existing probe surface and require completion evidence through real browser input so acceptance measures gameplay instead of a debug backdoor.
A real v1.4 game showed repeated Escape events can toggle pause multiple times and end screens can resume gameplay. Ignore keyboard repeats and lock the runtime after completion or failure.
Real-browser review found the core3d shell requests an undeclared favicon. Ship a tiny standalone SVG and reference it relatively, keeping binary data out of editable HTML.
The star-lamp maze GDD weakened an explicit sequential objective into unordered collection to match the scaffold. Add a threed_basic-only fidelity rule so private GameScene state may implement the requested mechanic without widening the public API or changing Phaser prompts.
Document that ordered objectives remain ordered and should use minimal private GameScene state instead of being reinterpreted as the scaffold's unordered pickup loop.
Prevent generated acceptance criteria from strengthening declared win conditions or relying on instrumented artifacts, so production evidence reflects the shipped game.
Keep real media out of generated source and session context, and require complete playthrough evidence from the final uninstrumented artifact.
Prevent generation sessions from reading screenshots as Base64; automated checks use smoke and visible DOM while human review opens the reported file path.
Align W movement with the three.js camera forward vector and make in-page restart dispose input listeners plus scene-owned GPU resources. The source-level self-check locks both contracts without adding runtime test hooks.
Phase 6 changes must correct stale values and consumers in the GDD body instead of leaving contradictory appendices. Document the restart resource-ownership contract exposed by the template fix.
The core shell still used the opposite Z sign for the camera-right vector. Lock both components in the runtime contract self-check so yawed movement cannot regress independently.
v1.9 production still named runtime state and texture behavior that did not exist. Require unstable implementation details to be copied from the final consumer or removed, so the GDD cannot invent a plausible second truth.
Some providers ignore the requested image size and returned 1254x1254 files for a 1024x1024 contract. Normalize backgrounds, sprites, and animation frames immediately before writing so asset-pack paths always point at the requested canvas without exposing inline media.
Generated games replaced correct camera movement and disposal despite the scaffold already providing both. Make those shell sections immutable in v1 and keep media references path-only, with the existing runtime self-check pinning the manual contract.
Generated completion notes blamed a dispose defect on a frozen template whose protected block was already correct. Require path, SHA-256, and diff evidence so production feedback cannot promote a self-authored transient edit into a pipeline defect.
Generated GDDs can claim reconciliation while retaining stale tuning aliases or spawn yaw values. Require direct final source/config and SceneMap comparison before completion.
The pre-commit formatter changed an unrelated table while committing the source-truth rule. Restore the untouched lines so the final review diff stays scoped.
Generated GDDs retained stale renderConfig instructions and claimed a camera-far consumer that did not exist. Require final values and a named runtime leaf so production reviews can reject those false claims.
Mathematical overlap let generated routes pass while leaving player-radius corridors and finish triggers on collision boundaries. Define measurable clearance and target-center rules, and pin final config descriptions to their real consumers.
The 3D GDD producer hard-coded a single-route collectible plan, so generated games could only reskin movement and pickup. Require verbs, pressure, feedback, escalation, win/lose states, and runtime consumers while leaving Phaser guidance untouched.
The module manual defined threed_basic as collect-everything on one route, which prevented the builder from planning distinct play. Define the minimal core-loop contract and allow only semantic SceneMap arrays and path-referenced image keys with real consumers.
A mandatory lose state would contradict peaceful game requests. Keep the gameplay contract strict while allowing an explicitly declared no-fail tension and progression response.
Repeated generated games mislabeled camera far as config-backed and proved only one side of a claimed route choice. Put those checks in the shared GDD producer so later games must ground camera ownership and branch coverage in final code.
added 9 commits
August 6, 2026 17:13
The first non-collection game claimed a committed fast/safe choice while only exercising one route. Require intended and forbidden adjacency checks plus final play coverage for every branch.
A prose-only core loop can combine individually plausible timings and resource values into an unwinnable game. Require winning and losing traces with derived deadlines, state deltas, and authored-event closure before a 3D design is called playable.
Make the builder derive route timing and state deltas from final authored data, then reconcile event totals and terminal states after tuning. This keeps build and smoke from standing in for actual playability.
Prevent inferred or substitute play traces from being reported as exact-strategy acceptance evidence. Preserve the existing no-op behavior for 2D archetypes.
Keep feasibility evidence honest across arbitrary 3D mechanics by separating derived traces from exact observed playthroughs and carrying state through escalation thresholds.
Generated 3D games can make SceneMap array lengths and config count leaves co-own the same value while using the config only in an equality assertion. State the single-truth rule at GDD production so counts remain authored data unless gameplay consumes a separate threshold.
Create the DOM HUD before GameScene emits its constructor-time progress event. This prevents generated games from overwriting a real initial total with the UIScene default and locks the ordering with the existing runtime contract self-check.
Make the ordering guard mutation-honest by requiring both UIScene.show and GameScene construction to exist in the expected order; deleting either anchor can no longer pass through indexOf(-1).
Disable hidden reasoning for the dedicated GDD request so a reasoning model cannot consume the entire response budget and return empty content. Keep a 32K document ceiling and pin the accepted creative temperature; cover the emitted request contract with a focused test.
This was referenced Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
结论
封装
threed_basicv1：在不修改 Phaser 2D 路线的前提下，补齐 3D 分类、three.js 模板、品类模块、GDD/资产协议和生成期验收合同。本 PR 从
origin/main@c54307e干净汇聚，只包含 3D 相关提交；不夹带 fork main 上的 PixelForge 对接、文本清理或本地错题记录。能力矩阵
three.js 迷宫漫游→threed_basic；2D 横版/俯视仍分别为platformer/top_down0.179.1+ TypeScript + Vite；DOM Title/HUD/Pause/Complete/Overgenerate_game_assets；贴图/天空盒/ billboard；1024² 与路径 manifest 纪律clean 毕业局
fe5f5b79e862e336/lunar-beacon-keeper-v1-clean-v01:00、Beat 302:00实际进入；压力间隔45→33.75→22.5s00:37、idle LOSE00:51、伤血98→65后恢复100、胜负重开 PASSg44v-lunar-beacon-keeper-3d-v1-milestone，graduation_valid=true验收
test:civ2-acceptPASSfox-grove-platformer、neon-flotilla的v2-accept均 PASS（既有 WARN 保持）protocol=6 registered=6 consistent=Truegit diff --checkPASS；40 files，+4295/-24；2D Phaser 文件 0 diff前端对接清单
POST /v1/games，body{prompt, slug?}，202 后保存idGET /v1/games/{id}；只按status+exit+error判终态，不以final_text冒充完成events?after_id=N&limit=M；或 WSevents/live?after_id=N，游标使用 DB eventidGET /v1/games/{id}/usage，分 agent/MCP/media/wall-clockGET /v1/games/{id}/files；raw=1仅文本，不是游戏静态托管terminalStatus当前未包含timeout，超时局不会发送 end；进入前端联调前必须在控制面修复CheckOrigin=true仅适合本机开发；部署前随鉴权/CORS 收紧冻结层 DA（相对
origin/main@c54307e）packages/core/src/tools/game-type-classifier.ts+ testpackages/core/src/tools/generate-gdd.ts+ testpackages/core/src/tools/generate-assets.ts+ testagent-test/templates/core3d/**agent-test/templates/modules/threed_basic/**、agent-test/docs/modules/threed_basic/**agent-test/docs/asset_protocol.md、agent-test/docs/debug_protocol.md完整文件级清单由本 PR 的 40-file diff 提供。没有修改 Go 控制面、workspace/engine/store、MCP 挂载、2D Phaser 模板。
HACK-IT 提醒
模板不内置某一种玩法的示例短句；分类器测试提供 3D/2D 最小句例，GDD 规则提供通用机制合同。这样避免把“信标/收集/某个测试局”固化成默认答案。
后续边界
本 PR 只关闭 v1。物理、3D 模型、触屏和 v2 玩法扩展不在此 PR；应在 v1 合并与前端 P1 接缝修复后另开版本。