@perplexdotgg/mecs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 9547-3732 Québec inc. / perplex.gg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+<div style="display: flex;">
+  <img src="./mecs.svg" width="152" height="64" style="margin-right: 16px;" />
+  <h1>MECS - Monomorph Entity Component System</h1>
+</div>
+
+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).
+
+<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.
+</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
+- 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.
+
+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.
+
+## Usage
+
+### Install into your project
+
+```bash
+npm install @perplexdotgg/mecs
+```
+
+
+### Defining an Entity schema to create your Entity class
+
+The following is Typescript code. The Javascript version is below this.
+
+```ts
+import { createClass } from 'monomorph';
+import { createEntityClass, type QueryMap, type VirtualComponent } 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 {}
+
+// define all the components you want entities to potentially have
+const components = {
+  // defining components when they are monomorph classes:
+  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;
+
+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'],
+
+    // listeners can added now, or later (see the Queries docs below)
+    afterEntityAdded: (entity) => {
+      // this is called when an entity newly matches this query
+    },
+    beforeEntityRemoved: (entity) => {
+      // this is called when an entity no longer matches this query,
+      // just before a relevant component is removed from the entity
+    },
+  },
+  query2: {
+    with: ['localTransform', 'globalTransform'],
+    without: [],
+  },
+} as const satisfies QueryMap<Entity, typeof components>;
+
+let debugLogging: boolean | undefined = false;
+
+// 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) {
+
+  // most methods will likely exist on your components directly,
+  // but you can also extend the generated entity class
+  myEntityMethod() {
+    // your code here! use 'this' like you would expect
+    if (this.hasComponent('example')) {
+      this.example.whatever = 5;
+    }
+  }
+}
+```
+
+<details>
+  <summary>Javascript version</summary>
+
+```js
+import { createClass } from 'monomorph';
+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(projectileProps) {}
+class Transform extends createClass(transformProps) {}
+
+// and some non-monomorph class
+class MyClass {}
+
+// define all the components you want entities to potentially have
+const components = {
+  // defining components when they are monomorph classes:
+  localTransform: Transform,
+  globalTransform: Transform,
+  Projectile, // this is shorthand for: projectile: Projectile
+
+  // 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,
+};
+
+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'],
+
+    // listeners can added now, or later (see the Queries docs below)
+    afterEntityAdded: (entity) => {
+      // this is called when an entity newly matches this query
+    },
+    beforeEntityRemoved: (entity) => {
+      // this is called when an entity no longer matches this query,
+      // just before a relevant component is removed from the entity
+    },
+  },
+  query2: {
+    with: ['localTransform', 'globalTransform'],
+    without: [],
+  },
+};
+
+let debugLogging = false;
+
+// 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) {
+
+  // most methods will likely exist on your components directly,
+  // but you can also extend the generated entity class
+  myEntityMethod() {
+    // your code here! use 'this' like you would expect
+    if (this.hasComponent('example')) {
+      this.example.whatever = 5;
+    }
+  }
+}
+```
+</details>
+
+### Creating and destroying entities
+Like monomorph's create method, entities accept the same object representations as inputs for each component. All components instances will be created automatically as needed
+
+```ts
+const entity1 = Entity.create({
+  localTransform: {
+    position: { x: 0, y: 0, z: 0, },
+    orientation: { x: 0, y: 0, z: 0, w: 1 },
+    scale: 1,
+  },
+  projectile: {
+    speed: 4,
+    direction: { x: 1, y: 0, z: 0 },
+  },
+});
+
+// now entity1 is of the Entity class, and entity1.localTransform is of the Transform class
+// so you can call methods on it like so:
+entity1.localTransform.composeMatrix();
+
+const entity2 = Entity.create({
+  projectile: {
+    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
+// 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
+entity2.destroy();
+
+// 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
+```
+
+### Accessing components and methods
+```js
+// calling component methods
+entity1.projectile.checkCollisions();
+
+// calling entity methods
+entity1.myEntityMethod();
+
+entity1.addComponent('globalTransform', {
+  position: { x: 1, y: 2, z: 3, },
+  orientation: { x: 0, y: 0, z: 0, w: 1 },
+  scale: 1,
+});
+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
+
+// 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')) { /* */ }
+
+```
+
+### Iterating on entities and components
+```ts
+// all entities
+for (const entity of Entity.pool) {
+
+}
+
+// only for monomorph-class components, iterating all instances of a component
+for (const transform of Entity.components.localTransform) {
+
+}
+
+// only for monomorph-class components, iterating all instances of a component,
+// along with the entity for each
+for (const [transform, entity] of Entity.componentsWithEntities.localTransform) {
+
+}
+```
+
+### Iterating on queries, and adding/removing listeners
+For defining queries, see the [entity schema definition section](#defining-an-entity-schema-to-create-your-entity-class) above
+```ts
+// all entities matching a query
+for (const entity of Entity.queries.projectiles) {
+
+}
+
+// in addition to being able to define `afterEntityAdded` and `beforeEntityRemoved` functions in
+// the schema, you can dynamically add a new listener for entities matching a query,
+// useful if you want to put this logic in your system code for example
+function afterProjectileExists(entity) {
+  // do whatever
+}
+
+Entity.queries.projectiles.afterEntityAdded.addListener(afterProjectileExists);
+// you can also remove listeners
+Entity.queries.projectiles.afterEntityAdded.removeListener(afterProjectileExists);
+
+Entity.queries.projectiles.beforeEntityRemoved.addListener(someListener);
+Entity.queries.projectiles.beforeEntityRemoved.removeListener(someListener);
+
+```
+
+## 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)
+- Want to see something here? Please create an [issue on codeberg](https://codeberg.org/perplexdotgg/mecs/issues)
+
+## 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!

package/build/index.d.ts

@@ -0,0 +1,131 @@
+import { InputType } from 'monomorph';
+import { MonomorphClass } from 'monomorph';
+import { MonomorphInstance } from 'monomorph';
+import { PartialRecursive } 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 ComponentMap = Record<string, 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];
+};
+
+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 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>> {
+    componentMap: CM;
+    addComponent: <CCK extends LowercaseFirstLetter<keyof CM>, CC extends CM[OriginalComponentKey<CCK, CM>] = CM[OriginalComponentKey<CCK, CM>]>(key: CCK, data: ComponentInput<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 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> {
+    new (data: I): E;
+    componentMap: CM;
+    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]>;
+        };
+    };
+    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]>>>;
+        };
+    };
+    queries: {
+        [K in keyof QM]: {
+            afterEntityAdded: {
+                addListener(listener: (entity: E) => void): void;
+                removeListener(listener: (entity: E) => void): void;
+            };
+            beforeEntityRemoved: {
+                addListener(listener: (entity: E) => void): void;
+                removeListener(listener: (entity: E) => void): void;
+            };
+            [Symbol.iterator](): IterableIterator<WithComponent<E, ElementOfArray<QM[K]['with']> extends LowercaseFirstLetter<keyof E["componentMap"]> ? ElementOfArray<QM[K]['with']> : never>>;
+        };
+    };
+}
+
+export declare type EntityInput<CM extends ComponentMap> = Partial<{
+    [K in keyof CM as LowercaseFirstLetter<K>]: ComponentInput<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 EntityInstanceWithPool<CM extends ComponentMap, I extends EntityInput<CM>, E> = NoInfer<E & {
+    pool: EntityPoolClass<E> | null;
+    createInPool(data?: I): EntityInstanceWithPool<CM, I, E>;
+}>;
+
+export declare interface EntityPoolClass<M> {
+    /**
+     * create a new instance of this monomorph's pool
+     * @param maxLength the maximum length of this pool, if not specified, it will be Infinity
+     */
+    new (maxLength?: number): EntityPoolClass<M>;
+    array: M[];
+    /**
+     * indices that are free to use, these are ones that have specifically been instantiated, initially this is empty
+     */
+    freeIndices: number[];
+    /**
+     * a limit for how big this pool is allowed to get, an error
+     * is thrown when creating an instance when this limit is reached
+     */
+    maxLength: number;
+    /** 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;
+}
+
+export declare function getEntityClassCode<C, CM extends ComponentMap>(componentMap: CM, queries?: QueryMap<C, CM>, debug?: boolean): string;
+
+declare type LowercaseFirstLetter<S> = S extends `${infer FirstLetter}${infer Rest}` ? `${Lowercase<FirstLetter>}${Rest}` : S;
+
+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> = {
+    with?: LowercaseFirstLetter<keyof CM>[];
+    without?: LowercaseFirstLetter<keyof CM>[];
+    afterEntityAdded?: (entity: C) => void;
+    beforeEntityRemoved?: (entity: C) => void;
+};
+
+export declare type QueryMap<C, CM extends ComponentMap> = Record<string, QueryConfig<C, CM>>;
+
+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> & {
+    [K in KCM as LowercaseFirstLetter<K>]-?: Exclude<C[K extends keyof C ? K : never], undefined | null>;
+}>;
+
+declare type Writeable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+export { }

package/build/mecs.js

@@ -0,0 +1,851 @@
+function lowercaseFirstLetter(str) {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+function isMonomorphClass(x) {
+  return typeof x === "function" && "serializedSize" in x;
+}
+function getEntityClassCode(componentMap, queries, debug) {
+  let monomorphReferenceCode = "";
+  let poolCreationCode = "";
+  let poolMapCreationCode = "const componentPools = {\n";
+  let componentToEntityCode = "";
+  let componentIndicesCode = "";
+  let addComponentFunctionsCode = "";
+  let removeComponentFunctionsCode = "";
+  let componentFlagsCode = "";
+  let createFromDataCode = "";
+  let createFromDataCodeAllNulls = "";
+  let destroyCode = "";
+  let componentIteratorFunctionsCode = "";
+  const componentFlags = [];
+  const componentIndices = {};
+  const monomorphsAlreadyAdded = /* @__PURE__ */ new Set();
+  let componentIndex = 0;
+  let componentFlagValue = 1n;
+  for (const [key, component] of Object.entries(componentMap)) {
+    const componentKey = lowercaseFirstLetter(key);
+    const isMonomorph = isMonomorphClass(component);
+    componentIndices[componentKey] = componentIndex;
+    componentIndicesCode += `
+      ${componentKey}: ${componentIndex},
+    `;
+    componentFlags.push(componentFlagValue);
+    componentFlagsCode += `${componentFlagValue}n, `;
+    createFromDataCode += `
+      if ('${componentKey}' in data) {
+        this.addComponent('${componentKey}', data.${componentKey}, false);
+      } else {
+        this.${componentKey} = null;
+      }
+    `;
+    createFromDataCodeAllNulls += `
+      this.${componentKey} = null;
+    `;
+    if (isMonomorph) {
+      if (!monomorphsAlreadyAdded.has(component.name)) {
+        monomorphReferenceCode += `
+          const ${component.name} = componentMap.${key};
+        `;
+        monomorphsAlreadyAdded.add(component.name);
+      }
+      poolCreationCode += `
+        const ${componentKey}Pool = new ${component.name}.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 += `
+        ${componentKey}: {
+          [Symbol.iterator]() {
+            const resultArray = [null, null];
+            let index = 0;
+            let nonEmpty = 0;
+            const iteratorResult = {
+              done: false,
+              value: null,
+            };
+
+            return {
+              next() {
+                ${""}
+                while (index < (${componentKey}Pool.length + ${componentKey}Pool.freeIndices.length) && (!${componentKey}PoolArray[index] || (${componentKey}PoolArray[index].version & 1) === 1)) {
+                  index++;
+                }
+
+                if (nonEmpty >= ${componentKey}Pool.length) {
+                  iteratorResult.done = true;
+                  iteratorResult.value = null;
+                  return iteratorResult;
+                }
+
+                resultArray[0] = ${componentKey}PoolArray[index];
+                resultArray[1] = ${componentKey}ComponentToEntity[index];
+                index++;
+                nonEmpty++;
+                iteratorResult.done = false;
+                iteratorResult.value = resultArray;
+                return iteratorResult;
+              }
+            };
+          }
+        },
+      `;
+    } else {
+      addComponentFunctionsCode += `
+        null,
+      `;
+      removeComponentFunctionsCode += `
+        null,
+      `;
+    }
+    componentFlagValue <<= 1n;
+    componentIndex++;
+  }
+  poolMapCreationCode += "\n};\n";
+  let queryWithFlag;
+  let queryWithoutFlag;
+  let queryIndex = 0;
+  let queryListenerCode = "";
+  let updateQueryMembershipsCode = "";
+  let createQueryEntityArraysCode = "";
+  let queriesObjectCode = "";
+  let queryCallbackReferencesCode = "";
+  for (const [queryName, queryConfig] of Object.entries(queries ?? {})) {
+    queryWithFlag = 0n;
+    for (const withComponent of queryConfig.with ?? []) {
+      if (withComponent in componentIndices) {
+        queryWithFlag |= componentFlags[componentIndices[withComponent]];
+      } else {
+        throw new Error(`Query "${queryName}" references non-existent component "${String(withComponent)}" in "with" array`);
+      }
+    }
+    queryWithoutFlag = 0n;
+    for (const withoutComponent of queryConfig.without ?? []) {
+      if (withoutComponent in componentIndices) {
+        queryWithoutFlag |= componentFlags[componentIndices[withoutComponent]];
+      } else {
+        throw new Error(`Query "${queryName}" references non-existent component "${String(withoutComponent)}" in "without" array`);
+      }
+    }
+    queryListenerCode += `
+      const queryEntityAddedListeners${queryIndex} = [
+        ${queryConfig.afterEntityAdded ? "queryMap." + queryName + ".afterEntityAdded" : ""}
+      ];
+      const queryEntityRemovedListeners${queryIndex} = [
+        ${queryConfig.beforeEntityRemoved ? "queryMap." + queryName + ".beforeEntityRemoved" : ""}
+      ];
+
+      function afterEntityAdded${queryIndex} (entity) {
+        for (const listener of queryEntityAddedListeners${queryIndex}) {
+          listener(entity);
+        }
+      }
+
+      function beforeEntityRemoved${queryIndex} (entity) {
+        for (const listener of queryEntityRemovedListeners${queryIndex}) {
+          listener(entity);
+        }
+      }
+    `;
+    updateQueryMembershipsCode += `
+      if (
+        this.queryIndices[${queryIndex}] === -1
+        && (this.componentFlags & ${queryWithFlag}n) === ${queryWithFlag}n
+        && (this.componentFlags & ~${queryWithoutFlag}n) === this.componentFlags
+      ) {
+        ${!debug ? "" : `
+          console.log('adding entity to query "${queryName}"', this);
+        `}
+        this.componentFlags |= ${queryWithFlag}n;
+        if (queryEntityFreeIndices${queryIndex}.length > 0) {
+          const index = queryEntityFreeIndices${queryIndex}.pop();
+          this.queryIndices[${queryIndex}] = index;
+          queryEntities${queryIndex}[index] = this;
+        } else {
+          this.queryIndices[${queryIndex}] = queryEntities${queryIndex}.length;
+          queryEntities${queryIndex}.push(this);
+        }
+
+        afterEntityAdded${queryIndex}(this);
+
+        ${!debug ? "" : `
+          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
+        )
+      ) {
+
+        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);
+          }
+        }
+
+        const index = this.queryIndices[${queryIndex}];
+        this.queryIndices[${queryIndex}] = -1;
+        queryEntities${queryIndex}[index] = null;
+        queryEntityFreeIndices${queryIndex}.push(index);
+
+        ${!debug ? "" : `
+          console.log('removed entity from query "${queryName}"', this);
+        `}
+      }
+    `;
+    createQueryEntityArraysCode += `
+      const queryEntities${queryIndex} = [null];
+      queryEntities${queryIndex}.pop();
+      const queryEntityFreeIndices${queryIndex} = [0];
+      queryEntityFreeIndices${queryIndex}.pop();
+    `;
+    queriesObjectCode += `
+      ${queryName}: {
+        array: queryEntities${queryIndex},
+        afterEntityAdded: {
+          fn: afterEntityAdded${queryIndex},
+          addListener(listener) {
+            queryEntityAddedListeners${queryIndex}.push(listener);
+          },
+          removeListener(listener) {
+            const index = queryEntityAddedListeners${queryIndex}.indexOf(listener);
+            if (index !== -1) {
+              queryEntityAddedListeners${queryIndex}.splice(index, 1);
+            }
+          },
+          listeners: queryEntityAddedListeners${queryIndex},
+        },
+        beforeEntityRemoved: {
+          fn: beforeEntityRemoved${queryIndex},
+          addListener(listener) {
+            queryEntityRemovedListeners${queryIndex}.push(listener);
+          },
+          removeListener(listener) {
+            const index = queryEntityRemovedListeners${queryIndex}.indexOf(listener);
+            if (index !== -1) {
+              queryEntityRemovedListeners${queryIndex}.splice(index, 1);
+            }
+          },
+          listeners: queryEntityRemovedListeners${queryIndex},
+        },
+        [Symbol.iterator]() {
+          let index = 0;
+          let entity = null;
+          const iteratorResult = {
+            done: false,
+            value: null,
+          };
+
+          return {
+            next() {
+              // we need to skip nulls, nulls are used to maintain the order of the array during the frame, otherwise if we
+              // use swap/replace we may miss an entity that got swapped to an index before the one we're iterating over
+
+              while (index < queryEntities${queryIndex}.length) {
+                entity = queryEntities${queryIndex}[index];
+                index++;
+                if (entity !== null) {
+                  iteratorResult.done = false;
+                  iteratorResult.value = entity;
+                  return iteratorResult;
+                }
+              }
+
+              iteratorResult.done = true;
+              iteratorResult.value = null;
+              return iteratorResult;
+            },
+          };
+        },
+      },
+    `;
+    queryIndex++;
+  }
+  const code = `
+    ${monomorphReferenceCode}
+    ${poolCreationCode}
+    ${poolMapCreationCode}
+    ${componentToEntityCode}
+    const componentIndices = {
+      ${componentIndicesCode}
+    };
+    const addComponentFunctions = [
+      ${addComponentFunctionsCode}
+    ];
+    const removeComponentFunctions = [
+      ${removeComponentFunctionsCode}
+    ];
+    const componentFlags = [ ${componentFlagsCode} ];
+
+    ${createQueryEntityArraysCode}
+
+    ${queryListenerCode}
+
+    const queries = {
+      ${queriesObjectCode}
+    };
+
+    const componentToEntity = new Array(${componentIndex});
+    for (let i = 0; i < ${componentIndex}; i++) {
+      componentToEntity[i] = [null];
+      componentToEntity[i].pop();
+    }
+
+    ${queryCallbackReferencesCode}
+
+    function iterateOverPool(pool) {
+      let index = 0;
+      let nonEmpty = 0;
+      const array = pool.array;
+      const maxLength = pool.maxLength;
+      const iteratorResult = {
+        done: false,
+        value: null,
+      };
+
+      return {
+        next() {
+          ${""}
+          while (index < (pool.length + pool.freeIndices.length) && (!array[index] || (array[index].version & 1) === 1)) {
+            index++;
+          }
+
+          ${""}
+          if (index >= maxLength || nonEmpty >= pool.length) {
+            iteratorResult.done = true;
+            iteratorResult.value = null;
+            return iteratorResult;
+          }
+
+          const value = array[index];
+          index++;
+          nonEmpty++;
+          iteratorResult.done = false;
+          iteratorResult.value = value;
+          return iteratorResult;
+        }
+      };
+    }
+
+    function iterateOverReferenceList(referenceList, fixDestroyed = true) {
+      let index = 0;
+      const poolArray = referenceList.pool.array;
+      const arrayOfIndices = referenceList.arrayOfIndices;
+      const arrayOfVersions = referenceList.arrayOfVersions;
+      const array = referenceList.array;
+      const maxLength = referenceList.maxLength;
+      const iteratorResult = {
+        done: false,
+        value: null,
+      };
+      let poolItem;
+
+      return {
+        next() {
+          if (!arrayOfIndices.length || index >= arrayOfIndices.length) {
+            iteratorResult.done = true;
+            iteratorResult.value = null;
+            return iteratorResult;
+          }
+
+          poolItem = poolArray[arrayOfIndices[index]];
+
+          ${""}
+          while (index < arrayOfIndices.length && (((poolItem.version & 1) === 1) || poolItem.version !== arrayOfVersions[index])) {
+            if (fixDestroyed) {
+              if (index < arrayOfIndices.length - 1) {
+                arrayOfIndices[index] = arrayOfIndices[arrayOfIndices.length - 1];
+                arrayOfVersions[index] = arrayOfVersions[arrayOfVersions.length - 1];
+                poolItem = poolArray[arrayOfIndices[index]];
+              }
+
+              referenceList.length -= 1;
+            } else {
+              index++;
+              if (index < arrayOfIndices.length) {
+                poolItem = poolArray[arrayOfIndices[index]];
+              }
+            }
+          }
+
+          if (index >= arrayOfIndices.length) {
+            iteratorResult.done = true;
+            iteratorResult.value = null;
+            return iteratorResult;
+          }
+
+          index++;
+          iteratorResult.done = false;
+          iteratorResult.value = poolItem;
+          return iteratorResult;
+        }
+      };
+    }
+
+    const theClass = class {
+      constructor(data, index = 0, updateQueryMemberships = true) {
+        this.index = index;
+        this.version = 0; ${""}
+        this.pool = this.constructor.pool;
+        this.queryIndices = new Array(${queryIndex}).fill(-1);
+        this.componentFlags = 0n; ${""}
+        if (data) {
+          ${createFromDataCode}
+        } else {
+          ${createFromDataCodeAllNulls}
+        }
+        if (updateQueryMemberships) {
+          this.updateQueryMemberships();
+        }
+      }
+
+      fullSet(data, updateQueryMemberships = true) {
+        this.queryIndices.fill(-1);
+        this.componentFlags = 0n;
+        if (data) {
+          ${createFromDataCode}
+        } else {
+          ${createFromDataCodeAllNulls}
+        }
+        if (updateQueryMemberships) {
+          this.updateQueryMemberships();
+        }
+      }
+
+      addComponent(key, data, updateQueryMemberships = true) {
+        const componentIndex = componentIndices[key];
+        const fn = addComponentFunctions[componentIndex];
+        this[key] = fn ? fn(data, this) : data;
+
+        this.componentFlags |= componentFlags[componentIndex];
+
+        if (updateQueryMemberships) {
+          this.updateQueryMemberships();
+        }
+      }
+
+      removeComponent(key, updateQueryMemberships = true) {
+        const componentIndex = componentIndices[key];
+        const componentFlag = componentFlags[componentIndex];
+        ${!debug ? "" : `
+        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;
+      }
+
+      destroy(updateQueryMemberships = true) {
+        ${destroyCode}
+        if (this.version & 1 === 1) {
+          ${""}
+          return;
+        }
+        this.version++; // becomes odd, meaning deleted
+        if (this.pool) {
+          this.pool.length--;
+          this.pool.freeIndices.push(this.index);
+        }
+      }
+
+      hasComponent(key) {
+        return (this.componentFlags & componentFlags[componentIndices[key]]) !== 0n;
+      }
+
+      updateQueryMemberships(componentFlagThatWasRemoved) {
+        ${updateQueryMembershipsCode}
+      }
+
+      static get ReferenceList() {
+        if (!this.DynamicReferenceListClass) {
+          const currentClass = this;
+          this.DynamicReferenceListClass = class {
+            constructor(pool, maxLength = Infinity, data = undefined, classConstructor = currentClass) {
+              this.pool = pool;
+              this.maxLength = maxLength;
+              this.arrayOfIndices = [];
+              this.arrayOfVersions = [];
+              this.classConstructor = classConstructor;
+
+              if (data?.length) {
+                for (const item of data) {
+                  this.create(item);
+                }
+              }
+            }
+
+            get length() {
+              return this.arrayOfIndices.length;
+            }
+
+            set length(v) {
+              this.arrayOfIndices.length = v;
+              this.arrayOfVersions.length = v;
+            }
+
+            push(instance) {
+              if (this.length >= this.maxLength) {
+                throw new Error("Could not add instance to reference list, reference list maxLength of "+this.maxLength+" has been reached");
+              }
+              if (instance.pool !== this.pool) {
+                throw new Error("Could not add instance to reference list, instance does not belong to the same pool as the reference list");
+              }
+              const length = this.length;
+              this.arrayOfIndices[length] = instance.index;
+              this.arrayOfVersions[length] = instance.version;
+              return length;
+            }
+
+            getAtIndex(index, fixDestroyed = true) {
+              if (index < 0 || index >= this.arrayOfIndices.length) {
+                return null;
+              }
+              let poolItem = this.pool.array[this.arrayOfIndices[index]];
+
+              if (fixDestroyed) {
+                while (index < this.arrayOfIndices.length && ((poolItem.version & 1) === 1 || poolItem.version !== this.arrayOfVersions[index])) {
+                  if (index < this.arrayOfIndices.length - 1) {
+                    this.arrayOfIndices[index] = this.arrayOfIndices[this.arrayOfIndices.length - 1];
+                    this.arrayOfVersions[index] = this.arrayOfVersions[this.arrayOfVersions.length - 1];
+                  }
+
+                  this.length -= 1;
+
+                  if (index < this.arrayOfIndices.length) {
+                    poolItem = this.pool.array[this.arrayOfIndices[index]];
+                  } else {
+                    return null;
+                  }
+                }
+              } else if ((poolItem.version & 1) === 1 || poolItem.version !== this.arrayOfVersions[index]) {
+                return null;
+              }
+
+              return poolItem;
+            }
+
+            remove(instance) {
+              for (let i = 0; i < this.arrayOfIndices.length; i++) {
+                if (this.arrayOfIndices[i] === instance.index && this.arrayOfVersions[i] === instance.version) {
+                  if (i < this.arrayOfIndices.length - 1) {
+                    this.arrayOfIndices[i] = this.arrayOfIndices[this.arrayOfIndices.length - 1];
+                    this.arrayOfVersions[i] = this.arrayOfVersions[this.arrayOfVersions.length - 1];
+                  }
+                  this.length -= 1;
+                  return i;
+                }
+              }
+              return -1;
+            }
+
+            removeIndex(index) {
+              if (index < 0 || index >= this.arrayOfIndices.length) {
+                return false;
+              }
+              if (index < this.arrayOfIndices.length - 1) {
+                this.arrayOfIndices[index] = this.arrayOfIndices[this.arrayOfIndices.length - 1];
+                this.arrayOfVersions[index] = this.arrayOfVersions[this.arrayOfVersions.length - 1];
+              }
+              this.length -= 1;
+              return true;
+            }
+
+            clear() {
+              this.length = 0;
+            }
+
+            create(data) {
+              const instance = this.classConstructor.create(data, this.pool);
+              const length = this.length;
+              this.arrayOfIndices[length] = instance.index;
+              this.arrayOfVersions[length] = instance.version;
+              return instance;
+            }
+
+            [Symbol.iterator]() {
+              return iterateOverReferenceList(this, true);
+            }
+
+            get iterateIgnoreEmpty() {
+              const self = this;
+              return {
+                [Symbol.iterator]() {
+                  return iterateOverReferenceList(self, false);
+                }
+              };
+            }
+          }
+        }
+
+        return this.DynamicReferenceListClass;
+      }
+
+      static get pool() {
+        if (!this.dynamicPoolInstance) {
+          this.dynamicPoolInstance = new this.Pool();
+        }
+        return this.dynamicPoolInstance;
+      }
+
+      static get Pool() {
+        if (!this.DynamicPoolClass) {
+          const currentClass = this;
+          this.DynamicPoolClass = class {
+            constructor(length = Infinity, classConstructor = currentClass) {
+              this.length = 0;
+              this.maxLength = length;
+              this.array = new Array(isFinite(length) ? length : undefined);
+              this.freeIndices = [1];
+              this.freeIndices.pop();
+              this.classConstructor = classConstructor;
+            }
+
+            [Symbol.iterator]() {
+              return iterateOverPool(this);
+            }
+
+            create(data, updateQueryMemberships = true) {
+              return this.classConstructor.create(data, this, updateQueryMemberships);
+            }
+
+            toArray(array, startOffset = 0, skipPoolReferences = false) {
+              let offset = startOffset;
+
+              if (this.maxLength > 0 && isFinite(this.length)) {
+                array[offset++] = isFinite(this.maxLength) ? this.maxLength : -1;
+                array[offset++] = this.length + this.freeIndices.length;
+              }
+
+              array[offset++] = this.freeIndices.length;
+              for (let i = 0; i < this.freeIndices.length; i++) {
+                array[offset++] = this.freeIndices[i];
+              }
+
+              ${""}
+
+              for (let i = 0; i < this.length + this.freeIndices.length; i++) {
+                const instance = this.array[i];
+                if (instance === undefined) {
+                  array[offset++] = -1;
+                  continue;
+                }
+                array[offset++] = instance.version;
+                if (instance.version & 1) {${""}
+                  continue;
+                }
+                offset = instance.toArray(array, offset, skipPoolReferences);
+              }
+
+              return offset;
+            }
+
+            fromArray(arrayOfData, references, startOffset = 0, classConstructor = this.classConstructor) {
+              let offset = startOffset;
+
+              this.maxLength = arrayOfData[offset++];
+              if (this.maxLength === -1) {
+                this.maxLength = Infinity;
+              }
+              const usedLength = arrayOfData[offset++];
+              this.length = 0;
+
+              const freeIndicesLength = arrayOfData[offset++];
+              this.freeIndices.length = freeIndicesLength;
+              for (let i = 0; i < freeIndicesLength; i++) {
+                this.freeIndices[i] = arrayOfData[offset++];
+              }
+
+
+              for (let i = 0; i < usedLength; i++) {
+                const version = arrayOfData[offset++];
+
+                if (version & 1) {
+                  if (this.array[i]) {
+                    this.array[i].version = version;
+                  }
+                  continue;
+                }
+
+                this.length++;
+
+                if (this.array[i] === undefined) {
+                  this.array[i] = new classConstructor(undefined, i, this);
+                }
+
+                this.array[i].version = version;
+
+                offset = this.array[i].fromArray(arrayOfData, references, offset);
+              }
+
+              return offset;
+            }
+
+            fromArrayNoReferences(arrayOfData, startOffset = 0, classConstructor = this.classConstructor) {
+              let offset = startOffset;
+
+              this.maxLength = arrayOfData[offset++];
+              if (this.maxLength === -1) {
+                this.maxLength = Infinity;
+              }
+              const usedLength = arrayOfData[offset++];
+              this.length = 0;
+
+              const freeIndicesLength = arrayOfData[offset++];
+              this.freeIndices.length = freeIndicesLength;
+              for (let i = 0; i < freeIndicesLength; i++) {
+                this.freeIndices[i] = arrayOfData[offset++];
+              }
+
+              for (let i = 0; i < usedLength; i++) {
+                const version = arrayOfData[offset++];
+
+                if (version & 1) {
+                  if (this.array[i]) {
+                    this.array[i].version = version;
+                  }
+                  continue;
+                }
+
+                this.length++;
+
+                if (this.array[i] === undefined) {
+                  this.array[i] = new classConstructor(undefined, i, this);
+                }
+
+                this.array[i].version = version;
+
+                offset = this.array[i].fromArrayNoReferences(arrayOfData, offset);
+              }
+
+              return offset;
+            }
+
+            fromArrayOnlyReferences(arrayOfData, references, startOffset = 0, classConstructor = this.classConstructor) {
+              let offset = startOffset;
+
+              this.maxLength = arrayOfData[offset++];
+              if (this.maxLength === -1) {
+                this.maxLength = Infinity;
+              }
+              const usedLength = arrayOfData[offset++];
+              this.length = 0;
+
+              const freeIndicesLength = arrayOfData[offset++];
+              this.freeIndices.length = freeIndicesLength;
+              for (let i = 0; i < freeIndicesLength; i++) {
+                this.freeIndices[i] = arrayOfData[offset++];
+              }
+
+              for (let i = 0; i < usedLength; i++) {
+                const version = arrayOfData[offset++];
+
+                if (version & 1) {
+                  if (this.array[i]) {
+                    this.array[i].version = version;
+                  }
+                  continue;
+                }
+
+                this.length++;
+
+                if (this.array[i] === undefined) {
+                  this.array[i] = new classConstructor(undefined, i, this);
+                }
+
+                this.array[i].version = version;
+
+                offset = this.array[i].fromArrayOnlyReferences(arrayOfData, references, offset);
+              }
+
+              return offset;
+            }
+          }
+        }
+
+        return this.DynamicPoolClass;
+      }
+
+    }
+
+    theClass.queries = queries;
+    theClass.componentToEntity = componentToEntity;
+    theClass.components = componentPools;
+    theClass.componentsWithEntities = {
+      ${componentIteratorFunctionsCode}
+    };
+
+    theClass.create = function(data, updateQueryMemberships = true) {
+      const pool = this.pool;
+      if (pool.freeIndices.length) {
+        const index = pool.freeIndices.pop();
+        pool.length++;
+        const instance = pool.array[index];
+        instance.version++; ${""}
+        instance.fullSet(data, updateQueryMemberships);
+        return instance;
+      } else {
+        const instance = new this(data, pool.length, updateQueryMemberships);
+        pool.array[pool.length] = instance;
+        pool.length++;
+        return instance;
+      }
+    }
+
+    return theClass;
+  `;
+  if (debug) {
+    console.log("code", code);
+  }
+  return code;
+}
+function createEntityClass(debug) {
+  return (componentMap, queries) => new Function("componentMap", "queryMap", getEntityClassCode(componentMap, queries, debug))(componentMap, queries);
+}
+export {
+  createEntityClass,
+  getEntityClassCode
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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.",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/perplexdotgg/mecs"
+  },
+  "license": "MIT",
+  "author": "perplex.gg",
+  "type": "module",
+  "main": "build/mecs.js",
+  "types": "build/index.d.ts",
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "build",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "watch": "tsc --watch",
+    "test": "vitest",
+    "bench": "vitest bench"
+  },
+  "dependencies": {
+    "monomorph": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.1",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.7",
+    "vite-plugin-conditional-compiler": "^0.4.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.15"
+  }
+}