skills polish
This commit is contained in:
wass08
@@ -74,3 +74,5 @@ Concrete guidance with examples.
|
||||
| `scene-registry` | Global node ID → Object3D map and `useRegistry` |
|
||||
| `selection-managers` | Two-layer selection (viewer + editor), events, outliner |
|
||||
| `events` | Typed event bus — emitting and listening to node and grid events |
|
||||
| `node-schemas` | Zod schema pattern for node types, createNode, updateNode |
|
||||
| `spatial-queries` | Placement validation (canPlaceOnFloor/Wall/Ceiling) for tools |
|
||||
|
||||
@@ -26,7 +26,7 @@ Example keys: `wall:click`, `item:enter`, `door:double-click`, `grid:pointerdown
|
||||
'click' | 'move' | 'enter' | 'leave' | 'pointerdown' | 'pointerup' | 'context-menu' | 'double-click'
|
||||
```
|
||||
|
||||
The `grid:*` events fire when the user interacts with empty space (no node hit). See @apps/editor/hooks/use-grid-events.ts.
|
||||
The `grid:*` events fire when the user interacts with empty space (no node hit). They are **not** emitted by a mesh — `useGridEvents(gridY)` (@apps/editor/hooks/use-grid-events.ts) manually raycasts against a ground plane and calls `emitter.emit('grid:click', …)`. Mount it in any tool or editor component that needs empty-space interactions.
|
||||
|
||||
## NodeEvent Shape
|
||||
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
description: Node type definitions, Zod schema pattern, and how to create nodes in the scene
|
||||
globs: packages/core/src/schema/**
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Node Schemas
|
||||
|
||||
All node types are defined as Zod schemas in `packages/core/src/schema/nodes/`. Each schema extends `BaseNode` and exports both the schema and its inferred TypeScript type.
|
||||
|
||||
**Sources**: @packages/core/src/schema/base.ts, @packages/core/src/schema/nodes/
|
||||
|
||||
## BaseNode
|
||||
|
||||
Every node shares these fields:
|
||||
|
||||
```ts
|
||||
{
|
||||
object: 'node' // always literal 'node'
|
||||
id: string // typed ID e.g. "wall_abc123"
|
||||
type: string // node type discriminator e.g. "wall"
|
||||
name?: string // optional display name
|
||||
parentId: string | null // parent node ID; null = root
|
||||
visible: boolean // defaults to true
|
||||
metadata: Record<string, unknown> // arbitrary JSON, defaults to {}
|
||||
}
|
||||
```
|
||||
|
||||
## Defining a New Node Type
|
||||
|
||||
```ts
|
||||
// packages/core/src/schema/nodes/my-node.ts
|
||||
import { z } from 'zod'
|
||||
import { BaseNode, objectId, nodeType } from '../base'
|
||||
|
||||
export const MyNode = BaseNode.extend({
|
||||
id: objectId('my-node'), // generates IDs like "my-node_abc123"
|
||||
type: nodeType('my-node'), // sets literal type discriminator
|
||||
// add node-specific fields:
|
||||
width: z.number().default(1),
|
||||
label: z.string().optional(),
|
||||
}).describe('My node — one-line description of what it represents')
|
||||
|
||||
export type MyNode = z.infer<typeof MyNode>
|
||||
export type MyNodeId = MyNode['id']
|
||||
```
|
||||
|
||||
Then add `MyNode` to the `AnyNode` union in `packages/core/src/schema/types.ts`.
|
||||
|
||||
## Creating Nodes in Tools
|
||||
|
||||
Always use `.parse()` to validate and generate a proper typed ID. Never construct a plain object manually.
|
||||
|
||||
```ts
|
||||
import { WallNode } from '@pascal-app/core'
|
||||
import { useScene } from '@pascal-app/core'
|
||||
|
||||
// 1. Parse validates and fills defaults (including auto-generated id)
|
||||
const wall = WallNode.parse({ name: 'Wall 1', start: [0, 0], end: [5, 0] })
|
||||
|
||||
// 2. createNode(node, parentId?) inserts it into the scene
|
||||
const { createNode } = useScene.getState()
|
||||
createNode(wall, levelId)
|
||||
```
|
||||
|
||||
For batch creation:
|
||||
|
||||
```ts
|
||||
const { createNodes } = useScene.getState()
|
||||
createNodes([
|
||||
{ node: WallNode.parse({ start: [0, 0], end: [5, 0] }), parentId: levelId },
|
||||
{ node: WallNode.parse({ start: [5, 0], end: [5, 4] }), parentId: levelId },
|
||||
])
|
||||
```
|
||||
|
||||
## Updating Nodes
|
||||
|
||||
```ts
|
||||
const { updateNode } = useScene.getState()
|
||||
updateNode(wall.id, { height: 2.8 }) // partial update, merges with existing
|
||||
```
|
||||
|
||||
## Real Examples
|
||||
|
||||
- **Simple geometry node**: @packages/core/src/schema/nodes/wall.ts — `start`, `end`, `thickness`, `height`
|
||||
- **Polygon node**: @packages/core/src/schema/nodes/slab.ts — `polygon: [number, number][]`, `holes`
|
||||
- **Positioned node**: @packages/core/src/schema/nodes/item.ts — `position`, `rotation`, `scale`, `asset`
|
||||
|
||||
## Rules
|
||||
|
||||
- **Always use `.parse()`** — it generates the correct ID prefix and fills defaults. `WallNode.parse({...})` not `{ type: 'wall', id: '...' }`.
|
||||
- **Never hardcode IDs.** Let `objectId('type')` generate them.
|
||||
- **Add new node types to `AnyNode`** in `types.ts` or they won't be accepted by the store.
|
||||
- **Keep schemas in `packages/core`**, not in the viewer or editor — the schema is shared by all packages.
|
||||
@@ -40,10 +40,10 @@ import { useRegistry } from '@pascal-app/core'
|
||||
import { useNodeEvents } from '../../hooks/use-node-events'
|
||||
import { useScene } from '@pascal-app/core'
|
||||
|
||||
export function MyNodeRenderer({ id }: { id: MyNodeId }) {
|
||||
const node = useScene(s => s.nodes[id] as MyNode)
|
||||
const { ref } = useRegistry(id)
|
||||
const events = useNodeEvents(id)
|
||||
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}>
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
description: Placement validation for tools — canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling
|
||||
globs: apps/editor/components/tools/**
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Spatial Queries
|
||||
|
||||
`useSpatialQuery()` validates whether an item can be placed at a given position without overlapping existing items. Every placement tool must call it before committing a node to the scene.
|
||||
|
||||
**Source**: @packages/core/src/hooks/spatial-grid/use-spatial-query.ts
|
||||
|
||||
## Hook
|
||||
|
||||
```ts
|
||||
const { canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling } = useSpatialQuery()
|
||||
```
|
||||
|
||||
All three methods return `{ valid: boolean; conflictIds: string[] }`.
|
||||
`canPlaceOnWall` additionally returns `adjustedY: number` (snapped height).
|
||||
|
||||
---
|
||||
|
||||
## canPlaceOnFloor
|
||||
|
||||
```ts
|
||||
canPlaceOnFloor(
|
||||
levelId: string,
|
||||
position: [number, number, number],
|
||||
dimensions: [number, number, number], // scaled width/height/depth
|
||||
rotation: [number, number, number],
|
||||
ignoreIds?: string[], // pass [draftItem.id] to exclude self
|
||||
): { valid: boolean; conflictIds: string[] }
|
||||
```
|
||||
|
||||
**Usage in a tool:**
|
||||
```ts
|
||||
const pos: [number, number, number] = [x, 0, z]
|
||||
const { valid } = canPlaceOnFloor(levelId, pos, getScaledDimensions(item), item.rotation, [item.id])
|
||||
if (valid) createNode(item, levelId)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## canPlaceOnWall
|
||||
|
||||
```ts
|
||||
canPlaceOnWall(
|
||||
levelId: string,
|
||||
wallId: string,
|
||||
localX: number, // distance along wall from start
|
||||
localY: number, // height from floor
|
||||
dimensions: [number, number, number],
|
||||
attachType: 'wall' | 'wall-side', // 'wall' needs clearance both sides; 'wall-side' only one
|
||||
side?: 'front' | 'back',
|
||||
ignoreIds?: string[],
|
||||
): { valid: boolean; conflictIds: string[]; adjustedY: number }
|
||||
```
|
||||
|
||||
`adjustedY` contains the snapped Y so items sit flush on the slab — always use it instead of the raw `localY`:
|
||||
|
||||
```ts
|
||||
const { valid, adjustedY } = canPlaceOnWall(levelId, wallId, x, y, dims, 'wall', undefined, [item.id])
|
||||
if (valid) updateNode(item.id, { wallT: x, wallY: adjustedY })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## canPlaceOnCeiling
|
||||
|
||||
```ts
|
||||
canPlaceOnCeiling(
|
||||
ceilingId: string,
|
||||
position: [number, number, number],
|
||||
dimensions: [number, number, number],
|
||||
rotation: [number, number, number],
|
||||
ignoreIds?: string[],
|
||||
): { valid: boolean; conflictIds: string[] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Slab Elevation
|
||||
|
||||
When items rest on a slab (not flat ground), use these to get the correct Y:
|
||||
|
||||
```ts
|
||||
import { spatialGridManager } from '@pascal-app/core'
|
||||
|
||||
// Y at a single point
|
||||
const y = spatialGridManager.getSlabElevationAt(levelId, x, z)
|
||||
|
||||
// Y considering the item's full footprint (highest slab point under item)
|
||||
const y = spatialGridManager.getSlabElevationForItem(levelId, position, dimensions, rotation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
- **Always pass `[item.id]` in `ignoreIds`** when validating a draft item that already exists in the scene — otherwise it collides with itself.
|
||||
- **Use `adjustedY` from `canPlaceOnWall`** — don't use the raw cursor Y for wall-mounted items.
|
||||
- **Use `getScaledDimensions(item)`** (@packages/core/src/schema/nodes/item.ts) to account for item scale, not the raw `asset.dimensions`.
|
||||
- Validate on every pointer move for live feedback (highlight ghost red/green). Only `createNode` / `updateNode` on pointer up or click.
|
||||
|
||||
See @apps/editor/components/tools/item/use-placement-coordinator.tsx for a full implementation.
|
||||
@@ -89,4 +89,4 @@ Core and viewer systems are mounted inside `<Viewer>` alongside renderers. See @
|
||||
</Viewer>
|
||||
```
|
||||
|
||||
4. If the system must run before renderers, place it earlier in the JSX tree.
|
||||
4. **Mount order matters.** Most viewer systems run *after* renderers in the JSX tree — they consume `sceneRegistry` data that renderers populate on mount. Only place a system before renderers if it explicitly does not read the registry.
|
||||
|
||||
Reference in New Issue
Block a user