@dcl-regenesislabs/opendcl 0.2.0 → 0.2.1-26238928766.commit-28648d7

package/skills/game-design/SKILL.md

@@ -17,7 +17,7 @@ Decentraland is a **continuous, shared 3D world**. Design around these constrain
 
 ## 2. Scene Limitation Formulas
 
-All limits scale with parcel count `n`. Know these formulas and design within them.
+All limits scale with parcel count `n`. **Except for hard MB file-size limits on deploy, all other limits CAN be exceeded** — scenes won't crash, but performance degrades and the scene may be unusable on low-end devices. Treat the table as guidelines, not enforcement.
 
 | Resource | Formula | 1 parcel | 2 parcels | 4 parcels | 9 parcels | 16 parcels |
 |---|---|---|---|---|---|---|
@@ -35,7 +35,6 @@ All limits scale with parcel count `n`. Know these formulas and design within th
 
 - **Dimensions must be power-of-two**: 256, 512, 1024, 2048
 - **Recommended sizes**: 1024x1024 for scene objects, 512x512 for wearables
-- **Avoid textures over 2048x2048** — they consume excessive memory and often exceed limits
 - **Use texture atlases** to combine multiple small textures into one, reducing draw calls and material count
 - Prefer compressed formats (WebP) over raw PNG where possible
 - Share texture references across materials — do not duplicate texture files

package/skills/lighting-environment/SKILL.md

@@ -5,22 +5,47 @@ description: Dynamic lighting and environment in Decentraland scenes. LightSourc
 
 # Lighting and Environment in Decentraland
 
-## Point Lights
+## Authoring split
 
-Emit light in all directions from a position:
+`LightSource` is supported in `main-entities.ts` — declare the lamp's fixture model AND its light in the same entry. The user can drag the fixture in the editor and the light follows.
 
 ```typescript
-import { engine, Transform, LightSource } from '@dcl/sdk/ecs'
-import { Vector3, Color3 } from '@dcl/sdk/math'
+// main-entities.ts
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  ceiling_lamp: {
+    components: {
+      Transform: { position: { x: 8, y: 3, z: 8 } },
+      GltfContainer: { src: 'models/lamp.glb' },
+      LightSource: {
+        type: { $case: 'point', point: {} },
+        color: { r: 1, g: 1, b: 1 },
+        intensity: 16000
+      }
+    }
+  }
+} satisfies Scene
+```
 
-const light = engine.addEntity()
-Transform.create(light, { position: Vector3.create(8, 3, 8) })
+For purely decorative lights with no mesh, declare a Transform-only entity and skip `GltfContainer`. Toggling lights at runtime still happens in `src/index.ts` via `LightSource.getMutable(getEntityOrNullByName('ceiling_lamp'))`.
 
-LightSource.create(light, {
-  type: LightSource.Type.Point({}),
-  color: Color3.White(),
-  intensity: 300  // candela
-})
+## Point Lights
+
+Emit light in all directions from a position:
+
+```typescript
+// main-entities.ts entry
+ambient_point: {
+  components: {
+    Transform: { position: { x: 8, y: 3, z: 8 } },
+    LightSource: {
+      type: { $case: 'point', point: {} },
+      color: { r: 1, g: 1, b: 1 },
+      intensity: 16000  // candela — point lights typically need 8000–32000 to be visible
+    }
+  }
+}
 ```
 
 ### Colored Point Light
@@ -29,29 +54,31 @@ LightSource.create(light, {
 LightSource.create(light, {
   type: LightSource.Type.Point({}),
   color: Color3.create(1, 0.5, 0),  // Warm orange
-  intensity: 200,
+  intensity: 12000,
   range: 15  // Maximum distance in meters
 })
 ```
 
 ## Spot Lights
 
-Emit a cone of light in a direction:
+Emit a cone of light in a direction. The cone's orientation comes from the entity's Transform rotation.
 
 ```typescript
-import { Quaternion } from '@dcl/sdk/math'
-
-const spotlight = engine.addEntity()
-Transform.create(spotlight, {
-  position: Vector3.create(8, 4, 8),
-  rotation: Quaternion.fromEulerDegrees(-90, 0, 0)  // Point downward
-})
-
-LightSource.create(spotlight, {
-  type: LightSource.Type.Spot({ innerAngle: 25, outerAngle: 45 }),
-  color: Color3.White(),
-  intensity: 800
-})
+// main-entities.ts
+stage_spot: {
+  components: {
+    Transform: {
+      position: { x: 8, y: 4, z: 8 },
+      rotation: { x: -0.7071, y: 0, z: 0, w: 0.7071 }  // pitch -90° (down)
+    },
+    GltfContainer: { src: 'models/spotlight.glb' },
+    LightSource: {
+      type: { $case: 'spot', spot: { innerAngle: 25, outerAngle: 45 } },
+      color: { r: 1, g: 1, b: 1 },
+      intensity: 16000
+    }
+  }
+}
 ```
 
 - `innerAngle` — full-brightness cone angle (degrees)
@@ -66,10 +93,12 @@ Enable shadows on point or spot lights:
 LightSource.create(spotlight, {
   type: LightSource.Type.Spot({ innerAngle: 25, outerAngle: 45 }),
   shadow: true,
-  intensity: 800
+  intensity: 16000
 })
 ```
 
+> Shadows are only available on **spot lights**, not point lights.
+
 ### Shadow Mask Textures (Gobos)
 
 Project a pattern through the light:
@@ -91,10 +120,11 @@ lightData.active = !lightData.active
 
 ## Light Limits
 
-- Maximum **one active light per parcel** (16m x 16m)
-- The renderer auto-culls lights based on quality settings and proximity
-- Up to ~3 shadowed lights visible at once
-- Intensity is in candela — visible distance grows roughly with `sqrt(intensity)`
+- Maximum **one active light per parcel** (16m x 16m) — multi-parcel scenes can group lights close together when needed.
+- The renderer auto-culls lights based on quality settings and proximity. Quality range allows **4–10 lights visible simultaneously**.
+- Shadows are only available on spot lights; up to ~3 shadowed lights visible at once.
+- Intensity is in candela. Practical visible range: point lights ~8000–32000, spot lights ~10000–24000. Values below ~1000 are usually invisible.
+- Emissive materials **don't illuminate surrounding entities** — they only have a glow effect on themselves. Combine an emissive material with a `LightSource` for both.
 
 ## SkyboxTime (Day/Night Cycle)
 
@@ -171,38 +201,55 @@ executeTask(async () => {
 
 ## Emissive Materials (Glow Effects)
 
-For a visual glow without casting light on surroundings:
+`Material` is supported in `main-entities.ts`, so a glow that doesn't need to cast light on surroundings can be declared inline:
 
 ```typescript
-import { engine, Material } from '@dcl/sdk/ecs'
-import { Color4, Color3 } from '@dcl/sdk/math'
-
-// Self-illuminated material (emissiveColor uses Color3, not Color4)
-Material.setPbrMaterial(entity, {
-  albedoColor: Color4.create(0, 0, 0, 1),
-  emissiveColor: Color3.create(0, 1, 0),  // Green glow
-  emissiveIntensity: 2.0
-})
+// main-entities.ts
+glowing_orb: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    MeshRenderer: { mesh: { $case: 'sphere', sphere: {} } },
+    Material: {
+      material: {
+        $case: 'pbr',
+        pbr: {
+          albedoColor: { r: 0, g: 0, b: 0, a: 1 },
+          emissiveColor: { r: 0, g: 1, b: 0 },
+          emissiveIntensity: 2.0
+        }
+      }
+    }
+  }
+}
 ```
 
 ### Combining Emissive + LightSource
 
-For an object that both glows visually and casts light:
+A single entity can carry both — emissive glow on the material AND light emission.
 
 ```typescript
-// Visual glow on the mesh
-Material.setPbrMaterial(bulb, {
-  emissiveColor: Color3.create(1, 0.9, 0.7),
-  emissiveIntensity: 1.5
-})
-
-// Actual light emission
-LightSource.create(bulb, {
-  type: LightSource.Type.Point({}),
-  color: Color3.create(1, 0.9, 0.7),
-  intensity: 200,
-  range: 10
-})
+// main-entities.ts
+bulb: {
+  components: {
+    Transform: { position: { x: 8, y: 3, z: 8 } },
+    GltfContainer: { src: 'models/bulb.glb' },
+    Material: {
+      material: {
+        $case: 'pbr',
+        pbr: {
+          emissiveColor: { r: 1, g: 0.9, b: 0.7 },
+          emissiveIntensity: 1.5
+        }
+      }
+    },
+    LightSource: {
+      type: { $case: 'point', point: {} },
+      color: { r: 1, g: 0.9, b: 0.7 },
+      intensity: 12000,
+      range: 10
+    }
+  }
+}
 ```
 
 ### Shadow Types
@@ -220,7 +267,7 @@ LightSource.create(spotEntity, {
     shadow: PBLightSource_ShadowType.ST_SOFT
   }),
   shadow: true,
-  intensity: 800
+  intensity: 16000
 })
 ```
 

package/skills/multiplayer-sync/SKILL.md

@@ -5,7 +5,36 @@ description: Synchronize state between players in Decentraland using CRDT networ
 
 # Multiplayer Synchronization in Decentraland
 
-Decentraland scenes are inherently multiplayer. All players in the same scene share the same space. SDK7 uses CRDT-based synchronization.
+## Authoring split
+
+`syncEntity()` adds a `NetworkEntity` component at runtime — and `NetworkEntity` is **not** in `main-entities.ts`'s supported component list. The pattern is:
+
+- **Predefined synced entities** (a door, a switch, a scoreboard — known at author time): declare them in `main-entities.ts` with their visual components. Look them up in `src/index.ts` and call `syncEntity(entity, [...componentIds], SyncIds.NAME)` there.
+- **Dynamically-spawned synced entities** (projectiles, drops, runtime-created game objects): create with `engine.addEntity()` in `src/index.ts` and `syncEntity` immediately.
+
+```typescript
+// main-entities.ts
+door: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    MeshRenderer: { mesh: { $case: 'box', box: { uvs: [] } } }
+  }
+}
+```
+
+```typescript
+// src/index.ts
+import { engine, Transform, syncEntity } from '@dcl/sdk/network'
+
+export function main() {
+  const door = engine.getEntityOrNullByName('door')
+  if (door) syncEntity(door, [Transform.componentId], SyncIds.DOOR)
+}
+```
+
+Decentraland scenes are inherently multiplayer — every player in the same scene shares the same space. **By default, however, players interact with the environment independently — changes one player makes are NOT shared with others.** Opt in to sharing by wrapping mutable state in `syncEntity`, broadcasting events through `MessageBus`, or persisting through your own backend.
+
+`syncEntity` state persists only as long as **at least one player remains in the scene**. The state resets as soon as the scene is empty. For durable state across scene resets, persist to your own server.
 
 > **Runtime constraint:** Decentraland runs in a QuickJS sandbox. No Node.js APIs (`fs`, `http`, `path`, `process`). Use `fetch()` and `WebSocket` for network communication. See the **scene-runtime** skill for async patterns.
 
@@ -24,7 +53,7 @@ Choose the right networking approach based on what you need:
 **Decision flow:**
 1. Does every player need to see the same state, including late joiners? --> `syncEntity`
 2. Is it a fire-and-forget event only for players currently in the scene? --> `MessageBus`
-3. Do you need to talk to an external server? --> `fetch` or `signedFetch`
+3. Do you need state persisted after all players leave, or server-side validation? --> external server via `fetch` or `signedFetch`
 4. Do you need continuous real-time server communication? --> `WebSocket`
 5. Combine approaches freely: use `syncEntity` for world state, `MessageBus` for effects, and `fetch` for persistence.
 

package/skills/nft-blockchain/SKILL.md

@@ -7,25 +7,28 @@ description: NFT display and blockchain interaction in Decentraland. NftShape (f
 
 ## Display NFT Artwork
 
-Show an NFT from Ethereum in a decorative frame:
+`NftShape` is supported in `main-entities.ts` — declare the framed NFT directly. The user can drag it around in the visual editor.
 
 ```typescript
-import { engine, Transform, NftShape, NftFrameType } from '@dcl/sdk/ecs'
-import { Vector3, Quaternion, Color4 } from '@dcl/sdk/math'
-
-const nftFrame = engine.addEntity()
-Transform.create(nftFrame, {
-  position: Vector3.create(8, 2, 8),
-  rotation: Quaternion.fromEulerDegrees(0, 0, 0)
-})
-
-NftShape.create(nftFrame, {
-  urn: 'urn:decentraland:ethereum:erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d:558536',
-  color: Color4.White(),
-  style: NftFrameType.NFT_CLASSIC
-})
+// main-entities.ts
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  hero_nft: {
+    components: {
+      Transform: { position: { x: 8, y: 2, z: 8 } },
+      NftShape: {
+        urn: 'urn:decentraland:ethereum:erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d:558536',
+        color: { r: 1, g: 1, b: 1, a: 1 },
+        style: 0  // NftFrameType.NFT_CLASSIC — enum values are integers in the literal
+      }
+    }
+  }
+} satisfies Scene
 ```
 
+The `style` field is a numeric enum — the literal cannot reference `NftFrameType.NFT_CLASSIC` directly because the AST walker only accepts JSON-compatible expressions. Use the integer value (table below) and leave a comment.
+
 ### NFT URN Format
 
 ```
@@ -37,31 +40,33 @@ urn:decentraland:ethereum:erc721:<contractAddress>:<tokenId>
 
 ### Available Frame Styles
 
-```typescript
-NftFrameType.NFT_CLASSIC            // Simple classic frame
-NftFrameType.NFT_BAROQUE_ORNAMENT   // Ornate baroque
-NftFrameType.NFT_DIAMOND_ORNAMENT   // Diamond pattern
-NftFrameType.NFT_MINIMAL_WIDE       // Minimal wide border
-NftFrameType.NFT_MINIMAL_GREY       // Minimal grey border
-NftFrameType.NFT_BLOCKY             // Pixelated/blocky
-NftFrameType.NFT_GOLD_EDGES         // Gold edge trim
-NftFrameType.NFT_GOLD_CARVED        // Carved gold
-NftFrameType.NFT_GOLD_WIDE          // Wide gold border
-NftFrameType.NFT_GOLD_ROUNDED       // Rounded gold
-NftFrameType.NFT_METAL_MEDIUM       // Medium metal
-NftFrameType.NFT_METAL_WIDE         // Wide metal
-NftFrameType.NFT_METAL_SLIM         // Slim metal
-NftFrameType.NFT_METAL_ROUNDED      // Rounded metal
-NftFrameType.NFT_PINS               // Pinned to wall
-NftFrameType.NFT_MINIMAL_BLACK      // Minimal black
-NftFrameType.NFT_MINIMAL_WHITE      // Minimal white
-NftFrameType.NFT_TAPE               // Taped to wall
-NftFrameType.NFT_WOOD_SLIM          // Slim wood
-NftFrameType.NFT_WOOD_WIDE          // Wide wood
-NftFrameType.NFT_WOOD_TWIGS         // Twig/branch wood
-NftFrameType.NFT_CANVAS             // Canvas style
-NftFrameType.NFT_NONE               // No frame
-```
+| value | enum name | description |
+|---|---|---|
+| 0  | NFT_CLASSIC          | Simple classic frame |
+| 1  | NFT_BAROQUE_ORNAMENT | Ornate baroque |
+| 2  | NFT_DIAMOND_ORNAMENT | Diamond pattern |
+| 3  | NFT_MINIMAL_WIDE     | Minimal wide border |
+| 4  | NFT_MINIMAL_GREY     | Minimal grey border |
+| 5  | NFT_BLOCKY           | Pixelated/blocky |
+| 6  | NFT_GOLD_EDGES       | Gold edge trim |
+| 7  | NFT_GOLD_CARVED      | Carved gold |
+| 8  | NFT_GOLD_WIDE        | Wide gold border |
+| 9  | NFT_GOLD_ROUNDED     | Rounded gold |
+| 10 | NFT_METAL_MEDIUM     | Medium metal |
+| 11 | NFT_METAL_WIDE       | Wide metal |
+| 12 | NFT_METAL_SLIM       | Slim metal |
+| 13 | NFT_METAL_ROUNDED    | Rounded metal |
+| 14 | NFT_PINS             | Pinned to wall |
+| 15 | NFT_MINIMAL_BLACK    | Minimal black |
+| 16 | NFT_MINIMAL_WHITE    | Minimal white |
+| 17 | NFT_TAPE             | Taped to wall |
+| 18 | NFT_WOOD_SLIM        | Slim wood |
+| 19 | NFT_WOOD_WIDE        | Wide wood |
+| 20 | NFT_WOOD_TWIGS       | Twig/branch wood |
+| 21 | NFT_CANVAS           | Canvas style |
+| 22 | NFT_NONE             | No frame |
+
+In `src/index.ts` where enum identifiers are allowed, use `NftFrameType.NFT_CLASSIC` etc. directly.
 
 ## Check Player Wallet
 

package/skills/npcs/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: npcs
+description: Create NPCs (non-player characters) in Decentraland scenes. Two approaches: the NPC Toolkit library (dcl-npc-toolkit) for GLB-based NPCs with built-in dialogue, movement, and state machines; and AvatarShape for avatar-look NPCs dressed in wearables. Use when the user wants to add an NPC, character, shopkeeper, quest giver, guard, or any non-player entity with behavior or dialogue. For live player data (position, profile, wearables) see player-avatar instead.
+---
+
+# NPCs in Decentraland
+
+Two approaches — choose based on what the NPC needs to do:
+
+| Approach | Use when |
+|---|---|
+| **NPC Toolkit** (`dcl-npc-toolkit`) | GLB model, needs dialogue, walking, state machine behavior |
+| **AvatarShape** | Needs to look like a Decentraland avatar (wearables, expressions) |
+
+## Authoring split
+
+- **AvatarShape NPCs** are static and fully declarable in `main-entities.ts` (`AvatarShape` is in the supported component list). Click handlers / proximity systems live in `src/index.ts`.
+- **NPC Toolkit NPCs** are created via `createNPC(...)` from the toolkit library, which is a runtime API — call it from `src/index.ts`. The placement entity itself (a marker for the spawn position) can still live in `main-entities.ts` if you want it editable in the gizmo.
+
+---
+
+## Approach 1 — NPC Toolkit (GLB-based)
+
+The toolkit handles dialogue UI, movement along paths, animations, and interaction out of the box.
+
+**Install:**
+```bash
+npm i dcl-npc-toolkit
+```
+
+**Basic usage:**
+```typescript
+// src/index.ts
+import { createNPC, Dialog } from 'dcl-npc-toolkit'
+import { Vector3, Quaternion } from '@dcl/sdk/math'
+
+export function main() {
+  const npcEntity = createNPC(
+    { position: Vector3.create(8, 0, 8), rotation: Quaternion.fromEulerDegrees(0, 180, 0) },
+    'models/guard.glb',
+    (entity) => {
+      // called when player clicks the NPC
+      startDialogue(entity)
+    },
+    {
+      idleAnim: 'Idle',
+      walkingAnim: 'Walk',
+      hoverText: 'Talk',
+      onlyExternalTrigger: false
+    }
+  )
+}
+```
+
+### Gotchas (NPC Toolkit)
+
+- **Button labels are visually truncated.** Dialog button labels render with `textWrap: 'nowrap'` in a fixed-width slot (~217px at default font 16). Anything past ~15 characters is silently clipped — no ellipsis. Use short labels like `"Yes"`, `"No thanks"`, `"Tell me more"`, `"Decline"`. To fit longer text, drop `fontSize` (e.g. 12) or set `size` on the button.
+- Opening dialogs on an entity not created via `createNPC` requires `addDialog(entity)` and a minimal `npcDataComponent.set(entity, ...)` — see the toolkit reference for the full setup.
+- Speech bubbles need `createDialogBubble(entity)` before `talkBubble`. Bubbles do not render question buttons; questions are HUD-only.
+
+---
+
+## Approach 2 — AvatarShape (Decentraland avatar look)
+
+Create an NPC that looks like a Decentraland player avatar, dressed in any wearables. **Supported in `main-entities.ts`** — declare the NPC declaratively:
+
+```typescript
+// main-entities.ts
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  guard: {
+    components: {
+      Transform: { position: { x: 8, y: 0, z: 8 } },
+      AvatarShape: {
+        id: 'npc-1',                                                       // unique (required)
+        name: 'Guard',                                                     // shown above head
+        bodyShape: 'urn:decentraland:off-chain:base-avatars:BaseMale',
+        wearables: [
+          'urn:decentraland:off-chain:base-avatars:eyebrows_00',
+          'urn:decentraland:off-chain:base-avatars:mouth_00',
+          'urn:decentraland:off-chain:base-avatars:eyes_00',
+          'urn:decentraland:off-chain:base-avatars:blue_tshirt',
+          'urn:decentraland:off-chain:base-avatars:brown_pants',
+          'urn:decentraland:off-chain:base-avatars:classic_shoes',
+          'urn:decentraland:off-chain:base-avatars:short_hair'
+        ],
+        emotes: [],
+        hairColor: { r: 0.92, g: 0.76, b: 0.62 },
+        skinColor: { r: 0.94, g: 0.85, b: 0.6 }
+      }
+    }
+  }
+} satisfies Scene
+```
+
+**Notes:**
+- Always include eyebrows, mouth, and eyes wearables — the avatar won't render face features without them.
+- Moving the `Transform` position causes the NPC to walk/run to the destination (it does **not** teleport).
+- Use `expressionTriggerTimestamp` as a Lamport timestamp to replay the same emote: first play = 0, second play = 1, etc.
+
+### Playing expressions on an AvatarShape NPC
+
+```typescript
+// src/index.ts
+const npc = engine.getEntityOrNullByName('guard')
+if (npc) {
+  AvatarShape.getMutable(npc).expressionTriggerId = 'wave'
+  AvatarShape.getMutable(npc).expressionTriggerTimestamp = 1
+}
+```
+
+### Mannequin mode (show wearables without a body)
+
+Useful for storefronts and wearable displays:
+
+```typescript
+// main-entities.ts
+mannequin: {
+  components: {
+    Transform: { position: { x: 4, y: 0, z: 4 } },
+    AvatarShape: {
+      id: 'mannequin-1',
+      name: 'Display',
+      bodyShape: 'urn:decentraland:off-chain:base-avatars:BaseMale',
+      wearables: ['urn:decentraland:matic:collections-v2:0x...:0'],
+      emotes: [],
+      show_only_wearables: true
+    }
+  }
+}
+```
+
+For the full `AvatarShape` field reference and common base wearable URNs, see the `player-avatar` skill's references.
+
+---
+
+## Adding interactivity to AvatarShape NPCs
+
+AvatarShape entities are **not clickable by default** — they have no collider, so pointer events won't register on them directly. Use one of:
+
+### Option A — Add a MeshCollider for click interaction
+
+Declare the collider in `main-entities.ts` alongside the AvatarShape:
+
+```typescript
+// main-entities.ts (added to the guard entry above)
+MeshCollider: { mesh: { $case: 'cylinder', cylinder: {} } }
+```
+
+```typescript
+// src/index.ts
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+
+export function main() {
+  const npc = engine.getEntityOrNullByName('guard')
+  if (npc) pointerEventsSystem.onPointerDown(
+    { entity: npc, opts: { button: InputAction.IA_POINTER, hoverText: 'Talk' } },
+    () => { console.log('Player clicked NPC') }
+  )
+}
+```
+
+### Option B — Proximity-based interaction
+
+Trigger the interaction when the player walks near the NPC (no collider required):
+
+```typescript
+import { engine, pointerEventsSystem } from '@dcl/sdk/ecs'
+
+export function main() {
+  const npc = engine.getEntityOrNullByName('guard')
+  if (npc) pointerEventsSystem.onProximityEnter(
+    { entity: npc, opts: { maxPlayerDistance: 4 } },
+    () => { /* start dialogue or other interaction */ }
+  )
+}
+```
+
+See the `add-interactivity` skill for the full Proximity Events API.

package/skills/optimize-scene/SKILL.md

@@ -5,9 +5,15 @@ description: Optimize Decentraland scene performance. Scene limit formulas (tria
 
 # Optimizing Decentraland Scenes
 
+## Authoring split
+
+The patterns in this skill — object pools, LOD, asset preloading, system throttling — are all **runtime mechanics** and live in `src/index.ts`. The static layout (chairs, walls, lamps, the props that get LOD'd) should still be declared in `main-entities.ts`; the optimization code reads those entities by name (`engine.getEntityOrNullByName`) or by component query (`engine.getEntitiesWith(Transform)`).
+
+The parenting optimization (a static container with many children) is best expressed in `main-entities.ts` using `Transform.parent: 'parent_name'` — that way the editor can move the entire group as a unit.
+
 ## Scene Limits (Per Parcel Count)
 
-All limits scale with parcel count `n`. Triangles, entities, and bodies scale linearly. Materials, textures, and height scale logarithmically.
+All limits scale with parcel count `n`. Triangles, entities, and bodies scale linearly. Materials, textures, and height scale logarithmically. **Except for hard MB size limits on deploy, all other limits CAN be exceeded** — scenes won't crash, but performance degrades and the scene may become unusable on lower-end devices. Treat the numbers as guidelines, not enforcement.
 
 | Resource | Formula | 1 parcel | 2 parcels | 4 parcels | 9 parcels | 16 parcels |
 |---|---|---|---|---|---|---|
@@ -100,7 +106,6 @@ MeshRenderer.setPlane(entity)  // Very cheap
 
 - **Dimensions must be power-of-two**: 256, 512, 1024, 2048
 - **Recommended sizes**: 512x512 for most objects, 1024x1024 max for hero pieces
-- **Avoid textures over 2048x2048** — they consume excessive memory and often exceed limits
 - Use `.png` for UI/sprites with transparency
 - Use `.jpg` for photos and textures without transparency
 - Prefer compressed formats (WebP) over raw PNG where possible