@dcl-regenesislabs/bevy-headless-server 0.1.0-31413755159.commit-5b7586c

package/README.md

@@ -0,0 +1,60 @@
+# @dcl-regenesislabs/bevy-headless-server
+
+Decentraland authoritative scene server, powered by the [bevy explorer](https://github.com/decentraland/bevy-explorer)
+engine. A drop-in replacement for `@dcl/hammurabi-server`: same CLI contract, native binary
+instead of Node + Babylon.
+
+```bash
+npx @dcl-regenesislabs/bevy-headless-server --realm http://localhost:8000
+```
+
+The Decentraland SDK spawns this automatically for scenes with `authoritativeMultiplayer`
+enabled; you rarely need to run it by hand.
+
+## Options
+
+| Flag | Meaning |
+| --- | --- |
+| `--realm <url>` | Realm to serve. Required. |
+| `--position <x,y>` | Parcel to load. Defaults to `0,0`. |
+| `--production` | Production mode; disables preview-only behaviour. |
+| `--tick-hz <n>` | Scene tick rate. Defaults to 30. |
+| `--timeout <secs>` | Exit cleanly after N seconds. |
+
+`--scene-id`, `--private-key` and `--env` are accepted for hammurabi compatibility and ignored.
+
+## Orchestrated mode (multiplayer-server)
+
+`--orchestrated` starts the engine in multi-scene worker mode: no realm needed, scenes are
+added and removed over stdin (JSON lines) with pre-minted comms adapters, and control
+events come back on stdout with the `@bevy-ctl ` prefix.
+
+Orchestrators that manage the process themselves can skip the CLI and resolve the engine
+path programmatically:
+
+```js
+const { resolveBinary } = require('@dcl-regenesislabs/bevy-headless-server')
+spawn(resolveBinary(), ['--orchestrated'], { stdio: ['pipe', 'pipe', 'inherit'] })
+```
+
+## How the binary is delivered
+
+The engine ships as four platform packages (`darwin-arm64`, `darwin-x64`, `linux-x64`,
+`win32-x64`) listed under `optionalDependencies`; your package manager installs only the one
+matching your machine. Each contains two files that **must stay in the same directory** —
+the engine execs its scene-runtime sidecar from its own location.
+
+Set `DCL_BEVY_SERVER_PATH` to an absolute path to use a pre-installed engine instead
+(useful for Electron hosts that bundle their own copy).
+
+Exit code `78` means the engine is permanently unavailable here — unsupported platform,
+missing binary, or bad arguments — so a caller can fall back to another implementation
+instead of retrying.
+
+## Linux runtime dependencies
+
+The engine links the graphics/audio stack even when running headless:
+
+```bash
+sudo apt install libasound2 libudev1 libgl1 libx11-6 libxext6
+```

package/bin/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict'
+
+const { spawn } = require('child_process')
+const path = require('path')
+const {
+  resolveBinary,
+  UnsupportedPlatformError,
+  MissingBinaryError
+} = require('../lib/resolve-binary')
+
+// Exit code 78 (EX_CONFIG) means "permanently unavailable here" — callers use it to
+// fall back to another server implementation instead of retrying.
+const EXIT_UNAVAILABLE = 78
+
+const USAGE = `
+  Decentraland authoritative scene server (bevy engine)
+
+  Usage: bevy-headless-server --realm <url> [options]
+
+    --realm <url>          Realm to serve. Required unless --orchestrated.
+    --position <x,y>       Parcel to load. Default 0,0.
+    --production           Production mode (disables preview-only behaviour).
+    --orchestrated         Multi-scene mode driven over stdin by an orchestrator
+                           (the multiplayer-server worker contract).
+    --tick-hz <n>          Scene tick rate. Default 30.
+    --timeout <secs>       Exit cleanly after N seconds.
+    --version              Print version and exit.
+    -h, --help             This message.
+
+  Environment:
+    DCL_BEVY_SERVER_PATH   Absolute path to a pre-installed \`headless\` binary,
+                           bypassing the bundled platform package.
+`
+
+function fail(message, code) {
+  process.stderr.write(`bevy-headless-server: ${message}\n`)
+  process.exit(code)
+}
+
+/** Translate the hammurabi-server CLI contract into bevy-headless flags. */
+function translate(argv) {
+  const out = []
+  let realm = null
+  let position = null
+  let production = false
+  let orchestrated = false
+  const passthrough = { '--tick-hz': true, '--timeout': true, '--scene-threads': true }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    // hammurabi accepts --flag=value; bevy's parser wants them separated.
+    const eq = arg.indexOf('=')
+    const name = eq === -1 ? arg : arg.slice(0, eq)
+    const inlineValue = eq === -1 ? null : arg.slice(eq + 1)
+    const takeValue = () => (inlineValue !== null ? inlineValue : argv[++i])
+
+    switch (name) {
+      case '--realm':
+        realm = takeValue()
+        break
+      case '--position':
+        position = takeValue()
+        break
+      case '--production':
+        production = true
+        break
+      case '--orchestrated':
+        orchestrated = true
+        break
+      case '-h':
+      case '--help':
+        process.stdout.write(USAGE)
+        process.exit(0)
+        break
+      case '--version':
+        process.stdout.write(`${require('../package.json').version}\n`)
+        process.exit(0)
+        break
+      // Accepted by hammurabi, no equivalent here. Warn rather than fail so an
+      // orchestrator passing extra flags still boots.
+      case '--scene-id':
+      case '--private-key':
+      case '--env':
+        takeValue()
+        process.stderr.write(`bevy-headless-server: ignoring unsupported flag ${name}\n`)
+        break
+      default:
+        if (passthrough[name]) {
+          out.push(name, takeValue())
+        } else {
+          process.stderr.write(`bevy-headless-server: ignoring unknown flag ${arg}\n`)
+        }
+    }
+  }
+
+  // orchestrated mode gets scenes (with their content URLs) over stdin, so no realm
+  if (!realm && !orchestrated) fail('--realm is required', EXIT_UNAVAILABLE)
+  if (realm) {
+    try {
+      // eslint-disable-next-line no-new
+      new URL(realm)
+    } catch (e) {
+      fail(`--realm is not a valid URL: ${realm}`, EXIT_UNAVAILABLE)
+    }
+  }
+  if (position && !/^-?\d+,-?\d+$/.test(position)) {
+    fail(`--position must be "x,y", got: ${position}`, EXIT_UNAVAILABLE)
+  }
+
+  const args = orchestrated ? ['--orchestrated'] : ['--server-mode']
+  if (realm) args.unshift('--realm', realm)
+  if (position) args.push('--location', position)
+  if (!production) args.push('--preview')
+  return args.concat(out)
+}
+
+function main() {
+  const args = translate(process.argv.slice(2))
+
+  let exe
+  try {
+    exe = resolveBinary()
+  } catch (err) {
+    if (err instanceof UnsupportedPlatformError || err instanceof MissingBinaryError) {
+      fail(err.message, EXIT_UNAVAILABLE)
+    }
+    throw err
+  }
+
+  const child = spawn(exe, args, { stdio: 'inherit', env: process.env })
+
+  child.on('error', (err) => {
+    if (process.platform === 'linux' && /ENOENT|not found/i.test(err.message)) {
+      process.stderr.write(
+        'bevy-headless-server: the engine failed to start. On Linux it needs:\n' +
+          '  sudo apt install libasound2 libudev1 libgl1 libx11-6 libxext6\n'
+      )
+      process.exit(EXIT_UNAVAILABLE)
+    }
+    fail(`failed to start the engine: ${err.message}`, EXIT_UNAVAILABLE)
+  })
+
+  const forward = (signal) => () => {
+    if (!child.killed) child.kill(signal)
+  }
+  process.on('SIGTERM', forward('SIGTERM'))
+  process.on('SIGINT', forward('SIGINT'))
+  process.on('exit', forward('SIGTERM'))
+
+  child.on('close', (code, signal) => {
+    process.exit(signal ? 1 : code === null ? 1 : code)
+  })
+}
+
+main()

package/install.js

@@ -0,0 +1,20 @@
+'use strict'
+
+// Advisory postinstall check. The binary itself arrives through optionalDependencies;
+// this only turns npm's silent optional-dependency skip (npm/cli#4828, and every
+// --ignore-scripts / --no-optional install) into a readable message at install time
+// rather than a confusing failure at first run.
+
+const { resolveBinary, platformKey } = require('./lib/resolve-binary')
+
+try {
+  resolveBinary()
+} catch (err) {
+  const key = platformKey()
+  process.stderr.write(
+    `\n@dcl-regenesislabs/bevy-headless-server: ${err.message}\n` +
+      (key
+        ? `  Fix with: npm install @dcl-regenesislabs/bevy-headless-server-${key}@${require('./package.json').version}\n\n`
+        : '\n')
+  )
+}

package/lib/resolve-binary.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// Platform packages ship `headless` and `dcl_deno_ipc` side by side. The engine
+// spawns the sidecar from its own directory under a fixed name, so the pair must
+// never be split or copied apart.
+const SUPPORTED = {
+  'darwin arm64': 'darwin-arm64',
+  'darwin x64': 'darwin-x64',
+  'linux x64': 'linux-x64',
+  'win32 x64': 'win32-x64'
+}
+
+function platformKey() {
+  return SUPPORTED[`${process.platform} ${process.arch}`]
+}
+
+class UnsupportedPlatformError extends Error {}
+class MissingBinaryError extends Error {}
+
+function resolveFromPackage(key) {
+  const pkg = `@dcl-regenesislabs/bevy-headless-server-${key}`
+  const dir = path.dirname(require.resolve(`${pkg}/package.json`))
+  return path.join(dir, 'bin')
+}
+
+/**
+ * Absolute path to the `headless` executable.
+ * DCL_BEVY_SERVER_PATH overrides everything (Creator Hub / pre-seeded installs).
+ */
+function resolveBinary() {
+  const override = process.env.DCL_BEVY_SERVER_PATH
+  if (override) {
+    if (!fs.existsSync(override)) {
+      throw new MissingBinaryError(`DCL_BEVY_SERVER_PATH points at a missing file: ${override}`)
+    }
+    return verifySidecar(override)
+  }
+
+  const key = platformKey()
+  if (!key) {
+    throw new UnsupportedPlatformError(
+      `no bevy-headless build for ${process.platform}-${process.arch} ` +
+        `(supported: ${Object.values(SUPPORTED).join(', ')})`
+    )
+  }
+
+  let binDir
+  try {
+    binDir = resolveFromPackage(key)
+  } catch (err) {
+    throw new MissingBinaryError(
+      `@dcl-regenesislabs/bevy-headless-server-${key} is not installed. ` +
+        `If your package manager skipped optional dependencies, reinstall with them enabled ` +
+        `or install that package explicitly.`
+    )
+  }
+
+  const exe = path.join(binDir, process.platform === 'win32' ? 'headless.exe' : 'headless')
+  if (!fs.existsSync(exe)) {
+    throw new MissingBinaryError(`corrupt install: ${exe} is missing — reinstall the package`)
+  }
+  return verifySidecar(exe)
+}
+
+function verifySidecar(exe) {
+  const sidecar = path.join(
+    path.dirname(exe),
+    process.platform === 'win32' ? 'dcl_deno_ipc.exe' : 'dcl_deno_ipc'
+  )
+  if (!fs.existsSync(sidecar)) {
+    throw new MissingBinaryError(
+      `the scene runtime sidecar is missing next to the engine (expected ${sidecar}). ` +
+        `The two binaries must live in the same directory.`
+    )
+  }
+  return exe
+}
+
+module.exports = { resolveBinary, platformKey, SUPPORTED, UnsupportedPlatformError, MissingBinaryError }

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dcl-regenesislabs/bevy-headless-server",
+  "version": "0.1.0-31413755159.commit-5b7586c",
+  "description": "Decentraland authoritative scene server (bevy engine) — drop-in replacement for @dcl/hammurabi-server",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decentraland/bevy-explorer.git",
+    "directory": "deploy/headless/launcher"
+  },
+  "bin": {
+    "bevy-headless-server": "bin/cli.js"
+  },
+  "main": "lib/resolve-binary.js",
+  "files": [
+    "bin/cli.js",
+    "lib/resolve-binary.js",
+    "install.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@dcl-regenesislabs/bevy-headless-server-darwin-arm64": "0.1.0-31413755159.commit-5b7586c",
+    "@dcl-regenesislabs/bevy-headless-server-darwin-x64": "0.1.0-31413755159.commit-5b7586c",
+    "@dcl-regenesislabs/bevy-headless-server-linux-x64": "0.1.0-31413755159.commit-5b7586c",
+    "@dcl-regenesislabs/bevy-headless-server-win32-x64": "0.1.0-31413755159.commit-5b7586c"
+  },
+  "commit": "5b7586c8b7e79106680c4d7fb8ab8fad842531b8"
+}