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

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

@@ -0,0 +1,185 @@
+// Game Flow's phase arithmetic, with no SDK and no I/O.
+//
+// The loop is lobby → round → intermission → round → …, and every phase is a
+// deadline rather than a timer: the server writes when a phase ENDS, and each
+// client derives its countdown from that one number against the shared clock.
+// A player who joins mid-round therefore lands on the same countdown as
+// everyone else without a single extra message.
+//
+// The lobby parks (endsAtMs 0) while the scene is short of players, so a round
+// never burns down in an empty world and the next arrival gets a full lobby.
+
+export type FlowPhase = 'lobby' | 'round' | 'intermission'
+
+/** What the flow wants the caller to do at this tick. */
+export type FlowAction = 'none' | 'startRound' | 'endRound'
+
+export interface FlowConfig {
+  roundMs: number
+  countdownMs: number
+  intermissionMs: number
+  minPlayers: number
+}
+
+/** The machine's own state. `round` counts rounds PLAYED, from 1. */
+export interface FlowState {
+  phase: FlowPhase
+  endsAtMs: number
+  round: number
+}
+
+/**
+ * What the server publishes. The head count only exists there — a client has no
+ * roster — so it rides the fact rather than being counted twice.
+ */
+export interface FlowFact extends FlowState {
+  present: number
+}
+
+export const MIN_SECONDS = 1
+export const MAX_SECONDS = 3600
+
+/** A creator can type anything into a number field; a 0-second round would spin. */
+export function clampSeconds(value: number): number {
+  if (!Number.isFinite(value)) return MIN_SECONDS
+  return Math.min(MAX_SECONDS, Math.max(MIN_SECONDS, Math.round(value)))
+}
+
+export function configFromSeconds(
+  round: number,
+  countdown: number,
+  intermission: number,
+  minPlayers: number
+): FlowConfig {
+  return {
+    roundMs: clampSeconds(round) * 1000,
+    countdownMs: clampSeconds(countdown) * 1000,
+    intermissionMs: clampSeconds(intermission) * 1000,
+    minPlayers: Number.isFinite(minPlayers) ? Math.max(1, Math.round(minPlayers)) : 1
+  }
+}
+
+export function lobbyState(): FlowState {
+  return { phase: 'lobby', endsAtMs: 0, round: 0 }
+}
+
+/** Defensive read: the fact crossed the wire and a script can clobber the key. */
+export function asFlowFact(value: unknown): FlowFact | null {
+  if (typeof value !== 'object' || value === null) return null
+  const record = value as Record<string, unknown>
+  const phase = record.phase
+  if (phase !== 'lobby' && phase !== 'round' && phase !== 'intermission') return null
+  const num = (key: string): number => {
+    const raw = record[key]
+    return typeof raw === 'number' && Number.isFinite(raw) ? Math.max(0, Math.floor(raw)) : 0
+  }
+  return { phase, endsAtMs: num('endsAtMs'), round: num('round'), present: num('present') }
+}
+
+/**
+ * One tick of the machine. Pure: the caller owns the clock, the head count, and
+ * the two side effects (`startRound` calls game.newRound, `endRound` closes the
+ * round out). Rounds never end here in script mode by accident — the caller
+ * decides whether an expired round deadline is the end or only a ceiling.
+ */
+export function advanceFlow(
+  state: FlowState,
+  config: FlowConfig,
+  present: number,
+  nowMs: number
+): { state: FlowState; action: FlowAction } {
+  if (state.phase === 'round') {
+    if (state.endsAtMs > 0 && nowMs >= state.endsAtMs) return { state, action: 'endRound' }
+    return { state, action: 'none' }
+  }
+  const ready = present >= config.minPlayers
+  if (state.phase === 'intermission') {
+    if (nowMs < state.endsAtMs) return { state, action: 'none' }
+    if (!ready) return { state: { phase: 'lobby', endsAtMs: 0, round: state.round }, action: 'none' }
+    return { state, action: 'startRound' }
+  }
+  if (!ready) {
+    if (state.endsAtMs === 0) return { state, action: 'none' }
+    return { state: { ...state, endsAtMs: 0 }, action: 'none' }
+  }
+  if (state.endsAtMs === 0) {
+    return { state: { ...state, endsAtMs: nowMs + config.countdownMs }, action: 'none' }
+  }
+  if (nowMs >= state.endsAtMs) return { state, action: 'startRound' }
+  return { state, action: 'none' }
+}
+
+// A round always carries a deadline, even where a script owns the end: it is the
+// ceiling that keeps a forgotten game.newRound() from wedging the loop forever.
+// Only the panel differs — in script mode it hides a clock it does not own.
+export function roundState(state: FlowState, config: FlowConfig, nowMs: number): FlowState {
+  return { phase: 'round', endsAtMs: nowMs + config.roundMs, round: state.round + 1 }
+}
+
+export function intermissionState(state: FlowState, config: FlowConfig, nowMs: number): FlowState {
+  return { phase: 'intermission', endsAtMs: nowMs + config.intermissionMs, round: state.round }
+}
+
+/** Whole seconds left, the way a countdown reads them. */
+export function secondsLeft(state: { endsAtMs: number }, nowMs: number): number {
+  if (state.endsAtMs === 0) return 0
+  return Math.max(0, Math.ceil((state.endsAtMs - nowMs) / 1000))
+}
+
+export function formatCountdown(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds))
+  const rest = total % 60
+  return `${Math.floor(total / 60)}:${rest < 10 ? '0' : ''}${rest}`
+}
+
+/** One row of whatever a board key holds — the shapes real games write vary. */
+export interface Standing {
+  player: string
+  score: number
+}
+
+const PLAYER_FIELDS = ['player', 'p', 'address', 'wallet', 'name']
+const SCORE_FIELDS = ['score', 'points', 'pts', 'value', 'seconds', 'time', 'best']
+
+/**
+ * Read a board out of a `game.state` key. Creators write these rows themselves,
+ * so the field names differ game to game — anything with a player-ish and a
+ * number-ish field is a standing, and anything else is skipped rather than
+ * rendered as `[object Object]`.
+ */
+export function standingsOf(value: unknown): Standing[] {
+  if (!Array.isArray(value)) return []
+  const out: Standing[] = []
+  for (const item of value) {
+    if (typeof item !== 'object' || item === null) continue
+    const record = item as Record<string, unknown>
+    const playerKey = PLAYER_FIELDS.find((key) => typeof record[key] === 'string' && record[key] !== '')
+    const scoreKey = SCORE_FIELDS.find((key) => typeof record[key] === 'number' && Number.isFinite(record[key]))
+    if (playerKey === undefined || scoreKey === undefined) continue
+    out.push({ player: String(record[playerKey]), score: Number(record[scoreKey]) })
+  }
+  return out
+}
+
+/** Wallets are long; a podium line reads better with the tail. */
+export function shortName(player: string): string {
+  return player.startsWith('0x') && player.length > 10 ? `${player.slice(0, 6)}…${player.slice(-4)}` : player
+}
+
+/** The winners line broadcast to every player at the end of a round. */
+export function podiumLine(value: unknown, places: number): string {
+  const top = standingsOf(value).slice(0, Math.max(1, places))
+  if (top.length === 0) return 'Round over — nobody scored.'
+  return `Round over — ${top.map((row, i) => `${i + 1}. ${shortName(row.player)}`).join('  ')}`
+}
+
+export function panelText(fact: FlowFact | null, nowMs: number, showClock: boolean, needed: number): string {
+  if (fact === null) return 'GAME FLOW\n--:--\nwaiting for the Multiplayer Server'
+  if (fact.phase === 'lobby') {
+    if (fact.endsAtMs === 0) return `LOBBY\n--:--\n${fact.present}/${needed} players`
+    return `LOBBY\n${formatCountdown(secondsLeft(fact, nowMs))}\nstarting`
+  }
+  if (fact.phase === 'intermission') return `ROUND ${fact.round} OVER\n${formatCountdown(secondsLeft(fact, nowMs))}`
+  if (!showClock) return `ROUND ${fact.round}`
+  return `ROUND ${fact.round}\n${formatCountdown(secondsLeft(fact, nowMs))}`
+}

package/prefabs/health-respawn/ai.md

@@ -0,0 +1,76 @@
+---
+prefab: health-respawn
+claims-state: game.state.health
+claims-messages: respawn
+---
+
+# Health & Respawn — AI guide
+
+Hit points the server owns, and a respawn point players come back to.
+
+The project copy is normally custom/health_respawn/ — check what is on disk, a
+second copy is custom/health_respawn_2/.
+
+## When to use
+
+Any scene where players can die: a fall, a hazard, a fight. Place ONE anywhere;
+it is invisible. A second copy is a no-op (the first one's params win).
+
+Do NOT write your own health map, death check or teleport-home code — this prefab
+owns all three, and health a client can edit is health nobody can trust.
+
+## API
+
+    import { damage, healthOf } from '../../custom/health_respawn/scripts/health'
+
+- `damage(player, amount)` — WHICH SIDE: the SERVER, inside the `if (isServer())`
+  branch, from a `game.onRequest`, `game.onEnterArea`, `game.every` or
+  `game.onRoundStart` handler. Takes the player to a minimum of 0; at 0 this
+  prefab respawns them within half a second and refills them. A player who is not
+  in the scene is ignored.
+- `healthOf(player)` — reads hit points on either side, the client included.
+- `game.state.health` — the whole `{ wallet: points }` map, readable on every
+  client and by late joiners. Read it to draw bars or count who is alive; never
+  write it.
+
+Params of the prefab's script — set them in the placePrefab request:
+
+- `respawnAt`: the entity players come back to. Pick a pad or marker that sits at
+  the scene root — the position is read straight off its Transform. Until it is
+  picked, nothing respawns and the console says so.
+- `maxHealth`: hit points a player starts every life with (default 100). Also the
+  refill at a new round.
+- `dieBelowHeight`: players below this height die (default 0 = off). This is the
+  death plane for a climbing or platforming scene; set it under the lowest floor
+  a player is allowed to stand on.
+
+## Hazards
+
+A hurting area is a Trigger Area plus one handler in the server branch — this
+prefab deliberately has no area list, because damage belongs to it and detection
+belongs to the area. `game.onEnterArea` is a server verb:
+
+    start(): void {
+      if (isServer()) {
+        game.onEnterArea('Moat', (player) => damage(player, 100))
+        return
+      }
+    }
+
+## Do / Don't
+
+- DON'T call `damage` on the client. Only the server changes synced state, so the
+  call does nothing there.
+- DON'T teleport a dead player yourself. The server broadcasts `respawn` to that
+  one player and their own client moves them; a `movePlayerTo` in your code moves
+  the wrong avatar or none.
+- DON'T handle `respawn` yourself with `game.onBroadcast('respawn', …)`. This
+  prefab already listens on it, on the client side.
+- DO reset scores in `game.onRoundStart` if you also want a fresh scoreboard —
+  this prefab only refills health.
+
+## Example
+
+"Kill anyone who falls off the tower and send them back to the base": place Health
+& Respawn, pick the BaseSpawn pad as `respawnAt`, and set `dieBelowHeight` to the
+height just under the tower's first floor. No script at all.

package/prefabs/health-respawn/composite.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "Health & Respawn"
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::Script",
+      "data": {
+        "0": {
+          "json": {
+            "value": [
+              {
+                "path": "{assetPath}/scripts/health-respawn.ts",
+                "priority": 0,
+                "layout": "{\"params\":{},\"actions\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/health-respawn/data.json

@@ -0,0 +1,38 @@
+{
+  "id": "5cc3b4d7-2a87-4825-9a53-e2b007bcff24",
+  "name": "Health & Respawn",
+  "description": "Players can take damage and respawn. Works with: Game Flow, Trigger Area.",
+  "category": "custom",
+  "group": "Multiplayer Server",
+  "tags": [
+    "player",
+    "health",
+    "damage",
+    "respawn",
+    "multiplayer",
+    "server"
+  ],
+  "requiresSdk": "auth-server",
+  "requiredPermissions": [
+    "ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE"
+  ],
+  "drivenBy": {
+    "rule": "Nothing takes hit points by itself — the server calls damage() wherever the harm happens, and this item does the dying and the respawn.",
+    "code": "game.onEnterArea('Spikes', (player) => damage(player, 25))",
+    "next": "Press New script below, write that inside the isServer() block it comes with, and import damage from the health.ts beside this item's own script."
+  },
+  "version": "1.1.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "Initial release: hit points the server owns in game.state.health, a respawn point picked in the inspector, a \"die below height\" death plane, and a damage() other server code calls."
+    },
+    {
+      "version": "1.1.0",
+      "notes": "The placed item's Script card now shows the damage() call that takes hit points, under its respawn settings."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/health-respawn/scripts/health-respawn.ts

@@ -0,0 +1,98 @@
+// Players can take damage and respawn. The server owns everyone's hit points and
+// decides who died; a client only moves its own player when the server says so,
+// because moving an avatar is the one thing only that player's client can do.
+//
+// Hit points live in `game.state.health` — one wallet → points map every player
+// can read, which is what makes a health bar or a "who is still alive" check a
+// plain read instead of a message. Other server code hurts a player through
+// damage() below; the sweep here notices the zero and respawns them.
+import { Transform, type Entity } from '@dcl/sdk/ecs'
+import { isServer } from '@dcl/sdk/network'
+import { movePlayerTo } from '~system/RestrictedActions'
+import { game, type Player } from '~runtime/game'
+import { asHealthMap, clampMax, deadPlayers } from './pure/health'
+import { HEALTH_KEY } from './health'
+
+const RESPAWN = 'respawn'
+const SWEEP_S = 0.5
+const NO_POINT = "Players won't respawn anywhere until you pick a respawn point."
+
+// One Health & Respawn owns the roster. A second copy would revive everyone the
+// first one just killed, half a second apart.
+let claimed = false
+
+export class HealthRespawn {
+  private primary = false
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    /** Where players come back. Pick the pad or marker they should land on. */
+    public respawnAt: Entity = 0 as Entity,
+    /** Hit points a player starts every life with. */
+    public maxHealth: number = 100,
+    /** Players who fall below this height die. Leave at 0 to switch it off. */
+    public dieBelowHeight: number = 0
+  ) {}
+
+  start(): void {
+    // Claimed before the branch: each side keeps its own `claimed`, and the copy
+    // that answers a respawn must be the same one whose params drive the sweep.
+    this.primary = !claimed
+    claimed = true
+    if (!this.primary) {
+      console.log('[healthRespawn] a second Health & Respawn is placed — only the first tracks health')
+      return
+    }
+    if (this.respawnAt === (0 as Entity)) console.log(`[healthRespawn] ${NO_POINT}`)
+    if (isServer()) {
+      game.onReady(() => game.setState({ [HEALTH_KEY]: {} }))
+      game.onPlayerJoin((player) => this.revive(player))
+      game.onPlayerLeave((player) => {
+        const map = { ...asHealthMap(game.state[HEALTH_KEY]) }
+        delete map[player]
+        game.setState({ [HEALTH_KEY]: map })
+      })
+      game.onRoundStart(() => {
+        const map = asHealthMap(game.state[HEALTH_KEY])
+        const full: Record<string, number> = {}
+        for (const player of Object.keys(map)) full[player] = clampMax(this.maxHealth)
+        game.setState({ [HEALTH_KEY]: full })
+      })
+      game.every(SWEEP_S, () => this.sweep())
+      return
+    }
+    game.onBroadcast(RESPAWN, () => this.goHome())
+  }
+
+  private sweep(): void {
+    const map = asHealthMap(game.state[HEALTH_KEY])
+    const dead = deadPlayers(map, (player) => game.positionOf(player), this.deathPlane)
+    if (dead.length === 0) return
+    const next = { ...map }
+    for (const player of dead) {
+      next[player] = clampMax(this.maxHealth)
+      game.broadcast(RESPAWN, {}, player)
+    }
+    game.setState({ [HEALTH_KEY]: next })
+  }
+
+  private get deathPlane(): number {
+    return Number.isFinite(this.dieBelowHeight) ? this.dieBelowHeight : 0
+  }
+
+  private revive(player: Player): void {
+    game.setState({
+      [HEALTH_KEY]: { ...asHealthMap(game.state[HEALTH_KEY]), [player]: clampMax(this.maxHealth) }
+    })
+  }
+
+  private goHome(): void {
+    const point = this.respawnAt === (0 as Entity) ? null : Transform.getOrNull(this.respawnAt)
+    if (point === null) {
+      console.log(`[healthRespawn] ${NO_POINT}`)
+      return
+    }
+    void movePlayerTo({ newRelativePosition: { ...point.position } })
+  }
+}

package/prefabs/health-respawn/scripts/health.ts

@@ -0,0 +1,22 @@
+// What other scripts call to read and change a player's hit points. It lives
+// beside health-respawn.ts rather than in it because a prefab's script file
+// exports exactly one class — the runtime constructs the first function-valued
+// export, so a helper sitting next to the class could be built instead of it.
+import { game, type Player } from '~runtime/game'
+import { afterDamage, asHealthMap } from './pure/health'
+
+export const HEALTH_KEY = 'health'
+
+/** Hit points a player has right now. 0 means they are on their way back. */
+export function healthOf(player: Player): number {
+  return asHealthMap(game.state[HEALTH_KEY])[player] ?? 0
+}
+
+/**
+ * Hurt a player. Call it from server code — a client cannot change anyone's
+ * health. At zero the placed Health & Respawn sends them back to its respawn
+ * point on their next sweep.
+ */
+export function damage(player: Player, amount: number): void {
+  game.setState({ [HEALTH_KEY]: afterDamage(asHealthMap(game.state[HEALTH_KEY]), player, amount) })
+}

package/prefabs/health-respawn/scripts/pure/health.ts

@@ -0,0 +1,60 @@
+// Health & Respawn's bookkeeping, with no SDK and no I/O.
+//
+// Health is one shared fact — a wallet → hit points map under `game.state.health`
+// — so every player can draw a bar for anyone without asking, and a late joiner
+// reads the whole roster from the snapshot. The map is the ONLY place hit points
+// live: the server's sweep reacts to a zero, whoever wrote it.
+
+export type HealthMap = Record<string, number>
+
+export const MIN_HEALTH = 1
+export const MAX_HEALTH = 100000
+
+export function clampMax(value: number): number {
+  if (!Number.isFinite(value)) return 100
+  return Math.min(MAX_HEALTH, Math.max(MIN_HEALTH, Math.round(value)))
+}
+
+/** Defensive read: the map crossed the wire and a script can clobber the key. */
+export function asHealthMap(value: unknown): HealthMap {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {}
+  const out: HealthMap = {}
+  for (const [player, points] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof points === 'number' && Number.isFinite(points)) out[player] = Math.max(0, Math.floor(points))
+  }
+  return out
+}
+
+/**
+ * The map after `amount` damage. A player with no entry is not on the roster —
+ * hurting them would invent a roster row that never gets cleaned up.
+ */
+export function afterDamage(map: HealthMap, player: string, amount: number): HealthMap {
+  const before = map[player]
+  if (before === undefined) return map
+  const hurt = Number.isFinite(amount) ? Math.max(0, Math.round(amount)) : 0
+  return { ...map, [player]: Math.max(0, before - hurt) }
+}
+
+/**
+ * The players to respawn right now: at or below zero, or fallen
+ * past the death plane. `dieBelowY` of 0 switches the plane off — a scene whose
+ * ground sits at y 0 would otherwise kill everyone standing on it.
+ */
+export function deadPlayers(
+  map: HealthMap,
+  feetOf: (player: string) => { y: number } | null,
+  dieBelowY: number
+): string[] {
+  const out: string[] = []
+  for (const [player, points] of Object.entries(map)) {
+    if (points <= 0) {
+      out.push(player)
+      continue
+    }
+    if (dieBelowY === 0) continue
+    const feet = feetOf(player)
+    if (feet !== null && feet.y < dieBelowY) out.push(player)
+  }
+  return out
+}

package/prefabs/high-stool/composite.json

@@ -0,0 +1,74 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core::GltfContainer",
+      "data": {
+        "0": {
+          "json": {
+            "src": "{assetPath}/HighStool.glb",
+            "visibleMeshesCollisionMask": 0,
+            "invisibleMeshesCollisionMask": 3
+          }
+        }
+      }
+    },
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "High Stool"
+          }
+        },
+        "513": {
+          "json": {
+            "value": "Sit Spot"
+          }
+        }
+      }
+    },
+    {
+      "name": "core::Transform",
+      "data": {
+        "513": {
+          "json": {
+            "position": {
+              "x": 0.0194,
+              "y": 0.4707,
+              "z": 0.5924
+            },
+            "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\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/high-stool/data.json

@@ -0,0 +1,30 @@
+{
+  "id": "f8ee0d2a-19f5-45a9-9029-cd46d7a8f834",
+  "name": "High Stool",
+  "description": "A tall bar stool. Players can sit on it.",
+  "category": "custom",
+  "tags": [
+    "seat",
+    "furniture",
+    "sit"
+  ],
+  "version": "1.1.0",
+  "changelog": [
+    {
+      "version": "1.1.0",
+      "notes": "The seat no longer runs on the Multiplayer Server, where it was walking every sit spot's transform chain each frame for nobody to see."
+    },
+    {
+      "version": "1.0.0",
+      "notes": "Initial release"
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  },
+  "requiredPermissions": [
+    "ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE",
+    "ALLOW_TO_TRIGGER_AVATAR_EMOTE"
+  ],
+  "group": "Seats"
+}