@perplexdotgg/mecs 0.1.0 → 0.3.0

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>
@@ -5,25 +10,32 @@
 
 MECS is an [ECS](https://en.wikipedia.org/wiki/Entity_component_system) library for Typescript and Javascript games and simulations, built around [Monomorph](http://codeberg.org/perplexdotgg/monomorph), a library for performant objects. The API is inspired by [Miniplex](https://github.com/hmans/miniplex), though the implementation is quite different.
 
-MECS focuses on the developer's experience in their IDE, especially around auto-complete and compile-type type-checking, while maintaining very high performance, about as high as you can achieve with an [AoS design](https://en.wikipedia.org/wiki/AoS_and_SoA).
+Although using Monomorph classes as components gives you some extra features, it is not a requirement or dependency of MECS. You can use primitives (number, boolean, etc) or your own classes, and customize their lifecycle with component config objects. See the "[Non-Monomorph Components](#non-monomorph-components)" and "[Customizing Components](#customizing-components)" sections below for more details.
+
+MECS focuses on the developer's experience in their IDE, especially around auto-complete and compile-time type-checking, while maintaining very high performance, about as high as you can achieve with an [AoS design](https://en.wikipedia.org/wiki/AoS_and_SoA).
 
 <details>
-  <summary>Why not use SoA design?</summary>
-  While SoA can achieve better performance in the best cases, it tends to be unwieldy, especially for nested fields, and generally ECS implementations lack auto-complete for components and properties.
+  <summary>Side note: Why not use SoA design?</summary>
+  While SoA can achieve better performance in the best cases, it tends to be unwieldy, especially for nested fields, and generally ECS implementations lack auto-complete for components and properties. For larger game projecting, remembering all component names and their properties is quite difficult. Using JS getters with SoA (to achieve auto complete) gives much worse overall performance than AoS.
 </details>
 
+---
+
 ## Features
-- Entities and monomorph-based components automatically gain **object-pooling** features, eliminating most garbage collection through automatic object re-use. Just create and destroy entities and components, and the pooling and re-use is taken care of.
-- Simple and minimal: There are only entities, components and queries
+- Automatically generates highly optimized JS class code for your specific entity schema, at start up
+- Entities and monomorph-based components automatically gain **object-pooling** features, eliminating most garbage collection ("Major GC") through automatic object re-use. Just create and destroy entities and components, and the pooling and re-use is taken care of.
+- Simple and minimal API: There are only entities, components and queries
 - Queries, aka archetypes, automatically match and track entities based on which components they have, or don't have
 - Strong compile-time type safety if you use Typescript (recommended)
 - Coming soon: automatic serialization/deserialization (to/from number arrays) of entities (fully or a subset of components) to create snapshots
 
-MECS creates a single entity pool, or world, when it creates your entity class from the schema you provide.
+For convenience, MECS automatically puts entities in a central pool by default, so they can be re-used. However you can also create multiple pools for an entity class, or have multiple entity classes with different schemas and pools.
 
-MECS has no built-in concept of "systems" in the ECS sense, instead it provides queries to help you quickly write efficient code that processes specific archetypes of entities. Your systems can just be functions that iterate over entities matching a query, and your systems can also subscribe to entities newly matching, or no longer matching, a query
+MECS has no built-in concept of "systems" in the ECS sense, instead it provides queries to help you quickly write efficient code that processes specific archetypes of entities. Your systems can just be functions that iterate over entities matching a query, and your systems can also subscribe to entities newly matching, or no longer matching, a query.
 
-MECS has been created primarily around having a single entity schema/pool where all entities _can_ have all possible components types, but most entities only have a subset of them. If all your entities have all the same components, it is likely simpler to use [Monomorph](http://codeberg.org/perplexdotgg/monomorph) on its own.
+### When to use MECS over Monomorph alone
+
+MECS has been created primarily around having a single entity schema/pool, where most entities only have a subset of the possible components. For example, some but not all of your entities might be visible, they may or may not have physics properties, some might be controlled by input, and so on. If all your entities have all the same components, it may be simpler to use [Monomorph](http://codeberg.org/perplexdotgg/monomorph) on its own.
 
 ## Usage
 
@@ -36,20 +48,17 @@ npm install @perplexdotgg/mecs
 
 ### Defining an Entity schema to create your Entity class
 
-The following is Typescript code. The Javascript version is below this.
+The following is JavaScript code. The Typescript version is below this.
 
-```ts
+```js
 import { createClass } from 'monomorph';
-import { createEntityClass, type QueryMap, type VirtualComponent } from '@perplexdotgg/mecs';
+import { createEntityClass } from '@perplexdotgg/mecs';
 
 // imagine some monomorph classes in your project
 // see the monomorph docs for more on those:
 // https://codeberg.org/perplexdotgg/monomorph
-class Projectile extends createClass<Projectile, typeof projectileProps>(projectileProps) {}
-class Transform extends createClass<Transform, typeof transformProps>(transformProps) {}
-
-// and some non-monomorph class
-class MyClass {}
+class Projectile extends createClass(projectileProps) {}
+class Transform extends createClass(transformProps) {}
 
 // define all the components you want entities to potentially have
 const components = {
@@ -57,20 +66,15 @@ const components = {
   localTransform: Transform,
   globalTransform: Transform,
   Projectile, // this is shorthand for: projectile: Projectile
+};
 
-  // for non-monomorph classes, pass a key with value null.
-  // this syntax allows for the correct types to be expected and inferred.
-  // you are responsible for creating and managing
-  // this field, including any needed clean-up before it is removed
-  myClass: null! as VirtualComponent<MyClass>,
-} as const;
-
+// define queries you want to do. these always stay up-to-date, efficiently
 const queries = {
   projectiles: {
     // an entity must have all of these components to match this query
     with: ['globalTransform', 'projectile'],
     // AND it can have none of these components to match this query
-    without: ['myClass'],
+    without: ['localTransform'],
 
     // listeners can added now, or later (see the Queries docs below)
     afterEntityAdded: (entity) => {
@@ -79,22 +83,24 @@ const queries = {
     beforeEntityRemoved: (entity) => {
       // this is called when an entity no longer matches this query,
       // just before a relevant component is removed from the entity
+      // and/or before an entity is destroyed
     },
   },
   query2: {
     with: ['localTransform', 'globalTransform'],
     without: [],
   },
-} as const satisfies QueryMap<Entity, typeof components>;
+};
 
-let debugLogging: boolean | undefined = false;
+// additional Entity class options, see "Entity Class Options" below
+const extraOptions = {};
 
-// automatically create our entity class from the schemas above
+// automatically create our entity class from the schemas above.
 // note that there are two function calls after createEntityClass
-// to circumvent a typescript limitation, see https://github.com/microsoft/TypeScript/issues/10571
-class Entity extends createEntityClass<Entity>(debugLogging)(components, queries) {
+// to circumvent a typescript limitation (sorry, vanilla JS folks!)
+class Entity extends createEntityClass(extraOptions)(components, queries) {
 
-  // most methods will likely exist on your components directly,
+  // most methods will likely exist on your components rather than your entities,
   // but you can also extend the generated entity class
   myEntityMethod() {
     // your code here! use 'this' like you would expect
@@ -106,20 +112,18 @@ class Entity extends createEntityClass<Entity>(debugLogging)(components, queries
 ```
 
 <details>
-  <summary>Javascript version</summary>
+  <summary>Typescript version</summary>
 
-```js
+```ts
 import { createClass } from 'monomorph';
-import { createEntityClass } from '@perplexdotgg/mecs';
+import { createEntityClass, type QueryMap, type ComponentMap, type ComponentConfig } from '@perplexdotgg/mecs';
 
-// imagine some monomorph classes in your project
-// see the monomorph docs for more on those:
+// imagine some monomorph classes in your project, see the monomorph docs for more on those:
 // https://codeberg.org/perplexdotgg/monomorph
-class Projectile extends createClass(projectileProps) {}
-class Transform extends createClass(transformProps) {}
+class Projectile extends createClass<Projectile, typeof projectileProps>(projectileProps) {}
+class Transform extends createClass<Transform, typeof transformProps>(transformProps) {}
 
-// and some non-monomorph class
-class MyClass {}
+// non-monomorph components are also supported, see "Non-Monomorph Components" below
 
 // define all the components you want entities to potentially have
 const components = {
@@ -127,19 +131,15 @@ const components = {
   localTransform: Transform,
   globalTransform: Transform,
   Projectile, // this is shorthand for: projectile: Projectile
+} as const satisfies ComponentMap;
 
-  // for non-monomorph classes, pass a key with value null.
-  // you are responsible for creating and managing
-  // this field, including any needed clean-up before it is removed
-  myClass: null,
-};
-
+// define queries you want to do. these always stay up-to-date, efficiently
 const queries = {
   projectiles: {
     // an entity must have all of these components to match this query
     with: ['globalTransform', 'projectile'],
     // AND it can have none of these components to match this query
-    without: ['myClass'],
+    without: ['localTransform'],
 
     // listeners can added now, or later (see the Queries docs below)
     afterEntityAdded: (entity) => {
@@ -154,16 +154,17 @@ const queries = {
     with: ['localTransform', 'globalTransform'],
     without: [],
   },
-};
+} as const satisfies QueryMap<Entity, typeof components>;
 
-let debugLogging = false;
+// additional Entity class options, see "Entity Class Options" below
+const extraOptions = {};
 
-// automatically create our entity class from the schemas above
+// automatically create our entity class from the schemas above.
 // note that there are two function calls after createEntityClass
-// to circumvent a typescript limitation (sorry, vanilla JS folks!)
-class Entity extends createEntityClass(debugLogging)(components, queries) {
+// to circumvent a typescript limitation ([TS issue 10571](https://github.com/microsoft/TypeScript/issues/10571))
+class Entity extends createEntityClass<Entity>(extraOptions)(components, queries) {
 
-  // most methods will likely exist on your components directly,
+  // most methods will likely exist on your components rather than your entities,
   // but you can also extend the generated entity class
   myEntityMethod() {
     // your code here! use 'this' like you would expect
@@ -180,14 +181,14 @@ Like monomorph's create method, entities accept the same object representations
 
 ```ts
 const entity1 = Entity.create({
-  localTransform: {
-    position: { x: 0, y: 0, z: 0, },
-    orientation: { x: 0, y: 0, z: 0, w: 1 },
+  globalTransform: {
+    position: [0, 0, 0],
+    orientation: [0, 0, 0],
     scale: 1,
   },
   projectile: {
     speed: 4,
-    direction: { x: 1, y: 0, z: 0 },
+    direction: [1, 0, 0],
   },
 });
 
@@ -200,9 +201,6 @@ const entity2 = Entity.create({
     speed: 4,
     direction: { x: 1, y: 0, z: 0 },
   },
-
-  // you are responsible for instantiating your custom classes
-  myClass: new MyClass(),
 });
 
 // destroy() to return the entity to the pool, it will automatically be re-used later
@@ -210,11 +208,105 @@ const entity2 = Entity.create({
 // before the component(s) needed for the query are deleted
 // each destroyed component also gets recycled in its own component pool
 entity2.destroy();
+```
+
+### Entity Class Options
+When creating your entity class, you can pass as an optional parameter to `createEntityClass`, an object with the following properties:
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `skipSafetyChecks` | `boolean` | `false` | Set to `true` to skip safety checks when adding/removing components, improving performance. It is recommended to keep this `false` during development and `true` in production builds. |
+| `logCode` | `boolean` | `false` | Set to `true` to `console.log` the code that was automatically generated for the base Entity class. |
+| `logComponents` | `boolean` | `false` | Set to `true` to `console.log` every time a component is added or removed from an entity. (note: this affects the generated Entity code) |
+| `logQueries` | `boolean` | `false` | Set to `true` to `console.log` every time an entity is added or removed from a query. (note: this affects the generated Entity code) |
+
+
+### Non-Monomorph Components
+For components that are not monomorph classes, such as your own classes or primitives like numbers and booleans,
+you can quickly define them with a default value (such as `null`) as the component config. You are then responsible for creating and managing these components, including any necessary cleanup before they are removed. Below is a simple example; see the "[Customizing Components](#customizing-components)" section below for more advanced options.
+
+This is the Javascript versiom, the Typescript version is below.
+
+```js
+// some non-monomorph class
+class MyClass {}
+
+const components = {
+  // allows entity.addComponent('isVisible') without specifying the second parameter, in this case
+  // entity.isVisible will be true. this is how you can use components as simple flags
+  isVisible: true,
+
+  // for non-monomorph classes, you can use a key with value null, or a default value of your choice.
+  // you are responsible for creating and managing this field, including any needed clean-up
+  // before it is removed. the `null` here is the default value that will be used when
+  // entity.addComponent('myClass') is called without a second parameter, and it is also the value set on
+  // the entity when the component is removed
+  myClass: null,
+
+  // you have much more control over the component's lifecycle, by passing a component config object,
+  // see the "Customizing Components" section below for details
+  myCustomComponent: {
+    // component config options here, see "Customizing Components" below
+  },
+
+} as const satisfies ComponentMap;
+
+const queries = {};
+
+class Entity extends createEntityClass()(components, queries) {}
+
+const entity = Entity.create({
+  myClass: new MyClass(),
+  isVisible: true,
+});
+// now entity.myClass is an instance of MyClass, and entity.isVisible is true
 
-// note: if you need to do a cleanup on your custom class (like MyClass above),
-// use a query's beforeEntityRemoved method/listeners for that purpose
+entity.destroy();
+// now entity.myClass is null, but note that entity.isVisible is still true, based on the value in the `components` config above
 ```
 
+<details>
+  <summary>TypeScript Version</summary>
+
+```ts
+// some non-monomorph class
+class MyClass {}
+
+const components = {
+  // allows entity.addComponent('isVisible') without specifying the second parameter, in this case
+  // entity.isVisible will be true. this is how you can use components as simple flags
+  isVisible: true as unknown as ComponentConfig<true>,
+
+  // for non-monomorph classes, you can use a key with value null, or a default value of your choice.
+  // you are responsible for creating and managing this field, including any needed clean-up
+  // before it is removed. the `null` here is the default value that will be used when
+  // entity.addComponent('myClass') is called without a second parameter, and it is also the value set on
+  // the entity when the component is removed
+  myClass: null as unknown as ComponentConfig<MyClass>,
+
+  // you have much more control over the component's lifecycle, by passing a component config object,
+  // see the "Customizing Components" section below for details
+  myCustomComponent: {
+    // config options here, see below
+  } as const satisfies ComponentConfig<TheComponentType, AcceptedInputTypes>,
+
+} as const satisfies ComponentMap;
+
+const queries = {};
+
+class Entity extends createEntityClass<Entity>()(components, queries) {}
+
+const entity = Entity.create({
+  myClass: new MyClass(),
+  isVisible: true,
+});
+// now entity.myClass is an instance of MyClass, and entity.isVisible is true
+
+entity.destroy();
+// now entity.myClass is null, and entity.isVisible is still true, based on the values in the `components` object above
+```
+
+</details>
+
 ### Accessing components and methods
 ```js
 // calling component methods
@@ -223,6 +315,7 @@ entity1.projectile.checkCollisions();
 // calling entity methods
 entity1.myEntityMethod();
 
+// adding amd accessing a monomorph-based component using json notation
 entity1.addComponent('globalTransform', {
   position: { x: 1, y: 2, z: 3, },
   orientation: { x: 0, y: 0, z: 0, w: 1 },
@@ -232,15 +325,15 @@ entity1.globalTransform.position.x += 5;
 
 // add a component, using another component as input data
 entity2.addComponent('localTransform', entity1.localTransform);
-// ^^ they will not be the same objects, they will just have the same data
-// this is also true for nested objects
+// ^^ they will not be the same objects, they will just have the same data,
+// this is also true for nested objects. i.e:
+// entity2.localTransform will be a deep copy of entity1.localTransform
 
 // remove a component
 entity1.removeComponent('projectile');
 
-// checking if a component exists on an entity, two ways to do so:
-if (entity1.globalTransform) { /* */ }
-if (entity1.hasCompoonent('globalTransform')) { /* */ }
+// checking if a component exists on an entity:
+if (entity1.hasComponent('globalTransform')) { /* */ }
 
 ```
 
@@ -287,9 +380,167 @@ 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` along with MECS's `LazyComponent`. See the Typescript tests in [`tests/lazyComponents.test.ts`](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/lazyComponents.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: LazyComponent(() => Turret),
+
+  // alternatively, you can use a component config object for further customization:
+  turret: {
+    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, {}) {}
+```
+
+
+### 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).
+
+This is the Javascript version, the Typescript version is below.
+
+```js
+class MyClass {}
+
+const components = {
+  myClass: {
+    // called after the component is added to an entity
+    afterComponentAdded: (myClassInstance, entity, componentKey) => {
+      // do any additional actions on myClassInstance here
+      // componentKey will be the string 'myClass' in this case
+    },
+
+    // called before the component is removed from an entity
+    beforeComponentRemoved: (myClassInstance, entity, componentKey) => {
+      // do any needed cleanup on myClassInstance here
+    },
+
+    // this function will be called to process the input data when adding this component
+    processDataOnAdd: (data) => {
+      if (data === null) {
+        // provide a default value if needed
+        data = new MyClass();
+      }
+      // modify and return the data as needed
+      return data;
+    },
+  },
+
+  myCustomMonomorphComponent: {
+    monomorphClass: SomeMonomorphClass,
+
+    // all other config options are available, see the tests for more examples
+  },
+};
+
+const queries = {};
+
+class Entity extends createEntityClass()(components, queries) {}
+
+const entity = Entity.create({
+  myClass: null, // this will automatically be processed by processDataOnAdd
+});
+
+// entity.myClass is now an instance of MyClass
+
+const entity2 = Entity.create({
+  myClass: new MyClass(), // this still works, because of the (data === null) check in processDataOnAdd
+});
+```
+
+<details>
+  <summary>TypeScript Version</summary>
+
+```ts
+class MyClass {}
+
+const components = {
+  myClass: {
+    // called after the component is added to an entity
+    afterComponentAdded: (myClassInstance, entity, componentKey) => {
+      // do any additional actions on myClassInstance here
+      // componentKey will be the string 'myClass' in this case
+    },
+
+    // called before the component is removed from an entity
+    beforeComponentRemoved: (myClassInstance, entity, componentKey) => {
+      // do any needed cleanup on myClassInstance here
+    },
+
+    // this function will be called to process the input data when adding this component
+    processDataOnAdd: (data) => {
+      if (data === null) {
+        // provide a default value if needed
+        data = new MyClass();
+      }
+      // modify and return the data as needed
+      return data;
+    },
+    // ComponentConfig<MyClass, MyClass | null> means that entity.myClass will be of type MyClass,
+    // and when adding the component, the input data can be either MyClass or null
+  } as const satisfies ComponentConfig<MyClass, MyClass | null>,
+
+  myCustomMonomorphComponent: {
+    monomorphClass: SomeMonomorphClass,
+
+    // all other config options are available, see the tests for more examples
+  } as const satisfies ComponentConfig<SomeMonomorphClass>,
+} as const satisfies ComponentMap;
+
+const queries = {};
+
+class Entity extends createEntityClass<Entity>()(components, queries) {}
+
+const entity = Entity.create({
+  myClass: null, // this will automatically be processed by processDataOnAdd
+});
+
+// entity.myClass is now an instance of MyClass
+
+const entity2 = Entity.create({
+  myClass: new MyClass(), // this still works
+});
+```
+
+</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. |
+| `afterComponentAdded` | Function: `(componentInstance, entity, componentKey) => void` | A function that will be called after the component is added. This will happen before any query membership-related triggers occur.  |
+| `afterComponentAddedCode` | String or Function that returns a string | Like the above, but you provide the code that will be injected directly into the generated Entity code for this component. See the [tests](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts) for more details. |
+| `beforeComponentRemoved` | Function: `(componentInstance, entity, componentKey) => void` | A function that will be called before the component is removed. This will happen after any query membership-related triggers occur. |
+| `beforeComponentRemovedCode` | String or Function that returns a string | Like the above, but you provide the code that will be injected directly into the generated Entity code for this component. See the [tests](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts) for more details. |
+| `processDataOnAdd` | Function: `(data) => processedData` | A function that will be called to process the input data when adding this component. The returned value will be used as the component's value for non-monomorph components. For monomorph components, the processed value will be passed to the class's create method. |
+| `processDataOnAddCode` | String or Function that returns a string | Like the above, but you provide the code that will be injected directly into the generated Entity code for this component. See the [tests](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts) for more details. |
+| `nullComponent` | Function: `(entity, componentKey) => void` | By default, i.e. when this option is not specified, the component property on the entity gets set to `null` when the component is removed from the entity. To override that behavior, you can provide a function that does whatever you prefer (pass a noop function to leave the value as is) |
+| `nullComponentCode` | String or Function that returns a string | Like the above, but you provide the code that will be injected directly into the generated Entity code for this component. See the [tests](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts) for more details. |
+| `beforeEntityClassCode` | String or Function that returns a string | Code that will be injected at the start of the generated code, before the Entity class's code. Useful for defining helper functions or values needed by all the options above. See the [tests](https://codeberg.org/perplexdotgg/mecs/src/branch/main/tests/customComponents.test.ts) for more details. |
+
 ## Roadmap
 
-- Integrating the upcoming version of monomorph where non-monomorth classes are better supported (e.g. to allow a component to contain a reference to an html element)
 - Example project/template coming soon
 - Basic benchmarks
 - Entity/component data debugging tool(s)
@@ -297,4 +548,4 @@ Entity.queries.projectiles.beforeEntityRemoved.removeListener(someListener);
 
 ## 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,54 +1,106 @@
 import { InputType } from 'monomorph';
 import { MonomorphClass } from 'monomorph';
 import { MonomorphInstance } from 'monomorph';
-import { PartialRecursive } from 'monomorph';
+import { NumberArray } from 'monomorph';
 import { WithPool } from 'monomorph';
 
-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 VirtualComponent<infer T> ? T : X;
+export declare type ComponentConfig<ComponentType, ComponentInputType extends any = InputType<ComponentType> extends never ? ComponentType : InputType<ComponentType>> = {
+    monomorphClass?: ComponentType extends MonomorphClass<any, any, any> ? ComponentType : ComponentType extends MonomorphInstance<infer P, infer I> ? MonomorphClass<P, I, ComponentType> : never;
+    afterComponentAdded?: (componentInstance: ComponentType extends abstract new (...args: any) => any ? InstanceType<ComponentType> : ComponentType, entity: any, componentKey: string) => void;
+    afterComponentAddedCode?: string | ComponentConfigFunction<ComponentType, ComponentInputType>;
+    beforeComponentRemoved?: (componentInstance: ComponentType extends abstract new (...args: any) => any ? InstanceType<ComponentType> : ComponentType, entity: any, componentKey: string) => void;
+    beforeComponentRemovedCode?: string | ComponentConfigFunction<ComponentType, ComponentInputType>;
+    processDataOnAdd?: (data: ComponentInputType) => ComponentInputType;
+    processDataOnAddCode?: string | ((options: {
+        dataVariableName: string;
+        componentConfigReference: string;
+    }) => string);
+    nullComponent?: (entity: any, componentKey: string) => void;
+    nullComponentCode?: string | ComponentConfigFunction<ComponentType, ComponentInputType>;
+    beforeEntityClassCode?: string | ComponentConfigBeforeEntityClassFunction<ComponentType, ComponentInputType>;
+};
+
+export declare type ComponentConfigBeforeEntityClassFunction<ComponentType, ComponentInputType> = ((options: {
+    componentKey: string;
+    componentFlagValue: bigint;
+    componentIndex: number;
+    componentConfig: ComponentConfig<ComponentType, ComponentInputType>;
+}) => string);
+
+export declare type ComponentConfigFunction<ComponentType, ComponentInputType> = ((options: {
+    entityVariableName: string;
+    componentKey: string;
+    componentFlagValue: bigint;
+    componentIndex: number;
+    componentConfig: ComponentConfig<ComponentType, ComponentInputType>;
+}) => string);
 
-export declare type ComponentMap = Record<string, any>;
+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> | 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];
+    [K in keyof CM as LowercaseFirstLetter<K>]?: ExtractMonomorphClass<CM[K]> extends MonomorphClass<infer P, infer I, infer M> ? M : ExtractMonomorphClass<CM[K]>;
 };
 
-export declare function createEntityClass<C>(debug?: boolean): <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 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 EntityInput<CM>> {
     componentMap: CM;
-    addComponent: <CCK extends LowercaseFirstLetter<keyof CM>, CC extends CM[OriginalComponentKey<CCK, CM>] = CM[OriginalComponentKey<CCK, CM>]>(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;
-    copy(other: this): this;
-    set(data: PartialRecursive<I>): this;
     destroy(): void;
     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>;
     Pool: NoInfer<EntityPoolClass<C>>;
 };
 
-export declare interface EntityConstructor<QM extends QueryMap<any, CM>, E extends EntityInstance<CM, I, QM>, I extends EntityInput<CM>, CM extends ComponentMap> {
+declare type EntityCodeGenerationOptions = {
+    /**
+     * If true, logs all the generated class code for the entity class
+     */
+    logCode?: boolean;
+    /**
+     * If true, logs when components are added to or removed from entities
+     */
+    logComponents?: boolean;
+    /**
+     * If true, logs when entities are added to or removed from queries
+     */
+    logQueries?: boolean;
+    /**
+     * If true, skips safety checks such as trying to add a component that an entity already has
+     * It is recommended that you set to true in production to improve performance, while leave false
+     * during development to catch unintended mistakes, or missing hasComponent() checks in your code
+     */
+    skipSafetyChecks?: boolean;
+};
+
+export declare interface EntityConstructor<QM extends QueryMap<any, CM>, E extends EntityInstance<CM, I>, I extends EntityInput<CM>, 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> ? LowercaseFirstLetter<K> : never]: {
-            [Symbol.iterator](): IterableIterator<[WithPool<InstanceType<CM[K]>>, 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> ? LowercaseFirstLetter<K> : never]: {
-            [Symbol.iterator](): IterableIterator<WithPool<InstanceType<CM[K]>>>;
+        [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: {
@@ -67,10 +119,10 @@ 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>]: ComponentInput<CM[K]>;
+    [K in keyof CM as LowercaseFirstLetter<K>]: ComponentInput<ExtractMonomorphClass<CM[K]>>;
 }>;
 
-export declare type EntityInstance<CM extends ComponentMap, I extends EntityInput<CM>, QM extends QueryMap<any, CM>> = EntityBaseProperties<CM, I, QM> & ComponentMapClassProperties<CM>;
+export declare type EntityInstance<CM extends ComponentMap, I extends 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;
@@ -96,13 +148,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 function getEntityClassCode<C, CM extends ComponentMap>(componentMap: CM, queries?: QueryMap<C, CM>, debug?: boolean): string;
+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> = {
@@ -116,8 +192,6 @@ export declare type QueryMap<C, CM extends ComponentMap> = Record<string, QueryC
 
 declare type UppercaseFirstLetter<S> = S extends `${infer FirstLetter}${infer Rest}` ? `${Uppercase<FirstLetter>}${Rest}` : S;
 
-export declare type VirtualComponent<T> = T;
-
 export declare type WithComponent<C extends {
     componentMap: any;
 }, KCM extends LowercaseFirstLetter<keyof C['componentMap']>> = Writeable<Omit<C, KCM> & {

package/build/mecs.js

@@ -1,22 +1,33 @@
+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;
+  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, debug) {
+function getEntityClassCode(componentMap, queries, options) {
   let monomorphReferenceCode = "";
   let poolCreationCode = "";
   let poolMapCreationCode = "const componentPools = {\n";
   let componentToEntityCode = "";
+  let referenceComponentFunctionsCode = "";
   let componentIndicesCode = "";
   let addComponentFunctionsCode = "";
   let removeComponentFunctionsCode = "";
+  let nullComponentCode = "";
   let componentFlagsCode = "";
   let createFromDataCode = "";
   let createFromDataCodeAllNulls = "";
   let destroyCode = "";
-  let componentIteratorFunctionsCode = "";
+  let componentWithEntityIteratorFunctionsCode = "";
   const componentFlags = [];
   const componentIndices = {};
   const monomorphsAlreadyAdded = /* @__PURE__ */ new Set();
@@ -27,7 +38,7 @@ function getEntityClassCode(componentMap, queries, debug) {
     const isMonomorph = isMonomorphClass(component);
     componentIndices[componentKey] = componentIndex;
     componentIndicesCode += `
-      ${componentKey}: ${componentIndex},
+      ['${componentKey}', ${componentIndex}],
     `;
     componentFlags.push(componentFlagValue);
     componentFlagsCode += `${componentFlagValue}n, `;
@@ -41,43 +52,133 @@ function getEntityClassCode(componentMap, queries, debug) {
     createFromDataCodeAllNulls += `
       this.${componentKey} = null;
     `;
+    destroyCode += `
+      if ((thisComponentFlags & ${componentFlagValue}n) !== 0n) {
+        this.removeComponent('${componentKey}', updateQueryMemberships);
+      }
+    `;
+    let processedDataCode = "data";
+    let afterComponentAddedCode = "";
+    let beforeComponentRemovedCode = "";
+    if (isComponentConfig(component)) {
+      if ("beforeEntityClassCode" in component) {
+        if (typeof component.beforeEntityClassCode === "string") {
+          referenceComponentFunctionsCode += component.beforeEntityClassCode;
+        } else {
+          referenceComponentFunctionsCode += component.beforeEntityClassCode({
+            componentKey,
+            componentFlagValue,
+            componentIndex,
+            componentConfig: component
+          });
+        }
+      }
+      if ("afterComponentAdded" in component) {
+        referenceComponentFunctionsCode += `
+          const ${componentKey}OnAdded = componentMap.${key}.afterComponentAdded;
+        `;
+        afterComponentAddedCode = `
+          ${componentKey}OnAdded(entity.${componentKey}, entity, '${componentKey}');
+        `;
+      } else if ("afterComponentAddedCode" in component) {
+        if (typeof component.afterComponentAddedCode === "string") {
+          afterComponentAddedCode = component.afterComponentAddedCode;
+        } else {
+          afterComponentAddedCode = component.afterComponentAddedCode({
+            entityVariableName: "entity",
+            componentKey,
+            componentFlagValue,
+            componentIndex,
+            componentConfig: component
+          });
+        }
+      }
+      if ("beforeComponentRemoved" in component) {
+        referenceComponentFunctionsCode += `
+          const ${componentKey}OnRemoved = componentMap.${key}.beforeComponentRemoved;
+        `;
+        beforeComponentRemovedCode = `
+          ${componentKey}OnRemoved(entity.${componentKey}, entity, '${componentKey}');
+        `;
+      } else if ("beforeComponentRemovedCode" in component) {
+        if (typeof component.beforeComponentRemovedCode === "string") {
+          beforeComponentRemovedCode = component.beforeComponentRemovedCode;
+        } else {
+          beforeComponentRemovedCode = component.beforeComponentRemovedCode({
+            entityVariableName: "entity",
+            componentKey,
+            componentFlagValue,
+            componentIndex,
+            componentConfig: component
+          });
+        }
+      }
+      if ("processDataOnAdd" in component) {
+        referenceComponentFunctionsCode += `
+          const ${componentKey}ProcessDataOnAdd = componentMap.${key}.processDataOnAdd;
+        `;
+        processedDataCode = `${componentKey}ProcessDataOnAdd(data)`;
+      } else if ("processDataOnAddCode" in component) {
+        if (typeof component.processDataOnAddCode === "string") {
+          processedDataCode = component.processDataOnAddCode;
+        } else {
+          processedDataCode = component.processDataOnAddCode({ dataVariableName: "data", componentConfigReference: "componentMap." + key });
+        }
+      }
+      if ("nullComponent" in component) {
+        referenceComponentFunctionsCode += `
+          const ${componentKey}NullComponent = componentMap.${key}.nullComponent;
+        `;
+        nullComponentCode = `
+          ${componentKey}NullComponent(entity, '${componentKey}');
+        `;
+      } else if ("nullComponentCode" in component) {
+        if (typeof component.nullComponentCode === "string") {
+          nullComponentCode = component.nullComponentCode;
+        } else {
+          nullComponentCode = component.nullComponentCode({
+            entityVariableName: "entity",
+            componentKey,
+            componentFlagValue,
+            componentIndex,
+            componentConfig: component
+          });
+        }
+      } else {
+        nullComponentCode = `
+          entity.${componentKey} = null;
+        `;
+      }
+    } else if (!isMonomorph) {
+      processedDataCode = "data ?? componentMap." + key;
+      if (typeof component === "number" || typeof component === "string" || typeof component === "boolean" || component === null || component === void 0) {
+        nullComponentCode = `
+          entity.${componentKey} = ${component === void 0 ? "undefined" : JSON.stringify(component)};
+        `;
+      }
+    }
     if (isMonomorph) {
-      if (!monomorphsAlreadyAdded.has(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 ${component.name} = componentMap.${key};
+          const ${monomorphClassName} = componentMap.${key}${"monomorphClass" in component ? ".monomorphClass" : ""}${isLazyMonomorph ? ".fnInArray[0]" : ""};
         `;
-        monomorphsAlreadyAdded.add(component.name);
+        monomorphsAlreadyAdded.add(monomorphClassName);
       }
       poolCreationCode += `
-        const ${componentKey}Pool = new ${component.name}.Pool();
+        const ${componentKey}Pool = new ${resolvedMonomorphClass}.Pool();
         const ${componentKey}PoolArray = ${componentKey}Pool.array;
       `;
       poolMapCreationCode += `
         ${componentKey}: ${componentKey}Pool,
       `;
-      addComponentFunctionsCode += `
-        (data, entity) => {
-          const instance = ${component.name}.create(data, ${componentKey}Pool);
-          ${componentKey}ComponentToEntity[instance.index] = entity;
-          return instance;
-        },
-      `;
-      removeComponentFunctionsCode += `
-        instance => {
-          ${componentKey}ComponentToEntity[instance.index] = null;
-          instance.destroy();
-        },
-      `;
-      destroyCode += `
-        if ((this.componentFlags & ${componentFlagValue}n) !== 0n) {
-          this.removeComponent('${componentKey}', updateQueryMemberships);
-        }
-      `;
       componentToEntityCode += `
         const ${componentKey}ComponentToEntity = [null];
         ${componentKey}ComponentToEntity.pop();
       `;
-      componentIteratorFunctionsCode += `
+      componentWithEntityIteratorFunctionsCode += `
         ${componentKey}: {
           [Symbol.iterator]() {
             const resultArray = [null, null];
@@ -113,12 +214,60 @@ function getEntityClassCode(componentMap, queries, debug) {
           }
         },
       `;
+      addComponentFunctionsCode += `
+        (data, entity, componentKey, updateQueryMemberships) => {
+          entity.componentFlags |= ${componentFlagValue}n;
+          entity.${componentKey} = ${resolvedMonomorphClass}.create(${processedDataCode}, ${componentKey}Pool);
+          ${componentKey}ComponentToEntity[entity.${componentKey}.index] = entity;
+
+          ${afterComponentAddedCode}
+
+          if (updateQueryMemberships) {
+            entity.updateQueryMemberships();
+          }
+        },
+      `;
+      removeComponentFunctionsCode += `
+        (instance, entity, componentKey, updateQueryMemberships) => {
+          const newFlagValue = entity.componentFlags & ~${componentFlagValue}n;
+          if (updateQueryMemberships) {
+            entity.updateQueryMemberships(newFlagValue);
+          }
+
+          ${beforeComponentRemovedCode}
+
+          ${componentKey}ComponentToEntity[instance.index] = null;
+          instance.destroy();
+
+          entity.componentFlags = newFlagValue;
+          ${nullComponentCode};
+        },
+      `;
     } else {
       addComponentFunctionsCode += `
-        null,
+        (data, entity, componentKey, updateQueryMemberships) => {
+          entity.componentFlags |= ${componentFlagValue}n;
+          entity.${componentKey} = ${processedDataCode};
+
+          ${afterComponentAddedCode}
+
+          if (updateQueryMemberships) {
+            entity.updateQueryMemberships();
+          }
+        },
       `;
       removeComponentFunctionsCode += `
-        null,
+        (currentComponentValue, entity, componentKey, updateQueryMemberships) => {
+          const newFlagValue = entity.componentFlags & ~${componentFlagValue}n;
+          if (updateQueryMemberships) {
+            entity.updateQueryMemberships(newFlagValue);
+          }
+
+          ${beforeComponentRemovedCode}
+
+          entity.componentFlags = newFlagValue;
+          ${nullComponentCode};
+        },
       `;
     }
     componentFlagValue <<= 1n;
@@ -173,13 +322,10 @@ function getEntityClassCode(componentMap, queries, debug) {
     updateQueryMembershipsCode += `
       if (
         this.queryIndices[${queryIndex}] === -1
-        && (this.componentFlags & ${queryWithFlag}n) === ${queryWithFlag}n
-        && (this.componentFlags & ~${queryWithoutFlag}n) === this.componentFlags
+        && (thisComponentFlags & ${queryWithFlag}n) === ${queryWithFlag}n
+        && (thisComponentFlags & ~${queryWithoutFlag}n) === thisComponentFlags
       ) {
-        ${!debug ? "" : `
-          console.log('adding entity to query "${queryName}"', this);
-        `}
-        this.componentFlags |= ${queryWithFlag}n;
+        // thisComponentFlags |= ${queryWithFlag}n;
         if (queryEntityFreeIndices${queryIndex}.length > 0) {
           const index = queryEntityFreeIndices${queryIndex}.pop();
           this.queryIndices[${queryIndex}] = index;
@@ -191,28 +337,19 @@ function getEntityClassCode(componentMap, queries, debug) {
 
         afterEntityAdded${queryIndex}(this);
 
-        ${!debug ? "" : `
+        ${!options?.logQueries ? "" : `
           console.log('added entity to query "${queryName}"', this);
         `}
       } else if (
         this.queryIndices[${queryIndex}] !== -1
         && (
-          (this.componentFlags & ${queryWithFlag}n) !== ${queryWithFlag}n
-          || (this.componentFlags & ~${queryWithoutFlag}n) !== this.componentFlags
+          (thisComponentFlags & ${queryWithFlag}n) !== ${queryWithFlag}n
+          || (thisComponentFlags & ~${queryWithoutFlag}n) !== thisComponentFlags
         )
       ) {
 
         if (queryEntityRemovedListeners${queryIndex}.length > 0) {
-          if (componentFlagThatWasRemoved !== undefined) {
-            // before calling the listeners, toggle the components that were removed, if any
-            // this is so that in the listener, the entity's hasComponent() calls correctly
-            // show that the component is still there, since the removal hasn't happened yet
-            this.componentFlags &= ~componentFlagThatWasRemoved;
-            beforeEntityRemoved${queryIndex}(this);
-            this.componentFlags &= ~componentFlagThatWasRemoved;
-          } else {
-            beforeEntityRemoved${queryIndex}(this);
-          }
+          beforeEntityRemoved${queryIndex}(this);
         }
 
         const index = this.queryIndices[${queryIndex}];
@@ -220,7 +357,7 @@ function getEntityClassCode(componentMap, queries, debug) {
         queryEntities${queryIndex}[index] = null;
         queryEntityFreeIndices${queryIndex}.push(index);
 
-        ${!debug ? "" : `
+        ${!options?.logQueries ? "" : `
           console.log('removed entity from query "${queryName}"', this);
         `}
       }
@@ -298,9 +435,10 @@ function getEntityClassCode(componentMap, queries, debug) {
     ${poolCreationCode}
     ${poolMapCreationCode}
     ${componentToEntityCode}
-    const componentIndices = {
+    ${referenceComponentFunctionsCode}
+    const componentIndices = new Map([
       ${componentIndicesCode}
-    };
+    ]);
     const addComponentFunctions = [
       ${addComponentFunctionsCode}
     ];
@@ -445,41 +583,36 @@ function getEntityClassCode(componentMap, queries, debug) {
       }
 
       addComponent(key, data, updateQueryMemberships = true) {
-        const componentIndex = componentIndices[key];
-        const fn = addComponentFunctions[componentIndex];
-        this[key] = fn ? fn(data, this) : data;
+        ${options?.skipSafetyChecks ? "" : `
+        if ((this.componentFlags & componentFlags[componentIndices.get(key)]) !== 0n) {
+          console.error('this entity:', this);
+          throw new Error('DEV-only check: Tried to add component "'+key+'" that this entity already has');
+        }
+        `}
 
-        this.componentFlags |= componentFlags[componentIndex];
+        (addComponentFunctions[componentIndices.get(key)])(data, this, key, updateQueryMemberships);
 
-        if (updateQueryMemberships) {
-          this.updateQueryMemberships();
-        }
+        ${!options?.logComponents ? "" : `
+          console.log('added component "'+key+'" to entity, updateQueryMemberships = ', updateQueryMemberships, 'entity = ', this);
+        `}
       }
 
       removeComponent(key, updateQueryMemberships = true) {
-        const componentIndex = componentIndices[key];
-        const componentFlag = componentFlags[componentIndex];
-        ${!debug ? "" : `
+        const componentIndex = componentIndices.get(key);
+        ${options?.skipSafetyChecks ? "" : `
         if ((this.componentFlags & componentFlags[componentIndex]) === 0n) {
           console.error('this entity:', this);
           throw new Error('DEV-only check: Tried to remove component "'+key+'" that this entity does not have');
         }
         `}
-        this.componentFlags &= ~componentFlag;
-
-        if (updateQueryMemberships) {
-          this.updateQueryMemberships(componentFlag);
-        }
-
-        const fn = removeComponentFunctions[componentIndex];
-        if (fn) {
-          fn(this[key], this, key);
-        }
-
-        this[key] = null;
+        (removeComponentFunctions[componentIndex])(this[key], this, key, updateQueryMemberships);
+        ${!options?.logComponents ? "" : `
+          console.log('removed component "'+key+'" from entity', this);
+        `}
       }
 
       destroy(updateQueryMemberships = true) {
+        const thisComponentFlags = this.componentFlags;
         ${destroyCode}
         if (this.version & 1 === 1) {
           ${""}
@@ -493,10 +626,10 @@ function getEntityClassCode(componentMap, queries, debug) {
       }
 
       hasComponent(key) {
-        return (this.componentFlags & componentFlags[componentIndices[key]]) !== 0n;
+        return (this.componentFlags & componentFlags[componentIndices.get(key)]) !== 0n;
       }
 
-      updateQueryMemberships(componentFlagThatWasRemoved) {
+      updateQueryMemberships(thisComponentFlags = this.componentFlags) {
         ${updateQueryMembershipsCode}
       }
 
@@ -813,9 +946,10 @@ function getEntityClassCode(componentMap, queries, debug) {
 
     theClass.queries = queries;
     theClass.componentToEntity = componentToEntity;
+    theClass.componentIndices = componentIndices;
     theClass.components = componentPools;
     theClass.componentsWithEntities = {
-      ${componentIteratorFunctionsCode}
+      ${componentWithEntityIteratorFunctionsCode}
     };
 
     theClass.create = function(data, updateQueryMemberships = true) {
@@ -835,17 +969,30 @@ function getEntityClassCode(componentMap, queries, debug) {
       }
     }
 
+    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 (debug) {
+  if (options?.logCode) {
     console.log("code", code);
   }
   return code;
 }
-function createEntityClass(debug) {
-  return (componentMap, queries) => new Function("componentMap", "queryMap", getEntityClassCode(componentMap, queries, debug))(componentMap, queries);
+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.1.0",
-  "description": "MECS - Monomorph ECS - A high-performance Entity Component System for TypeScript and JavaScript, designed for games and simulations.",
+  "version": "0.3.0",
+  "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",
@@ -26,11 +27,17 @@
     "test": "vitest",
     "bench": "vitest bench"
   },
-  "dependencies": {
-    "monomorph": "^1.2.0"
+  "peerDependencies": {
+    "monomorph": "^1.5.5"
+  },
+  "peerDependenciesMeta": {
+    "monomorph": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^25.0.1",
+    "monomorph": "^1.5.5",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",