|
1 | 1 | # BUILD_PR_DEBUG_SURFACES_3D_SUPPORT |
2 | 2 |
|
3 | | -## Purpose |
4 | | -Build a docs-only, implementation-ready bundle for the first reusable 3D support layer in the debug surfaces platform. |
5 | | - |
6 | | -## Build Mode |
7 | | -- Docs-only |
8 | | -- One PR purpose only |
9 | | -- No engine/runtime implementation files |
10 | | - |
11 | | -## Scope |
12 | | -In scope: |
13 | | -- Shared 3D panel inventory (summary-level) |
14 | | -- Shared 3D provider inventory (read-only snapshots) |
15 | | -- Optional shared 3D presets |
16 | | -- Adapter boundary contracts |
17 | | -- Adoption models and naming conventions |
18 | | -- Validation and rollout guidance |
19 | | - |
20 | | -Out of scope: |
21 | | -- Renderer-specific implementations |
22 | | -- Deep inspectors |
23 | | -- Network/multiplayer support |
24 | | -- Project-specific adapters in shared layer |
25 | | - |
26 | | -## Shared 3D Inventory |
27 | | -Panels: |
28 | | -- `panel.3d.transforms` |
29 | | -- `panel.3d.camera` |
30 | | -- `panel.3d.renderStages` |
31 | | -- `panel.3d.collisions` |
32 | | -- `panel.3d.sceneGraph` |
33 | | - |
34 | | -Providers: |
35 | | -- `provider.3d.transforms.snapshot` |
36 | | -- `provider.3d.camera.snapshot` |
37 | | -- `provider.3d.renderStages.snapshot` |
38 | | -- `provider.3d.collisions.snapshot` |
39 | | -- `provider.3d.sceneGraph.snapshot` |
40 | | - |
41 | | -Optional presets: |
42 | | -- `preset.3d.inspect` |
43 | | -- `preset.3d.render` |
44 | | -- `preset.3d.camera` |
45 | | - |
46 | | -## Adapter Boundaries |
47 | | -Shared layer responsibilities: |
48 | | -- Define generic panel/provider/preset descriptors. |
49 | | -- Provide registration seams and naming conventions. |
50 | | - |
51 | | -Project/sample responsibilities: |
52 | | -- Renderer-specific data extraction. |
53 | | -- Scene-specific mapping. |
54 | | -- Project-owned adapter implementations. |
55 | | - |
56 | | -## Naming Conventions |
57 | | -- Panels: `panel.3d.<domain>` |
58 | | -- Providers: `provider.3d.<domain>.snapshot` |
59 | | -- Presets: `preset.3d.<name>` |
60 | | - |
61 | | -## Target Structure |
62 | | -```text |
63 | | -engine/ |
64 | | - debug/ |
65 | | - standard/ |
66 | | - threeD/ |
67 | | - panels/ |
68 | | - providers/ |
69 | | - presets/ |
70 | | -``` |
71 | | - |
72 | | -## Guardrails |
73 | | -See `docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_GUARDRAILS.md`. |
74 | | - |
75 | | -## Validation Goals |
76 | | -- Shared 3D inventory is explicit and reusable. |
77 | | -- Shared layer remains renderer-agnostic. |
78 | | -- Project-specific adapters stay outside shared layer. |
79 | | -- Scope remains summary-level and opt-in. |
80 | | - |
81 | | -## Rollout Notes |
82 | | -1. Keep this BUILD docs-only. |
83 | | -2. APPLY should implement in small slices: |
84 | | - - provider contracts |
85 | | - - panels |
86 | | - - optional presets |
87 | | -3. Preserve existing 2D debug behavior parity. |
| 3 | +3D debug surface build. |
0 commit comments