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

package/skills/player-avatar/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: player-avatar
+description: Work with player avatars in Decentraland scenes. Read player position and profile data, customize appearance with AvatarBase, trigger emotes with triggerEmote/triggerSceneEmote, read equipped wearables via AvatarEquippedData, attach objects to players with AvatarAttach, create NPC avatars with AvatarShape, and modify avatars in areas. Use when user wants player data, emotes, wearables, avatar attachments, or NPCs.
+---
+
+# Player and Avatar System in Decentraland
+
+## Player Position and Movement
+
+Access the player's position via the reserved `engine.PlayerEntity`:
+
+```typescript
+import { engine, Transform } from '@dcl/sdk/ecs'
+
+function trackPlayer() {
+  if (!Transform.has(engine.PlayerEntity)) return
+
+  const playerTransform = Transform.get(engine.PlayerEntity)
+  console.log('Player position:', playerTransform.position)
+  console.log('Player rotation:', playerTransform.rotation)
+}
+
+engine.addSystem(trackPlayer)
+```
+
+### Distance-Based Logic
+
+```typescript
+import { Vector3 } from '@dcl/sdk/math'
+
+function proximityCheck() {
+  const playerPos = Transform.get(engine.PlayerEntity).position
+  const npcPos = Transform.get(npcEntity).position
+  const distance = Vector3.distance(playerPos, npcPos)
+
+  if (distance < 5) {
+    console.log('Player is near the NPC')
+  }
+}
+
+engine.addSystem(proximityCheck)
+```
+
+## Player Profile Data
+
+Get the player's name, wallet address, and guest status:
+
+```typescript
+import { getPlayer } from '@dcl/sdk/src/players'
+
+function main() {
+  const player = getPlayer()
+  if (player) {
+    console.log('Name:', player.name)
+    console.log('User ID:', player.userId)
+    console.log('Is guest:', player.isGuest)
+  }
+}
+```
+
+- `userId` — the player's Ethereum wallet address (or guest ID)
+- `isGuest` — `true` if the player hasn't connected a wallet
+
+## Avatar Attachments
+
+Attach 3D objects to a player's avatar:
+
+```typescript
+import { engine, Transform, GltfContainer, AvatarAttach, AvatarAnchorPointType } from '@dcl/sdk/ecs'
+
+const hat = engine.addEntity()
+GltfContainer.create(hat, { src: 'models/hat.glb' })
+
+// Attach to the local player's avatar
+AvatarAttach.create(hat, {
+  anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG
+})
+```
+
+### Anchor Points
+
+```typescript
+AvatarAnchorPointType.AAPT_NAME_TAG      // Above the head
+AvatarAnchorPointType.AAPT_RIGHT_HAND    // Right hand
+AvatarAnchorPointType.AAPT_LEFT_HAND     // Left hand
+AvatarAnchorPointType.AAPT_POSITION      // Avatar root position
+```
+
+### Attach to a Specific Player
+
+```typescript
+AvatarAttach.create(hat, {
+  avatarId: '0x123...abc',  // Target player's wallet address
+  anchorPointId: AvatarAnchorPointType.AAPT_RIGHT_HAND
+})
+```
+
+## Triggering Emotes
+
+### Default Emotes
+
+```typescript
+import { triggerEmote } from '~system/RestrictedActions'
+
+// Play a built-in emote
+triggerEmote({ predefinedEmote: 'robot' })
+triggerEmote({ predefinedEmote: 'wave' })
+triggerEmote({ predefinedEmote: 'clap' })
+```
+
+### Custom Scene Emotes
+
+```typescript
+import { triggerSceneEmote } from '~system/RestrictedActions'
+
+// Play a custom emote animation (file must end with _emote.glb)
+triggerSceneEmote({
+  src: 'animations/Snowball_Throw_emote.glb',
+  loop: false
+})
+```
+
+**Notes:**
+- Emotes play only while the player is standing still — walking or jumping interrupts them
+- Custom emote files must have the `_emote.glb` suffix
+
+## NPC Avatars
+
+Create avatar-shaped NPCs using `AvatarShape`:
+
+```typescript
+import { engine, Transform, AvatarShape } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const npc = engine.addEntity()
+Transform.create(npc, { position: Vector3.create(8, 0, 8) })
+
+AvatarShape.create(npc, {
+  id: 'npc-1',
+  name: 'Guard',
+  wearables: [
+    'urn:decentraland:off-chain:base-avatars:f_eyes_01',
+    'urn:decentraland:off-chain:base-avatars:f_eyebrows_01',
+    'urn:decentraland:off-chain:base-avatars:f_mouth_01',
+    'urn:decentraland:off-chain:base-avatars:sport_jacket',
+    'urn:decentraland:off-chain:base-avatars:oxford_pants'
+  ]
+})
+```
+
+NPC avatars are static — they display the avatar model but don't move or animate on their own. Combine with Animator or Tween for movement.
+
+## Avatar Modifier Areas
+
+Modify how avatars appear or behave in a region:
+
+```typescript
+import { engine, Transform, AvatarModifierArea, AvatarModifierType } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const modifierArea = engine.addEntity()
+Transform.create(modifierArea, {
+  position: Vector3.create(8, 1.5, 8),
+  scale: Vector3.create(4, 3, 4)
+})
+
+AvatarModifierArea.create(modifierArea, {
+  area: { box: Vector3.create(4, 3, 4) },
+  modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
+  excludeIds: ['0x123...abc']  // Optional: exclude specific players
+})
+```
+
+### Available Modifiers
+
+```typescript
+AvatarModifierType.AMT_HIDE_AVATARS       // Hide all avatars in the area
+AvatarModifierType.AMT_DISABLE_PASSPORTS  // Disable clicking on avatars to see profiles
+AvatarModifierType.AMT_DISABLE_JUMPING    // Prevent jumping in the area
+```
+
+### Movement Constraints
+
+```typescript
+// Prevent jumping in a specific area
+const constraintArea = engine.addEntity()
+Transform.create(constraintArea, {
+  position: Vector3.create(8, 5, 8),
+  scale: Vector3.create(6, 10, 6)
+})
+
+AvatarModifierArea.create(constraintArea, {
+  area: { box: Vector3.create(6, 10, 6) },
+  modifiers: [AvatarModifierType.AMT_DISABLE_JUMPING]
+})
+```
+
+## Teleporting the Player
+
+Move the player to a specific position:
+
+```typescript
+// Move player position
+const playerTransform = Transform.getMutable(engine.PlayerEntity)
+playerTransform.position = Vector3.create(8, 0, 8)
+
+// Move player with rotation
+playerTransform.position = Vector3.create(8, 0, 8)
+playerTransform.rotation = Quaternion.fromEulerDegrees(0, 180, 0)
+```
+
+### Keeping Player in Bounds
+
+```typescript
+function boundarySystem() {
+  const playerTransform = Transform.getMutable(engine.PlayerEntity)
+  const pos = playerTransform.position
+
+  // Clamp to scene bounds
+  if (pos.x < 0) playerTransform.position.x = 0
+  if (pos.x > 16) playerTransform.position.x = 16
+  if (pos.z < 0) playerTransform.position.z = 0
+  if (pos.z > 16) playerTransform.position.z = 16
+}
+
+engine.addSystem(boundarySystem)
+```
+
+## Best Practices
+
+- Always check `Transform.has(engine.PlayerEntity)` before reading player data — it may not be ready on the first frame
+- Use `getPlayer()` to check `isGuest` before attempting wallet-dependent features
+- `AvatarAttach` requires the target player to be in the same scene — attachments disappear when the player leaves
+- Custom emote files must use the `_emote.glb` naming convention
+- Use `AvatarModifierArea` with `AMT_HIDE_AVATARS` for private rooms or puzzle areas
+- Add `excludeIds` to modifier areas when you want specific players (like the scene owner) to remain visible
+- Teleporting the player works within scene bounds — respect parcel limits
+
+For component field details, see `context/components-reference.md`.

package/skills/smart-items/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: smart-items
+description: Use Decentraland asset pack smart items with pre-built behaviors like doors, buttons, platforms, teleporters, and interactive objects. Use when user wants pre-built interactive items, asset packs, doors, elevators, buttons, teleporters, or drag-and-drop style items.
+---
+
+# Smart Items in Decentraland
+
+Smart Items are pre-built interactive objects from Decentraland's asset packs. They come with built-in behaviors and can be combined using actions and triggers.
+
+## Available Asset Packs
+
+| Pack | Contents |
+|------|----------|
+| **Smart Items** | Doors, buttons, platforms, teleporters, spawn points |
+| **Cyberpunk** | Neon signs, holograms, futuristic furniture, vehicles |
+| **Fantasy** | Medieval buildings, treasure chests, torches, trees |
+| **Genesis City** | Urban buildings, street furniture, signs |
+| **Sci-Fi** | Space station parts, control panels, airlocks |
+| **Gallery** | Art frames, pedestals, display cases |
+| **Steampunk** | Gears, pipes, Victorian furniture |
+| **Pirates** | Ships, barrels, treasure, cannons |
+| **Western** | Saloon, cacti, wagons, buildings |
+
+## Using Smart Items via Code
+
+Smart items from the Creator Hub use a component-based system. When coding manually, you can recreate their behavior:
+
+### Door (Open/Close on Click)
+```typescript
+import { engine, Transform, GltfContainer, Animator, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import { Vector3, Quaternion } from '@dcl/sdk/math'
+
+const door = engine.addEntity()
+Transform.create(door, { position: Vector3.create(8, 0, 8) })
+GltfContainer.create(door, { src: 'models/door.glb' })
+
+let isOpen = false
+
+// If the model has animations
+Animator.create(door, {
+  states: [
+    { clip: 'open', playing: false, loop: false },
+    { clip: 'close', playing: false, loop: false }
+  ]
+})
+
+pointerEventsSystem.onPointerDown(
+  { entity: door, opts: { button: InputAction.IA_POINTER, hoverText: 'Open/Close' } },
+  () => {
+    isOpen = !isOpen
+    if (isOpen) {
+      Animator.playSingleAnimation(door, 'open')
+    } else {
+      Animator.playSingleAnimation(door, 'close')
+    }
+  }
+)
+```
+
+### Button (Trigger Action)
+```typescript
+const button = engine.addEntity()
+Transform.create(button, { position: Vector3.create(6, 1, 8) })
+GltfContainer.create(button, { src: 'models/button.glb' })
+
+Animator.create(button, {
+  states: [{ clip: 'press', playing: false, loop: false }]
+})
+
+pointerEventsSystem.onPointerDown(
+  { entity: button, opts: { button: InputAction.IA_POINTER, hoverText: 'Press' } },
+  () => {
+    Animator.playSingleAnimation(button, 'press')
+    // Trigger linked action
+    onButtonPressed()
+  }
+)
+
+function onButtonPressed() {
+  // Do something — open a door, show UI, play sound, etc.
+}
+```
+
+### Platform (Moving Platform)
+```typescript
+import { Tween, EasingFunction } from '@dcl/sdk/ecs'
+import { TweenSequence, TweenLoop } from '@dcl/sdk/ecs'
+
+const platform = engine.addEntity()
+Transform.create(platform, { position: Vector3.create(8, 0, 8) })
+GltfContainer.create(platform, { src: 'models/platform.glb' })
+
+// Move up and down
+Tween.create(platform, {
+  mode: Tween.Mode.Move({
+    start: Vector3.create(8, 0, 8),
+    end: Vector3.create(8, 5, 8)
+  }),
+  duration: 3000,
+  easingFunction: EasingFunction.EF_EASEINOUTSINE
+})
+
+TweenSequence.create(platform, {
+  sequence: [{
+    mode: Tween.Mode.Move({
+      start: Vector3.create(8, 5, 8),
+      end: Vector3.create(8, 0, 8)
+    }),
+    duration: 3000,
+    easingFunction: EasingFunction.EF_EASEINOUTSINE
+  }],
+  loop: TweenLoop.TL_RESTART
+})
+```
+
+### Teleporter
+```typescript
+import { movePlayerTo } from '~system/RestrictedActions'
+
+const teleporter = engine.addEntity()
+Transform.create(teleporter, { position: Vector3.create(4, 0, 4) })
+GltfContainer.create(teleporter, { src: 'models/teleporter.glb' })
+
+pointerEventsSystem.onPointerDown(
+  { entity: teleporter, opts: { button: InputAction.IA_POINTER, hoverText: 'Teleport' } },
+  () => {
+    // Move player to target position
+    void movePlayerTo({
+      newRelativePosition: Vector3.create(12, 0, 12),
+      cameraTarget: Vector3.create(12, 1, 13)
+    })
+  }
+)
+```
+
+**Note**: `movePlayerTo` requires the `ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE` permission in scene.json.
+
+## Action/Trigger Pattern
+
+Smart items in Creator Hub use an action/trigger pattern. You can replicate this:
+
+```typescript
+// Action registry
+type Action = () => void
+const actions: Map<string, Action> = new Map()
+
+function registerAction(name: string, action: Action) {
+  actions.set(name, action)
+}
+
+function triggerAction(name: string) {
+  const action = actions.get(name)
+  if (action) action()
+}
+
+// Register actions
+registerAction('openDoor', () => {
+  Animator.playSingleAnimation(door, 'open')
+})
+
+registerAction('playSound', () => {
+  AudioSource.getMutable(speaker).playing = true
+})
+
+// Trigger from button
+pointerEventsSystem.onPointerDown(
+  { entity: button, opts: { button: InputAction.IA_POINTER, hoverText: 'Activate' } },
+  () => {
+    triggerAction('openDoor')
+    triggerAction('playSound')
+  }
+)
+```
+
+## Tips
+
+- Smart items from Creator Hub export as code — you can inspect and modify the generated code
+- For complex item interactions, use an event bus pattern (register/trigger actions)
+- Models for smart items are in the asset-packs repository
+- Keep smart item models lightweight (under 1,000 triangles each)
+- Combine multiple simple smart items rather than creating one complex one