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

package/prefabs/curved-couch/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/game-flow/ai.md

@@ -0,0 +1,94 @@
+---
+prefab: game-flow
+claims-state: game.state.flow
+---
+
+# Game Flow — AI guide
+
+Lobby, countdown, rounds, winners: the prefab that runs a game from start to end,
+on top of `game.round`.
+
+The project copy is normally custom/game_flow/ — check what is on disk, a second
+copy is custom/game_flow_2/.
+
+## When to use
+
+Whenever the game is played in rounds: a race, a wave survival, a timed climb, a
+scored match. Place ONE anywhere; it is a sign you can move or hide. A second
+copy paints its own sign and drives nothing.
+
+Do NOT write a phase machine, a lobby timer or a "round over" flag in a script —
+this prefab owns all three, and two clocks writing one game never agree.
+
+## API
+
+There is nothing to import. Game Flow talks through the synced state and messages
+every script already has:
+
+- `game.state.flow` — `{ phase, endsAtMs, round, present }`. `phase` is
+  `'lobby' | 'round' | 'intermission'`; `endsAtMs` is a `game.now()` instant
+  (0 while the lobby is parked); `round` counts rounds PLAYED, from 1; `present`
+  is the head count. Read it, never write it.
+- `game.round` / `game.onRoundStart` — the engine's round tuple, as always. Game
+  Flow starts rounds with `game.newRound()`, so `game.round.number` and
+  `game.state.flow.round` differ by the boot round. Key per-round validity on
+  `game.round.id`, never on the number: the number counts rounds inside one wake
+  of the Multiplayer Server and starts again at 1 after it sleeps, so a token
+  written down in one wake would read as current in the next.
+- `game.broadcast('announce', { text })` — Game Flow tells every player who won at
+  the end of a round. If an Announcer is placed it shows the line; if not,
+  nothing happens. Read custom/announcer/ai.md if one is placed.
+
+WHICH SIDE: Game Flow decides everything on the SERVER and every client paints
+the sign from `game.state.flow`. Read the state on either side; write nothing,
+and call `game.newRound()` only from inside an `if (isServer())` branch.
+
+Params of the prefab's script — set them in the placePrefab request:
+
+- `roundSeconds`: how long a round lasts (default 300). With `endsWhen: 'script'`
+  it is only a ceiling.
+- `countdownSeconds`: how long the lobby counts down once enough players are in
+  (default 10).
+- `intermissionSeconds`: how long the winners stay up between rounds (default 10).
+- `minPlayers`: players needed before a round starts (default 1).
+- `endsWhen`: `'timer'` (the clock ends the round) or `'script'` (your code ends
+  it with `game.newRound()`, and the sign hides a clock it does not own).
+- `boardKey`: the `game.state` key the winners line is read from (default
+  `'leaderboard'`). Point a Leaderboard at the same key.
+
+## Ending a round from a script
+
+Set `endsWhen: 'script'` and call `game.newRound()` inside a server handler when
+your condition hits. Game Flow follows: it announces the winners of the round
+that just ended and starts the new one. Never call `game.newRound()` on a client
+and never both end the round and run your own intermission — the ceiling is the
+only other thing that can end it, and it exists so a forgotten call cannot wedge
+the round.
+
+## Do / Don't
+
+- DON'T write `game.state.flow` from a script. Set the params instead.
+- DON'T count players yourself for a lobby — `game.state.flow.present` is the
+  server's own count, and a client has no roster to count.
+- DON'T reset scores on a timer. Reset them in `game.onRoundStart`, which runs on
+  the server for every round Game Flow or your script starts.
+- DO write the board rows before the round ends, not after: the winners line is
+  read from `boardKey` at that instant. Rows are `{ player, score }`-ish objects
+  — `player`/`p`/`address` and `score`/`points`/`time` are all understood.
+
+## Example
+
+"End the round as soon as three players finish, and show the winners": place Game
+Flow with `endsWhen: 'script'`, then in the server branch of your own script
+
+    start(): void {
+      if (isServer()) {
+        game.onRequest('finish', (_data, player) => {
+          const done = [...(game.state.finishers ?? []), player]
+          game.setState({ finishers: done, leaderboard: board(done) })
+          if (done.length >= 3) game.newRound()
+          return { ok: true }
+        })
+        return
+      }
+    }

package/prefabs/game-flow/composite.json

@@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "Game Flow"
+          }
+        }
+      }
+    },
+    {
+      "name": "core::TextShape",
+      "data": {
+        "0": {
+          "json": {
+            "text": "GAME FLOW\n--:--\nwaiting for the Multiplayer Server",
+            "fontSize": 3,
+            "textColor": { "r": 1, "g": 1, "b": 1, "a": 1 },
+            "outlineColor": { "r": 0, "g": 0, "b": 0 },
+            "outlineWidth": 0.1
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::Script",
+      "data": {
+        "0": {
+          "json": {
+            "value": [
+              {
+                "path": "{assetPath}/scripts/game-flow.ts",
+                "priority": 0,
+                "layout": "{\"params\":{},\"actions\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/game-flow/data.json

@@ -0,0 +1,27 @@
+{
+  "id": "44374100-12fb-481f-90ce-2a4d81949084",
+  "name": "Game Flow",
+  "description": "Lobby, countdown, rounds, winners — runs your game from start to end. Works with: Leaderboard, Announcer.",
+  "category": "custom",
+  "group": "Multiplayer Server",
+  "tags": [
+    "multiplayer",
+    "server",
+    "round",
+    "lobby",
+    "countdown",
+    "timer",
+    "winners"
+  ],
+  "requiresSdk": "auth-server",
+  "version": "1.0.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "Initial release: lobby → round → winners on game.round, a countdown every client derives from one shared deadline, a winners line read from the board key a Leaderboard shows, and a \"script\" mode where your own game.newRound() ends the round and the round length is only a ceiling."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/game-flow/scripts/game-flow.ts

@@ -0,0 +1,168 @@
+// Lobby, countdown, rounds, winners — the piece that runs a game from start to
+// end. Everything it decides is decided once, on the server; the sign on the
+// placed entity is what every player draws from those decisions.
+//
+// The flow rides one shared fact, `game.state.flow` — a phase, the instant that
+// phase ends, and the number of rounds played. Nothing here is a timer, so a
+// player who joins mid-round reads the same countdown as everybody else, and a
+// restart lands everyone on the phase the scene is actually in.
+//
+// A script may end the round itself with game.newRound(); this piece follows it
+// rather than fighting it, and in that mode the round length is only a ceiling —
+// when the ceiling fires it goes out through game.newRound() too, so a round
+// never ends down two different paths. See ai.md in this folder.
+import { TextShape, type Entity } from '@dcl/sdk/ecs'
+import { isServer } from '@dcl/sdk/network'
+import { game } from '~runtime/game'
+import {
+  advanceFlow,
+  asFlowFact,
+  configFromSeconds,
+  intermissionState,
+  lobbyState,
+  panelText,
+  podiumLine,
+  roundState,
+  type FlowConfig,
+  type FlowState
+} from './pure/flow'
+
+const FLOW_KEY = 'flow'
+const ANNOUNCE = 'announce'
+const TICK_S = 0.25
+const PAINT_S = 0.2
+const PODIUM_PLACES = 3
+
+// One Game Flow runs the rounds. A second placed copy still paints its own sign,
+// but never drives the phases: two writers on one fact is a fight with no
+// winner, and a creator would only see the countdown stutter.
+let claimed = false
+
+export class GameFlow {
+  private primary = false
+  private present = new Set<string>()
+  private flow: FlowState = lobbyState()
+  private accum = 0
+  private painted = ''
+  private published = ''
+  private warnedCeiling = false
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    /** How long a round lasts. With "script" below this is only a ceiling. */
+    public roundSeconds: number = 300,
+    /** How long the lobby counts down once enough players are in. */
+    public countdownSeconds: number = 10,
+    /** How long the winners stay up between rounds. */
+    public intermissionSeconds: number = 10,
+    /** Players needed before a round starts. */
+    public minPlayers: number = 1,
+    /** Who ends a round: this clock, or your own script calling game.newRound(). */
+    public endsWhen: 'timer' | 'script' = 'timer',
+    /** The game.state key the winners come from — the key a Leaderboard shows. */
+    public boardKey: string = 'leaderboard'
+  ) {}
+
+  private get config(): FlowConfig {
+    return configFromSeconds(this.roundSeconds, this.countdownSeconds, this.intermissionSeconds, this.minPlayers)
+  }
+
+  start(): void {
+    if (isServer()) {
+      this.primary = !claimed
+      claimed = true
+      if (!this.primary) {
+        console.log('[gameFlow] a second Game Flow is placed — only the first runs the rounds')
+        return
+      }
+      game.onReady(() => {
+        this.flow = lobbyState()
+        this.publish()
+      })
+      game.onPlayerJoin((player) => {
+        this.present.add(player)
+      })
+      game.onPlayerLeave((player) => {
+        this.present.delete(player)
+      })
+      // Every round start comes through here — this piece's own and any a script
+      // starts — so the two can never both end one round. A round a script ended
+      // gets no podium from here: the script that closed it writes its own, and
+      // this one would be read from a board the script has not filled yet.
+      game.onRoundStart((round) => {
+        // Round 1 is the round every scene boots into; the lobby sits in it.
+        if (round.number <= 1) return
+        this.flow = roundState(this.flow, this.config, game.now())
+        this.publish()
+      })
+      game.every(TICK_S, () => this.tick())
+    }
+  }
+
+  update(dt: number): void {
+    if (isServer()) { return }
+    this.accum += dt
+    if (this.accum < PAINT_S) return
+    this.accum = 0
+    this.paint()
+  }
+
+  private tick(): void {
+    const config = this.config
+    const { state, action } = advanceFlow(this.flow, config, this.present.size, game.now())
+    this.flow = state
+    if (action === 'startRound') {
+      game.newRound()
+      return
+    }
+    if (action === 'endRound') {
+      // In script mode the deadline is only a ceiling, and ending the round here
+      // would skip the script's own close — its payout, its podium, its teleport
+      // home — with nothing printed. Go out the same door a script goes out.
+      if (this.endsWhen === 'script') {
+        this.warnCeiling()
+        game.newRound()
+        return
+      }
+      this.announcePodium()
+      this.flow = intermissionState(this.flow, config, game.now())
+    }
+    this.publish()
+  }
+
+  private warnCeiling(): void {
+    if (this.warnedCeiling) return
+    this.warnedCeiling = true
+    console.log(
+      '[server] Game Flow: The round hit its time ceiling — call game.newRound() from your script, or raise the ceiling.'
+    )
+  }
+
+  private announcePodium(): void {
+    game.broadcast(ANNOUNCE, { text: podiumLine(game.state[this.boardKey], PODIUM_PLACES) })
+  }
+
+  private publish(): void {
+    const fact = { ...this.flow, present: this.present.size }
+    const json = JSON.stringify(fact)
+    // 4 Hz of an unchanged fact is 4 Hz of wire traffic for nothing.
+    if (json === this.published) return
+    this.published = json
+    game.setState({ [FLOW_KEY]: fact })
+  }
+
+  private paint(): void {
+    const fact = asFlowFact(game.state[FLOW_KEY])
+    const text = panelText(fact, game.now(), this.endsWhen === 'timer', this.config.minPlayers)
+    if (text === this.painted) return
+    this.painted = text
+    TextShape.createOrReplace(this.entity, {
+      text,
+      fontSize: 3,
+      textColor: { r: 1, g: 1, b: 1, a: 1 },
+      outlineColor: { r: 0, g: 0, b: 0 },
+      outlineWidth: 0.1
+    })
+  }
+}