feat(sdk-commands): namespace local world storage by scene coordinates (pre-existing WIP)

Author: cyaiox

packages/@dcl/sdk-commands/src/commands/start/server/runtime-env.ts

@@ -1,5 +1,6 @@
 import path from 'path'
 import { CliComponents } from '../../../components'
+import { getObject } from '../../../logic/coordinates'
 
 // Find the sdk-commands package root by resolving its package.json
 const SDK_COMMANDS_ROOT = path.dirname(require.resolve('@dcl/sdk-commands/package.json'))
@@ -9,18 +10,34 @@ const SERVER_STORAGE_FILE = 'server-storage.json'
 /**
  * Structure for all server-side storage data.
  * Stored in sdk-commands package directory (hidden from users).
+ *
+ * `world` is namespaced by scene base coordinates (`"x,y"`) so that previewing
+ * different scenes does not share the same scene-storage bucket.
  */
 export interface ServerStorage {
   env: Record<string, string>
-  world: Record<string, unknown>
+  world: Record<string, Record<string, unknown>>
   players: Record<string, Record<string, unknown>>
 }
 
-const DEFAULT_STORAGE: ServerStorage = {
+/**
+ * Normalizes a scene base parcel (e.g. `"60, -9"`) into the canonical `"x,y"`
+ * key used to namespace world storage, so equivalent spellings map to one bucket.
+ */
+export function getSceneStorageKey(base: string): string {
+  const { x, y } = getObject(base)
+  return `${x},${y}`
+}
+
+const isPlainObject = (value: unknown): boolean => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+// Factory (not a shared const): each call returns fresh nested objects so callers
+// can never mutate a shared default and leak state into later loads.
+const createDefaultStorage = (): ServerStorage => ({
   env: {},
   world: {},
   players: {}
-}
+})
 
 /**
  * Ensures the runtime data directory exists.
@@ -45,21 +62,31 @@ export async function loadServerStorage(components: Pick<CliComponents, 'fs' | '
   try {
     const exists = await components.fs.fileExists(storagePath)
     if (!exists) {
-      return { ...DEFAULT_STORAGE }
+      return createDefaultStorage()
     }
 
     const content = await components.fs.readFile(storagePath, 'utf-8')
     const parsed = JSON.parse(content) as Partial<ServerStorage>
 
+    // `world` is now namespaced by scene coordinates (`"x,y"` -> key -> value).
+    // A file with any non-object top-level `world` entry predates that change
+    // (flat `key -> value`); its data has no scene to attribute to, so discard it.
+    // Local preview storage is disposable, so resetting is preferable to migrating.
+    const rawWorld = parsed.world ?? {}
+    const isLegacyWorld = Object.values(rawWorld).some((value) => !isPlainObject(value))
+    if (isLegacyWorld) {
+      components.logger.debug('Resetting legacy local preview world storage (pre scene-coordinate namespacing)')
+    }
+
     // Merge with defaults to ensure all keys exist
     return {
       env: parsed.env ?? {},
-      world: parsed.world ?? {},
+      world: isLegacyWorld ? {} : rawWorld,
       players: parsed.players ?? {}
     }
   } catch (error) {
     components.logger.error(`Failed to load ${SERVER_STORAGE_FILE}: ${error}`)
-    return { ...DEFAULT_STORAGE }
+    return createDefaultStorage()
   }
 }
 
@@ -183,52 +210,59 @@ export async function deleteEnvValue(components: Pick<CliComponents, 'fs' | 'log
 }
 
 /**
- * Gets all world storage data.
+ * Gets all world storage data for a scene, keyed by its base-coordinate bucket.
  */
 export async function getWorldStorage(
-  components: Pick<CliComponents, 'fs' | 'logger'>
+  components: Pick<CliComponents, 'fs' | 'logger'>,
+  sceneKey: string
 ): Promise<Record<string, unknown>> {
   const storage = await loadServerStorage(components)
-  return storage.world
+  return storage.world[sceneKey] ?? {}
 }
 
 /**
- * Gets a value from world storage.
+ * Gets a value from a scene's world storage.
  */
 export async function getWorldValue(
   components: Pick<CliComponents, 'fs' | 'logger'>,
+  sceneKey: string,
   key: string
 ): Promise<unknown | undefined> {
   const storage = await loadServerStorage(components)
-  return storage.world[key]
+  return storage.world[sceneKey]?.[key]
 }
 
 /**
- * Sets a value in world storage.
+ * Sets a value in a scene's world storage.
  */
 export async function setWorldValue(
   components: Pick<CliComponents, 'fs' | 'logger'>,
+  sceneKey: string,
   key: string,
   value: unknown
 ): Promise<void> {
   const storage = await loadServerStorage(components)
-  storage.world[key] = value
+  if (!storage.world[sceneKey]) {
+    storage.world[sceneKey] = {}
+  }
+  storage.world[sceneKey][key] = value
   await saveServerStorage(components, storage)
 }
 
 /**
- * Deletes a value from world storage.
+ * Deletes a value from a scene's world storage.
  * Returns true if key existed and was deleted, false otherwise.
  */
 export async function deleteWorldValue(
   components: Pick<CliComponents, 'fs' | 'logger'>,
+  sceneKey: string,
   key: string
 ): Promise<boolean> {
   const storage = await loadServerStorage(components)
-  if (!(key in storage.world)) {
+  if (!storage.world[sceneKey] || !(key in storage.world[sceneKey])) {
     return false
   }
-  delete storage.world[key]
+  delete storage.world[sceneKey][key]
   await saveServerStorage(components, storage)
   return true
 }

packages/@dcl/sdk-commands/src/commands/start/server/storage-service.ts

@@ -8,6 +8,8 @@ import {
   setEnvValue,
   deleteEnvValue,
   loadServerStorage,
+  getSceneStorageKey,
+  getWorldStorage,
   getWorldValue,
   setWorldValue,
   deleteWorldValue,
@@ -24,6 +26,10 @@ export function setupStorageEndpoints(
   router: Router<PreviewComponents>,
   workspace: Workspace
 ) {
+  // World (scene) storage is namespaced by the previewed scene's base coordinates,
+  // read directly from its scene.json (same source as routes.ts uses for the QR link).
+  const sceneKey = getSceneStorageKey(workspace.projects[0].scene.scene.base)
+
   const withKeyValidation: IHttpServerComponent.IRequestHandler<
     IHttpServerComponent.PathAwareContext<PreviewComponents, string>
   > = async (ctx, next) => {
@@ -88,8 +94,8 @@ export function setupStorageEndpoints(
     const limitParam = ctx.url.searchParams.get('limit')
     const offsetParam = ctx.url.searchParams.get('offset')
 
-    const storage = await loadServerStorage(components)
-    let entries = Object.entries(storage.world).map(([key, value]) => ({ key, value }))
+    const world = await getWorldStorage(components, sceneKey)
+    let entries = Object.entries(world).map(([key, value]) => ({ key, value }))
 
     if (prefix !== null && prefix !== '') {
       entries = entries.filter((entry) => entry.key.startsWith(prefix))
@@ -107,7 +113,7 @@ export function setupStorageEndpoints(
   router.get('/values/:key', withKeyValidation, async (ctx) => {
     const { key } = ctx.params
 
-    const value = await getWorldValue(components, key)
+    const value = await getWorldValue(components, sceneKey, key)
     if (value === undefined) {
       return { status: 404, body: { message: `Storage key '${key}' not found` } }
     }
@@ -120,7 +126,7 @@ export function setupStorageEndpoints(
     try {
       const bodyText = await ctx.request.text()
       const { value } = JSON.parse(bodyText)
-      await setWorldValue(components, key, value)
+      await setWorldValue(components, sceneKey, key, value)
       return { body: JSON.stringify({ value }) }
     } catch (error) {
       components.logger.error(`Failed to set storage value '${key}': ${error}`)
@@ -132,7 +138,7 @@ export function setupStorageEndpoints(
     const { key } = ctx.params
 
     try {
-      await deleteWorldValue(components, key)
+      await deleteWorldValue(components, sceneKey, key)
       return { status: 204 }
     } catch (error) {
       components.logger.error(`Failed to delete storage value '${key}': ${error}`)

packages/@dcl/sdk-commands/src/commands/storage/env.ts

@@ -7,7 +7,8 @@ import {
   createStorageInfo,
   makeAuthenticatedRequest,
   confirmAction,
-  getLinkerDappOptions
+  getLinkerDappOptions,
+  withPosition
 } from './shared'
 
 /**
@@ -43,7 +44,7 @@ export const handleEnv = async (action: string, key: string | undefined, options
 
     logger.info(`Setting environment variable '${key}' to ${baseURL}`)
 
-    const url = `${baseURL}/env/${encodeURIComponent(key)}`
+    const url = withPosition(`${baseURL}/env/${encodeURIComponent(key)}`, baseParcel)
     const info = createStorageInfo('env', 'set', url, worldName, baseParcel, parcels, key, value)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'PUT', url, { value })
@@ -63,7 +64,7 @@ export const handleEnv = async (action: string, key: string | undefined, options
 
     logger.info(`Deleting environment variable '${key}' from ${baseURL}`)
 
-    const url = `${baseURL}/env/${encodeURIComponent(key)}`
+    const url = withPosition(`${baseURL}/env/${encodeURIComponent(key)}`, baseParcel)
     const info = createStorageInfo('env', 'delete', url, worldName, baseParcel, parcels, key)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url)
@@ -91,7 +92,7 @@ export const handleEnv = async (action: string, key: string | undefined, options
 
     logger.info(`Clearing all environment variables from ${baseURL}`)
 
-    const url = `${baseURL}/env`
+    const url = withPosition(`${baseURL}/env`, baseParcel)
     const info = createStorageInfo('env', 'clear', url, worldName, baseParcel, parcels)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url, undefined, {

packages/@dcl/sdk-commands/src/commands/storage/player.ts

@@ -7,7 +7,8 @@ import {
   createStorageInfo,
   makeAuthenticatedRequest,
   confirmAction,
-  getLinkerDappOptions
+  getLinkerDappOptions,
+  withPosition
 } from './shared'
 
 /**
@@ -48,7 +49,10 @@ export const handlePlayer = async (action: string, key: string | undefined, opti
 
     logger.info(`Getting player storage value '${key}' for ${address} from ${baseURL}`)
 
-    const url = `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+    const url = withPosition(
+      `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`,
+      baseParcel
+    )
     const info = createStorageInfo('player', 'get', url, worldName, baseParcel, parcels, key, undefined, address)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'GET', url)
@@ -91,7 +95,10 @@ export const handlePlayer = async (action: string, key: string | undefined, opti
 
     logger.info(`Setting player storage value '${key}' for ${address} to ${baseURL}`)
 
-    const url = `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+    const url = withPosition(
+      `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`,
+      baseParcel
+    )
     const info = createStorageInfo('player', 'set', url, worldName, baseParcel, parcels, key, value, address)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'PUT', url, { value })
@@ -125,7 +132,10 @@ export const handlePlayer = async (action: string, key: string | undefined, opti
 
     logger.info(`Deleting player storage value '${key}' for ${address} from ${baseURL}`)
 
-    const url = `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+    const url = withPosition(
+      `${baseURL}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`,
+      baseParcel
+    )
     const info = createStorageInfo('player', 'delete', url, worldName, baseParcel, parcels, key, undefined, address)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url)
@@ -159,7 +169,7 @@ export const handlePlayer = async (action: string, key: string | undefined, opti
 
       logger.info(`Clearing all storage data for player ${address} from ${baseURL}`)
 
-      const url = `${baseURL}/players/${encodeURIComponent(address)}/values`
+      const url = withPosition(`${baseURL}/players/${encodeURIComponent(address)}/values`, baseParcel)
       const info = createStorageInfo(
         'player',
         'clear',
@@ -201,7 +211,7 @@ export const handlePlayer = async (action: string, key: string | undefined, opti
 
       logger.info(`Clearing all player storage data from ${baseURL}`)
 
-      const url = `${baseURL}/players`
+      const url = withPosition(`${baseURL}/players`, baseParcel)
       const info = createStorageInfo('player', 'clear', url, worldName, baseParcel, parcels)
 
       const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url, undefined, {

packages/@dcl/sdk-commands/src/commands/storage/scene.ts

@@ -7,7 +7,8 @@ import {
   createStorageInfo,
   makeAuthenticatedRequest,
   confirmAction,
-  getLinkerDappOptions
+  getLinkerDappOptions,
+  withPosition
 } from './shared'
 
 /**
@@ -38,7 +39,7 @@ export const handleScene = async (action: string, key: string | undefined, optio
 
     logger.info(`Getting scene storage value '${key}' from ${baseURL}`)
 
-    const url = `${baseURL}/values/${encodeURIComponent(key)}`
+    const url = withPosition(`${baseURL}/values/${encodeURIComponent(key)}`, baseParcel)
     const info = createStorageInfo('scene', 'get', url, worldName, baseParcel, parcels, key)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'GET', url)
@@ -64,7 +65,7 @@ export const handleScene = async (action: string, key: string | undefined, optio
 
     logger.info(`Setting scene storage value '${key}' to ${baseURL}`)
 
-    const url = `${baseURL}/values/${encodeURIComponent(key)}`
+    const url = withPosition(`${baseURL}/values/${encodeURIComponent(key)}`, baseParcel)
     const info = createStorageInfo('scene', 'set', url, worldName, baseParcel, parcels, key, value)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'PUT', url, { value })
@@ -84,7 +85,7 @@ export const handleScene = async (action: string, key: string | undefined, optio
 
     logger.info(`Deleting scene storage value '${key}' from ${baseURL}`)
 
-    const url = `${baseURL}/values/${encodeURIComponent(key)}`
+    const url = withPosition(`${baseURL}/values/${encodeURIComponent(key)}`, baseParcel)
     const info = createStorageInfo('scene', 'delete', url, worldName, baseParcel, parcels, key)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url)
@@ -112,7 +113,7 @@ export const handleScene = async (action: string, key: string | undefined, optio
 
     logger.info(`Clearing all scene storage data from ${baseURL}`)
 
-    const url = `${baseURL}/values`
+    const url = withPosition(`${baseURL}/values`, baseParcel)
     const info = createStorageInfo('scene', 'clear', url, worldName, baseParcel, parcels)
 
     const result = await makeAuthenticatedRequest(options.components, info, linkOptions, 'DELETE', url, undefined, {

packages/@dcl/sdk-commands/src/commands/storage/shared.ts

@@ -39,12 +39,27 @@ export const validateWorkspaceAndWorld = async (
     )
   }
 
-  const baseParcel = sceneJson.scene?.base || '0,0'
-  const parcels = sceneJson.scene?.parcels || ['0,0']
+  // getValidSceneJson (above) already validated the scene, so scene.base and
+  // scene.parcels are guaranteed to exist. Use them directly instead of a '0,0'
+  // fallback, which would silently target the wrong scene on the storage service.
+  const baseParcel = sceneJson.scene.base
+  const parcels = sceneJson.scene.parcels
 
   return { worldName, baseParcel, parcels }
 }
 
+/**
+ * Appends the scene base parcel as a `position` query param to a storage URL.
+ * The Server Side Storage service resolves which scene a request targets from
+ * this param; without it the service defaults to '0,0' and rejects world requests.
+ */
+export const withPosition = (url: string, baseParcel: string): string => {
+  // Keep the "x,y" comma literal (not percent-encoded) to match the convention used
+  // elsewhere (e.g. deploy's `&position=${scene.base}`) and what the service expects.
+  const separator = url.includes('?') ? '&' : '?'
+  return `${url}${separator}position=${baseParcel}`
+}
+
 /**
  * Builds metadata for server-side storage service requests (ADR-44 format)
  */