feat: add type safe entity names file (#1107)

* feat: add type safe entity names file

* fix build:

* simplify enum types

* update tests

Author: gonpombo8

packages/@dcl/ecs/src/engine/index.ts

@@ -189,14 +189,19 @@ function preEngine(options?: IEngineOptions): PreEngine {
     }
   }
 
-  function getEntityOrNullByName(value: string) {
+  function getEntityOrNullByName<T = string>(value: T) {
     const NameComponent = components.Name({ defineComponent })
     for (const [entity, name] of getEntitiesWith(NameComponent)) {
       if (name.value === value) return entity
     }
     return null
   }
 
+  function getEntityByName<T = never, K = T>(value: K & (T extends never ? never : string)): Entity {
+    const entity = getEntityOrNullByName(value)
+    return entity!
+  }
+
   function* getComponentDefGroup<T extends ComponentDefinition<any>[]>(...args: T): Iterable<[Entity, ...T]> {
     const [firstComponentDef, ...componentDefinitions] = args
     for (const [entity] of firstComponentDef.iterator()) {
@@ -252,6 +257,7 @@ function preEngine(options?: IEngineOptions): PreEngine {
     getComponent,
     getComponentOrNull: getComponentOrNull as IEngine['getComponentOrNull'],
     getEntityOrNullByName,
+    getEntityByName,
     removeComponentDefinition,
     registerComponentDefinition,
     entityContainer,
@@ -313,6 +319,7 @@ export function Engine(options?: IEngineOptions): IEngine {
     componentsIter: partialEngine.componentsIter,
     seal: partialEngine.seal,
     getEntityOrNullByName: partialEngine.getEntityOrNullByName,
+    getEntityByName: partialEngine.getEntityByName,
 
     update,
 

packages/@dcl/ecs/src/engine/types.ts

@@ -62,6 +62,7 @@ export type PreEngine = Pick<
   | 'seal'
   | 'entityContainer'
   | 'getEntityOrNullByName'
+  | 'getEntityByName'
 > & {
   getSystems: () => SystemItem[]
 }
@@ -245,7 +246,15 @@ export interface IEngine {
    * Search for the entity that matches de label string defined in the editor.
    * @param value - Name value string
    */
-  getEntityOrNullByName(label: string): Entity | null
+  getEntityOrNullByName<T = string>(label: T): Entity | null
+
+  /**
+   * @public
+   * Search for the entity that matches de label string defined in the editor.
+   * @param value - Name value string
+   * @typeParam T - The type of the entity name value
+   */
+  getEntityByName<T = never, K = T>(value: K & (T extends never ? never : string)): Entity
 
   /**
    * @public

packages/@dcl/inspector/src/lib/data-layer/host/utils/composite-dirty.ts

@@ -9,7 +9,7 @@ import {
 } from '@dcl/ecs'
 import { initComponents } from '@dcl/asset-packs'
 import { EditorComponentNames, EditorComponents } from '../../../sdk/components'
-import { dumpEngineToComposite, dumpEngineToCrdtCommands } from './engine-to-composite'
+import { dumpEngineToComposite, dumpEngineToCrdtCommands, generateEntityNamesType } from './engine-to-composite'
 import { FileSystemInterface } from '../../types'
 import { CompositeManager, createFsCompositeProvider } from './fs-composite-provider'
 import { getMinimalComposite } from '../../client/feeded-local-fs'
@@ -21,6 +21,7 @@ import { toSceneComponent } from './component'
 import { addNodesComponentsToPlayerAndCamera } from './migrations/add-nodes-to-player-and-camera'
 import { fixNetworkEntityValues } from './migrations/fix-network-entity-values'
 import { selectSceneEntity } from './migrations/select-scene-entity'
+import { DIRECTORY, withAssetDir } from '../fs-utils'
 
 enum DirtyEnum {
   // No changes
@@ -108,6 +109,9 @@ export async function compositeAndDirty(
       await fs.writeFile('main.crdt', Buffer.from(mainCrdt))
       await compositeProvider.save({ src: compositePath, composite }, 'json')
 
+      // Generate entity names type file
+      await generateEntityNamesType(engine, withAssetDir(DIRECTORY.SCENE + '/entity-names.ts'), 'EntityNames', fs)
+
       return composite
     } catch (e) {
       console.log('Failed saving composite')

packages/@dcl/inspector/src/lib/data-layer/host/utils/engine-to-composite.ts

@@ -8,9 +8,11 @@ import {
   IEngine,
   LastWriteWinElementSetComponentDefinition,
   PutComponentOperation,
-  getCompositeRootComponent
+  getCompositeRootComponent,
+  Name
 } from '@dcl/ecs'
 import { ReadWriteByteBuffer } from '@dcl/ecs/dist/serialization/ByteBuffer'
+import { FileSystemInterface } from '../../types'
 
 function componentToCompositeComponentData<T>(
   $case: 'json' | 'binary',
@@ -128,3 +130,87 @@ export function dumpEngineToCrdtCommands(engine: IEngine): Uint8Array {
 
   return crdtBuffer.toBinary()
 }
+
+/**
+ * Generate a TypeScript declaration file with a string literal union type containing all entity names in the scene.
+ * This allows for type-safe references to entities by name in scene scripts.
+ *
+ * @param engine The ECS engine instance
+ * @param outputPath The path where the .d.ts file should be written
+ * @param typeName The name for the generated type (default: "SceneEntityNames")
+ * @param fs FileSystem interface for writing the file
+ * @returns Promise that resolves when the file has been written
+ */
+export async function generateEntityNamesType(
+  engine: IEngine,
+  outputPath: string = 'scene-entity-names.d.ts',
+  typeName: string = 'SceneEntityNames',
+  fs: FileSystemInterface
+): Promise<void> {
+  try {
+    // Find the Name component definition
+
+    const NameComponent: typeof Name = engine.getComponentOrNull(Name.componentId) as typeof Name
+
+    if (!NameComponent) {
+      throw new Error('Name component not found in engine')
+    }
+
+    // Collect all names from entities
+    const names: string[] = []
+    for (const [_, nameValue] of engine.getEntitiesWith(NameComponent)) {
+      if (nameValue.value) {
+        names.push(nameValue.value)
+      }
+    }
+
+    // Sort names for consistency
+    names.sort()
+
+    // Remove duplicates
+    const uniqueNames = Array.from(new Set(names))
+
+    // Generate valid TypeScript identifiers and handle duplicates in a single pass
+    const validNameMap = new Map<string, string>()
+    const finalNames: Array<{ original: string; valid: string }> = []
+
+    for (const name of uniqueNames) {
+      // Create a valid TypeScript identifier
+      let validName = name
+        .replace(/[^a-zA-Z0-9_]/g, '_') // Replace non-alphanumeric chars with underscore
+        .replace(/^[0-9]/, '_$&') // Prepend underscore if starts with number
+
+      // Handle collision if this valid name already exists
+      if (validNameMap.has(validName)) {
+        // Add numeric suffix for uniqueness
+        let suffix = 1
+        while (validNameMap.has(`${validName}_${suffix}`)) {
+          suffix++
+        }
+        validName = `${validName}_${suffix}`
+      }
+
+      // Store the mapping and add to result
+      validNameMap.set(validName, name)
+      finalNames.push({ original: name, valid: validName })
+    }
+
+    // Generate the .d.ts file content
+    let fileContent = `// Auto-generated entity names from the scene\n\n`
+
+    // Add a constant object with name keys for IDE autocompletion
+    fileContent += `\n/**\n * Object containing all entity names in the scene for autocomplete support.\n */\n`
+    fileContent += `export enum ${typeName} {\n`
+
+    for (const { original, valid } of finalNames) {
+      fileContent += `  ${valid} = "${original}",\n`
+    }
+
+    fileContent += `} \n`
+
+    // Write to file
+    await fs.writeFile(outputPath, Buffer.from(fileContent, 'utf-8'))
+  } catch (e) {
+    console.error('Fail to generate entity names types', e)
+  }
+}

packages/@dcl/playground-assets/etc/playground-assets.api.md

@@ -1247,8 +1247,9 @@ export interface IEngine {
     getComponent<T>(componentId: number | string): ComponentDefinition<T>;
     getComponentOrNull<T>(componentId: number | string): ComponentDefinition<T> | null;
     getEntitiesWith<T extends [ComponentDefinition<any>, ...ComponentDefinition<any>[]]>(...components: T): Iterable<[Entity, ...ReadonlyComponentSchema<T>]>;
+    getEntityByName<T = never, K = T>(value: K & (T extends never ? never : string)): Entity;
     // @alpha
-    getEntityOrNullByName(label: string): Entity | null;
+    getEntityOrNullByName<T = string>(label: T): Entity | null;
     getEntityState(entity: Entity): EntityState;
     // (undocumented)
     _id: number;

packages/@dcl/sdk-commands/package-lock.json

@@ -12,5 +12,8 @@ describe('Generated Raycast ProtoBuf', () => {
 
     expect(newEngine.getEntityOrNullByName('CASLA')).toBeDefined()
     expect(newEngine.getEntityOrNullByName('Boedo')).toBe(null)
+
+    expect(newEngine.getEntityByName<string>('CASLA')).toBeDefined()
+    expect(newEngine.getEntityByName<string>('Boedo')).toBe(null)
   })
 })

test/ecs/components/Name.spec.ts

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=462.7k bytes
+SCENE_COMPILED_JS_SIZE_PROD=462.9k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -11,7 +11,7 @@ EVAL test/snapshots/development-bundles/static-scene.test.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 54k
-  MALLOC_COUNT = 13727
+  MALLOC_COUNT = 13735
   ALIVE_OBJS_DELTA ~= 2.70k
 CALL onStart()
   main.crdt: PUT_COMPONENT e=0x200 c=1 t=0 data={"position":{"x":5.880000114440918,"y":2.7916901111602783,"z":7.380000114440918},"rotation":{"x":0,"y":0,"z":0,"w":1},"scale":{"x":1,"y":1,"z":1},"parent":0}
@@ -56,4 +56,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 3k
   MALLOC_COUNT = -5
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 1209.35k bytes
+  MEMORY_USAGE_COUNT ~= 1209.94k bytes

test/snapshots/development-bundles/static-scene.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=463.2k bytes
+SCENE_COMPILED_JS_SIZE_PROD=463.4k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -11,7 +11,7 @@ EVAL test/snapshots/development-bundles/testing-fw.test.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 63k
-  MALLOC_COUNT = 14248
+  MALLOC_COUNT = 14260
   ALIVE_OBJS_DELTA ~= 2.85k
 CALL onStart()
   LOG: ["Adding one to position.y=0"]
@@ -64,4 +64,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 5k
   MALLOC_COUNT = -40
   ALIVE_OBJS_DELTA ~= -0.01k
-  MEMORY_USAGE_COUNT ~= 1217.97k bytes
+  MEMORY_USAGE_COUNT ~= 1218.62k bytes

test/snapshots/development-bundles/testing-fw.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=463.3k bytes
+SCENE_COMPILED_JS_SIZE_PROD=463.4k bytes
 THE BUNDLE HAS SOURCEMAPS
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
@@ -11,7 +11,7 @@ EVAL test/snapshots/development-bundles/two-way-crdt.test.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 63k
-  MALLOC_COUNT = 14248
+  MALLOC_COUNT = 14260
   ALIVE_OBJS_DELTA ~= 2.85k
 CALL onStart()
   LOG: ["Adding one to position.y=0"]
@@ -64,4 +64,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 5k
   MALLOC_COUNT = -40
   ALIVE_OBJS_DELTA ~= -0.01k
-  MEMORY_USAGE_COUNT ~= 1217.97k bytes
+  MEMORY_USAGE_COUNT ~= 1218.63k bytes

test/snapshots/development-bundles/two-way-crdt.test.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=203k bytes
+SCENE_COMPILED_JS_SIZE_PROD=203.1k bytes
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
   MALLOC_COUNT = 1005
@@ -9,7 +9,7 @@ EVAL test/snapshots/production-bundles/append-value-crdt.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 65k
-  MALLOC_COUNT = 12773
+  MALLOC_COUNT = 12784
   ALIVE_OBJS_DELTA ~= 2.85k
 CALL onStart()
   Renderer: APPEND_VALUE e=0x200 c=1063 t=0 data={"button":0,"hit":{"position":{"x":1,"y":2,"z":3},"globalOrigin":{"x":1,"y":2,"z":3},"direction":{"x":1,"y":2,"z":3},"normalHit":{"x":1,"y":2,"z":3},"length":10,"meshName":"mesh","entityId":512},"state":1,"timestamp":1,"analog":5,"tickNumber":0}
@@ -55,4 +55,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 14k
   MALLOC_COUNT = 31
   ALIVE_OBJS_DELTA ~= 0.01k
-  MEMORY_USAGE_COUNT ~= 909.46k bytes
+  MEMORY_USAGE_COUNT ~= 909.93k bytes

test/snapshots/production-bundles/append-value-crdt.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=236k bytes
+SCENE_COMPILED_JS_SIZE_PROD=236.1k bytes
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
   MALLOC_COUNT = 1005
@@ -9,7 +9,7 @@ EVAL test/snapshots/production-bundles/billboard.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 66k
-  MALLOC_COUNT = 14885
+  MALLOC_COUNT = 14892
   ALIVE_OBJS_DELTA ~= 3.25k
 CALL onStart()
   OPCODES ~= 0k
@@ -77,4 +77,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 10k
   MALLOC_COUNT = 0
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 1051.90k bytes
+  MEMORY_USAGE_COUNT ~= 1052.22k bytes

test/snapshots/production-bundles/billboard.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=199.2k bytes
+SCENE_COMPILED_JS_SIZE_PROD=199.3k bytes
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
   MALLOC_COUNT = 1005
@@ -9,7 +9,7 @@ EVAL test/snapshots/production-bundles/cube-deleted.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 55k
-  MALLOC_COUNT = 11927
+  MALLOC_COUNT = 11935
   ALIVE_OBJS_DELTA ~= 2.63k
 CALL onStart()
   OPCODES ~= 0k
@@ -42,4 +42,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 5k
   MALLOC_COUNT = 1
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 872.22k bytes
+  MEMORY_USAGE_COUNT ~= 872.62k bytes

test/snapshots/production-bundles/cube-deleted.ts.crdt

@@ -1,4 +1,4 @@
-SCENE_COMPILED_JS_SIZE_PROD=199.1k bytes
+SCENE_COMPILED_JS_SIZE_PROD=199.2k bytes
 (start empty vm 0.21.0-3680274614.commit-1808aa1)
   OPCODES ~= 0k
   MALLOC_COUNT = 1005
@@ -9,7 +9,7 @@ EVAL test/snapshots/production-bundles/cube.js
   REQUIRE: ~system/EngineApi
   REQUIRE: ~system/EngineApi
   OPCODES ~= 55k
-  MALLOC_COUNT = 11900
+  MALLOC_COUNT = 11908
   ALIVE_OBJS_DELTA ~= 2.62k
 CALL onStart()
   OPCODES ~= 0k
@@ -32,4 +32,4 @@ CALL onUpdate(0.1)
   OPCODES ~= 1k
   MALLOC_COUNT = 0
   ALIVE_OBJS_DELTA ~= 0.00k
-  MEMORY_USAGE_COUNT ~= 862.13k bytes
+  MEMORY_USAGE_COUNT ~= 862.53k bytes