Skip to content

Commit 56f69eb

Browse files
ToolboxAidToolboxAid
committed
Use the individual commit comment generated for each PR. Do not squash PR_26152_267 through PR_26152_271 into a single commit.
1 parent 2ddf213 commit 56f69eb

9 files changed

Lines changed: 1073 additions & 0 deletions

‎docs/dev/reports/engine_v2_v1_capability_inventory.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# PR_26152_267 Engine V2 / V1 Capability Inventory
2+
3+
## Scope
4+
5+
- Inventory existing `src/` and `src/engine/` capability families.
6+
- Inventory Engine V2 manifest-driven runtime capabilities already present under `src/engine/runtime`.
7+
- Map V1 capability families to V2 equivalents.
8+
- Identify reused, replaced, missing, and obsolete surfaces.
9+
10+
## Capability Map
11+
12+
| V1 / existing capability family | Representative existing surfaces | Engine V2 equivalent | Status |
13+
|---|---|---|---|
14+
| Core timing and engine loop | `src/engine/core/FixedTicker.js`, `FrameClock.js`, `Engine.js` | `runtimeTickLoop.js`, `runtimePlayableLoop.js`, `engineV2ConfigDrivenProofScene.js` | Replaced for V2 manifest runtime |
15+
| Object/entity model | `entity/`, `components/`, `ecs/World.js` | `objectDefinitionReader.js`, `runtimeObjectRecordFactory.js`, `runtimeObjectInstantiation.js` | Replaced by manifest object records |
16+
| Movement and physics | `systems/MovementSystem.js`, `physics/`, `systems/PhysicsSystem.js` | `runtimeMovementProcessing.js`, `runtimeTerrainEffects.js`, `runtimeEnvironmentEffects.js`, `engineV2ModifierStack.js` | Replaced/partitioned |
17+
| Collision | `collision/`, `systems/CollisionSystem.js`, `CollisionResolutionSystem.js` | `runtimeCollisionProcessing.js`, `runtimeTriggerProcessing.js` | Replaced for manifest flow |
18+
| Terrain/tilemap | `tilemap/`, tile collision helpers | `runtimeTerrainMaterialInstantiation.js`, `runtimeTerrainEffects.js` | Replaced conceptually; map authoring integration remains future |
19+
| Rendering | `rendering/CanvasRenderer.js`, `LayeredRenderSystem.js`, `SpriteRenderSystem.js`, `VectorDrawing.js` | `runtimeRenderingBootstrap.js`, `runtimeRenderPipeline.js`, `engineV2UiRuntime.js`, `engineV2EffectRuntime.js` | Partially replaced; reusable renderer helpers remain candidates |
20+
| Input | `input/`, `systems/InputControlSystem.js`, `InputMappingManifest.js` | `runtimeInputPipeline.js` | Adapted conceptually |
21+
| Camera | `camera/CameraSystem.js`, `Camera2D.js`, `ZoneCameraSystem.js` | `engineV2CameraRuntime.js` | Replaced/adapted |
22+
| Audio | `audio/AudioService.js`, media/synth/MIDI helpers | `engineV2AudioRuntime.js` | Adapted; low-level audio helpers remain reusable candidates |
23+
| Animation/effects | `animation/AnimationController.js`, `fx/ParticleSystem.js` | `engineV2AnimationRuntime.js`, `engineV2EffectRuntime.js` | Replaced/adapted |
24+
| AI/pathfinding | `ai/PatrolSystem.js`, `SteeringBehaviors.js`, `GridPathfinding.js` | `engineV2PatrolBehavior.js`, `engineV2ChaseFleeBehavior.js`, `engineV2PathfindingBaseline.js` | Adapted |
25+
| Combat | `combat/Combat.js`, projectile and collision systems | `engineV2AbilitySystem.js`, `engineV2ProjectileSystem.js`, `engineV2StatusEffectSystem.js`, `engineV2WeaponSystem.js`, runtime health/damage/cooldown/lives/outcomes | Replaced |
26+
| Possession/economy | Existing item/economy behavior is scattered or tool-owned | `engineV2InventorySystem.js`, `engineV2EquipmentSystem.js`, `engineV2ItemAndLootSystem.js`, `engineV2EconomyAndCurrency.js` | Added in V2 |
27+
| Interaction/quests/dialogue | `interaction/InteractionSystem.js`, `world/QuestSystem.js`, `world/SpawnSystem.js`, `world/EventScriptSystem.js` | `engineV2InteractionSystem.js`, `engineV2ContainerSystem.js`, `engineV2VendorSystem.js`, `engineV2CraftingFoundation.js`, `engineV2ObjectiveSystem.js`, `engineV2QuestSystem.js`, `engineV2DialogueSystem.js` | Replaced |
28+
| Persistence/save state | `persistence/`, `WorldSerializer.js`, browser storage services | `engineV2SaveStateModel.js`, `engineV2PersistenceRuntime.js`, `engineV2CheckpointSystem.js`, `engineV2ProfileStateSystem.js`, new shared Project Data Store contract | Partially replaced; browser storage is not authoritative |
29+
| Custom code/extensions | Earlier user-facing Code Studio concept | `engineV2CustomExtensionsHookRuntime.js` with Custom Extensions lifecycle/boundary | Replaced user-facing concept |
30+
| Networking/multiplayer | `network/` server/client/transport/debug surfaces | Engine V2 multiplayer boundary only | Future, not missing for initial Toolbox rebuild |
31+
| Debug/automation/replay/security/release | `debug/`, `automation/`, `replay/`, `security/`, `release/` | No direct V2 gameplay equivalent yet | Future/optional depending lane |
32+
| Theme/UI shell | `src/engine/theme`, `src/engine/ui` | Not Engine V2 gameplay runtime; remains separate surface | Reused/unchanged |
33+
34+
## Inventory Result
35+
36+
- Reused/adapted: input mapping concepts, audio helpers, camera concepts, AI/pathfinding concepts, render helper candidates.
37+
- Replaced: hard-coded object, movement, collision, rule, interaction, combat, objective, quest, dialogue, save/load, and proof-scene behavior now has manifest-driven V2 slices.
38+
- Missing/future: full networking, debug tooling integration, real database adapter, auth/admin/publish UI integration, deeper asset loading/binding integration.
39+
- Obsolete for V2 readiness: browser storage as authoritative project state, sample-dependent runtime validation, hard-coded game behavior, and user-facing Code Studio naming.
40+
41+
## Validation
42+
43+
- PASS: static capability inventory completed from existing `src/`, `src/engine/`, and Engine V2 runtime surfaces.
44+
- PASS: `git diff --check`
45+
46+
## Scope Exclusions
47+
48+
- No Toolbox rebuild.
49+
- No samples.
50+
- No runtime implementation changes for missing V1 capabilities.

‎docs/dev/reports/engine_v2_v1_gap_analysis.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# PR_26152_268 Engine V2 / V1 Gap Analysis
2+
3+
## Scope
4+
5+
- Analyze V1/existing capabilities not yet represented in Engine V2.
6+
- Classify each gap as required, optional, obsolete, or future.
7+
- Do not implement missing features in this PR.
8+
9+
## Gap Classification
10+
11+
| Gap | Classification | Reason |
12+
|---|---|---|
13+
| Real database-backed project store | Future | This stack adds the swappable contract and in-memory adapter only. PostgreSQL/DB work remains a later lane. |
14+
| Project/tool output persistence boundary | Required | Toolbox rebuild needs a store abstraction for projects, manifests, assets, tool outputs, Custom Extensions, approvals, and publish state. Covered by PR_26152_269/270. |
15+
| Browser storage as authoritative project store | Obsolete | `localStorage`/`sessionStorage` cannot be the authoritative project data store. |
16+
| Asset loading/binding integration | Required later | Existing `assets/` and rendering helpers are reusable candidates, but Toolbox rebuild should wire through Project Data Store boundaries before deeper runtime binding. |
17+
| Networking/multiplayer runtime | Future | Existing network stack is broad and should not block single-player manifest-driven Toolbox rebuild. |
18+
| Debug overlays/automation/replay | Optional | Valuable for diagnostics, but not required before the Toolbox rebuild may begin. |
19+
| Release/deployment packaging | Future | Publish/marketplace lanes need it; initial Toolbox rebuild only needs publish-state storage boundaries. |
20+
| Security/auth/admin implementation | Future | Contracts and approval state exist; auth/Admin UI implementation remains out of scope. |
21+
| OpenAI Custom Extension validation integration | Future | AI validation is advisory and contract-only; no provider integration yet. |
22+
| Samples as validation source | Obsolete for this lane | Samples remain out of scope and must not be used as readiness blockers. |
23+
| Hard-coded game-specific behavior | Obsolete | Engine V2 readiness is manifest-driven only. |
24+
| Legacy Code Studio user-facing naming | Obsolete | User-facing concept is Custom Extensions. Internal technical contracts may retain existing names until explicitly renamed. |
25+
26+
## Required Before Toolbox Rebuild
27+
28+
- PASS: Engine V2 manifest-driven runtime slices exist across object, terrain, environment, rules, playable loop, media, AI, combat, possession, interaction, persistence, player systems, and Custom Extensions.
29+
- PASS: V1/V2 inventory exists.
30+
- PASS: Required Project Data Store contract exists.
31+
- PASS: Required in-memory Project Data Store adapter exists.
32+
33+
## Remaining Required During Toolbox Rebuild
34+
35+
- Wire rebuilt Toolbox flows to the swappable Project Data Store contract.
36+
- Keep tool pages independent from direct storage implementation details.
37+
- Keep Custom Extension approvals human-gated for publish eligibility.
38+
39+
## Validation
40+
41+
- PASS: static gap analysis completed.
42+
- PASS: `git diff --check`
43+
44+
## Scope Exclusions
45+
46+
- No missing V1 feature implementation.
47+
- No Toolbox rebuild.
48+
- No samples.

‎docs/dev/reports/in_memory_project_data_store.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# PR_26152_270 In-Memory Project Data Store
2+
3+
## Scope
4+
5+
- Added `src/shared/projectDataStore/inMemoryProjectDataStore.js`.
6+
- Added `tests/shared/InMemoryProjectDataStore.test.mjs`.
7+
- Implemented a runtime/dev-only in-memory Project Data Store adapter.
8+
- Kept the implementation replaceable by a future real database adapter.
9+
10+
## Adapter Surface
11+
12+
- `putRecord(record)`
13+
- `getRecord(recordType, recordId)`
14+
- `listRecords(filters)`
15+
- `deleteRecord(recordType, recordId)`
16+
- `clear()`
17+
18+
## Boundary Rules
19+
20+
- The in-memory adapter validates records through `projectDataStoreContract.js`.
21+
- The adapter does not use `localStorage`.
22+
- The adapter does not use `sessionStorage`.
23+
- The adapter does not use IndexedDB.
24+
- The adapter does not introduce an external database dependency.
25+
- Returned records are cloned and frozen so callers cannot mutate stored data by reference.
26+
27+
## Test Coverage
28+
29+
- PASS: adapter validates against the shared Project Data Store contract.
30+
- PASS: initial records can seed the store.
31+
- PASS: invalid initial records reject visibly.
32+
- PASS: valid records can be written and read.
33+
- PASS: record replacement updates existing keys.
34+
- PASS: list filters work for record type, owner, and project.
35+
- PASS: delete removes records.
36+
- PASS: clear removes all records.
37+
- PASS: invalid records reject and are not stored.
38+
- PASS: source scan confirms no browser storage or IndexedDB usage.
39+
40+
## Validation
41+
42+
- PASS: `node tests/shared/InMemoryProjectDataStore.test.mjs`
43+
- PASS: `git diff --check`
44+
45+
## Scope Exclusions
46+
47+
- No real database.
48+
- No browser storage as authoritative store.
49+
- No Toolbox rebuild.
50+
- No samples.

‎docs/dev/reports/project_data_store_contract.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# PR_26152_269 Project Data Store Contract
2+
3+
## Scope
4+
5+
- Added `src/shared/contracts/projectDataStoreContract.js`.
6+
- Added `tests/shared/ProjectDataStoreContract.test.mjs`.
7+
- Defined a UI/tool-page independent project data store contract.
8+
- Covered these record types:
9+
- projects
10+
- manifests
11+
- assets
12+
- tool outputs
13+
- Custom Extensions
14+
- Custom Extension approvals
15+
- publish state
16+
17+
## Boundary Rules
18+
19+
- The store contract is swappable for a future real database.
20+
- Browser storage is not the authoritative store.
21+
- `localStorage` and `sessionStorage` are forbidden as persisted store state.
22+
- UI/tool-page state is forbidden as persisted store state.
23+
- runtime ProjectWorkspace state is forbidden as persisted store state.
24+
- auth session state is forbidden as persisted store state.
25+
26+
## Contract Coverage
27+
28+
- PASS: required record types and collection names are defined.
29+
- PASS: collection-to-record-type mapping is defined.
30+
- PASS: adapter method surface is defined: `putRecord`, `getRecord`, `listRecords`, `deleteRecord`, `clear`.
31+
- PASS: Custom Extension approval lifecycle states are represented.
32+
- PASS: publish-state values are represented.
33+
- PASS: valid records validate.
34+
- PASS: missing owner/project/payload values reject.
35+
- PASS: invalid approval and publish status values reject.
36+
- PASS: forbidden UI/browser/runtime fields reject.
37+
- PASS: records in the wrong collection reject.
38+
- PASS: adapter shape validation rejects incomplete adapters.
39+
40+
## Validation
41+
42+
- PASS: `node tests/shared/ProjectDataStoreContract.test.mjs`
43+
- PASS: `git diff --check`
44+
45+
## Scope Exclusions
46+
47+
- No UI implementation.
48+
- No Toolbox rebuild.
49+
- No samples.
50+
- No external database implementation.

‎docs/dev/reports/toolbox_readiness_gate.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# PR_26152_271 Toolbox Readiness Gate
2+
3+
## Gate Inputs
4+
5+
| Readiness input | Evidence | Status |
6+
|---|---|---|
7+
| V1/V2 capability inventory exists | `docs/dev/reports/engine_v2_v1_capability_inventory.md` | PASS |
8+
| V1/V2 gap analysis exists | `docs/dev/reports/engine_v2_v1_gap_analysis.md` | PASS |
9+
| Project Data Store contract exists | `src/shared/contracts/projectDataStoreContract.js` and `docs/dev/reports/project_data_store_contract.md` | PASS |
10+
| In-memory Project Data Store exists | `src/shared/projectDataStore/inMemoryProjectDataStore.js` and `docs/dev/reports/in_memory_project_data_store.md` | PASS |
11+
| Browser storage is not authoritative | Contract forbids `localStorage` and `sessionStorage`; adapter source scan passes | PASS |
12+
| Store is swappable for future DB | Shared adapter method surface is contract-tested | PASS |
13+
14+
## Readiness Decision
15+
16+
Toolbox rebuild may begin in the next implementation lane.
17+
18+
This PR stack does not begin the Toolbox rebuild. It only establishes the readiness evidence and the replaceable in-memory store required before rebuild work starts.
19+
20+
## Required Boundaries For Next Lane
21+
22+
- Rebuilt Toolbox flows must use the Project Data Store contract boundary.
23+
- The in-memory store may be used for runtime/dev storage only.
24+
- A future database adapter must replace the in-memory adapter without changing UI/tool page contracts.
25+
- Browser storage must not become the authoritative project, manifest, asset, tool output, Custom Extension, approval, or publish-state store.
26+
- Samples remain out of scope.
27+
28+
## Validation
29+
30+
- PASS: `git diff --check`
31+
- PASS: `node tests/shared/ProjectDataStoreContract.test.mjs`
32+
- PASS: `node tests/shared/InMemoryProjectDataStore.test.mjs`
33+
34+
## Scope Exclusions
35+
36+
- No Toolbox rebuild.
37+
- No samples.
38+
- No external database dependency.
39+
- No UI/page implementation.

0 commit comments

Comments
 (0)