@dcl-regenesislabs/web-editor 0.3.20 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl-regenesislabs/web-editor",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "license": "Apache-2.0",
   "description": "The Decentraland scene editor for the web explorer: editor.js plus the files it loads beside it. Served by version, not installed.",
   "repository": {

package/prefabs/camera-rig/ai.md

@@ -0,0 +1,81 @@
+---
+prefab: camera-rig
+claims-globals: __dclCameraRig_v1
+---
+
+# Camera Rig — AI guide
+
+A fixed game camera: while the player stands inside the rig's area (or all the
+time), their view switches to a camera looking down at the area from a fixed
+angle, far enough back that the whole area fits their screen, a phone's wide
+canvas included. Leaving the area gives the default camera back.
+
+The project copy is normally custom/camera_rig/ — check what is on disk, a
+second copy is custom/camera_rig_2/.
+
+## When to use
+
+Any game played on a board, arena or kitchen the player should see whole:
+Overcooked-style co-op, party games, top-down shooters, puzzle rooms, a
+mini-golf hole. The default third-person camera trails the avatar and hides
+most of such a play area; place one Camera Rig over it instead of writing
+VirtualCamera code.
+
+## API
+
+The rig's own Transform is the setup — no code, no names to wire:
+- position: the point the camera looks at. Place it at the centre of the play
+  area, at floor height.
+- scale: the area in metres (default 12 x 4 x 12). It is both where the camera
+  takes over and what it frames. Set it with the placePrefab `scale` to the
+  play area's size, leaving a metre of floor around the edges.
+- rotation: which way is up on screen (the rig's forward, +Z). The assistant
+  cannot rotate it; the default faces north (+Z). If the user wants another
+  side, tell them to turn the rig with the rotate gizmo.
+
+Params, set in the placePrefab request:
+- mode: 'isometric' (default; angled, the Overcooked look) | 'top-down'
+  (straight down, a board-game view) | 'follow' (the same fixed angle, but
+  the camera tracks the player, for areas bigger than one screen).
+- activeWhen: 'inside this area' (default) | 'always' (the whole scene, as
+  long as the player is in it).
+- angle: degrees the camera looks down from the horizon for isometric and
+  follow, 10 to 88 (default 55). Top-down ignores it.
+- distance: metres from the camera to the look point. 0 (default) computes it
+  so the whole area fits on screen; set it only to force a closer shot.
+- fitSize: metres of ground the shot must show across and deep. 0 (default)
+  uses the rig's scale; in follow mode 0 means 10 m around the player.
+- transitionSeconds: how long the view glides into the rig's camera (default
+  0.6, 0 cuts).
+
+Framing uses the player's real canvas aspect (a 1600x720 phone landscape is
+handled) plus a margin so the phone's touch buttons do not cover the edges.
+The framing math is in the module header of
+src/scripts/runtime/pure/cameraRig.ts.
+
+## Movement and players
+
+Movement keys keep working; the rig never freezes the avatar. Whether "forward"
+walks toward the top of the screen under a fixed camera depends on the
+explorer and is NOT verified yet: if the user reports inverted or sideways
+controls, say so plainly instead of patching it with InputModifier. Each player
+gets their own view: the rig only reacts to the player at that screen.
+
+## Do / Don't
+
+- DO place exactly one rig per play area. Overlapping rigs are allowed: the
+  one entered last wins, and leaving it falls back to the one still around the
+  player.
+- DON'T also set MainCamera or create a VirtualCamera in a script for the same
+  area; the rig owns the view while the player is inside. A script's own
+  cutscene camera is left alone when the rig lets go.
+- DON'T parent the rig to a scaled object: its scale is the area.
+- DON'T use 'follow' for a room that fits one screen; 'isometric' reads better.
+
+## Example
+
+"A kitchen game seen from above": the kitchen floor is 14 x 10 m centred at
+(16, 0, 16). placePrefab camera-rig named "Kitchen Camera" at position
+(16, 0, 16) with scale (16, 4, 12), params mode: 'isometric', angle: 55,
+activeWhen: 'inside this area'. Every cook who walks into the kitchen sees all
+the stations at once; walking out restores the normal camera.

package/prefabs/camera-rig/composite.json

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

package/prefabs/camera-rig/data.json

@@ -0,0 +1,22 @@
+{
+  "id": "7ea892f3-168f-40fb-8338-d9c91c23708e",
+  "name": "Camera Rig",
+  "description": "A fixed game camera — top-down, isometric or following the player — that takes over while a player is inside its area and frames the whole area on any screen, phones included.",
+  "category": "custom",
+  "tags": [
+    "camera",
+    "top-down",
+    "isometric",
+    "view"
+  ],
+  "version": "1.0.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "Initial release: a top-down, isometric or follow camera that takes over while a player is inside its area (or all the time), fits the whole area on desktop and phone screens, and hands the default camera back on the way out."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/camera-rig/scripts/camera-rig.ts

@@ -0,0 +1,199 @@
+// A fixed game camera. While this player stands inside the rig's area (or all
+// the time, with 'always'), their view switches to a camera that looks at the
+// rig from above along the rig's heading, far enough back that the whole area
+// fits on their screen — a phone's wide canvas included. Leaving the area hands
+// the default camera back.
+//
+// The rig's own Transform is the whole authoring surface: its position is where
+// the camera looks, its rotation is which way is up on screen, and its scale is
+// the area in metres — the volume the editor draws while building, and the
+// TriggerArea that decides "inside" while playing.
+//
+// The camera itself is a separate root entity: a VirtualCamera inherits its
+// entity's scale, and the rig's scale is the area, not something to film with.
+import {
+  MainCamera,
+  Transform,
+  TriggerArea,
+  UiCanvasInformation,
+  VirtualCamera,
+  engine,
+  triggerAreaEventsSystem,
+  type Entity
+} from '@dcl/sdk/ecs'
+import { isServer } from '@dcl/sdk/network'
+import { isMobile } from '@dcl/sdk/platform'
+import { localPlayerPosition } from '~runtime/playerPositions'
+import { entityWorld } from '~runtime/sceneNames'
+import { Membership } from '~runtime/pure/membership'
+import {
+  CAMERA_FOV_DEG,
+  aspectFor,
+  cameraOnTop,
+  cameraPose,
+  claimCamera,
+  framingDistance,
+  pitchFor,
+  releaseCamera,
+  yawOf,
+  type CameraPose,
+  type RigClaims
+} from '~runtime/pure/cameraRig'
+import type { Vec3 } from '~runtime/pure/worldTransform'
+
+// Collision layers by value: the SDK renamed CL_RESERVED2 to CL_MAIN_PLAYER, and
+// this script compiles against whatever pin the creator's project carries. The
+// local avatar alone carries 8, so the area reacts to the player at this screen.
+const CL_MAIN_PLAYER = 8
+const SPHERE_MESH = 1
+// A player on the boundary crosses it every few frames; without this the view
+// would snap back and forth.
+const EXIT_GRACE_S = 0.3
+const FOLLOW_EYE_M = 1
+const MOVED_EPSILON = 1e-3
+// Several rigs in one scene agree on who owns the screen through this key.
+const CLAIMS_KEY = '__dclCameraRig_v1'
+
+export class CameraRig {
+  private camera: Entity | null = null
+  private members = new Membership<Entity>()
+  private pose: CameraPose | null = null
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    /** How the camera looks at the area */
+    public mode: 'top-down' | 'isometric' | 'follow' = 'isometric',
+    /** When the camera takes over */
+    public activeWhen: 'inside this area' | 'always' = 'inside this area',
+    /** Degrees the camera looks down from the horizon, for isometric and follow. Top-down looks straight down. */
+    public angle: number = 55,
+    /** Metres from the camera to what it looks at. 0 fits the whole area on screen. */
+    public distance: number = 0,
+    /** Metres of ground the shot must show across and deep. 0 uses this rig's own area (its scale); follow uses 10. */
+    public fitSize: number = 0,
+    /** Seconds the view takes to glide into this camera. 0 cuts straight to it. */
+    public transitionSeconds: number = 0.6
+  ) {}
+
+  start(): void {
+    // The camera is one player's screen; a Multiplayer Server has none.
+    if (isServer()) return
+    const camera = engine.addEntity()
+    Transform.create(camera, { position: Transform.getOrNull(this.entity)?.position ?? { x: 0, y: 0, z: 0 } })
+    // Built as a value, not a literal, so an older SDK pin without `fov` still
+    // type-checks; its encoder drops the field and the explorer's default is 60.
+    const settings = {
+      defaultTransition: {
+        transitionMode: { $case: 'time' as const, time: Math.max(0, this.transitionSeconds) }
+      },
+      fov: CAMERA_FOV_DEG
+    }
+    VirtualCamera.create(camera, settings)
+    this.camera = camera
+
+    if (this.activeWhen === 'always') {
+      TriggerArea.deleteFrom(this.entity)
+      return
+    }
+    if (TriggerArea.getOrNull(this.entity)?.mesh === SPHERE_MESH) {
+      TriggerArea.setSphere(this.entity, CL_MAIN_PLAYER)
+    } else {
+      TriggerArea.setBox(this.entity, CL_MAIN_PLAYER)
+    }
+    // Stay as well as enter: a player who spawns inside the area never crosses
+    // into it, and the engine's enter fires only on the crossing.
+    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 {
+    const camera = this.camera
+    if (camera === null) return
+    this.members.tick(dt, EXIT_GRACE_S)
+    const active = this.activeWhen === 'always' || this.members.size > 0
+    if (active) this.aim(camera)
+    const claims = rigClaims()
+    if (active) claimCamera(claims, camera)
+    else releaseCamera(claims, camera)
+    applyClaims(claims)
+  }
+
+  private aim(camera: Entity): void {
+    const rig = entityWorld(this.entity)
+    if (rig === null) return
+    let target: Vec3 = rig.position
+    if (this.mode === 'follow') {
+      const feet = localPlayerPosition()
+      if (feet === null && this.pose !== null) return
+      if (feet !== null) target = { x: feet.x, y: feet.y + FOLLOW_EYE_M, z: feet.z }
+    }
+    const mobile = isMobile()
+    const canvas = UiCanvasInformation.getOrNull(engine.RootEntity)
+    const pitchDeg = pitchFor(this.mode, this.angle)
+    const distance = framingDistance({
+      mode: this.mode,
+      distance: this.distance,
+      fitSize: this.fitSize,
+      area: rig.scale,
+      pitchDeg,
+      aspect: aspectFor(canvas, mobile),
+      mobile
+    })
+    const pose = cameraPose(target, yawOf(rig.rotation), pitchDeg, distance)
+    if (this.pose !== null && samePose(this.pose, pose)) return
+    this.pose = pose
+    Transform.createOrReplace(camera, { position: pose.position, rotation: pose.rotation })
+  }
+
+  // result.trigger.entity is the avatar that moved; the area is triggeredEntity.
+  private seen(raw?: number): void {
+    const who = toEntity(raw)
+    if (who !== undefined) this.members.touch(who)
+  }
+
+  private gone(raw?: number): void {
+    const who = toEntity(raw)
+    if (who !== undefined) this.members.drop(who)
+  }
+}
+
+function toEntity(raw?: number): Entity | undefined {
+  return raw === undefined || raw === 0 ? undefined : (raw as Entity)
+}
+
+function samePose(a: CameraPose, b: CameraPose): boolean {
+  const p = Math.abs(a.position.x - b.position.x) + Math.abs(a.position.y - b.position.y) + Math.abs(a.position.z - b.position.z)
+  const r =
+    Math.abs(a.rotation.x - b.rotation.x) +
+    Math.abs(a.rotation.y - b.rotation.y) +
+    Math.abs(a.rotation.z - b.rotation.z) +
+    Math.abs(a.rotation.w - b.rotation.w)
+  return p < MOVED_EPSILON && r < MOVED_EPSILON
+}
+
+function isClaims(value: unknown): value is RigClaims<Entity> {
+  return typeof value === 'object' && value !== null && Array.isArray((value as { order?: unknown }).order)
+}
+
+function rigClaims(): RigClaims<Entity> {
+  const globals = globalThis as unknown as Record<string, unknown>
+  const current = globals[CLAIMS_KEY]
+  if (isClaims(current)) return current
+  const created: RigClaims<Entity> = { order: [], applied: null }
+  globals[CLAIMS_KEY] = created
+  return created
+}
+
+function applyClaims(claims: RigClaims<Entity>): void {
+  const wanted = cameraOnTop(claims)
+  if (wanted === claims.applied) return
+  if (wanted !== null) {
+    MainCamera.createOrReplace(engine.CameraEntity, { virtualCameraEntity: wanted })
+  } else if (MainCamera.getOrNull(engine.CameraEntity)?.virtualCameraEntity === claims.applied) {
+    // Only undo our own write: a cutscene camera a script set meanwhile stays.
+    MainCamera.createOrReplace(engine.CameraEntity, {})
+  }
+  claims.applied = wanted
+}