PRDs

Author: jonit-dev

docs/0-navigation.md

@@ -70,6 +70,12 @@ graph TD
     Implementation --> TSyringeRemoval[4-6 TSyringe Removal Status]
     Implementation --> HierarchySystem[4-7 Unity-Like Hierarchy System]
     Implementation --> ScriptSystem[4-8 Unity-Like Script System]
+    Implementation --> InGameUI[4-9 In-Game UI System]
+    Implementation --> ParticleSystem[4-10 Particle System]
+    Implementation --> CommandSystem[4-11 Command System]
+    Implementation --> AssetPipeline[4-12 Asset Pipeline]
+    Implementation --> CollisionDetection[4-13 Collision Detection System]
+    Implementation --> NetworkingSystem[4-14 Networking System]
 
     %% Supporting Documentation
     Patterns[🎨 Patterns] --> GamePatterns[5-1 Game Patterns]

docs/implementation/4-10-particle-system-prd.md

@@ -0,0 +1,200 @@
+# Particle System PRD
+
+## Overview
+
+### Context & Goals
+
+- Add GPU-accelerated particle effects (muzzle flash, smoke, sparks).
+- Author effects via ECS `ParticleComponent` plus presets.
+- Support bursts and continuous emitters with lifetime curves.
+
+### Current Pain Points
+
+- No standardized particle effects pipeline.
+- Visual feedback missing for actions and impacts.
+- Manual effect coding increases coupling and regressions.
+
+## Proposed Solution
+
+### High‑level Summary
+
+- Introduce `ParticleSystem` updating emitter state and GPU buffers.
+- Define `ParticleComponent` schema (Zod) with emission and material params.
+- Implement instanced/points-based renderer with curves (size, color over time).
+- Provide presets and editor-friendly parameters.
+
+### Architecture & Directory Structure
+
+```
+/src/core/
+  ├── systems/
+  │   └── ParticleSystem.ts
+  ├── lib/particles/
+  │   ├── curves.ts
+  │   ├── gpuBuffers.ts
+  │   └── materials.ts
+  └── components/particles/
+      ├── ParticleEmitter.tsx
+      └── ParticleComponent.schema.ts
+```
+
+## Implementation Plan
+
+1. Phase 1: Core (1 day)
+
+   1. Component schema + emitter lifecycle
+   2. CPU sim baseline; instanced rendering
+   3. Curves and color/size over lifetime
+
+2. Phase 2: GPU Path (1 day)
+
+   1. GPU buffer management
+   2. Materials and sorting strategies
+   3. Perf instrumentation
+
+3. Phase 3: Presets & Events (0.5 day)
+   1. Common presets (smoke/sparks)
+   2. Trigger via events (e.g., collision)
+
+## File and Directory Structures
+
+```
+/docs/implementation/
+  └── 4-10-particle-system-prd.md
+```
+
+## Technical Details
+
+```ts
+export interface IParticleComponent {
+  maxParticles: number;
+  emissionRate?: number; // particles/sec
+  burst?: { count: number; interval: number };
+  lifetime: [number, number]; // min,max
+  startColor?: [number, number, number, number];
+  endColor?: [number, number, number, number];
+  startSize?: number;
+  endSize?: number;
+  worldSpace?: boolean;
+}
+
+export interface IParticleSystemApi {
+  triggerBurst(entityId: number, count?: number): void;
+}
+```
+
+### Editor & Component Integration
+
+```ts
+// 1) Add a new KnownComponentType
+// src/core/lib/ecs/IComponent.ts
+export const KnownComponentTypes = {
+  // ...existing,
+  PARTICLES: 'Particles',
+} as const;
+
+// 2) Schema & data type
+// src/core/components/particles/ParticleComponent.schema.ts
+import { z } from 'zod';
+export const ParticleComponentSchema = z.object({
+  enabled: z.boolean().default(true),
+  maxParticles: z.number().int().positive().default(1024),
+  emissionRate: z.number().nonnegative().default(0),
+  burst: z.object({ count: z.number().int().positive(), interval: z.number().positive() }).optional(),
+  lifetime: z.tuple([z.number().positive(), z.number().positive()]).default([0.5, 1.5]),
+  startColor: z.tuple([z.number(), z.number(), z.number(), z.number()]).default([1,1,1,1]),
+  endColor: z.tuple([z.number(), z.number(), z.number(), z.number()]).default([1,1,1,0]),
+  startSize: z.number().positive().default(0.1),
+  endSize: z.number().positive().default(0.01),
+  worldSpace: z.boolean().default(true),
+});
+export type ParticleData = z.infer<typeof ParticleComponentSchema>;
+
+// 3) Inspector adapter
+// src/editor/components/inspector/adapters/ParticleAdapter.tsx
+export const ParticleAdapter: React.FC<{
+  particleComponent: IComponent<ParticleData> | null;
+  updateComponent: (type: string, data: unknown) => boolean;
+  removeComponent: (type: string) => boolean;
+}> = ({ particleComponent, updateComponent, removeComponent }) => {
+  // form controls for emission, lifetime, colors, sizes
+  return null;
+};
+
+// 4) Add menu entry + defaults
+// src/editor/components/menus/AddComponentMenu.tsx
+COMPONENT_DEFINITIONS.push({
+  id: KnownComponentTypes.PARTICLES,
+  name: 'Particles',
+  description: 'GPU-accelerated particle emitter',
+  icon: /* choose icon */, category: 'VFX',
+});
+// handle defaultData
+case KnownComponentTypes.PARTICLES:
+  defaultData = { enabled: true, maxParticles: 1024, emissionRate: 50, lifetime: [0.5,1.5] };
+  break;
+
+// 5) Visualization (optional)
+// src/editor/components/panels/ViewportPanel/components/ParticleVisualization.tsx
+// draw emitter gizmos, bounds, trajectories when selected
+
+// 6) Runtime registration
+// src/core/systems/ParticleSystem.ts
+registerSystem({ id: 'core.particles', order: 70, update: (dt) => particleSystem.update(dt) });
+```
+
+## Usage Examples
+
+```ts
+// Create an emitter and trigger a burst
+particles.triggerBurst(entityId, 30);
+```
+
+## Testing Strategy
+
+- Unit: curve evaluation, lifetime pool reuse, schema validation.
+- Integration: emitter updates in step loop, rendering stability under load.
+
+## Edge Cases
+
+| Edge Case           | Remediation                                         |
+| ------------------- | --------------------------------------------------- |
+| Excess particles    | Cap by `maxParticles` with LRU replacement          |
+| Transparent sorting | Use approximate back-to-front or disable depthWrite |
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant ECS
+  participant ParticleSystem
+  participant Renderer
+  ECS->>ParticleSystem: update emitters
+  ParticleSystem->>Renderer: upload buffers
+  Renderer-->>ParticleSystem: frame rendered
+```
+
+## Risks & Mitigations
+
+| Risk         | Mitigation                                 |
+| ------------ | ------------------------------------------ |
+| GPU overdraw | Limit size, soft particle options, pooling |
+| GC pressure  | Reuse buffers; object pools                |
+
+## Timeline
+
+- Total: ~2.5 days (Core 1, GPU 1, Presets 0.5)
+
+## Acceptance Criteria
+
+- Emitters spawn particles with curves and pooling.
+- GPU path sustains target FPS for 5k particles.
+- Event-triggered effects work (e.g., collisions).
+
+## Conclusion
+
+Adds a scalable particle pipeline with ECS-first authoring and GPU efficiency.
+
+## Assumptions & Dependencies
+
+- Three.js renderer; existing event bus; Zod available.

docs/implementation/4-11-command-system-prd.md

@@ -0,0 +1,181 @@
+# Command System PRD
+
+## Overview
+
+### Context & Goals
+
+- Provide undo/redo for gameplay/editor operations.
+- Enable AI/behavior scripts to enqueue reversible actions.
+- Standardize transactional changes across ECS.
+
+### Current Pain Points
+
+- No unified command contract or history.
+- Hard to revert multi-entity operations safely.
+- Limited observability for action auditing.
+
+## Proposed Solution
+
+### High‑level Summary
+
+- Define `ICommand` with `do/undo/serialize` and idempotency.
+- Maintain command stacks with grouping and checkpoints.
+- Emit events for telemetry and AI integration.
+- Persist compact history (optional caps, pruning).
+
+### Architecture & Directory Structure
+
+```
+/src/core/
+  ├── lib/commands/
+  │   ├── CommandBus.ts
+  │   ├── CommandHistory.ts
+  │   └── commands/
+  │       ├── TransformCommands.ts
+  │       └── ComponentCommands.ts
+  └── systems/
+      └── CommandSystem.ts
+```
+
+## Implementation Plan
+
+1. Phase 1: Contracts (0.5 day)
+
+   1. Define `ICommand` and bus/history APIs
+   2. Add grouping and checkpoint semantics
+
+2. Phase 2: Core Commands (0.5 day)
+
+   1. Transform add/update/remove
+   2. Generic component add/remove/update
+
+3. Phase 3: Integration (0.5 day)
+   1. Event emission for telemetry
+   2. Script API bridge for AI
+
+## File and Directory Structures
+
+```
+/docs/implementation/
+  └── 4-11-command-system-prd.md
+```
+
+## Technical Details
+
+```ts
+export interface ICommand<T = unknown> {
+  id: string;
+  do(context?: T): Promise<void> | void;
+  undo(context?: T): Promise<void> | void;
+  serialize?(): Record<string, unknown>;
+}
+
+export interface ICommandBus {
+  execute(cmd: ICommand): Promise<void>;
+  undo(): Promise<void>;
+  redo(): Promise<void>;
+  beginGroup(label?: string): void;
+  endGroup(): void;
+}
+```
+
+### Editor Integration
+
+```ts
+// 1) Wrap component mutations in CommandBus
+// src/editor/components/menus/AddComponentMenu.tsx
+// instead of componentManager.addComponent(...)
+await commandBus.execute(new AddComponentCommand({ entityId, type: componentType, data: defaultData }));
+
+// src/editor/components/inspector/adapters/*
+// replace updateComponent/removeComponent calls similarly via commands
+
+// 2) Toolbar bindings (undo/redo)
+// src/editor/store/editorStore.ts
+import { commandBus } from '@/core/lib/commands/CommandBus';
+undo: async () => { await commandBus.undo(); },
+redo: async () => { await commandBus.redo(); },
+
+// 3) Command examples
+// src/core/lib/commands/commands/ComponentCommands.ts
+export class AddComponentCommand implements ICommand {
+  constructor(private p: { entityId: number; type: string; data: unknown }) {}
+  async do() { componentManager.addComponent(this.p.entityId, this.p.type, this.p.data); }
+  async undo() { componentManager.removeComponent(this.p.entityId, this.p.type); }
+}
+
+export class UpdateComponentCommand implements ICommand {
+  constructor(private p: { entityId: number; type: string; prev: unknown; next: unknown }) {}
+  async do() { componentManager.updateComponent(this.p.entityId, this.p.type, this.p.next); }
+  async undo() { componentManager.updateComponent(this.p.entityId, this.p.type, this.p.prev); }
+}
+
+// 4) System registration (optional for telemetry/cleanup)
+// src/core/systems/CommandSystem.ts
+registerSystem({ id: 'core.commands', order: 10, update: () => commandBus.flush() });
+
+// 5) Script API bridge (for AI)
+// src/core/lib/scripting/ScriptAPI.ts
+export const createCommandAPI = (bus: ICommandBus) => ({
+  execute: (cmd: ICommand) => bus.execute(cmd),
+  undo: () => bus.undo(),
+  redo: () => bus.redo(),
+});
+```
+
+## Usage Examples
+
+```ts
+await commandBus.execute(new SetTransform({ entityId, position }));
+await commandBus.undo();
+```
+
+## Testing Strategy
+
+- Unit: idempotency, grouping behavior, history bounds.
+- Integration: ECS changes reversible across systems.
+
+## Edge Cases
+
+| Edge Case          | Remediation                                |
+| ------------------ | ------------------------------------------ |
+| Long chains        | Cap history; periodic checkpoints          |
+| Non-reversible ops | Gate behind safeguards; skip serialization |
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant CommandBus
+  participant ECS
+  Client->>CommandBus: execute(cmd)
+  CommandBus->>ECS: apply changes
+  Client->>CommandBus: undo()
+  CommandBus->>ECS: revert changes
+```
+
+## Risks & Mitigations
+
+| Risk               | Mitigation                                    |
+| ------------------ | --------------------------------------------- |
+| Inconsistent state | Snapshot before group; validation after apply |
+| Performance        | Batch updates; coalesce trivial commands      |
+
+## Timeline
+
+- Total: ~1.5 days (Contracts 0.5, Core 0.5, Integration 0.5)
+
+## Acceptance Criteria
+
+- Reversible transform/component changes.
+- Grouped actions undo/redo atomically.
+- Events emitted for telemetry.
+
+## Conclusion
+
+Creates a robust foundation for undoable gameplay/editor operations and AI control.
+
+## Assumptions & Dependencies
+
+- Event bus available; ECS component manager supports diffing.