@dcl/sdk-commands 7.28.0 → 7.28.1-34624845556.commit-7d0808b

package/dist/commands/start/multiplayer-server.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startMultiplayerServer = startMultiplayerServer;
+exports.spawnAuthServer = spawnAuthServer;
+const child_process_1 = require("child_process");
+const beautiful_logs_1 = require("../../logic/beautiful-logs");
+const log_1 = require("../../components/log");
+const utils_1 = require("./utils");
+const HAMMURABI_PACKAGE = '@dcl/hammurabi-server';
+const HAMMURABI_VERSION = 'next';
+const BEVY_PACKAGE = '@dcl-regenesislabs/bevy-headless-server';
+// `latest` moves only when someone dispatches bevy-explorer's publish-headless
+// workflow with dist_tag=latest — engine pushes to main land on `next` and cannot
+// change what previews run. DCL_SERVER_PACKAGE overrides for local builds.
+const BEVY_VERSION = 'latest';
+// The bevy server exits with this when it can never run here (unsupported platform,
+// missing binary, bad arguments). We fail the preview loudly instead of retrying:
+// a silent fallback would hide broken bevy installs from the people shipping them.
+const EXIT_UNAVAILABLE = 78;
+const DEFAULT_ENGINE = 'bevy';
+function selectedEngine() {
+    const requested = process.env.DCL_SERVER_ENGINE;
+    return requested === 'bevy' || requested === 'hammurabi' ? requested : DEFAULT_ENGINE;
+}
+/**
+ * npx accepts a directory or tarball as well as a registry spec, so pointing
+ * DCL_SERVER_PACKAGE at a local build exercises this spawn path without publishing.
+ */
+function packageSpec(engine) {
+    const override = process.env.DCL_SERVER_PACKAGE;
+    if (override)
+        return override;
+    return engine === 'bevy' ? `${BEVY_PACKAGE}@${BEVY_VERSION}` : `${HAMMURABI_PACKAGE}@${HAMMURABI_VERSION}`;
+}
+/**
+ * Registers cleanup handlers on the global process object
+ * Returns a function to remove the handlers
+ */
+function registerProcessCleanup(cleanup) {
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+    process.on('exit', cleanup);
+    return () => {
+        process.off('SIGTERM', cleanup);
+        process.off('SIGINT', cleanup);
+        process.off('exit', cleanup);
+    };
+}
+// `2026-08-11T14:28:33.522058Z  INFO scene_runner::renderer_context: ` — the
+// timestamp/level/target prefix the bevy engine's tracing puts on every line
+const TRACING_PREFIX = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})\.\d+Z\s+(INFO|WARN|ERROR|DEBUG|TRACE)\s+[\w:]+:\s?/;
+const HEARTBEAT_LINE = /^\[headless\] alive:/;
+// The engine colors its output even when piped, so lines arrive wrapped in ANSI
+// escapes and must be stripped before the prefix regex can match.
+// eslint-disable-next-line no-control-regex
+const ANSI_CODES = /\u001b\[[0-9;]*m/g;
+// Engine-internal noise in local preview: the asset pipeline hunts dot-prefixed
+// processed gltf paths the preview server never has (repeated on every scene
+// composition), and the headless build's expected gizmo/asset-loader startup
+// complaints about the renderer it deliberately doesn't have
+const ENGINE_NOISE = [
+    /^failed to process gltf/,
+    /^Path not found: \$ipfs/,
+    /^bevy_render feature is enabled but RenderApp was not detected/,
+    /^Could not find an asset loader matching: .* Path: Some\("embedded:\/\//
+];
+// `[[0, 0] 3.33] ` — parcel coords + scene clock the engine prepends to every
+// scene log line; redundant in a single-scene preview
+const SCENE_CONTEXT = /^\[\[-?\d+, -?\d+\] \d+\.\d+\] /;
+// color alone conveys the level; the LOG/WARN/ERROR words are dropped
+function colorByLevel(level, message) {
+    if (level === 'WARN')
+        return log_1.colors.yellow(message);
+    if (level === 'ERROR')
+        return log_1.colors.redBright(message);
+    return message;
+}
+// engine timestamps are UTC ISO with microseconds; show local wall-clock instead
+function localTime(utcTimestamp) {
+    const date = new Date(utcTimestamp + 'Z');
+    return isNaN(date.getTime()) ? '' : log_1.colors.dim(date.toTimeString().slice(0, 8)) + ' ';
+}
+/**
+ * Forwards a bevy child stream line by line, tagged `[Server]` to stand apart from
+ * the preview CLI's own output, dropping the tracing prefix (warnings yellow,
+ * errors red) and the periodic `[headless] alive:` heartbeat.
+ */
+function forwardEngineLogs(source, sink) {
+    if (!source)
+        return;
+    const serverTag = log_1.colors.greenBright('[Server]') + ' ';
+    const writeClean = (raw) => {
+        const line = raw.replace(ANSI_CODES, '');
+        if (!line.trim())
+            return;
+        if (HEARTBEAT_LINE.test(line))
+            return;
+        const match = line.match(TRACING_PREFIX);
+        if (!match) {
+            // launcher lines ([headless] realm=...): the [Server] tag replaces their own
+            sink.write(serverTag + line.replace(/^\[headless\] /, '') + '\n');
+            return;
+        }
+        const message = line.slice(match[0].length);
+        if (ENGINE_NOISE.some((pattern) => pattern.test(message)))
+            return;
+        if (SCENE_CONTEXT.test(message)) {
+            const sceneMessage = message.replace(SCENE_CONTEXT, '');
+            const sceneTag = sceneMessage.match(/^(LOG|WARN|ERROR|DEBUG) /);
+            const body = sceneTag ? sceneMessage.slice(sceneTag[0].length) : sceneMessage;
+            sink.write(serverTag + localTime(match[1]) + colorByLevel(sceneTag?.[1], body) + '\n');
+        }
+        else {
+            sink.write(serverTag + localTime(match[1]) + colorByLevel(match[2], message) + '\n');
+        }
+    };
+    let pending = '';
+    source.setEncoding('utf8');
+    source.on('data', (chunk) => {
+        const lines = (pending + chunk).split('\n');
+        pending = lines.pop() ?? '';
+        lines.forEach(writeClean);
+    });
+    source.on('end', () => {
+        if (pending)
+            writeClean(pending);
+    });
+}
+/**
+ * Starts the Multiplayer Server process using npx to install and run in one step
+ */
+function startMultiplayerServer(components, workingDir, realm, engine = DEFAULT_ENGINE) {
+    const pkg = packageSpec(engine);
+    (0, beautiful_logs_1.printProgressInfo)(components.logger, `Starting ${log_1.colors.bold('Multiplayer Server')} (${engine}) with realm: ${log_1.colors.bold(realm)}`);
+    const npxArgs = ['--yes', pkg, `--realm=${realm}`];
+    const npxCliJs = (0, utils_1.findNpxCliJs)();
+    // In Electron, override npm_config_prefix because npm derives its prefix from process.execPath,
+    // which points to the Electron Helper binary. This causes npm to look for a `lib/` directory
+    // inside the Helper bundle, which doesn't exist (ENOENT).
+    const env = (0, utils_1.isElectronEnvironment)()
+        ? { ...(0, utils_1.getSpawnEnv)(), npm_config_prefix: workingDir }
+        : { ...(0, utils_1.getSpawnEnv)() };
+    // Quiet the bevy engine's internal tracing chatter while keeping scene logs
+    // (scene_runner::renderer_context) and real warnings. An explicit RUST_LOG wins.
+    if (engine === 'bevy' && !env.RUST_LOG) {
+        env.RUST_LOG = 'warn,scene_runner::renderer_context=info';
+    }
+    // Bevy output goes through the line filter below; hammurabi keeps the terminal directly.
+    const stdio = engine === 'bevy' ? ['inherit', 'pipe', 'pipe'] : 'inherit';
+    // If npx-cli.js was found, run it directly via process.execPath (node in regular env,
+    // Electron Helper with ELECTRON_RUN_AS_NODE=1 in Electron). Otherwise fall back to npx binary.
+    const serverProcess = npxCliJs
+        ? (0, child_process_1.spawn)(process.execPath, [npxCliJs, ...npxArgs], { cwd: workingDir, shell: false, stdio, env })
+        : (0, child_process_1.spawn)((0, utils_1.getNpxBin)(), npxArgs, { cwd: workingDir, shell: false, stdio, env });
+    if (engine === 'bevy') {
+        forwardEngineLogs(serverProcess.stdout, process.stdout);
+        forwardEngineLogs(serverProcess.stderr, process.stderr);
+    }
+    serverProcess.on('error', (error) => {
+        (0, beautiful_logs_1.printWarning)(components.logger, `Multiplayer Server process error: ${error.message}`);
+    });
+    // Register cleanup handlers
+    const cleanup = () => {
+        if (!serverProcess.killed) {
+            serverProcess.kill('SIGTERM');
+        }
+    };
+    const removeCleanup = registerProcessCleanup(cleanup);
+    serverProcess.on('close', (code, signal) => {
+        removeCleanup();
+        if (code !== 0 && code !== null) {
+            // report abnormal exits (including bevy's exit-78 "can't run here") so we can
+            // tell from telemetry when the server is failing on users' machines
+            components.analytics.track('Multiplayer server exited', {
+                engine,
+                exitCode: code,
+                unavailable: code === EXIT_UNAVAILABLE
+            });
+            (0, beautiful_logs_1.printWarning)(components.logger, `Multiplayer Server exited with code ${code}`);
+        }
+        else if (signal && signal !== 'SIGTERM' && signal !== 'SIGINT') {
+            // SIGTERM/SIGINT are our own shutdown; anything else (SIGSEGV, SIGKILL/OOM)
+            // means the engine died out from under the preview
+            (0, beautiful_logs_1.printWarning)(components.logger, `Multiplayer Server terminated by signal ${signal}`);
+        }
+    });
+    return serverProcess;
+}
+/**
+ * Spawns the multiplayer server for the project.
+ * In the auth-server SDK, all scenes are authoritative multiplayer.
+ * Uses npx to handle installation and execution in a single step (works in Electron).
+ *
+ * Which implementation runs is chosen by DCL_SERVER_ENGINE (bevy | hammurabi), defaulting
+ * to bevy. When bevy reports itself unavailable on this machine (exit 78) the preview is
+ * aborted with instructions to opt into hammurabi — there is no automatic fallback.
+ *
+ * @param components - Preview components including logger
+ * @param project - The project to start the multiplayer server for
+ * @param realm - The realm URL to pass to the server
+ * @returns The ChildProcess if started, undefined otherwise
+ */
+function spawnAuthServer(components, project, realm) {
+    const engine = selectedEngine();
+    try {
+        const child = startMultiplayerServer(components, project.workingDirectory, realm, engine);
+        if (engine === 'bevy') {
+            child.on('close', (code) => {
+                if (code !== EXIT_UNAVAILABLE)
+                    return;
+                const { logger } = components;
+                logger.error(`The bevy multiplayer server (${packageSpec(engine)}) cannot run on this machine ` +
+                    `(exit ${EXIT_UNAVAILABLE}: unsupported platform or missing binary — ${process.platform}-${process.arch}).`);
+                logger.error(`To run the preview with the hammurabi server instead:`);
+                logger.error(`  DCL_SERVER_ENGINE=hammurabi npm start`);
+                // flush the 'Multiplayer server exited' event before killing the preview
+                void components.analytics.stop().finally(() => process.exit(EXIT_UNAVAILABLE));
+            });
+        }
+        return child;
+    }
+    catch (error) {
+        (0, beautiful_logs_1.printWarning)(components.logger, `Failed to start Multiplayer Server: ${error.message}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=multiplayer-server.js.map

package/dist/commands/start/multiplayer-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiplayer-server.js","sourceRoot":"","sources":["../../../src/commands/start/multiplayer-server.ts"],"names":[],"mappings":"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"}

package/dist/commands/start/server/routes.js

@@ -10,6 +10,7 @@ const http_server_1 = require("@well-known-components/http-server");
 const ws_1 = require("@well-known-components/http-server/dist/ws");
 const ws_2 = require("../data-layer/ws");
 const endpoints_1 = require("./endpoints");
+const storage_service_1 = require("./storage-service");
 const realm_1 = require("./realm");
 const utils_1 = require("../utils");
 exports.sceneUpdateClients = new Set();
@@ -60,6 +61,7 @@ async function wireRouter(components, workspace, dataLayer) {
         };
     });
     (0, realm_1.setupRealmAndComms)(components, router, localSceneParcels);
+    (0, storage_service_1.setupStorageEndpoints)(components, router, workspace);
     await (0, endpoints_1.setupEcs6Endpoints)(components, router, workspace);
     components.server.setContext(components);
     components.server.use(router.allowedMethods());

package/dist/commands/start/server/routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../../../src/commands/start/server/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../../../src/commands/start/server/routes.ts"],"names":[],"mappings":"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"}

package/dist/commands/start/server/runtime-env.d.ts

@@ -0,0 +1,71 @@
+import { CliComponents } from '../../../components';
+/**
+ * Structure for all server-side storage data.
+ * Stored in sdk-commands package directory (hidden from users).
+ */
+export interface ServerStorage {
+    env: Record<string, string>;
+    world: Record<string, unknown>;
+    players: Record<string, Record<string, unknown>>;
+}
+/**
+ * Loads all server-side storage data from server-storage.json.
+ */
+export declare function loadServerStorage(components: Pick<CliComponents, 'fs' | 'logger'>): Promise<ServerStorage>;
+/**
+ * Saves all server-side storage data to server-storage.json.
+ */
+export declare function saveServerStorage(components: Pick<CliComponents, 'fs' | 'logger'>, data: ServerStorage): Promise<void>;
+/**
+ * Loads environment variables from a .env file in the project directory.
+ * Returns a Map of key-value pairs.
+ */
+export declare function loadEnvFile(components: Pick<CliComponents, 'fs' | 'logger'>, projectDirectory: string): Promise<Map<string, string>>;
+/**
+ * Gets runtime environment variables.
+ */
+export declare function getEnvStorage(components: Pick<CliComponents, 'fs' | 'logger'>): Promise<Record<string, string>>;
+/**
+ * Gets merged environment variables.
+ * Runtime values (from server-storage.json) override .env values.
+ */
+export declare function getMergedEnv(components: Pick<CliComponents, 'fs' | 'logger'>, projectDirectory: string): Promise<Map<string, string>>;
+/**
+ * Sets a runtime environment variable.
+ */
+export declare function setEnvValue(components: Pick<CliComponents, 'fs' | 'logger'>, key: string, value: string): Promise<void>;
+/**
+ * Deletes a runtime environment variable.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+export declare function deleteEnvValue(components: Pick<CliComponents, 'fs' | 'logger'>, key: string): Promise<boolean>;
+/**
+ * Gets all world storage data.
+ */
+export declare function getWorldStorage(components: Pick<CliComponents, 'fs' | 'logger'>): Promise<Record<string, unknown>>;
+/**
+ * Gets a value from world storage.
+ */
+export declare function getWorldValue(components: Pick<CliComponents, 'fs' | 'logger'>, key: string): Promise<unknown | undefined>;
+/**
+ * Sets a value in world storage.
+ */
+export declare function setWorldValue(components: Pick<CliComponents, 'fs' | 'logger'>, key: string, value: unknown): Promise<void>;
+/**
+ * Deletes a value from world storage.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+export declare function deleteWorldValue(components: Pick<CliComponents, 'fs' | 'logger'>, key: string): Promise<boolean>;
+/**
+ * Gets a value from a player's storage.
+ */
+export declare function getPlayerValue(components: Pick<CliComponents, 'fs' | 'logger'>, address: string, key: string): Promise<unknown | undefined>;
+/**
+ * Sets a value in a player's storage.
+ */
+export declare function setPlayerValue(components: Pick<CliComponents, 'fs' | 'logger'>, address: string, key: string, value: unknown): Promise<void>;
+/**
+ * Deletes a value from a player's storage.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+export declare function deletePlayerValue(components: Pick<CliComponents, 'fs' | 'logger'>, address: string, key: string): Promise<boolean>;

package/dist/commands/start/server/runtime-env.js

@@ -0,0 +1,253 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadServerStorage = loadServerStorage;
+exports.saveServerStorage = saveServerStorage;
+exports.loadEnvFile = loadEnvFile;
+exports.getEnvStorage = getEnvStorage;
+exports.getMergedEnv = getMergedEnv;
+exports.setEnvValue = setEnvValue;
+exports.deleteEnvValue = deleteEnvValue;
+exports.getWorldStorage = getWorldStorage;
+exports.getWorldValue = getWorldValue;
+exports.setWorldValue = setWorldValue;
+exports.deleteWorldValue = deleteWorldValue;
+exports.getPlayerValue = getPlayerValue;
+exports.setPlayerValue = setPlayerValue;
+exports.deletePlayerValue = deletePlayerValue;
+const path_1 = __importDefault(require("path"));
+// Find the sdk-commands package root by resolving its package.json
+const SDK_COMMANDS_ROOT = path_1.default.dirname(require.resolve('@dcl/sdk-commands/package.json'));
+const RUNTIME_DATA_DIR = path_1.default.join(SDK_COMMANDS_ROOT, '.runtime-data');
+const SERVER_STORAGE_FILE = 'server-storage.json';
+function createDefaultStorage() {
+    return {
+        env: {},
+        world: {},
+        players: {}
+    };
+}
+let writeQueue = Promise.resolve();
+/**
+ * Serializes read-modify-write cycles against server-storage.json. The entire
+ * load→mutate→save must run under one lock: two handlers that each load the same
+ * snapshot would otherwise lose one update, and two concurrent saves would interleave
+ * their writes into a corrupt file.
+ */
+function serialize(task) {
+    const run = writeQueue.then(task, task);
+    writeQueue = run.then(() => undefined, () => undefined);
+    return run;
+}
+/**
+ * Ensures the runtime data directory exists.
+ */
+async function ensureRuntimeDir(components) {
+    try {
+        const exists = await components.fs.directoryExists(RUNTIME_DATA_DIR);
+        if (!exists) {
+            await components.fs.mkdir(RUNTIME_DATA_DIR, { recursive: true });
+        }
+    }
+    catch (error) {
+        components.logger.error(`Failed to create runtime data directory: ${error}`);
+    }
+}
+/**
+ * Loads all server-side storage data from server-storage.json.
+ */
+async function loadServerStorage(components) {
+    const storagePath = path_1.default.join(RUNTIME_DATA_DIR, SERVER_STORAGE_FILE);
+    try {
+        const exists = await components.fs.fileExists(storagePath);
+        if (!exists) {
+            return createDefaultStorage();
+        }
+        const content = await components.fs.readFile(storagePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return {
+            env: parsed.env ?? {},
+            world: parsed.world ?? {},
+            players: parsed.players ?? {}
+        };
+    }
+    catch (error) {
+        components.logger.error(`Failed to load ${SERVER_STORAGE_FILE}: ${error}`);
+        return createDefaultStorage();
+    }
+}
+/**
+ * Saves all server-side storage data to server-storage.json.
+ */
+async function saveServerStorage(components, data) {
+    await ensureRuntimeDir(components);
+    const storagePath = path_1.default.join(RUNTIME_DATA_DIR, SERVER_STORAGE_FILE);
+    try {
+        const tmpPath = `${storagePath}.tmp`;
+        await components.fs.writeFile(tmpPath, JSON.stringify(data, null, 2));
+        await components.fs.rename(tmpPath, storagePath);
+    }
+    catch (error) {
+        components.logger.error(`Failed to save ${SERVER_STORAGE_FILE}: ${error}`);
+        throw error;
+    }
+}
+/**
+ * Loads environment variables from a .env file in the project directory.
+ * Returns a Map of key-value pairs.
+ */
+async function loadEnvFile(components, projectDirectory) {
+    const envMap = new Map();
+    const envPath = path_1.default.join(projectDirectory, '.env');
+    try {
+        const exists = await components.fs.fileExists(envPath);
+        if (!exists) {
+            return envMap;
+        }
+        const content = await components.fs.readFile(envPath, 'utf-8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip empty lines and comments
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            const equalIndex = trimmed.indexOf('=');
+            if (equalIndex > 0) {
+                const key = trimmed.slice(0, equalIndex).trim();
+                let value = trimmed.slice(equalIndex + 1).trim();
+                // Remove surrounding quotes if present
+                if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                envMap.set(key, value);
+            }
+        }
+    }
+    catch (error) {
+        components.logger.error(`Failed to load .env file: ${error}`);
+    }
+    return envMap;
+}
+/**
+ * Gets runtime environment variables.
+ */
+async function getEnvStorage(components) {
+    const storage = await loadServerStorage(components);
+    return storage.env;
+}
+/**
+ * Gets merged environment variables.
+ * Runtime values (from server-storage.json) override .env values.
+ */
+async function getMergedEnv(components, projectDirectory) {
+    const envFile = await loadEnvFile(components, projectDirectory);
+    const runtimeEnv = await getEnvStorage(components);
+    // Runtime overrides .env
+    for (const [key, value] of Object.entries(runtimeEnv)) {
+        envFile.set(key, value);
+    }
+    return envFile;
+}
+/**
+ * Sets a runtime environment variable.
+ */
+async function setEnvValue(components, key, value) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        storage.env[key] = value;
+        await saveServerStorage(components, storage);
+    });
+}
+/**
+ * Deletes a runtime environment variable.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+async function deleteEnvValue(components, key) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        if (!(key in storage.env)) {
+            return false;
+        }
+        delete storage.env[key];
+        await saveServerStorage(components, storage);
+        return true;
+    });
+}
+/**
+ * Gets all world storage data.
+ */
+async function getWorldStorage(components) {
+    const storage = await loadServerStorage(components);
+    return storage.world;
+}
+/**
+ * Gets a value from world storage.
+ */
+async function getWorldValue(components, key) {
+    const storage = await loadServerStorage(components);
+    return storage.world[key];
+}
+/**
+ * Sets a value in world storage.
+ */
+async function setWorldValue(components, key, value) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        storage.world[key] = value;
+        await saveServerStorage(components, storage);
+    });
+}
+/**
+ * Deletes a value from world storage.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+async function deleteWorldValue(components, key) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        if (!(key in storage.world)) {
+            return false;
+        }
+        delete storage.world[key];
+        await saveServerStorage(components, storage);
+        return true;
+    });
+}
+/**
+ * Gets a value from a player's storage.
+ */
+async function getPlayerValue(components, address, key) {
+    const storage = await loadServerStorage(components);
+    return storage.players[address]?.[key];
+}
+/**
+ * Sets a value in a player's storage.
+ */
+async function setPlayerValue(components, address, key, value) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        if (!storage.players[address]) {
+            storage.players[address] = {};
+        }
+        storage.players[address][key] = value;
+        await saveServerStorage(components, storage);
+    });
+}
+/**
+ * Deletes a value from a player's storage.
+ * Returns true if key existed and was deleted, false otherwise.
+ */
+async function deletePlayerValue(components, address, key) {
+    return serialize(async () => {
+        const storage = await loadServerStorage(components);
+        if (!storage.players[address] || !(key in storage.players[address])) {
+            return false;
+        }
+        delete storage.players[address][key];
+        await saveServerStorage(components, storage);
+        return true;
+    });
+}
+//# sourceMappingURL=runtime-env.js.map

package/dist/commands/start/server/runtime-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../../../../src/commands/start/server/runtime-env.ts"],"names":[],"mappings":"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"}

package/dist/commands/start/server/storage-service.d.ts

@@ -0,0 +1,8 @@
+import { Router } from '@well-known-components/http-server';
+import { PreviewComponents } from '../types';
+import { CliComponents } from '../../../components';
+import { Workspace } from '../../../logic/workspace-validations';
+/**
+ * Sets up storage-related endpoints for environment variables, scene storage, and player storage.
+ */
+export declare function setupStorageEndpoints(components: CliComponents, router: Router<PreviewComponents>, workspace: Workspace): void;