@dcl-regenesislabs/web-editor 0.0.0-stage → 0.1.0

package/prefabs/tall-stool/scripts/seat.ts

@@ -0,0 +1,191 @@
+// Sit on this seat: click a sit spot -> the avatar is placed on it facing forward
+// and a looping sitting emote plays; moving cancels the emote engine-side (the
+// same mechanism the Creator Hub's seat smart items and Genesis Plaza use — no
+// avatar attach). Spots are child entities named "Sit Spot…" carrying only a
+// Transform; this script gives them their collider and pointer event at runtime.
+// With no such children (the standalone Sit Spot prefab), the entity itself is
+// the spot.
+import {
+  ColliderLayer,
+  InputAction,
+  Material,
+  MeshCollider,
+  MeshRenderer,
+  Schemas,
+  Transform,
+  VisibilityComponent,
+  engine,
+  pointerEventsSystem,
+  type Entity,
+  type LastWriteWinElementSetComponentDefinition
+} from '@dcl/sdk/ecs'
+import { Quaternion, Vector3 } from '@dcl/sdk/math'
+import { isServer } from '@dcl/sdk/network'
+import { movePlayerTo, triggerEmote, triggerSceneEmote } from '~system/RestrictedActions'
+
+const SPOT_NAME_PREFIX = 'sit spot'
+const HOVER_TEXT = 'Sit Here'
+const MAX_DISTANCE = 6
+const EMOTE_DELAY_S = 0.25
+const SITTING_EMOTES = ['sittingChair1', 'sittingChair2']
+// emote .glb files bundled in this prefab's folder (Genesis Plaza-style custom
+// poses, played via triggerSceneEmote); empty = the predefined chair emotes
+const SCENE_EMOTES: string[] = []
+
+// the Plaza-style "you can sit here" hint: a small glowing dot floating over
+// each free spot, pulsing gently, shown only to nearby players
+const DOT_VISIBLE_DIST = 10
+const DOT_OCCUPIED_DIST = 0.9
+const DOT_HEIGHT = 0.55
+const DOT_SIZE = 0.09
+const DOT_PULSE = 0.25
+
+type NameValue = { value: string }
+type NameComponent = LastWriteWinElementSetComponentDefinition<NameValue>
+
+// Every placed seat prefab bundles its own copy of this script (prefab folders are
+// self-contained), so the component may already be defined by a sibling copy.
+function nameComponent(): NameComponent {
+  const existing = engine.getComponentOrNull('core-schema::Name')
+  if (existing !== null) return existing as NameComponent
+  return engine.defineComponent('core-schema::Name', { value: Schemas.String })
+}
+
+function isSpotName(name: unknown): boolean {
+  return typeof name === 'string' && name.toLowerCase().startsWith(SPOT_NAME_PREFIX)
+}
+
+function sceneRelativeTransform(entity: Entity): { position: Vector3; rotation: Quaternion } {
+  const chain: Entity[] = []
+  let cursor = entity
+  while (cursor !== engine.RootEntity && chain.length < 32) {
+    chain.push(cursor)
+    const t = Transform.getOrNull(cursor)
+    if (t === null) break
+    cursor = t.parent ?? engine.RootEntity
+  }
+  let position = Vector3.Zero()
+  let rotation = Quaternion.Identity()
+  let scale = Vector3.One()
+  for (const link of chain.reverse()) {
+    const t = Transform.getOrNull(link)
+    if (t === null) continue
+    const local = Vector3.create(
+      t.position.x * scale.x,
+      t.position.y * scale.y,
+      t.position.z * scale.z
+    )
+    position = Vector3.add(position, Vector3.rotate(local, rotation))
+    rotation = Quaternion.multiply(rotation, t.rotation)
+    scale = Vector3.create(scale.x * t.scale.x, scale.y * t.scale.y, scale.z * t.scale.z)
+  }
+  return { position, rotation }
+}
+
+export class Seat {
+  private emoteIn = 0
+  private time = 0
+  private dots: Array<{ spot: Entity; dot: Entity; visible: boolean }> = []
+
+  constructor(
+    public src: string,
+    public entity: Entity
+  ) {}
+
+  start(): void {
+    if (isServer()) { return }
+    const Name = nameComponent()
+    const spots: Entity[] = []
+    for (const [child, transform] of engine.getEntitiesWith(Transform)) {
+      if (transform.parent !== this.entity) continue
+      const name = Name.getOrNull(child)
+      if (name !== null && isSpotName(name.value)) spots.push(child)
+    }
+    if (spots.length === 0) spots.push(this.entity)
+
+    for (const spot of spots) {
+      MeshCollider.setBox(spot, ColliderLayer.CL_POINTER)
+      pointerEventsSystem.onPointerDown(
+        {
+          entity: spot,
+          opts: { button: InputAction.IA_POINTER, hoverText: HOVER_TEXT, maxDistance: MAX_DISTANCE }
+        },
+        () => this.sit(spot)
+      )
+      // no collider on the dot: clicks pass through to the spot beneath it
+      const dot = engine.addEntity()
+      Transform.create(dot, {
+        parent: spot,
+        position: Vector3.create(0, DOT_HEIGHT, 0),
+        scale: Vector3.create(DOT_SIZE, DOT_SIZE, DOT_SIZE)
+      })
+      MeshRenderer.setSphere(dot)
+      Material.setPbrMaterial(dot, {
+        albedoColor: { r: 1, g: 1, b: 1, a: 0.85 },
+        emissiveColor: { r: 1, g: 1, b: 1 },
+        emissiveIntensity: 2,
+        roughness: 1
+      })
+      VisibilityComponent.create(dot, { visible: false })
+      this.dots.push({ spot, dot, visible: false })
+    }
+  }
+
+  update(dt: number): void {
+    // The hint walks a transform chain per spot per frame, and a seat is placed
+    // by the dozen: without this the Multiplayer Server pays for every one.
+    if (isServer()) { return }
+    this.time += dt
+    this.updateDots()
+    if (this.emoteIn <= 0) return
+    this.emoteIn -= dt
+    if (this.emoteIn > 0) return
+    if (SCENE_EMOTES.length > 0) {
+      // src is the script's directory (custom/<slug>/scripts) — the emotes live
+      // one level up, in the placed prefab's own folder
+      const root = this.src.replace(/\/scripts\/?$/, '')
+      const emote = SCENE_EMOTES[Math.floor(Math.random() * SCENE_EMOTES.length)]
+      void triggerSceneEmote({ src: `${root}/${emote}`, loop: true })
+      return
+    }
+    const emote = SITTING_EMOTES[Math.floor(Math.random() * SITTING_EMOTES.length)]
+    void triggerEmote({ predefinedEmote: emote })
+  }
+
+  private updateDots(): void {
+    const player = Transform.getOrNull(engine.PlayerEntity)?.position
+    const pulse = 1 + DOT_PULSE * Math.sin(this.time * 3)
+    for (const entry of this.dots) {
+      let visible = false
+      if (player !== undefined) {
+        const world = sceneRelativeTransform(entry.spot).position
+        const dist = Vector3.distance(player, world)
+        // hidden while someone (you) is on the spot — a glow over a seated
+        // avatar's head reads as a bug, not a hint
+        visible = dist < DOT_VISIBLE_DIST && dist > DOT_OCCUPIED_DIST
+      }
+      if (entry.visible !== visible) {
+        entry.visible = visible
+        VisibilityComponent.getMutable(entry.dot).visible = visible
+      }
+      if (visible) {
+        Transform.getMutable(entry.dot).scale = Vector3.create(
+          DOT_SIZE * pulse,
+          DOT_SIZE * pulse,
+          DOT_SIZE * pulse
+        )
+      }
+    }
+  }
+
+  private sit(spot: Entity): void {
+    const world = sceneRelativeTransform(spot)
+    const forward = Vector3.rotate(Vector3.Forward(), world.rotation)
+    void movePlayerTo({
+      newRelativePosition: world.position,
+      avatarTarget: Vector3.add(world.position, forward)
+    })
+    // let the teleport settle before the emote starts, or the walk cancels it
+    this.emoteIn = EMOTE_DELAY_S
+  }
+}

package/prefabs/trigger-zone/ai.md

@@ -0,0 +1,115 @@
+---
+prefab: trigger-zone
+---
+
+# Trigger Area — AI guide
+
+An invisible named volume that knows who is standing in it. Other scripts react
+to it BY NAME through the bus module in the project's shared runtime — nothing is
+wired, and a reacting script pasted into another scene keeps working.
+
+## When to use
+
+Any request shaped like "when a player walks somewhere / is somewhere / leaves
+somewhere": open a door, play a sound or emote, award points, show a message,
+start an ambience. One area per place — though several volumes may share a Name,
+and the bus then treats them as one place.
+
+## API
+
+AN AREA'S ID IS THE ENTITY'S NAME, matched trimmed and case-insensitively — the
+[Scene] block lists the areas the scene already has.
+
+Import from the project's shared runtime, the one place every runtime module lives:
+
+    import { isInZone, onZone, playersInZone, zoneOf } from './runtime/zoneBus'
+
+- isInZone(name): true while THIS viewer is inside. Occupancy — the default you want.
+- playersInZone(name): every avatar currently inside, deduped across volumes sharing the name.
+- onZone(name, 'enter' | 'exit' | 'any', fn): edges derived from occupancy; returns
+  an unsubscribe. Late subscribers get current occupancy replayed as enters. The
+  event: { zone, kind, entity (the avatar that MOVED — never the area), address,
+  local (true for this viewer), zoneEntity }.
+- zoneOf(entity): the area name of the entity a script is attached to ('' if unnamed).
+
+Full signatures (and zoneNames()) are in the module header: src/scripts/runtime/zoneBus.ts.
+
+Params of the area's own script — set them in the placePrefab request, never
+tell the user to change them:
+- who: 'this player' (default) | 'any player' — whose client the area reacts to.
+- fireWhen: 'every time' (default) | 'once per player' | 'once ever' — how often
+  an entry may fire.
+- exitDelay: seconds (default 0.3) a player may step back out before counting as
+  gone. Boundary hysteresis, NOT a cooldown — a reaction owns its own rate limit,
+  and naming that limit "cooldown" next to the area's settings reads as this one;
+  name it for what it limits and say so in its doc comment.
+
+## Occupancy beats edges
+
+Most "when someone is in here" code is occupancy, not events: isInZone() in
+update() cannot flicker, needs no debounce, and a door with two people in it
+does not close when one of them leaves.
+
+    update(): void { if (isInZone('Front Door Area')) this.open(); else this.close() }
+
+Use onZone(name, 'enter', …) only when the reaction really is one-shot, 'exit'
+for leaving, 'any' when one script handles both (event.kind is 'enter' | 'exit').
+Cover the edge the user asked for and no more.
+
+## Where the reaction script goes
+
+An entity's Script component is a LIST — an area carries its detector AND any
+reactions. Decide by what the reaction acts on:
+
+- It changes ANOTHER object ("open the door", "turn on the lights") → attach to
+  THAT object, resolved from the [Scene] roster, with public zone: string =
+  'Front Door Area'. A reaction living elsewhere needs telling which area; never
+  hardcode the name where a param would do.
+- It acts on the player, the UI, the sound, the score — nothing else involved
+  ("play an emote", "show a message", "give points") → attach to THE AREA ITSELF,
+  with an attachScript request naming the area, and give it NO zone param at all.
+  Not a blank one: a param the creator must leave empty is a field that can only
+  be got wrong. Call zoneOf(this.entity) in start() — the attachment already says
+  which area, and renaming the area can't orphan it. Exactly this shape, params
+  for the reaction only:
+
+      export class AreaPoints {
+        private zone = ''
+        constructor(public src: string, public entity: Entity, public points: number = 10) {}
+        start() {
+          this.zone = zoneOf(this.entity)
+          onZone(this.zone, 'enter', (e) => { if (e.local) this.award(e.address) })
+        }
+        update(dt: number) {}
+        private award(address: string) { /* what happens goes here */ }
+      }
+
+- NEVER pick an unrelated entity just to have somewhere to put a script. No
+  object involved → the area is the answer.
+- An area named in the prompt ("…when they enter Front Hall") says WHICH area to
+  attach to — it is not a request for a zone param.
+
+## Do / Don't
+
+- DON'T subscribe triggerAreaEventsSystem.onTriggerEnter/Stay/Exit on an area
+  entity. The SDK keeps exactly ONE callback per (entity, event), so your
+  subscription silently replaces the prefab's own detector and the area stops
+  working for everybody. The prefab owns those callbacks; you consume the bus.
+- DON'T hand-roll proximity (distance loops against the player). The prefab
+  exists so you never do.
+- The volume IS the entity's Transform scale in metres, so the scale gizmo is the
+  resize tool. Neither you nor the editor can measure a model's bounding box —
+  place the area NEAR the object at a sensible size and say in one line to drag
+  the scale handles to fit. Never claim you fitted it.
+- Detection is client-side only: the headless server has no avatar colliders, so
+  an area never fires there. Fine for doors, lights, sound, ambience. When an area
+  gates something valuable (a reward, a score, a paid area) put the decision in a
+  game.onEnterArea(name, fn) on the server — it re-checks the player's real
+  position before it counts — and say in one line that the bus alone is
+  client-trusted rather than implying it is safe.
+
+## Example
+
+"Make the door open when someone walks up": placePrefab trigger-zone named
+"Front Door Area" (4×3×4 at the doorway, who: 'any player'), then a script on
+the Door entity whose update() runs the isInZone snippet above.

package/prefabs/trigger-zone/composite.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "Trigger Zone"
+          }
+        }
+      }
+    },
+    {
+      "name": "core::Transform",
+      "data": {
+        "0": {
+          "json": {
+            "scale": { "x": 4, "y": 3, "z": 4 }
+          }
+        }
+      }
+    },
+    {
+      "name": "core::TriggerArea",
+      "data": {
+        "0": {
+          "json": {
+            "mesh": 0,
+            "collisionMask": 8
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::Script",
+      "data": {
+        "0": {
+          "json": {
+            "value": [
+              {
+                "path": "{assetPath}/scripts/trigger-zone.ts",
+                "priority": 0,
+                "layout": "{\"params\":{},\"actions\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/trigger-zone/data.json

@@ -0,0 +1,31 @@
+{
+  "id": "f1794ec8-ed62-42c8-a71b-6c52e04b161a",
+  "name": "Trigger Area",
+  "slug": "trigger_zone",
+  "description": "An invisible area that knows who is standing in it. Name it, scale it with the gizmo, then have a script react to that name.",
+  "category": "custom",
+  "tags": [
+    "trigger",
+    "area",
+    "interactivity"
+  ],
+  "drivenBy": {
+    "rule": "The area only publishes who is standing in it — a Script reacts to its name through './runtime/zoneBus', on this item or on any other entity in the scene.",
+    "code": "onZone('Front Door', 'enter', (event) => { /* what happens */ })",
+    "next": "Use the Add a reaction button below and the new Script arrives already listening to this area."
+  },
+  "version": "1.1.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "Initial release: an invisible named area that publishes who is standing in it, so a Script anywhere in the scene reacts to it by name with nothing wired."
+    },
+    {
+      "version": "1.1.0",
+      "notes": "The placed area's Script card now shows the onZone line a Script reacts with, under its area settings."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/trigger-zone/scripts/trigger-zone.ts

@@ -0,0 +1,89 @@
+// An invisible named area that knows who is standing in it. The zone's id is the
+// entity's NAME — the one handle the creator, the script and the AI already
+// share — so another script reacts with `isInZone('Front Hall')` and nothing has
+// to be wired. Matching is case- and whitespace-insensitive (zoneRegistry).
+//
+// The area's size and rotation come from the entity's own Transform: scale is
+// metres, so the scale gizmo is the resize tool. Detection is client-side only —
+// the server has no avatar colliders, so a zone never fires there.
+import { TriggerArea, triggerAreaEventsSystem, type Entity } from '@dcl/sdk/ecs'
+import { Membership } from '~runtime/pure/membership'
+import { emitZone, publishZone, zoneOf } from '~runtime/zoneBus'
+
+// Collision layers by value, not by name: the SDK renamed CL_RESERVED2 to
+// CL_MAIN_PLAYER, and this script compiles against whatever pin the creator's
+// project happens to carry.
+const CL_PLAYER = 4
+const CL_MAIN_PLAYER = 8
+const SPHERE_MESH = 1
+
+// TriggerAreaResult carries plain numbers; Entity is the branded form of the
+// same id. 0 is the root, never an avatar.
+function toEntity(raw?: number): Entity | undefined {
+  return raw === undefined || raw === 0 ? undefined : (raw as Entity)
+}
+
+export class TriggerZone {
+  private members = new Membership<Entity>()
+  private zone = ''
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    /**
+     * Whose client reacts. "this player" is right for anything that happens to
+     * the person who walked in; "any player" also fires for other avatars.
+     */
+    public who: 'this player' | 'any player' = 'this player',
+    /** How often an entry may fire */
+    public fireWhen: 'every time' | 'once per player' | 'once ever' = 'every time',
+    /**
+     * Seconds a player may step back out before the zone counts them as gone.
+     * Deliberately NOT called a cooldown: this is boundary hysteresis, nothing to
+     * do with how often a reaction may fire — a reaction owns its own rate limit.
+     */
+    public exitDelay: number = 0.3
+  ) {}
+
+  start(): void {
+    // The local avatar's collider is CL_PLAYER|CL_MAIN_PLAYER and every remote
+    // avatar's is CL_PLAYER alone, so masking on 8 settles "this player only" in
+    // rapier — cheaper and safer than a JS identity guard.
+    const mask = this.who === 'this player' ? CL_MAIN_PLAYER : CL_PLAYER
+    if (TriggerArea.getOrNull(this.entity)?.mesh === SPHERE_MESH) {
+      TriggerArea.setSphere(this.entity, mask)
+    } else {
+      TriggerArea.setBox(this.entity, mask)
+    }
+
+    this.zone = zoneOf(this.entity)
+    publishZone(this.zone, this.entity, () => this.members.list())
+
+    // triggerAreaEventsSystem keeps exactly ONE callback per (entity, event):
+    // anything else subscribing to this entity silently replaces the zone's own
+    // detector. Consumers use the bus, never onTriggerEnter.
+    triggerAreaEventsSystem.onTriggerEnter(this.entity, (result) => this.seen(result.trigger?.entity))
+    triggerAreaEventsSystem.onTriggerStay(this.entity, (result) => this.seen(result.trigger?.entity))
+    triggerAreaEventsSystem.onTriggerExit(this.entity, (result) => this.gone(result.trigger?.entity))
+  }
+
+  update(dt: number): void {
+    for (const who of this.members.tick(dt, this.exitDelay)) {
+      emitZone(this.zone, 'exit', who, this.entity)
+    }
+  }
+
+  // result.trigger.entity is the avatar that moved; result.triggeredEntity is
+  // this area. Reading the wrong one is a silent no-op.
+  private seen(raw?: number): void {
+    const who = toEntity(raw)
+    if (who === undefined) return
+    if (this.members.touch(who, this.fireWhen)) emitZone(this.zone, 'enter', who, this.entity)
+  }
+
+  private gone(raw?: number): void {
+    const who = toEntity(raw)
+    if (who === undefined) return
+    this.members.drop(who)
+  }
+}

package/prefabs/video-screen/composite.json

@@ -0,0 +1,98 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core::GltfContainer",
+      "data": {
+        "0": {
+          "json": {
+            "src": "{assetPath}/video_player.glb",
+            "visibleMeshesCollisionMask": 0,
+            "invisibleMeshesCollisionMask": 3
+          }
+        }
+      }
+    },
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "Video Screen"
+          }
+        }
+      }
+    },
+    {
+      "name": "core::VideoPlayer",
+      "data": {
+        "0": {
+          "json": {
+            "src": "https://player.vimeo.com/external/552481870.m3u8?s=c312c8533f97e808fccc92b0510b085c8122a875",
+            "playing": true,
+            "volume": 1,
+            "loop": true
+          }
+        }
+      }
+    },
+    {
+      "name": "core::GltfNodeModifiers",
+      "data": {
+        "0": {
+          "json": {
+            "modifiers": [
+              {
+                "path": "",
+                "castShadows": true,
+                "material": {
+                  "material": {
+                    "$case": "unlit",
+                    "unlit": {
+                      "texture": {
+                        "tex": {
+                          "$case": "videoTexture",
+                          "videoTexture": {
+                            "videoPlayerEntity": "{self}",
+                            "wrapMode": 0,
+                            "filterMode": 0
+                          }
+                        }
+                      },
+                      "alphaTest": 0.5,
+                      "castShadows": true,
+                      "alphaTexture": {
+                        "tex": {
+                          "$case": "texture",
+                          "texture": {
+                            "src": "",
+                            "wrapMode": 0,
+                            "filterMode": 0,
+                            "offset": { "x": 0, "y": 0 },
+                            "tiling": { "x": 1, "y": 1 }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::VideoScreen",
+      "data": {
+        "0": {
+          "json": {
+            "thumbnail": "",
+            "defaultMediaSource": 0,
+            "defaultURL": "https://player.vimeo.com/external/552481870.m3u8?s=c312c8533f97e808fccc92b0510b085c8122a875"
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/video-screen/data.json

@@ -0,0 +1,21 @@
+{
+  "id": "37188734-4562-4f21-afeb-2752c39278f4",
+  "name": "Video Screen",
+  "description": "A flat screen that plays a video file or a live stream, with volume and playback controls.",
+  "category": "custom",
+  "tags": [
+    "video",
+    "screen",
+    "stream"
+  ],
+  "version": "1.0.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "Initial release"
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/wooden-chair/composite.json

@@ -0,0 +1,74 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core::GltfContainer",
+      "data": {
+        "0": {
+          "json": {
+            "src": "{assetPath}/Chair 1.glb",
+            "visibleMeshesCollisionMask": 0,
+            "invisibleMeshesCollisionMask": 3
+          }
+        }
+      }
+    },
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "Wooden Chair"
+          }
+        },
+        "513": {
+          "json": {
+            "value": "Sit Spot"
+          }
+        }
+      }
+    },
+    {
+      "name": "core::Transform",
+      "data": {
+        "513": {
+          "json": {
+            "position": {
+              "x": 0.0044,
+              "y": 0,
+              "z": 0.2835
+            },
+            "rotation": {
+              "x": 0,
+              "y": 0,
+              "z": 0,
+              "w": 1
+            },
+            "scale": {
+              "x": 1,
+              "y": 1,
+              "z": 1
+            },
+            "parent": 0
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::Script",
+      "data": {
+        "0": {
+          "json": {
+            "value": [
+              {
+                "path": "{assetPath}/scripts/seat.ts",
+                "priority": 0,
+                "layout": "{\"params\":{},\"actions\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}