@dcl-regenesislabs/opendcl 0.1.0-22234509684.commit-63dfd19

package/skills/multiplayer-sync/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: multiplayer-sync
+description: Synchronize state between players in Decentraland multiplayer scenes using CRDT-based networking. Use when user wants multiplayer, sync state, network entities, shared world state, or real-time collaboration.
+---
+
+# Multiplayer Synchronization in Decentraland
+
+Decentraland scenes are inherently multiplayer. All players in the same scene share the same space. SDK7 uses CRDT-based synchronization.
+
+## How Sync Works
+
+- Components on entities created via `engine.addEntity()` are **automatically synced** between all players in the scene.
+- The Decentraland runtime uses CRDTs (Conflict-free Replicated Data Types) to resolve conflicts.
+- Last-write-wins semantics for most components (Transform, Material, etc.).
+- No server code needed — sync is built into the runtime.
+
+## Basic Synced Entity
+
+Any entity with standard components syncs automatically:
+
+```typescript
+import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
+import { Vector3, Color4 } from '@dcl/sdk/math'
+
+// This entity and all its components sync to all players
+const sharedCube = engine.addEntity()
+Transform.create(sharedCube, { position: Vector3.create(8, 1, 8) })
+MeshRenderer.setBox(sharedCube)
+Material.setPbrMaterial(sharedCube, { albedoColor: Color4.Red() })
+
+// When any player changes the transform, all players see it
+function moveCube() {
+  const transform = Transform.getMutable(sharedCube)
+  transform.position.x += 1  // All players see this change
+}
+```
+
+## Custom Synced Components
+
+Define custom components that sync between players:
+
+```typescript
+import { engine, Schemas } from '@dcl/sdk/ecs'
+
+// Define a custom synced component
+const ScoreBoard = engine.defineComponent('scoreBoard', {
+  score: Schemas.Int,
+  playerName: Schemas.String,
+  lastUpdated: Schemas.Int64
+})
+
+// Use it on an entity — automatically syncs
+const board = engine.addEntity()
+ScoreBoard.create(board, { score: 0, playerName: '', lastUpdated: 0 })
+
+// Update from any player
+function addScore(points: number) {
+  const data = ScoreBoard.getMutable(board)
+  data.score += points
+  data.lastUpdated = Date.now()
+}
+```
+
+## Player-Specific Data
+
+Use `PlayerIdentityData` to distinguish players:
+
+```typescript
+import { engine, PlayerIdentityData } from '@dcl/sdk/ecs'
+
+engine.addSystem(() => {
+  for (const [entity] of engine.getEntitiesWith(PlayerIdentityData)) {
+    const data = PlayerIdentityData.get(entity)
+    console.log('Player:', data.address, 'Guest:', data.isGuest)
+  }
+})
+```
+
+## Schema Types
+
+Available schema types for custom components:
+
+| Type | Usage |
+|------|-------|
+| `Schemas.Boolean` | true/false |
+| `Schemas.Int` | Integer numbers |
+| `Schemas.Float` | Decimal numbers |
+| `Schemas.String` | Text strings |
+| `Schemas.Int64` | Large integers (timestamps) |
+| `Schemas.Vector3` | 3D coordinates |
+| `Schemas.Quaternion` | Rotations |
+| `Schemas.Color3` | RGB colors |
+| `Schemas.Color4` | RGBA colors |
+| `Schemas.Entity` | Entity reference |
+| `Schemas.Array(innerType)` | Array of values |
+| `Schemas.Map(valueType)` | Key-value maps |
+| `Schemas.Optional(innerType)` | Nullable values |
+| `Schemas.Enum(enumType)` | Enum values |
+
+## Communication Patterns
+
+### Global State (Shared Object)
+```typescript
+// One entity holds shared game state
+const gameState = engine.addEntity()
+const GameState = engine.defineComponent('gameState', {
+  phase: Schemas.String,
+  timeRemaining: Schemas.Int,
+  isActive: Schemas.Boolean
+})
+GameState.create(gameState, { phase: 'waiting', timeRemaining: 60, isActive: false })
+```
+
+### Per-Player State
+```typescript
+// Track each player's state separately using their entity
+engine.addSystem(() => {
+  for (const [entity] of engine.getEntitiesWith(PlayerIdentityData)) {
+    // Each player's entity is unique to them
+    // Attach custom components to player entities for per-player data
+  }
+})
+```
+
+## Important Notes
+
+- **All component changes sync automatically** — no explicit "send" calls needed
+- **CRDT resolution**: If two players change the same component simultaneously, last-write-wins
+- **No server-side code**: Decentraland scenes run entirely client-side with CRDT sync
+- **Entity limits apply**: Each synced entity counts toward the scene's entity budget
+- **Custom schemas must be deterministic**: Same component name = same schema across all clients
+- For server-authoritative multiplayer with validation and anti-cheat, see the `authoritative-server` skill

package/skills/nft-blockchain/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: nft-blockchain
+description: Display NFT artwork and interact with blockchain from Decentraland scenes. Show NFTs using NftShape with frame styles, check player wallet with getPlayer, sign messages with signedFetch, interact with smart contracts using eth-connect and createEthereumProvider, and handle MANA transactions. Use when user wants NFTs, blockchain, wallet, smart contracts, Web3, or crypto.
+---
+
+# NFT and Blockchain in Decentraland
+
+## Display NFT Artwork
+
+Show an NFT from Ethereum in a decorative frame:
+
+```typescript
+import { engine, Transform, NftShape, NftFrameType } from '@dcl/sdk/ecs'
+import { Vector3, 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
+})
+```
+
+### NFT URN Format
+
+```
+urn:decentraland:ethereum:erc721:<contractAddress>:<tokenId>
+```
+
+- Works with any ERC-721 NFT on Ethereum mainnet
+- The image is loaded automatically from the NFT's metadata
+
+### 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
+```
+
+## Check Player Wallet
+
+```typescript
+import { getPlayer } from '@dcl/sdk/src/players'
+
+function checkWallet() {
+  const player = getPlayer()
+  if (player && !player.isGuest) {
+    console.log('Player wallet address:', player.userId)
+    // userId is the Ethereum wallet address
+  } else {
+    console.log('Player is guest (no wallet)')
+  }
+}
+```
+
+Always check `isGuest` before attempting any blockchain interaction — guest players don't have a connected wallet.
+
+## Signed Requests
+
+Send authenticated requests to a backend, signed with the player's wallet:
+
+```typescript
+import { signedFetch } from '@dcl/sdk/signed-fetch'
+
+executeTask(async () => {
+  try {
+    const response = await signedFetch('https://example.com/api/action', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        action: 'claimReward',
+        amount: 100
+      })
+    })
+
+    const result = await response.json()
+    console.log('Result:', result)
+  } catch (error) {
+    console.log('Request failed:', error)
+  }
+})
+```
+
+`signedFetch` automatically includes a cryptographic signature proving the player's identity. Your backend can verify this signature to authenticate requests.
+
+## MANA Transactions
+
+```typescript
+import { manaUser } from '@dcl/sdk/ethereum'
+
+executeTask(async () => {
+  try {
+    // Check MANA balance
+    const balance = await manaUser.balance()
+    console.log('MANA balance:', balance)
+
+    // Send MANA to another address
+    const result = await manaUser.send('0x123...abc', 100) // 100 MANA
+    console.log('MANA sent:', result)
+  } catch (error) {
+    console.log('MANA transaction failed:', error)
+  }
+})
+```
+
+## Smart Contract Interaction
+
+Requires the `eth-connect` package:
+
+```bash
+npm install eth-connect
+```
+
+### Store ABI in a Separate File
+
+```typescript
+// contracts/myContract.ts
+export default [
+  {
+    "constant": true,
+    "inputs": [{ "name": "_owner", "type": "address" }],
+    "name": "balanceOf",
+    "outputs": [{ "name": "balance", "type": "uint256" }],
+    "type": "function"
+  }
+  // ... rest of ABI
+]
+```
+
+### Create Contract Instance
+
+```typescript
+import { RequestManager, ContractFactory } from 'eth-connect'
+import { createEthereumProvider } from '@dcl/sdk/ethereum-provider'
+import { abi } from '../contracts/myContract'
+
+executeTask(async () => {
+  try {
+    // Create web3 provider
+    const provider = createEthereumProvider()
+    const requestManager = new RequestManager(provider)
+
+    // Create contract at a specific address
+    const factory = new ContractFactory(requestManager, abi)
+    const contract = await factory.at('0x2a8fd99c19271f4f04b1b7b9c4f7cf264b626edb') as any
+
+    // Read data (no gas required)
+    const balance = await contract.balanceOf('0x123...abc')
+    console.log('Balance:', balance)
+  } catch (error) {
+    console.log('Contract interaction failed:', error)
+  }
+})
+```
+
+### Write Operations (Require Gas)
+
+```typescript
+executeTask(async () => {
+  try {
+    const userData = getPlayer()
+    if (userData.isGuest) return
+
+    // Write operation — prompts the player to sign the transaction
+    const writeResult = await contract.transfer(
+      '0xRecipientAddress',
+      100,
+      {
+        from: userData.userId,
+        gas: 100000,
+        gasPrice: await requestManager.eth_gasPrice()
+      }
+    )
+    console.log('Transaction hash:', writeResult)
+  } catch (error) {
+    console.log('Transaction failed:', error)
+  }
+})
+```
+
+### Gas Price and Balance Checking
+
+```typescript
+import { RequestManager } from 'eth-connect'
+import { createEthereumProvider } from '@dcl/sdk/ethereum-provider'
+
+executeTask(async () => {
+  const provider = createEthereumProvider()
+  const requestManager = new RequestManager(provider)
+
+  const gasPrice = await requestManager.eth_gasPrice()
+  console.log('Current gas price:', gasPrice)
+
+  const balance = await requestManager.eth_getBalance('0x123...abc', 'latest')
+  console.log('Account balance:', balance)
+})
+```
+
+## Testing with Sepolia
+
+For development, use the Sepolia testnet:
+
+1. Set MetaMask to Sepolia network
+2. Get test ETH from a Sepolia faucet
+3. Deploy your contracts to Sepolia
+4. Contract addresses differ between mainnet and testnet — use environment checks
+
+## Best Practices
+
+- **Always check `isGuest`** before any blockchain interaction — guest players can't sign transactions
+- Use `executeTask(async () => { ... })` for all async blockchain calls
+- Store ABI files separately (e.g., `contracts/`) — don't inline large ABIs
+- Handle errors gracefully — blockchain operations can fail (rejected by user, insufficient gas, network issues)
+- `eth-connect` must be installed as a dependency: `npm install eth-connect`
+- Use `signedFetch` for backend authentication instead of raw `fetch` — it proves the player's identity
+- Read operations (view/pure functions) don't require gas; write operations prompt the user to sign
+- Test on Sepolia before deploying to mainnet
+- NFT URNs only work with Ethereum mainnet ERC-721 tokens
+
+For component field details, see `context/components-reference.md`.

package/skills/optimize-scene/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: optimize-scene
+description: Optimize Decentraland scene performance, reduce entity count, minimize triangle budgets, improve loading times, and stay within scene limits. Use when user wants to optimize, improve performance, fix lag, reduce load time, or check scene limits.
+---
+
+# Optimizing Decentraland Scenes
+
+## Scene Limits (Per Parcel Count)
+
+| Parcels | Max Entities | Max Triangles | Max Textures | Max Materials | Max Height |
+|---------|-------------|---------------|-------------|--------------|-----------|
+| 1 | 512 | 10,000 | 10 MB | 20 | 20m |
+| 2 | 1,024 | 20,000 | 20 MB | 40 | 20m |
+| 4 | 2,048 | 40,000 | 40 MB | 80 | 20m |
+| 8 | 4,096 | 80,000 | 80 MB | 160 | 20m |
+| 16 | 8,192 | 160,000 | 160 MB | 320 | 20m |
+
+## Entity Count Optimization
+
+### Reuse Entities
+```typescript
+// BAD: Creating new entity each time
+function spawnBullet() {
+  const bullet = engine.addEntity() // Creates entity every call
+  // ...
+}
+
+// GOOD: Object pooling
+const bulletPool: Entity[] = []
+function getBullet(): Entity {
+  const existing = bulletPool.find(e => !ActiveBullet.has(e))
+  if (existing) return existing
+  const newBullet = engine.addEntity()
+  bulletPool.push(newBullet)
+  return newBullet
+}
+```
+
+### Remove Unused Entities
+```typescript
+engine.removeEntity(entity) // Frees the entity slot
+```
+
+### Use Parenting
+Instead of separate transforms for each child, use entity hierarchy:
+```typescript
+const parent = engine.addEntity()
+Transform.create(parent, { position: Vector3.create(8, 0, 8) })
+
+// Children inherit parent transform
+const child1 = engine.addEntity()
+Transform.create(child1, { position: Vector3.create(0, 1, 0), parent })
+
+const child2 = engine.addEntity()
+Transform.create(child2, { position: Vector3.create(1, 1, 0), parent })
+```
+
+## Triangle Count Optimization
+
+### Use Lower-Poly Models
+- Small props: 100-500 triangles
+- Medium objects: 500-1,500 triangles
+- Large buildings: 1,500-5,000 triangles
+- Hero pieces: Up to 10,000 triangles
+
+### Use LOD (Level of Detail)
+Show simpler models at distance:
+```typescript
+engine.addSystem(() => {
+  // Check distance to player and swap models
+  const playerPos = Transform.get(engine.PlayerEntity).position
+  const objPos = Transform.get(myEntity).position
+  const distance = Vector3.distance(playerPos, objPos)
+
+  const gltf = GltfContainer.getMutable(myEntity)
+  if (distance > 30) {
+    gltf.src = 'models/building_lod2.glb' // Low poly
+  } else if (distance > 15) {
+    gltf.src = 'models/building_lod1.glb' // Medium poly
+  } else {
+    gltf.src = 'models/building_lod0.glb' // High poly
+  }
+})
+```
+
+### Use Primitives Instead of Models
+For simple shapes, `MeshRenderer` is lighter than loading a .glb:
+```typescript
+MeshRenderer.setBox(entity)    // Very cheap
+MeshRenderer.setSphere(entity) // Cheap
+MeshRenderer.setPlane(entity)  // Very cheap
+```
+
+## Texture Optimization
+
+- Use `.png` for UI/sprites with transparency
+- Use `.jpg` for photos and textures without transparency
+- Compress textures: 512x512 or 1024x1024 max for most use cases
+- Use texture atlases (combine multiple textures into one image)
+- Avoid 4096x4096 textures unless absolutely necessary
+- Reuse materials across entities:
+```typescript
+// GOOD: Define material once, apply to many
+Material.setPbrMaterial(entity1, { texture: Material.Texture.Common({ src: 'images/wall.jpg' }) })
+Material.setPbrMaterial(entity2, { texture: Material.Texture.Common({ src: 'images/wall.jpg' }) })
+// Same texture URL = shared in memory
+```
+
+## System Optimization
+
+### Avoid Per-Frame Allocations
+```typescript
+// BAD: Creates new Vector3 every frame
+engine.addSystem(() => {
+  const target = Vector3.create(8, 1, 8) // Allocation!
+})
+
+// GOOD: Reuse constants
+const TARGET = Vector3.create(8, 1, 8)
+engine.addSystem(() => {
+  // Use TARGET
+})
+```
+
+### Throttle Expensive Operations
+```typescript
+let lastCheck = 0
+engine.addSystem((dt) => {
+  lastCheck += dt
+  if (lastCheck < 0.5) return // Only run every 0.5 seconds
+  lastCheck = 0
+  // Expensive operation here
+})
+```
+
+### Remove Systems When Not Needed
+```typescript
+const systemFn = (dt: number) => { /* ... */ }
+engine.addSystem(systemFn)
+
+// When no longer needed:
+engine.removeSystem(systemFn)
+```
+
+## Loading Time Optimization
+
+- Lazy-load 3D models (load on demand, not all at scene start)
+- Use compressed .glb files (Draco compression)
+- Minimize total asset size
+- Use CDN URLs for large shared assets when possible
+- Preload critical assets, defer non-essential ones
+
+## Common Performance Pitfalls
+
+1. **Too many systems**: Each system runs every frame. Combine related logic.
+2. **Unnecessary component queries**: Cache `engine.getEntitiesWith()` results when the set doesn't change.
+3. **Large GLTF files**: Optimize in Blender before export (decimate, remove hidden faces).
+4. **Uncompressed audio**: Use .mp3 instead of .wav for music (10x smaller).
+5. **Continuous raycasting**: Set `continuous: false` unless you need per-frame raycasting.
+6. **Text rendering**: `TextShape` is expensive. Use `Label` (UI) for text that doesn't need to be in 3D space.