Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

threejs-core-scene-graph

/threejs-core-scene-graph

Tworzy sceny Three.js i zarządza hierarchią obiektów, grupami, warstwami, mgłą oraz zwalnianiem zasobów przez dispose().

Repozytorium
claude-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
7
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tworzy sceny Three.js i zarządza hierarchią obiektów, grupami, warstwami, mgłą oraz zwalnianiem zasobów przez dispose().

Oryginalny opis (EN)

Use when creating Three.js scenes, adding objects, managing parent-child hierarchies, or organizing 3D content. Prevents the common mistake of using add() instead of attach() for reparenting, forgetting matrixAutoUpdate, or missing dispose() calls. Covers Object3D, Scene, Group, Mesh, Layers, Fog, traversal, coordinate conversion. Keywords: scene graph, Object3D, add, remove, traverse, layers, fog, parent, children, visibility, Three.js scene setup, group objects, show hide object, organize scene.

Jak działa

  1. Quick Reference
  2. Hierarchy Methods
  3. Traversal
  4. Matrix System
  5. Scene Class
  6. Fog
  7. Group
  8. Mesh
  9. Layers System
  10. lookAt() Behavior Difference
Sekcje z nagłówków SKILL.md, w oryginale · 333 linii, 1 559 słów
Podgląd SKILL.md
---
name: threejs-core-scene-graph
description: >
  Use when creating Three.js scenes, adding objects, managing parent-child
  hierarchies, or organizing 3D content. Prevents the common mistake of
  using add() instead of attach() for reparenting, forgetting
  matrixAutoUpdate, or missing dispose() calls. Covers Object3D, Scene,
  Group, Mesh, Layers, Fog, traversal, coordinate conversion.
  Keywords: scene graph, Object3D, add, remove, traverse, layers, fog, parent, children, visibility, Three.js scene setup, group objects, show hide object, organize scene.
license: MIT
compatibility: "Designed for Claude Code. Requires Three.js r160+."
metadata:
  author: OpenAEC-Foundation
  version: "1.0"
---

# threejs-core-scene-graph

## Quick Reference

### Scene Graph Hierarchy

| Class | Extends | Purpose |
|-------|---------|---------|
| `Object3D` | `EventDispatcher` | Base class for ALL 3D objects. Provides transform, hierarchy, traversal |
| `Scene` | `Object3D` | Root container. Adds background, environment, fog, overrideMaterial |
| `Group` | `Object3D` | Semantic container with no extra functionality. Use for logical grouping |
| `Mesh` | `Object3D` | Geometry + Material. The primary visible object in a scene |
| `Camera` | `Object3D` | View projection. ALWAYS add to scene for matrix updates |
| `Light` | `Object3D` | Illumination. ALWAYS add to scene for rendering |

### Object3D Core Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `position` | `Vector3` | `(0,0,0)` | Local position relative to parent |
| `rotation` | `Euler` | `(0,0,0,'XYZ')` | Local rotation. Linked to `quaternion` -- modifying one ALWAYS updates the other |
| `quaternion` | `Quaternion` | `(0,0,0,1)` | Local rotation as quaternion. Linked to `rotation` |
| `scale` | `Vector3` | `(1,1,1)` | Local scale. Non-uniform scale causes normal distortion |
| `visible` | `boolean` | `true` | When `false`, object and ALL descendants are skipped during rendering |
| `layers` | `Layers` | layer 0 | 32-bit bitmask for selective rendering and raycasting |
| `castShadow` | `boolean` | `false` | Whether object casts shadows |
| `receiveShadow` | `boolean` | `false` | Whether object receives shadows |
| `frustumCulled` | `boolean` | `true` | Set `false` for skyboxes or objects that MUST always render |
| `renderOrder` | `number` | `0` | Higher values render later. Use for transparency sorting |
| `name` | `string` | `""` | Human-readable label. Use `getObjectByName()` for lookup |
| `userData` | `object` | `{}` | Custom application data dictionary |

### Identity Properties

| Property | Type | Description |
|----------|------|-------------|
| `uuid` | `string` | Read-only RFC 4122 v4 identifier. Auto-generated |
| `id` | `number` | Auto-incrementing integer. Unique per runtime session |
| `name` | `string` | User-assigned. NEVER relied upon as unique identifier |
| `type` | `string` | Read-only class name (e.g., `"Mesh"`, `"Group"`) |

### Critical Warnings

**NEVER** modify `children` array directly -- ALWAYS use `add()`, `remove()`, `clear()`, or `attach()`. Direct modification breaks internal bookkeeping (parent references, event dispatch).

**NEVER** modify the children array during `traverse()` -- collect objects first, then modify after traversal completes. Adding during traversal causes unpredictable iteration.

**NEVER** use `add()` when reparenting an object that must keep its world position -- ALWAYS use `attach()` instead. `add()` preserves local transform; `attach()` preserves world transform.

**NEVER** read `matrixWorld` after changing position/rotation/scale in the same frame without calling `updateWorldMatrix(true, false)` first -- the world matrix is stale until the next render or explicit update.

**NEVER** store Three.js objects in `userData` without manual disposal -- `userData` is NOT automatically cleaned up by `dispose()`.

**NEVER** forget to dispose textures, geometries, and materials when removing objects -- `remove()` and `clear()` only detach from the scene graph, they do NOT free GPU memory.

---

## Hierarchy Methods

### add() vs attach() -- The Critical Difference

```javascript
import { Scene, Group, Mesh, BoxGeometry, MeshStandardMaterial } from 'three';

const scene = new Scene();
const groupA = new Group();
const groupB = new Group();
groupA.position.set(10, 0, 0);
groupB.position.set(0, 5, 0);
scene.add(groupA, groupB);

const mesh = new Mesh(new BoxGeometry(), new MeshStandardMaterial());
mesh.position.set(0, 0, 0);
groupA.add(mesh);
// mesh world position = (10, 0, 0) -- inherited from groupA

// WRONG: add() preserves LOCAL transform -- mesh jumps to (0, 5, 0) world
groupB.add(mesh); // auto-removes from groupA first

// CORRECT: attach() preserves WORLD transform -- mesh stays at (10, 0, 0) visually
groupA.add(mesh); // reset
groupB.attach(mesh); // mesh.position is recalculated to maintain world position
```

### remove(), removeFromParent(), clear()

```javascript
// Remove specific children
group.remove(meshA, meshB);

// Remove self from parent (safe when parent is null)
mesh.removeFromParent();

// Remove ALL children -- ALWAYS prefer over manual iteration
group.clear();
```

**Edge case:** `remove()` NEVER throws if the object is not a child -- it silently does nothing.

---

## Traversal

```javascript
// Depth-first traversal of ALL descendants
scene.traverse((object) => {
  if (object.isMesh) {
    object.castShadow = true;
  }
});

// Skip invisible objects and their subtrees
scene.traverseVisible((object) => {
  // only visits objects where visible === true
});

// Walk UP to root (does NOT include the starting object)
mesh.traverseAncestors((ancestor) => {
  console.log(ancestor.name);
});

// Find by name, id, or arbitrary property
const wall = scene.getObjectByName('north-wall');
const obj = scene.getObjectById(42);
const selectable = scene.getObjectByProperty('userData', { selectable: true });
```

**Performance:** All search methods are O(n). For frequent lookups, ALWAYS cache the reference.

---

## Matrix System

### Automatic Mode (Default)

The renderer calls `updateMatrixWorld()` on the scene before every render, which recursively:
1. Calls `updateMatrix()` on each object (composes `matrix` from position/rotation/scale)
2. Computes `matrixWorld = parent.matrixWorld * matrix`

### Manual Mode (Performance Optimization)

```javascript
// For static objects -- skip per-frame matrix recomputation
object.matrixAutoUpdate = false;
object.matrix.compose(position, quaternion, scale);
object.matrixWorldNeedsUpdate = true;
```

### Reading World-Space Values Mid-Frame

```javascript
import { Vector3, Quaternion } from 'three';

object.position.set(10, 0, 0);
object.updateWorldMatrix(true, false); // update parents first

const worldPos = new Vector3();
object.getWorldPosition(worldPos);

const worldQuat = new Quaternion();
object.getWorldQuaternion(worldQuat);

const worldScale = new Vector3();
object.getWorldScale(worldScale);

const worldDir = new Vector3();
object.getWorldDirection(worldDir);
```

### Coordinate Conversion

```javascript
// MUTATION WARNING: both methods modify the input vector in-place
const localPoint = new Vector3(5, 0, 0);
object.localToWorld(localPoint); // localPoint is now in world coordinates

const worldPoint = new Vector3(15, 3, 0);
object.worldToLocal(worldPoint); // worldPoint is now in object's local coordinates
```

---

## Scene Class

```javascript
import { Scene, Color, Fog, FogExp2, TextureLoader } from 'three';

const scene = new Scene();
scene.background = new Color(0x222222);         // solid color
scene.environment = hdrTexture;                  // IBL for all PBR materials
scene.environmentIntensity = 1.5;                // boost environment lighting
scene.environmentRotation.set(0, Math.PI, 0);   // rotate environment
scene.fog = new Fog(0xcccccc, 10, 100);         // linear fog
scene.overrideMaterial = depthMaterial;          // debug: force all objects to one material
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `background` | `Color \| Texture \| CubeTexture \| null` | `null` | Scene background |
| `environment` | `Texture \| null` | `null` | IBL environment map for all PBR materials without own `envMap` |
| `fog` | `Fog \| FogExp2 \| null` | `null` | Scene fog effect |
| `overrideMaterial` | `Material \| null` | `null` | Forces ALL objects to use this material |
| `backgroundBlurriness` | `number` | `0` | Blur for background (0-1) |
| `backgroundIntensity` | `number` | `1` | Background brightness multiplier |
| `backgroundRotation` | `Euler` | `(0,0,0)` | Background rotation |
| `environmentIntensity` | `number` | `1` | Environment map brightness multiplier |
| `environmentRotation` | `Euler` | `(0,0,0)` | Environment map rotation |

---

## Fog

### Fog (Linear Interpolation)

```javascript
import { Fog } from 'three';
scene.fog = new Fog(0xffffff, 10, 200); // color, near, far
```

### FogExp2 (Exponential Density)

```javascript
import { FogExp2 } from 'three';
scene.fog = new FogExp2(0xffffff, 0.01); // color, density
```

**Material interaction:** Every material has a `fog` property (default: `true`). `ShaderMaterial` and `RawShaderMaterial` default to `fog: false` -- you MUST set `fog: true` and include fog shader chunks manually for custom shaders to respond to fog.

---

## Group

`Group` extends `Object3D` with zero additional functionality. It exists purely as a semantic container for organizing objects:

```javascript
import { Group } from 'three';

const buildingGroup = new Group();
buildingGroup.name = 'building-01';
buildingGroup.add(walls, roof, foundation);
scene.add(buildingGroup);

// Transform all children together
buildingGroup.position.set(50, 0, 0);
buildingGroup.rotation.y = Math.PI / 4;
```

---

## Mesh

`Mesh` combines a `BufferGeometry` with a `Material` to create a visible surface:

```javascript
import { Mesh, BoxGeometry, MeshStandardMaterial } from 'three';

const mesh = new Mesh(
  new BoxGeometry(1, 1, 1),
  new MeshStandardMaterial({ color: 0x00ff00 })
);

// Multi-material with geometry groups
const materials = [materialA, materialB];
geometry.addGroup(0, 36, 0);   // start, count, materialIndex
geometry.addGroup(36, 36, 1);
const multiMesh = new Mesh(geometry, materials);

// Morph targets
mesh.morphTargetInfluences[0] = 0.5; // blend between base and morph target
```

---

## Layers System

A 32-bit bitmask system for selective rendering and raycasting:

```javascript
import { Layers } from 'three';

// Objects are on layer 0 by default
mesh.layers.set(1);        // ONLY layer 1 (removes from layer 0)
mesh.layers.enable(2);     // add layer 2 (keep layer 1)
mesh.layers.disable(1);    // remove layer 1
mesh.layers.toggle(3);     // flip layer 3

// Camera renders only objects with overlapping layers
camera.layers.enable(1);   // camera now sees layers 0 AND 1

// Test overlap
const visible = camera.layers.test(mesh.layers); // true if any layer overlaps
```

**Use cases:**
- Layer 0: default visible objects
- Layer 1: helpers/gizmos (disable on production camera)
- Layer 2: bloom-only objects (selective post-processing)
- Layers 3-31: custom (collision groups, selection sets, LOD groups)

---

## lookAt() Behavior Difference

```javascript
// Camera: points NEGATIVE-Z toward target (looks AT the target)
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

// Non-camera objects: points POSITIVE-Z toward target
mesh.lookAt(targetPosition);
```

ALWAYS call `lookAt()` after setting `position` -- it computes rotation from the current position.

---

## Reference Links

- [references/methods.md](references/methods.md) -- Complete Object3D, Scene, Group, Mesh, Layers API signatures
- [references/examples.md](references/examples.md) -- Working code examples for common scene graph operations
- [references/anti-patterns.md](references/anti-patterns.md) -- What NOT to do with scene graph management

### Official Sources

- https://threejs.org/docs/#api/en/core/Object3D
- https://threejs.org/docs/#api/en/scenes/Scene
- https://threejs.org/docs/#api/en/scenes/Fog
- https://threejs.org/docs/#api/en/scenes/FogExp2
- https://threejs.org/docs/#api/en/objects/Group
- https://threejs.org/docs/#api/en/objects/Mesh
- https://threejs.org/docs/#api/en/core/Layers
Pliki w paczce (5)
  • .gitkeep 1 KB
  • SKILL.md 12 KB
  • references/anti-patterns.md 9 KB
  • references/examples.md 8 KB
  • references/methods.md 11 KB

Wersje

W bazie nie ma innych skilli o nazwie threejs-core-scene-graph.

Migawka bazy z 13.11.2026 · wersja paczki fe8b6405871f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100threejs-objects
    Zarządza obiektami sceny Three.js: hierarchią, siatkami, instancingiem, szkieletami, LOD i wyborem obiektów.
  • 100threejs-fundamentals
    Tworzy scenę Three.js od podstaw: mgłę, kamery, renderer, pętlę animacji, hierarchię obiektów i przekształcenia.
  • 100threejs-errors-performance
    Diagnozuje wydajność sceny Three.js: niski FPS, wycieki pamięci, zbyt wiele wywołań rysowania i zużycie pamięci GPU.
  • 100threejs-fundamentals
    Konfiguruje sceny 3D w Three.js: kamery, renderer, hierarchię Object3D i układy współrzędnych.
  • 100threejs-fundamentals
    Pomaga ustawiać sceny Three.js: kamery, renderer, drzewo Object3D i transformacje oraz układ współrzędnych.
  • 100threejs-fundamentals
    Prowadzi przez podstawy Three.js: konfigurację sceny, kamery, renderery, hierarchię Object3D, układy współrzędnych i transformacje.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.