@latticexyz/recs 2.0.0-next.1 → 2.0.0-next.11

package/src/Component.spec.ts

@@ -0,0 +1,275 @@
+import {
+  defineComponent,
+  setComponent,
+  removeComponent,
+  getComponentValue,
+  hasComponent,
+  withValue,
+  componentValueEquals,
+  getEntitiesWithValue,
+  overridableComponent,
+} from "./Component";
+import { Type } from "./constants";
+import { createEntity, getEntitySymbol } from "./Entity";
+import { AnyComponent, Entity, World } from "./types";
+import { createWorld } from "./World";
+
+describe("Component", () => {
+  let world: World;
+
+  beforeEach(() => {
+    world = createWorld();
+  });
+
+  it("emit changes to its stream", () => {
+    const entity = createEntity(world);
+    const component = defineComponent(world, { x: Type.Number, y: Type.Number });
+
+    const mock = jest.fn();
+    component.update$.subscribe((update) => {
+      mock(update);
+    });
+
+    setComponent(component, entity, { x: 1, y: 2 });
+    setComponent(component, entity, { x: 7, y: 2 });
+    setComponent(component, entity, { x: 7, y: 2 });
+    removeComponent(component, entity);
+
+    expect(mock).toHaveBeenNthCalledWith(1, { entity, value: [{ x: 1, y: 2 }, undefined], component });
+    expect(mock).toHaveBeenNthCalledWith(2, {
+      entity,
+      component,
+      value: [
+        { x: 7, y: 2 },
+        { x: 1, y: 2 },
+      ],
+    });
+    expect(mock).toHaveBeenNthCalledWith(3, {
+      entity,
+      component,
+      value: [
+        { x: 7, y: 2 },
+        { x: 7, y: 2 },
+      ],
+    });
+    expect(mock).toHaveBeenNthCalledWith(4, { entity, component, value: [undefined, { x: 7, y: 2 }] });
+  });
+
+  describe("defineComponent", () => {
+    it("should register the component in the world", () => {
+      expect(world.components.length).toBe(0);
+      defineComponent(world, { value: Type.Boolean });
+      expect(world.components.length).toBe(1);
+    });
+  });
+
+  describe("setComponent", () => {
+    let component: AnyComponent;
+    let entity: Entity;
+    let value: number;
+
+    beforeEach(() => {
+      component = defineComponent(world, { value: Type.Number });
+      entity = createEntity(world);
+      value = 1;
+      setComponent(component, entity, { value });
+    });
+
+    it("should store the component value", () => {
+      expect(component.values.value.get(getEntitySymbol(entity))).toBe(value);
+    });
+
+    it("should store the entity", () => {
+      expect(hasComponent(component, entity)).toBe(true);
+    });
+
+    it.todo("should store the value array");
+  });
+
+  describe("removeComponent", () => {
+    let component: AnyComponent;
+    let entity: Entity;
+    let value: number;
+
+    beforeEach(() => {
+      component = defineComponent(world, { value: Type.Number });
+      entity = createEntity(world);
+      value = 1;
+      setComponent(component, entity, { value });
+      removeComponent(component, entity);
+    });
+
+    it("should remove the component value", () => {
+      expect(component.values.value.get(getEntitySymbol(entity))).toBe(undefined);
+    });
+
+    it("should remove the entity", () => {
+      expect(hasComponent(component, entity)).toBe(false);
+    });
+
+    // it("shouldremove the component from the entity's component set", () => {
+    //   expect(world.entities.get(entity)?.has(component)).toBe(false);
+    // });
+  });
+
+  describe("hasComponent", () => {
+    it("should return true if the entity has the component", () => {
+      const component = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity = createEntity(world);
+      const value = { x: 1, y: 2 };
+      setComponent(component, entity, value);
+
+      expect(hasComponent(component, entity)).toEqual(true);
+    });
+  });
+
+  describe("getComponentValue", () => {
+    it("should return the correct component value", () => {
+      const component = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity = createEntity(world);
+      const value = { x: 1, y: 2 };
+      setComponent(component, entity, value);
+
+      const receivedValue = getComponentValue(component, entity);
+      expect(receivedValue).toEqual(value);
+    });
+  });
+
+  describe("getComponentValueStrict", () => {
+    it.todo("should return the correct component value");
+    it.todo("should error if the component value does not exist");
+  });
+
+  describe("componentValueEquals", () => {
+    const value1 = { x: 1, y: 2, z: "x" };
+    const value2 = { x: 1, y: 2, z: "x" };
+    const value3 = { x: "1", y: 2, z: "x" };
+
+    expect(componentValueEquals(value1, value2)).toBe(true);
+    expect(componentValueEquals(value2, value3)).toBe(false);
+  });
+
+  describe("withValue", () => {
+    it("should return a ComponentWithValue", () => {
+      const component = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const value = { x: 1, y: 2 };
+      const componentWithValue = withValue(component, value);
+      expect(componentWithValue).toEqual([component, value]);
+    });
+  });
+
+  describe("getEntitiesWithValue", () => {
+    it("Should return all and only entities with this value", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity1 = createEntity(world, [withValue(Position, { x: 1, y: 2 })]);
+      createEntity(world, [withValue(Position, { x: 2, y: 1 })]);
+      createEntity(world);
+      const entity4 = createEntity(world, [withValue(Position, { x: 1, y: 2 })]);
+
+      expect(getEntitiesWithValue(Position, { x: 1, y: 2 })).toEqual(new Set([entity1, entity4]));
+    });
+  });
+
+  describe("overridableComponent", () => {
+    it("should return a overridable component", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const OverridablePosition = overridableComponent(Position);
+      expect("addOverride" in OverridablePosition).toBe(true);
+      expect("addOverride" in OverridablePosition).toBe(true);
+    });
+
+    it("should mirror all values of the source component", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity1 = createEntity(world);
+      setComponent(Position, entity1, { x: 1, y: 2 });
+
+      const OverridablePosition = overridableComponent(Position);
+      expect(getComponentValue(OverridablePosition, entity1)).toEqual({ x: 1, y: 2 });
+    });
+
+    it("the overridable component should be updated if the original component is updated", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity1 = createEntity(world);
+      setComponent(Position, entity1, { x: 1, y: 2 });
+
+      const OverridableComponent = overridableComponent(Position);
+
+      setComponent(Position, entity1, { x: 2, y: 2 });
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 2, y: 2 });
+
+      const entity2 = createEntity(world, [withValue(Position, { x: 3, y: 3 })]);
+      expect(getComponentValue(OverridableComponent, entity2)).toEqual({ x: 3, y: 3 });
+    });
+
+    it("should return the updated component value if there is a relevant update for the given entity", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity1 = createEntity(world);
+      const entity2 = createEntity(world);
+      setComponent(Position, entity1, { x: 1, y: 2 });
+      setComponent(Position, entity2, { x: 5, y: 6 });
+
+      const OverridableComponent = overridableComponent(Position);
+      OverridableComponent.addOverride("firstOverride", { entity: entity1, value: { x: 2, y: 3 } });
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 2, y: 3 });
+      expect(getComponentValue(OverridableComponent, entity2)).toEqual({ x: 5, y: 6 });
+
+      OverridableComponent.addOverride("secondOverride", { entity: entity1, value: { x: 3, y: 3 } });
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 3, y: 3 });
+
+      OverridableComponent.removeOverride("secondOverride");
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 2, y: 3 });
+
+      setComponent(Position, entity1, { x: 10, y: 20 });
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 2, y: 3 });
+
+      OverridableComponent.removeOverride("firstOverride");
+      expect(getComponentValue(OverridableComponent, entity1)).toEqual({ x: 10, y: 20 });
+    });
+
+    it("adding an override should trigger reactions depending on the getComponentValue of the overriden component", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const entity1 = createEntity(world);
+      setComponent(Position, entity1, { x: 1, y: 2 });
+
+      const OverridablePosition = overridableComponent(Position);
+
+      const spy = jest.fn();
+      OverridablePosition.update$.subscribe(spy);
+
+      expect(spy).toHaveBeenCalledTimes(0);
+
+      OverridablePosition.addOverride("firstOverride", { entity: entity1, value: { x: 3, y: 3 } });
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy).toHaveBeenLastCalledWith({
+        entity: entity1,
+        component: OverridablePosition,
+        value: [
+          { x: 3, y: 3 },
+          { x: 1, y: 2 },
+        ],
+      });
+
+      OverridablePosition.removeOverride("firstOverride");
+      expect(spy).toHaveBeenCalledTimes(2);
+      expect(spy).toHaveBeenLastCalledWith({
+        entity: entity1,
+        component: OverridablePosition,
+        value: [
+          { x: 1, y: 2 },
+          { x: 3, y: 3 },
+        ],
+      });
+
+      OverridablePosition.addOverride("secondOverride", {
+        entity: "42" as Entity,
+        value: { x: 2, y: 3 },
+      });
+      expect(spy).toHaveBeenLastCalledWith({
+        entity: "42",
+        component: OverridablePosition,
+        value: [{ x: 2, y: 3 }, undefined],
+      });
+      expect(spy).toHaveBeenCalledTimes(3);
+    });
+  });
+});

package/src/Component.ts

@@ -18,6 +18,11 @@ import {
 import { isFullComponentValue, isIndexer } from "./utils";
 import { getEntityString, getEntitySymbol } from "./Entity";
 
+export type ComponentMutationOptions = {
+  /** Skip publishing this mutation to the component's update stream. Mostly used internally during initial hydration. */
+  skipUpdateStream?: boolean;
+};
+
 function getComponentName(component: Component<any, any, any>) {
   return (
     component.metadata?.componentName ??
@@ -37,7 +42,7 @@ function getComponentName(component: Component<any, any, any>) {
  * @param schema {@link Schema} of component values. Uses Type enum as bridge between typescript types and javascript accessible values.
  * @param options Optional: {
  *    id: descriptive id for this component (otherwise an autogenerated id is used),
- *    metadata: arbitrary metadata (eg. contractId for solecs mapped components),
+ *    metadata: arbitrary metadata,
  *    indexed: if this flag is set, an indexer is applied to this component (see {@link createIndexer})
  * }
  * @returns Component object linked to the provided World
@@ -80,7 +85,8 @@ export function defineComponent<S extends Schema, M extends Metadata, T = unknow
 export function setComponent<S extends Schema, T = unknown>(
   component: Component<S, Metadata, T>,
   entity: Entity,
-  value: ComponentValue<S, T>
+  value: ComponentValue<S, T>,
+  options: ComponentMutationOptions = {}
 ) {
   const entitySymbol = getEntitySymbol(entity);
   const prevValue = getComponentValue(component, entity);
@@ -109,7 +115,9 @@ export function setComponent<S extends Schema, T = unknown>(
       }
     }
   }
-  component.update$.next({ entity, value: [value, prevValue], component });
+  if (!options.skipUpdateStream) {
+    component.update$.next({ entity, value: [value, prevValue], component });
+  }
 }
 
 /**
@@ -132,16 +140,17 @@ export function updateComponent<S extends Schema, T = unknown>(
   component: Component<S, Metadata, T>,
   entity: Entity,
   value: Partial<ComponentValue<S, T>>,
-  initialValue?: ComponentValue<S, T>
+  initialValue?: ComponentValue<S, T>,
+  options: ComponentMutationOptions = {}
 ) {
   const currentValue = getComponentValue(component, entity);
   if (currentValue === undefined) {
     if (initialValue === undefined) {
       throw new Error(`Can't update component ${getComponentName(component)} without a current value or initial value`);
     }
-    setComponent(component, entity, { ...initialValue, ...value });
+    setComponent(component, entity, { ...initialValue, ...value }, options);
   } else {
-    setComponent(component, entity, { ...currentValue, ...value });
+    setComponent(component, entity, { ...currentValue, ...value }, options);
   }
 }
 
@@ -153,14 +162,17 @@ export function updateComponent<S extends Schema, T = unknown>(
  */
 export function removeComponent<S extends Schema, M extends Metadata, T = unknown>(
   component: Component<S, M, T>,
-  entity: Entity
+  entity: Entity,
+  options: ComponentMutationOptions = {}
 ) {
   const entitySymbol = getEntitySymbol(entity);
   const prevValue = getComponentValue(component, entity);
   for (const key of Object.keys(component.values)) {
     component.values[key].delete(entitySymbol);
   }
-  component.update$.next({ entity, value: [undefined, prevValue], component });
+  if (!options.skipUpdateStream) {
+    component.update$.next({ entity, value: [undefined, prevValue], component });
+  }
 }
 
 /**

package/src/Entity.spec.ts

@@ -0,0 +1,45 @@
+import { defineComponent, getComponentValue, hasComponent, withValue } from "./Component";
+import { Type } from "./constants";
+import { createEntity } from "./Entity";
+import { World } from "./types";
+import { createWorld } from "./World";
+
+describe("Entity", () => {
+  let world: World;
+
+  beforeEach(() => {
+    world = createWorld();
+  });
+
+  describe("createEntity", () => {
+    it("should return a unique id", () => {
+      const firstEntity = createEntity(world);
+      const secondEntity = createEntity(world);
+      expect(firstEntity).not.toEqual(secondEntity);
+    });
+
+    it("should register the entity in the world", () => {
+      expect([...world.getEntities()].length).toEqual(0);
+      createEntity(world);
+      expect([...world.getEntities()].length).toEqual(1);
+    });
+
+    it("should create an entity with given components and values", () => {
+      const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
+      const CanMove = defineComponent(world, { value: Type.Boolean });
+
+      const value1 = { x: 1, y: 1 };
+      const value2 = { x: 2, y: 1 };
+
+      const movableEntity = createEntity(world, [withValue(Position, value1), withValue(CanMove, { value: true })]);
+
+      const staticEntity = createEntity(world, [withValue(Position, value2)]);
+
+      expect(getComponentValue(Position, movableEntity)).toEqual(value1);
+      expect(hasComponent(CanMove, movableEntity)).toBe(true);
+
+      expect(getComponentValue(Position, staticEntity)).toEqual(value2);
+      expect(hasComponent(CanMove, staticEntity)).toBe(false);
+    });
+  });
+});

package/src/Entity.ts

@@ -8,7 +8,7 @@ import { Component, ComponentValue, Entity, EntitySymbol, World } from "./types"
  * @param components Array of [{@link defineComponent Component}, {@link ComponentValue}] tuples to be added to this entity.
  * (Use {@link withValue} to generate these tuples with type safety.)
  * @param options Optional: {
- *   id: {@link Entity} for this entity. Use this for entities that were created outside of recs, eg. in the corresponding solecs contracts.
+ *   id: {@link Entity} for this entity. Use this for entities that were created outside of recs.
  *   idSuffix: string to be appended to the auto-generated id. Use this for improved readability. Do not use this if the `id` option is provided.
  * }
  * @returns index of this entity in the {@link World}. This {@link Entity} is used to refer to this entity in other recs methods (eg {@link setComponent}).