Files

T

Wassim SAMADandClaude Opus 4.7 7b946ce8b7 wiki: add node-definitions doc for three-checkbox composition model

New page covering the geometry/renderer/system trio that registry-driven
kinds opt into. Documents:

- The three optional fields on NodeDefinition and when each applies
- Generic <GeometrySystem> + <ParametricNodeRenderer> runtime
- GeometryContext shape (resolve / children / siblings / parent)
- Combination matrix for shelf / spawn / zone / door / window / GLB items
- Migration recipe from custom renderer+system files to def.geometry
- Rules around purity, dispose-on-rebuild, register-once

renderers.md and systems.md gain "prefer registry-driven" banners and
link out to the new page. Architecture README adds the page to the
index so review-architecture skill picks it up.

The pattern was validated by the shelf spike: inline-JSX geometry was
visibly laggy on parametric edits; moving to a per-kind system reading
dirtyNodes (mirroring door/wall/item) restored smoothness. The three-
checkbox model generalises that win so most future kinds need only a
pure geometry function.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-15 08:29:54 -04:00

3.1 KiB

Raw Blame History

Renderers

Node renderer pattern in packages/viewer.

Applies to: packages/viewer/**.

Renderers live in packages/viewer/src/components/renderers/. Each renderer is responsible for one node type's Three.js geometry and materials — nothing else.

For registry-driven kinds, the default is no custom renderer. Set def.geometry instead and the framework mounts a generic renderer + geometry system for you. See node-definitions.md. The pattern below applies to kinds that do need a custom renderer (GLB, <Html>, drei, instancing, shader materials).

Dispatch Chain

<SceneRenderer>          — iterates rootNodeIds from useScene
  └─ <NodeRenderer>      — switches on node.type, renders the matching component
       └─ <WallRenderer> — (or SlabRenderer, DoorRenderer, …)

See packages/viewer/src/components/renderers/scene-renderer.tsx and packages/viewer/src/components/renderers/node-renderer.tsx.

Renderer Responsibilities

A renderer should:

Read its node from useScene via the node's ID
Register its mesh(es) with useRegistry() so other systems can look them up
Subscribe to pointer events via useNodeEvents()
Render geometry and apply materials based on node properties

A renderer must not:

Run geometry generation logic (that belongs in a System)
Import anything from apps/editor
Manage selection state directly (use useViewer for read, emit events for write)
Perform expensive per-frame calculations in the component body

Example — Minimal Renderer

// packages/viewer/src/components/renderers/my-node/index.tsx
import { useRegistry } from '@pascal-app/core'
import { useNodeEvents } from '../../hooks/use-node-events'
import { useScene } from '@pascal-app/core'

export function MyNodeRenderer({ node }: { node: MyNode }) {
  const ref = useRef<Mesh>(null!)
  useRegistry(node.id, 'my-node', ref)   // 3 args: id, type, ref — no return value
  const events = useNodeEvents(node, 'my-node')

  return (
    <mesh ref={ref} {...events}>
      <boxGeometry args={[node.width, node.height, node.depth]} />
      <meshStandardMaterial color={node.color} />
    </mesh>
  )
}

Adding a New Node Type

For new kinds, prefer the registry-driven model in node-definitions.md. The legacy steps below apply only when a kind needs a custom React renderer (GLB loaders, <Html> portals, etc.) and lives in packages/viewer rather than packages/nodes/<kind>:

Create packages/viewer/src/components/renderers/<type>/index.tsx
Add a case to NodeRenderer in node-renderer.tsx
Add the corresponding system in packages/core/src/systems/ if the node needs derived geometry
Export from packages/viewer/src/index.ts if needed externally

Performance Notes

Use useMemo for geometry that depends on node properties — avoid recreating on every render.
For complex cutout or boolean geometry, delegate to a System (e.g. WallCutout).
Register one mesh per node ID; if a renderer spawns multiple meshes, use a group ref or pick the primary one for registry.

3.1 KiB Raw Blame History