@perplexdotgg/mecs 0.2.0 → 0.3.1

package/README.md

@@ -1,3 +1,8 @@
+[![npm version](https://img.shields.io/npm/v/@perplexdotgg/mecs.svg)](https://www.npmjs.com/package/@perplexdotgg/mecs)
+[![repo](https://img.shields.io/badge/codeberg-repo-7d48ff?logo=codeberg&logoColor=ff7d48)](https://codeberg.org/perplexdotgg/mecs)
+[![license](https://img.shields.io/npm/l/@perplexdotgg/mecs.svg?color=7d48ff)](http://codeberg.org/perplexdotgg/mecs/src/branch/main/LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-7d48ff.svg)](https://codeberg.org/perplexdotgg/mecs/pulls)
+
 <div style="display: flex;">
   <img src="./mecs.svg" width="152" height="64" style="margin-right: 16px;" />
   <h1>MECS - Monomorph Entity Component System</h1>
@@ -187,9 +192,9 @@ const entity1 = Entity.create({
   },
 });
 
-// now entity1 is of the Entity class, and entity1.localTransform is of the Transform class
+// now entity1 is of the Entity class, and entity1.globalTransform is of the Transform class
 // so you can call methods on it like so:
-entity1.localTransform.composeMatrix();
+entity1.globalTransform.composeMatrix();
 
 const entity2 = Entity.create({
   projectile: {
@@ -198,7 +203,7 @@ const entity2 = Entity.create({
   },
 });
 
-// destroy() to return the entity to the pool, it will automatically be re-used later
+// you can use destroy() to return an entity to the pool, it will automatically be re-used later
 // this iterates on all components to remove them first, and triggers queries just
 // before the component(s) needed for the query are deleted
 // each destroyed component also gets recycled in its own component pool
@@ -243,7 +248,7 @@ const components = {
     // component config options here, see "Customizing Components" below
   },
 
-} as const satisfies ComponentMap;
+};
 
 const queries = {};
 
@@ -375,6 +380,41 @@ Entity.queries.projectiles.beforeEntityRemoved.removeListener(someListener);
 
 ```
 
+### Components that reference Entities
+You can have components that reference other entities, by using Monomorph's `LazyReferenceType` and `LazyReferenceListType`. This will usually 'just work', but in some situations you may also need to use MECS's `LazyComponent`. See the Typescript tests in [`tests/componentsWithEntityReferences.test.ts`](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/componentsWithEntityReferences.test.ts) and [`tests/lazyComponentsWithEntityReferences.test.ts`](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/lazyComponentsWithEntityReferences.test.ts) for examples. Below is a simple Javascript example:
+
+```js
+const turretProps = {
+  targetEntity: LazyReferenceType(() => Entity),
+
+  // or for multiple referenced entities:
+  targetEntities: LazyReferenceListType(() => Entity),
+};
+class Turret extends createClass(turretProps) {}
+
+const components = {
+  turret: Turret,
+  // or the lazy loaded version:
+  // turret: LazyComponent(() => Turret),
+
+  // alternatively, you can use a component config object for further customization:
+  turret: {
+    monomorphClass: Turret,
+    // or the lazy loaded version:
+    // monomorphClass: LazyComponent(() => Turret),
+
+    // other config options here, for example:
+    afterComponentAdded: (turretInstance, entity, componentKey) => {
+      if (turretInstance.targetEntity === null) {
+        // example maybe automatically select a target in this situation
+      }
+    },
+  },
+};
+class Entity extends createEntityClass()(components, queries) {}
+```
+
+
 ### Customizing Components
 For both monomorph and non-monomorph types, you can pass a component config object, allowing you to customize the component's lifecycle. A brief example is below with a few of the options, for many more option examples, see the tests in
 [`tests/customComponents.test.ts`](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts).
@@ -486,6 +526,10 @@ const entity2 = Entity.create({
 
 </details>
 
+---
+
+Here are all the available component config options:
+
 | Option | Type | Description |
 | --- | --- | --- |
 | `monomorphClass` | A [Monomorph](http://codeberg.org/perplexdotgg/monomorph) class | If you want to customize the component lifecycle for a monomorph class, set this to the monomorphClass. Otherwise do not set this field. |
@@ -508,4 +552,4 @@ const entity2 = Entity.create({
 
 ## How to contribute
 
-If you like this project and would like to support our work, please consider contributing code via pull requests, or donating via [open collective](https://opencollective.com/perplexgg). Contributions are greatly appreciated!
+If you like this project and would like to support our work, please consider contributing code via [pull requests](https://codeberg.org/perplexdotgg/mecs/pulls), or donating via [open collective](https://opencollective.com/perplexgg). Contributions are greatly appreciated!

package/build/index.d.ts

@@ -1,6 +1,7 @@
 import { InputType } from 'monomorph';
 import { MonomorphClass } from 'monomorph';
 import { MonomorphInstance } from 'monomorph';
+import { NumberArray } from 'monomorph';
 import { WithPool } from 'monomorph';
 
 export declare type ComponentConfig<ComponentType, ComponentInputType extends any = InputType<ComponentType> extends never ? ComponentType : InputType<ComponentType>> = {
@@ -36,23 +37,26 @@ export declare type ComponentConfigFunction<ComponentType, ComponentInputType> =
 
 export declare type ComponentInput<X> = X extends MonomorphClass<infer P, infer I, infer M> ? M extends MonomorphInstance<infer iP, infer iI> ? InputType<M> : never : X extends ComponentConfig<infer CT, infer I> ? I : X;
 
-export declare type ComponentMap = Record<string, ComponentConfig<any, any> | MonomorphClass<any, any, any> | MonomorphClass<any, any, any>>;
+export declare type ComponentMap = Record<string, ComponentConfig<any, any> | MonomorphClass<any, any, any> | LazyWrapper<MonomorphClass<any, any, any>> | ComponentConfig<MonomorphClass<any, any, any>, any> | ComponentConfig<LazyWrapper<MonomorphClass<any, any, any>>, any>>;
 
 declare type ComponentMapClassProperties<CM> = {
-    [K in keyof CM as LowercaseFirstLetter<K>]?: CM[K] extends MonomorphClass<infer P, infer I, infer M> ? M : CM[K] extends ComponentConfig<infer MC, infer I> ? MC extends MonomorphClass<infer P, infer iI, infer M> ? M : MC : CM[K];
+    [K in keyof CM as LowercaseFirstLetter<K>]?: ExtractMonomorphClass<CM[K]> extends MonomorphClass<infer P, infer I, infer M> ? M : ExtractMonomorphClass<CM[K]>;
 };
 
+export declare type ComponentMapInput<CM extends ComponentMap> = Partial<{
+    [K in keyof CM as LowercaseFirstLetter<K>]: ComponentInput<ExtractMonomorphClass<CM[K]>>;
+}>;
+
 export declare function createEntityClass<C>(options?: EntityCodeGenerationOptions): <CM extends ComponentMap, QM extends QueryMap<C, CM>, I extends EntityInput<CM> = EntityInput<CM>>(componentMap: CM, queries?: QM) => EntityClassWithStatics<C, CM, QM, I>;
 
 export declare type CreateEntityFunction<C, CM extends ComponentMap, I extends EntityInput<CM>> = (data?: I, pool?: EntityPoolClass<C>) => EntityInstanceWithPool<CM, I, C>;
 
 declare type ElementOfArray<T> = T extends (infer E)[] ? E : never;
 
-declare interface EntityBaseProperties<CM extends ComponentMap, I extends EntityInput<CM>, QM extends QueryMap<any, CM>> {
+declare interface EntityBaseProperties<CM extends ComponentMap, I extends any = EntityInput<CM>> {
     componentMap: CM;
-    addComponent: <CCK extends LowercaseFirstLetter<keyof CM>, CC extends CM[OriginalComponentKey<CCK, CM>] = CM[OriginalComponentKey<CCK, CM>]>(...a: CC extends {
-        monomorphClass: any;
-    } ? (undefined extends ComponentInput<CC['monomorphClass']> ? [key: CCK, data?: ComponentInput<CC['monomorphClass']>] : [key: CCK, data: ComponentInput<CC['monomorphClass']>]) : (undefined extends ComponentInput<CC> ? [key: CCK, data?: ComponentInput<CC>] : [key: CCK, data: ComponentInput<CC>])) => void;
+    __typescriptOnlyInputType: I;
+    addComponent: <CCK extends LowercaseFirstLetter<keyof CM>, CC extends CM[OriginalComponentKey<CCK, CM>] = CM[OriginalComponentKey<CCK, CM>]>(...a: (undefined extends ComponentInput<ExtractMonomorphClass<CC>> ? [key: CCK, data?: ComponentInput<ExtractMonomorphClass<CC>>] : [key: CCK, data: ComponentInput<ExtractMonomorphClass<CC>>])) => void;
     removeComponent: <CCK extends LowercaseFirstLetter<keyof CM>>(key: CCK) => void;
     hasComponent: <CCK extends LowercaseFirstLetter<keyof CM>>(key: CCK) => boolean;
     clone(): this;
@@ -60,7 +64,7 @@ declare interface EntityBaseProperties<CM extends ComponentMap, I extends Entity
     isDestroyed(): boolean;
 }
 
-export declare type EntityClass<CM extends ComponentMap, I extends EntityInput<CM> = EntityInput<CM>, QM extends QueryMap<any, CM> = QueryMap<any, CM>, E extends EntityInstance<CM, I, QM> = EntityInstance<CM, I, QM>> = EntityConstructor<QM, E, I, CM>;
+export declare type EntityClass<CM extends ComponentMap, I extends EntityInput<CM> = EntityInput<CM>, QM extends QueryMap<any, CM> = QueryMap<any, CM>, E extends EntityInstance<CM, I> = EntityInstance<CM, I>> = EntityConstructor<QM, E, I, CM>;
 
 export declare type EntityClassWithStatics<C, CM extends ComponentMap, QM extends QueryMap<C, CM>, I extends EntityInput<CM> = EntityInput<CM>> = EntityClass<CM, I, QM> & {
     create: CreateEntityFunction<C, CM, I>;
@@ -88,26 +92,19 @@ declare type EntityCodeGenerationOptions = {
     skipSafetyChecks?: boolean;
 };
 
-export declare interface EntityConstructor<QM extends QueryMap<any, CM>, E extends EntityInstance<CM, I, QM>, I extends EntityInput<CM>, CM extends ComponentMap> {
+export declare interface EntityConstructor<QM extends QueryMap<any, CM>, E extends EntityInstance<CM, I>, I extends any, CM extends ComponentMap> {
     new (data: I): E;
     componentMap: CM;
+    __typescriptOnlyInputType: I;
     pool: EntityPoolClass<E>;
     componentsWithEntities: {
-        [K in keyof CM as CM[K] extends MonomorphClass<infer P, infer I, infer M> | {
-            monomorphClass: MonomorphClass<infer P, infer I, infer M>;
-        } ? LowercaseFirstLetter<K> : never]: {
-            [Symbol.iterator](): IterableIterator<[WithPool<InstanceType<CM[K] extends MonomorphClass<any, any, any> ? CM[K] : CM[K] extends {
-                monomorphClass: MonomorphClass<any, any, any>;
-            } ? CM[K]['monomorphClass'] : never>>, E]>;
+        [K in keyof CM as ExtractMonomorphClass<CM[K]> extends MonomorphClass<infer P, infer I, infer M> ? LowercaseFirstLetter<K> : never]: {
+            [Symbol.iterator](): IterableIterator<[WithPool<InstanceType<ExtractMonomorphClass<CM[K]>>>, E]>;
         };
     };
     components: {
-        [K in keyof CM as CM[K] extends MonomorphClass<infer P, infer I, infer M> | {
-            monomorphClass: MonomorphClass<infer P, infer I, infer M>;
-        } ? LowercaseFirstLetter<K> : never]: {
-            [Symbol.iterator](): IterableIterator<WithPool<InstanceType<CM[K] extends MonomorphClass<any, any, any> ? CM[K] : CM[K] extends {
-                monomorphClass: MonomorphClass<any, any, any>;
-            } ? CM[K]['monomorphClass'] : never>>>;
+        [K in keyof CM as ExtractMonomorphClass<CM[K]> extends MonomorphClass<infer P, infer I, infer M> ? LowercaseFirstLetter<K> : never]: {
+            [Symbol.iterator](): IterableIterator<WithPool<InstanceType<ExtractMonomorphClass<CM[K]>>>>;
         };
     };
     queries: {
@@ -125,13 +122,9 @@ export declare interface EntityConstructor<QM extends QueryMap<any, CM>, E exten
     };
 }
 
-export declare type EntityInput<CM extends ComponentMap> = Partial<{
-    [K in keyof CM as LowercaseFirstLetter<K>]: CM[K] extends {
-        monomorphClass: any;
-    } ? ComponentInput<CM[K]['monomorphClass']> : ComponentInput<CM[K]>;
-}>;
+export declare type EntityInput<X extends ComponentMap | EntityClass<any, any, any, any> | EntityInstanceWithPool<any, any, any> | EntityInstance<any, any>> = X extends ComponentMap ? ComponentMapInput<X> : X extends EntityConstructor<infer QM, infer E, infer I, infer CM> ? I : X extends EntityInstanceWithPool<infer CM, infer I, infer E> ? I : X extends EntityInstance<infer CM, infer I> ? I : never;
 
-export declare type EntityInstance<CM extends ComponentMap, I extends EntityInput<CM>, QM extends QueryMap<any, CM>> = ComponentMapClassProperties<CM> & EntityBaseProperties<CM, I, QM>;
+export declare type EntityInstance<CM extends ComponentMap, I extends any = EntityInput<CM>> = ComponentMapClassProperties<CM> & EntityBaseProperties<CM, I>;
 
 export declare type EntityInstanceWithPool<CM extends ComponentMap, I extends EntityInput<CM>, E> = NoInfer<E & {
     pool: EntityPoolClass<E> | null;
@@ -157,13 +150,37 @@ export declare interface EntityPoolClass<M> {
     /** how many non-destroyed objects are in this pool, i.e. how many would be iterated on */
     length: number;
     [Symbol.iterator](): IterableIterator<WithPool<M>>;
-    create: (data?: M extends EntityInstance<infer CM, infer I, any> ? EntityInput<CM> : undefined) => M extends EntityInstanceWithPool<infer CM, infer I, any> ? EntityInstanceWithPool<CM, I, M> : never;
+    create(data?: M extends EntityInstance<infer CM, infer I> ? EntityInput<CM> : undefined): M extends EntityInstanceWithPool<infer CM, infer I, any> ? EntityInstanceWithPool<CM, I, M> : never;
+    toArray(array: NumberArray, startOffset?: number): number;
+    fromArray(array: NumberArray, startOffset?: number, classConstructor?: new (...args: any[]) => M): number;
+    fromArrayNoReferences(array: NumberArray, startOffset?: number, classConstructor?: new (...args: any[]) => M): number;
+    fromArrayOnlyReferences(array: NumberArray, references?: any, startOffset?: number, classConstructor?: new (...args: any[]) => M): number;
 }
 
+export declare type ExtractMonomorphClass<CC> = CC extends {
+    monomorphClass?: infer MC extends MonomorphClass<any, any, any>;
+} ? MC : CC extends ({
+    monomorphClass?: {
+        fnInArray: [() => infer MC extends MonomorphClass<any, any, any>];
+    };
+}) ? MC : CC extends {
+    fnInArray: [() => infer MC extends MonomorphClass<any, any, any>];
+} ? MC : CC;
+
 export declare function getEntityClassCode<C, CM extends ComponentMap>(componentMap: CM, queries?: QueryMap<C, CM>, options?: EntityCodeGenerationOptions): string;
 
+export declare function LazyComponent<F extends () => T, T>(componentFn: F): LazyWrapper<ReturnType<F>>;
+
+export declare type LazyMonomorphComponentConfig<MC extends MonomorphClass<any, any, any>> = ComponentConfig<LazyWrapper<MC>, InputType<InstanceType<MC>>>;
+
+export declare type LazyWrapper<T> = {
+    fnInArray: [() => T];
+};
+
 declare type LowercaseFirstLetter<S> = S extends `${infer FirstLetter}${infer Rest}` ? `${Lowercase<FirstLetter>}${Rest}` : S;
 
+export declare type MonomorphComponentConfig<MC extends MonomorphClass<any, any, any>> = ComponentConfig<MC, InputType<InstanceType<MC>>> | ComponentConfig<LazyWrapper<MC>, InputType<InstanceType<MC>>>;
+
 declare type OriginalComponentKey<CCK extends LowercaseFirstLetter<keyof CM>, CM extends ComponentMap> = CCK extends keyof CM ? CCK : UppercaseFirstLetter<CCK>;
 
 export declare type QueryConfig<C, CM extends ComponentMap> = {

package/build/mecs.js

@@ -1,8 +1,17 @@
+function LazyComponent(componentFn) {
+  return { fnInArray: [componentFn] };
+}
 function lowercaseFirstLetter(str) {
   return str.charAt(0).toLowerCase() + str.slice(1);
 }
 function isMonomorphClass(x) {
-  return typeof x === "function" && "serializedSize" in x || typeof x === "object" && "monomorphClass" in x;
+  return typeof x === "function" && "serializedSize" in x || x instanceof Object && ("monomorphClass" in x || "fnInArray" in x);
+}
+function isComponentConfig(x) {
+  return x instanceof Object;
+}
+function isLazyMonomorphClass(x) {
+  return x instanceof Object && ("fnInArray" in x || "monomorphClass" in x && x.monomorphClass instanceof Object && "fnInArray" in x.monomorphClass);
 }
 function getEntityClassCode(componentMap, queries, options) {
   let monomorphReferenceCode = "";
@@ -51,7 +60,7 @@ function getEntityClassCode(componentMap, queries, options) {
     let processedDataCode = "data";
     let afterComponentAddedCode = "";
     let beforeComponentRemovedCode = "";
-    if (typeof component === "object" && component !== null) {
+    if (isComponentConfig(component)) {
       if ("beforeEntityClassCode" in component) {
         if (typeof component.beforeEntityClassCode === "string") {
           referenceComponentFunctionsCode += component.beforeEntityClassCode;
@@ -149,15 +158,17 @@ function getEntityClassCode(componentMap, queries, options) {
       }
     }
     if (isMonomorph) {
-      const monomorphClassName = ("monomorphClass" in component ? component.monomorphClass : component).name;
+      const isLazyMonomorph = isLazyMonomorphClass(component);
+      const monomorphClassName = isLazyMonomorph ? `LazyComponent__${componentKey}` : ("monomorphClass" in component ? component.monomorphClass : component).name;
+      const resolvedMonomorphClass = isLazyMonomorph ? "(" + monomorphClassName + "())" : monomorphClassName;
       if (!monomorphsAlreadyAdded.has(monomorphClassName)) {
         monomorphReferenceCode += `
-          const ${monomorphClassName} = componentMap.${key}${"monomorphClass" in component ? ".monomorphClass" : ""};
+          const ${monomorphClassName} = componentMap.${key}${"monomorphClass" in component ? ".monomorphClass" : ""}${isLazyMonomorph ? ".fnInArray[0]" : ""};
         `;
         monomorphsAlreadyAdded.add(monomorphClassName);
       }
       poolCreationCode += `
-        const ${componentKey}Pool = new ${monomorphClassName}.Pool();
+        const ${componentKey}Pool = new ${resolvedMonomorphClass}.Pool();
         const ${componentKey}PoolArray = ${componentKey}Pool.array;
       `;
       poolMapCreationCode += `
@@ -206,7 +217,7 @@ function getEntityClassCode(componentMap, queries, options) {
       addComponentFunctionsCode += `
         (data, entity, componentKey, updateQueryMemberships) => {
           entity.componentFlags |= ${componentFlagValue}n;
-          entity.${componentKey} = ${monomorphClassName}.create(${processedDataCode}, ${componentKey}Pool);
+          entity.${componentKey} = ${resolvedMonomorphClass}.create(${processedDataCode}, ${componentKey}Pool);
           ${componentKey}ComponentToEntity[entity.${componentKey}.index] = entity;
 
           ${afterComponentAddedCode}
@@ -958,6 +969,18 @@ function getEntityClassCode(componentMap, queries, options) {
       }
     }
 
+    theClass.Reference = class {
+      constructor(reference) {
+        if (reference && !(reference.version & 1)) {
+          this.reference = reference;
+          this.version = reference.version;
+        } else {
+          this.reference = null;
+          this.version = -1;
+        }
+      }
+    }
+
     return theClass;
   `;
   if (options?.logCode) {
@@ -969,6 +992,7 @@ function createEntityClass(options) {
   return (componentMap, queries) => new Function("componentMap", "queryMap", getEntityClassCode(componentMap, queries, options))(componentMap, queries);
 }
 export {
+  LazyComponent,
   createEntityClass,
   getEntityClassCode
 };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@perplexdotgg/mecs",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MECS - Monomorph ECS - A high-performance Entity Component System for TypeScript and JavaScript projects, designed for games and simulations.",
   "repository": {
     "type": "git",
     "url": "https://codeberg.org/perplexdotgg/mecs"
   },
+  "funding": "https://opencollective.com/perplexgg",
   "license": "MIT",
   "author": "perplex.gg",
   "type": "module",
@@ -27,7 +28,7 @@
     "bench": "vitest bench"
   },
   "peerDependencies": {
-    "monomorph": "^1.5.0"
+    "monomorph": "^1.5.5"
   },
   "peerDependenciesMeta": {
     "monomorph": {
@@ -36,7 +37,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.1",
-    "monomorph": "^1.5.0",
+    "monomorph": "^1.5.5",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",