Miniplex 2.0 Beta 1!

[hmans]

Hooray, it's the first beta release of Miniplex 2.0! While the documentation is being updated (including an all-new website that is still deeply work in progress!), I'd like to provide you with a summary of the changes so you can start giving this thing a go in your projects.

Focus:

Miniplex 2.0 is a complete rewrite of the library, but while it does bring some breaking changes, it will still allow you to do everything that you've been doing with 1.0. When upgrading a 1.0 project to 2.0, most changes you will need to do are related to things having been renamed.

The headline changes in 2.0:

• A lot more relaxed and lightweight! Where Miniplex 1.0 would immediately crash your entire application when, for example, adding a component to an entity that already has the component, Miniplex 2.0 will simply no-op and continue.
• Much more flexible! Miniplex 2.0 finally lets you create archetypes of entities that do not have a specific component, and goes even further than that; you can now create predicate-based archetypes using any kind of function.
• Better type support! If you're using TypeScript, you will be happy to hear that type support has been significantly improved, with much better narrowed types for created archetypes, and support for both predicates with type guards as well as type generics.
• The React API has been significantly simplified.

Installing:

While Miniplex 2.0 is in beta, you will need to install it using the beta tag:

npm add miniplex@beta
yarn add miniplex@beta
pnpm add miniplex@beta

Core:

• world.createEntity has been renamed and simplified to just world.add (which now returns the correct type for the entity, too), and world.destroyEntity to world.remove. addComponent and removeComponent have not been changed.

  const entity = world.add({ position: { x: 0, y: 0 } })
  world.addComponent(entity, "velocity", { x: 0, y: 0 })
  world.remove(entity)

• There is a new world.update function that you may use to update an entity and make sure it is reindexed across the various archetypes. It provides a number of different overloads to provide some flexibility in how you update the entity.

  world.update(entity, { position: { x: 1, y: 1 } })
  world.update(entity, "position", { x: 1, y: 1 })
  world.update(entity, () => ({ position: { x: 1, y: 1 } }))
  world.update(entity, (e) => (e.position = { x: 1, y: 1 }))

  Please keep in mind that in Miniplex, you'll typically mutate your entities anyway, so going through this function is not strictly necessary. The upcoming documentation will go into more detail as to when using this function is useful (or even necessary), and when you should avoid it.

• The Tag type and constant have been removed. For tag-like components, simply use true (which Tag was just an alias for.)

• Entities added to a world no longer receive a __miniplex component. This component has always been an internal implementation detail, but you might have used it in the past to get a unique identifier for an entity. This can now be done through world.id(entity), with ID lookups being available through world.entity(id).

• Archetypes can now be iterated over directly. Example:

  const moving = world.archetype("position", "velocity")
  
  for (const { position, velocity } of moving) {
    position.x += velocity.x
    position.y += velocity.y
  }

  You can use this to neatly fetch the first entity from an archetype that you only expect to have a single entity in it:

  const [player] = world.archetype("player")

• The queuing functionality that was built into the World class has been removed. If you've relied on this in the past, miniplex now exports a queue object that you can use instead. Example:

  import { queue } from "miniplex"
  
  queue(() => {
    // Do something
  })
  
  /* Later */
  queue.flush()

  Please note that this is being provided to make upgrading to 2.0 a little easier, and will likely be removed in a future version.

• world.archetype can now take a predicate! You can use this as an escape hatch for creating any kind of archetype based on the conditions you specify. Example:

  const almostDead = world.archetype((entity) => entity.health < 10)

  Please note that his requires entities with the health component to be updated through the world.update function in order to keep the archetype up to date.

• You can use with and without as an alternative API for creating archetypes. Example:

  const moving = world.with("position", "velocity")
  const alive = world.without("dead")

• You can use where to create a predicate-based iterator. This allows you to quickly filter a set of entities without creating new archetypes or other objects. Example:

  for (const entity of world.where((entity) => entity.health < 10)) {
    // Do something
  }

• All of these can be nested!

  world
    .with("position", "velocity")
    .without("dead")
    .where((entity) => entity.health < 10)

• Entities fetched from an archetype will have much improved types, but you can also specify a type to narrow to via these functions' generics:

  const player = world.archetype<Player>("player")

• Miniplex provides the new Strictly and With types which you can use to compose types from your entity main type:

  type Entity = {
    position: { x: number; y: number }
    velocity: { x: number; y: number }
  }
  
  type Player = With<Entity, "position" | "velocity">
  
  const player = world.archetype<Player>("player")

React:

• The miniplex-react package has been retired, you can now import the React-specific bits from miniplex/react. The main export of that package has been renamed to createReactAPI and expects to be passed an instance of a world, so the setup now looks like this:

  import { World } from "miniplex"
  import { createReactAPI } from "miniplex/react" // !
  
  /* It now expects a world as its argument, so you need to create one first: */
  const world = new World()
  const ECS = createReactAPI(world)

• The <Archetype> component now supports the with and without properties:

  <Archetype with={["position", "velocity"]} without="dead">
    {/* ... */}
  </Archetype>

• If you already have a reference to an archetype, you can pass it to the newly improved <Entities> component to automatically render all entities contained within it, and have them automatically update when the archetype changes:

  <Entities in={archetype}>{/* ... */}</Entities>

  If you ever want to list a simple array of entities, you can use the same component (but it will not automatically update if the array contents change):

  <Entities in={[entity1, entity2]}>{/* ... */}</Entities>

• <ManagedEntities> has been removed. You were probably not using it. If you were, you can replicate the same behavior using a combination of the <Entities> or <Archetype> components and a useEffect hook.

• The useEntity hook has been renamed to useCurrentEntity.

• The world-scoped useArchetype hook has been removed, and superceded by the new global useEntities hook:

  /* Before */
  const entities = useArchetype("position", "velocity")
  
  /* Now */
  const entities = useEntities(world.with("position", "velocity"))

Feedback and Questions?

This is the first beta of a big new release for this library, and since it is a complete rewrite, there are bound to be some bugs and rough edges.

• Got feedback? Please post it under this post, I'd love to read it!
• Found an issue? Please open an issue!

[mikecann]

Just upgraded our project to use 2.0 and everything looks great, nice work! Only one thing I would mention:

You can use this to neatly fetch the first entity from an archetype that you only expect to have a single entity in it:
const [player] = world.archetype("player")

Unfortunately this does not work if you want to check for the first element in an if statement:

if (archetype[0]) {
 // do something
}

So you now have to do this:

const [first] = archetype;
if (first) {
 // do something
}

Which is annoying.

The alternative is: archetype.entities[0] which im guessing causes a iteration and allocation of an array just to access the first element.

IMO the archetype should have a .first still and maybe an isEmpty too

[hmans]

Thanks for giving it a try, and for posting this feedback!

Unfortunately this does not work if you want to check for the first element in an if statement:

if (archetype[0]) {
 // do something
}

This is because archetype itself is not the array, so it doesn't let you do numerical index accesses. (I wonder if this is something I can teach it to do?)

The alternative is: archetype.entities[0] which im guessing causes a iteration and allocation of an array just to access the first element.

Nope, this is actually extremely cheap, since here you're accessing the entities array directly!

IMO the archetype should have a .first still and maybe an isEmpty too

I think an archetype.first getter is fine (I've created #259 for this.) Not sure about isEmpty and similar, since you can just compare archetype.size === 0, but I'll think about it.

[mikecann]

In the docs for 2.0 you talk about this being safe but unfortunately it isnt always. For example this throws an error:

import { World } from "miniplex";

interface Entity {
  health: { value: number };
  age: {};
}

test(`it works`, () => {
  const world = new World<Entity>();
  const archetype = world.archetype("health", "age");

  const entityA = world.add({
    health: { value: 10 },
    age: {},
  });

  const entityB = world.add({
    health: { value: 20 },
    age: {},
  });

  for (const entity of archetype) {
    console.log(entity.health.value);
    world.remove(entityA);
    world.remove(entityB);
  }
});

Cannot read properties of undefined (reading 'health')
TypeError: Cannot read properties of undefined (reading 'health')

[FuriouZz]

Hello @hmans @mikecann 👋

Just followed your conversation. Why not hide archetype.entities to the user?

If iterating over archetype.entities or using forEach is not recommended, why not making archetype.entities private and propose a method getEntities() or similar to get a copy of all entities.

Your library will propose a fully "safe" API. We can iterate with forof over the archetype or by using getEntities(). And if an issue occured during the iteration, it is the responsability of the user.

[mikecann]

If you remove other entities that live at random positions (other than the current cursor), there's a high potential for problems arising,

Ahh this was the part I was missing. This makes total sense now, thanks.

I recommend implementing an entity destruction mechanism by introducing a destroyed component that you add to entities that should be destroyed

Great suggestion! Thanks :)

Why not hide archetype.entities to the user?

There are still uses such as "map", "filter", "find" and other array methods that dont exist on archetype. IMO it should be kept for now.

[hmans]

Ahh this was the part I was missing. This makes total sense now, thanks.

The price for making random deletion 100% safe is creating additional objects, or queuing.

Right now, the user could choose to iterate through a copy of the archetype like this:

for (const entity of [...archetype]) {
  /* go crazy */
}

This would allow them to randomly remove entities, at the cost of an extra array created every time this loop is called (and which may also become a performance issue with larger arrays.)

I could wrap this in the library (eg. for (const entity of archetype.safe) or similar), but I'd be worried that users will quickly default to using that (because "safe" sounds nice!), ruining their project's performance in the process.

Alternatively, I could bake queueing functionality back into the library. This could take a different form form what we had in 1.0, for example this:

/* Wrap a block of code in `world.queue` */
world.queue(() => {
  for (const entity of archetype) {
    /*
    Any calls to add, remove, update, addComponent and setComponent
    are now put into a queue, instead of executed immediately
    */
    world.remove(entityA)
    world.remove(entityB)
  }
})

/* After exiting the function, the queue is flushed automatically */

What do you think?

(There are some complexities to something like this that make this a clear candidate for a 2.1 release.)

[mikecann]

Ye agreed dont do the archetype.safe thing.. too tempting to fall in the pit of failure with that.

Alternatively, I could bake queueing functionality back into the library.

Ye I think it would be nice to have queuing baked in a post 2.0 release.

[hmans]

If iterating over archetype.entities or using forEach is not recommended, why not making archetype.entities private and propose a method getEntities() or similar to get a copy of all entities.

In the upcoming documentation, the two recommended ways of iterating over archetypes are these two:

For convenience:

for (const entity of archetype) {
  /* Do things */
}

For performance:

for (let i = 0; i < archetype.entities.length; i++) {
  const entity = archetype.entities[i]
  /* Do things */
}

Or in reverse, which allows for safe deletion of the entity from within the loop:

for (let i = archetype.entities.length - 1; i >= 0; i--) {
  const entity = archetype.entities[i]
  /* Do things */
}

[itsdouges]

Heya! Upgrading today for fun, I'll post some thoughts in this comment as I come across them.

• Did you ever think about a useEntities api that takes a callback that is given the world for convenience?

const ECS = createReactApi(new World<...>());

const entities = ECS.useEntities(world => world.with('active'));

• Does Component have a ref anymore? I don't see it on types. I was using this before to add imperative components to the entity on events. I can use the callback and have the same behaviour but it's a bit potato potato.
• Does useCurrentEntity no longer throw if its not found? The type suggests it won't anymore. Easy enough to implement it on my end.
• I think useEntity was already called useCurrentEntity
• When any entity component is added/removed is every bucket reindexed? I'm seeing unexpected behaviour and curious about the inner workings. I would have expected it would only update if the components you've "queried" change, but it seems like it's updating even when they don't change (others have though). I see this behaviour in both v1 and v2 beta, but in v2 I'm getting more updates that I need to dig into as it's broken the camera focus system a bit. Very plausible I just have a bug somewhere so I'll keep digging.
• 🤔 removing components now re-create the entity in a new instance, that doesn't seem desirable https://github.com/hmans/miniplex/blob/main/packages/miniplex-core/src/World.ts#L67

---

This line of code is causing a new entity reference every time the Entity component renders https://github.com/hmans/miniplex/blob/main/packages/miniplex-react/src/createReactAPI.tsx#L32, which might explain all of my whacky behaviour I'm seeing.

// Creates a new entity reference every render
<Entity>
  ...
</Entity>

// Does not create a new entity reference every render
<Entity entity={useState(() => ({}))[0]}>
  ...
</Entity>

To fix it we'll probably want to conditionally create it in the render function as each Entity element should have its own unique reference.

function Entity({ entity }) {
  const [defaultEntity] = useState(() => ({}));
  const actualEntity = entity || defaultEntity;
}

(Yep that fixes things for me)

diff --git a/node_modules/@miniplex/react/dist/miniplex-react.esm.js b/node_modules/@miniplex/react/dist/miniplex-react.esm.js
index f61d109..90168a8 100644
--- a/node_modules/@miniplex/react/dist/miniplex-react.esm.js
+++ b/node_modules/@miniplex/react/dist/miniplex-react.esm.js
@@ -1,5 +1,5 @@
 import { Bucket } from '@miniplex/core';
-import React, { useLayoutEffect, useEffect, useContext, memo, useMemo, useRef, createContext } from 'react';
+import React, { useLayoutEffect, useEffect, useContext, useState, memo, useMemo, useRef, createContext } from 'react';
 import { useRerender } from '@hmans/use-rerender';
 
 function _extends() {
@@ -93,9 +93,10 @@ var createReactAPI = function createReactAPI(world) {
     return useContext(EntityContext);
   };
   var RawEntity = function RawEntity(_ref) {
+    var defaultEntity = useState(() => ({}))[0];
     var givenChildren = _ref.children,
       _ref$entity = _ref.entity,
-      entity = _ref$entity === void 0 ? {} : _ref$entity;
+      entity = _ref$entity === void 0 ? defaultEntity : _ref$entity;
     /* Add the entity to the bucket represented by this component if it isn't already part of it. */
     useIsomorphicLayoutEffect(function () {
       if (world.has(entity)) return;

[hmans]

Thanks for the thorough feedback, @itsdouges! Let me address these one by one:

Did you ever think about a useEntities api that takes a callback that is given the world for convenience?

Yes, I've thought about it, but so far decided against it because I've been intending to guide users towards declaring their archetypes outside of components. All in all, though, I'm not against offering this as an alternative API, I just wouldn't want to make it the default.

• Offer bound ECS.useEntities(world => bucket) API #267

Does Component have a ref anymore?

Hm, it should, but maybe something is off. I will check.

Does useCurrentEntity no longer throw if its not found?

I will check. It should throw when not run inside an entity context.

• useCurrentEntity should throw when not run inside an entity context #268

When any entity component is added/removed is every bucket reindexed? I'm seeing unexpected behaviour and curious about the inner workings.

When an entity is added, removed, or has components added/removed, the world will emit its onEntityAdded etc. events. Archetypes and other buckets derived from the world will subscribe to this event, causing them to re-check the entity, but these buckets will only themselves be updated if the indexing state of the given entity changes.

Can you describe a scenario (or maybe even provide some code, in Codesandbox or not) that demonstrates the unexpected behavior that you're seeing?

removing components now re-create the entity in a new instance, that doesn't seem desirable https://github.com/hmans/miniplex/blob/main/packages/miniplex-core/src/World.ts#L67

The future object here is only used for the reindexing check. The entity object remains the same object. The only drawback here is a little extra memory usage (because a new object is created for these checks; but at least it will reuse the actual component object, since it's only a shallow clone.)

The reason I'm doing this is that without it, the removed component would already be gone by the time onEntityRemoved event callbacks where invoked. By doing this, the removed component is still available, allowing the event callback to access it.

This line of code is causing a new entity reference every time the Entity component renders https://github.com/hmans/miniplex/blob/main/packages/miniplex-react/src/createReactAPI.tsx#L32, which might explain all of my whacky behaviour I'm seeing.

Good catch, that's a pretty nasty bug!

• <Entity> will destroy and re-create its entity on every rerender #269

Thanks for all the good feedback, and keep it coming!

[itsdouges]

Thanks mate! Also sorry I mean ref on Entity component not Component component 😅

[itsdouges]

Can you go into more detail around archetypes being created outside of components/hooks? Does it result in better perf? If it's explained above just say so and I'll read when I have a chance

[hmans]

Hot damn, I accidentally created a new thread for my replies — sorry!

Can you go into more detail around archetypes being created outside of components/hooks? Does it result in better perf? If it's explained above just say so and I'll read when I have a chance

Basically, every time you do world.with("foo"), it will run a tiny amount of memoization code that makes sure the returned archetype is the same object.

Outside of React, I'm advising users to create references to their archetypes outside of code that runs once every frame because running that memoization code every frame is just unnecessary overhead.

Inside of React, this code would run every time the component re-renders, which ideally shouldn't happen too often (especially not once per frame), so it's not as important there really.

[hmans]

I didn't create an issue for it, but 728feb4 now lets <Entity> accept refs.