Major Changes

• 8a7a315: Miniplex 2.0 is a complete rewrite of the library, with a heavy focus on further improving the developer experience, and squashing some significant bugs.

  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 simplifies and extends the query API (formerly often referred to as "archetypes"); you can now create queries through world.with("componentName"), chain these together, use the new without, or even create advanced predicate-based queries using where.
  • Improved type support! If you're using TypeScript, you will be happy to hear that type support has been significantly improved, with much better type narrowing for queries.
  • The React API has been significantly simplified, and some pretty big bugs have been squashed. (Turns out Miniplex 1.0's React API really didn't like React's ``` much. Whoops!)

  Some more details on the changes:

  • 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.

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

  • 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).

  • Queries can now be iterated over directly. Example:

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

    This is, in fact, now the recommended way to iterate over entities, since it is extremely efficient, and will make sure that the list of entities is being iterated over in reverse, which makes it safe to modify it during iteration.

    You can also 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.with("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.

  • with and without are the new API for building queries. Examples:

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

  • The new world.where now allows you to build predicate-based queries! You can use this as an escape hatch for creating any kind of query based on any conditions you specify. Example:

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

    Please note that his requires entities with the health component to be reindexed using the world.reindex function in order to keep the archetype up to date. Please refer to the documentation for more details.

  • 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 chained!

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

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

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

  • Miniplex provides the new Strict 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 = Strict<With<Entity, "position" | "velocity">>
    
    const player = world.archetype<Player>("player")

  • The event library Miniplex uses has been changed to Eventery, which brings a change in API. Where before you would have done onEntityAdded.add(listener), you will now to onEntityAdded.subscribe(listener).

Patch Changes

• Updated dependencies [8a7a315]
  • @miniplex/[email protected]

Patch Changes

• 2303870: Bump minimum version of miniplex peer dependency.

Major Changes

• 8a7a315: - The library has been significantly simplified and an almost mind-boggling number of bugs have beens quashed.

  • The main import and initialization have changed:

    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)

  • All lists of entities are now rendered through the upgraded <Entities> component, which takes an array of entities or a query (or even a world) as its in prop:

    <Entities in={world.with("asteroid")}>{/* ... */}</Entities>

    If you're passing in a query or a world, the component will automatically re-render when the entities appear or disappear. If you don't want this, you can also just pass in a plain array containing entities:

    <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> component and a useEffect hook.

  • The useEntity hook has been renamed to useCurrentEntity.

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

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

Major Changes

• 8a7a315: Miniplex 2.0 now implements its core "reactive bucket" functionality in a small micropackage called @miniplex/bucket. It can be pretty useful even outside of Miniplex, and will eventually be extracted into its own project.

Patch Changes

• 85f97cc: World.reindex(entity) is now a public method. When creating queries that use .where(predicate) to check entities by value, you are expected to use it to notify the world that an entity whose values you have mutated should be reindexed.

Patch Changes

• aca22ff: Given the miniplex-react package's documentation an overhaul for the upcoming 2.0.0 release. Do give it a read, feedback welcome!

Patch Changes

• 1671bb5: Breaking Change: Restructured the main entrypoint packages to what they were in Miniplex 1.0, with the miniplex package now only providing the vanilla, framework-agnostic ECS functionality, and miniplex-react adding the React glue (and using miniplex as a peer dependency.)

Patch Changes

• 1671bb5: Breaking Change: Restructured the main entrypoint packages to what they were in Miniplex 1.0, with the miniplex package now only providing the vanilla, framework-agnostic ECS functionality, and miniplex-react adding the React glue (and using miniplex as a peer dependency.)

Patch Changes

• ae19dd0: Aaaaah, it's Miniplex 2.0 Beta 4! The library received some major refactoring for this beta, making it significantly less complex, and at the same time easier to explain and document. Which, sadly, also means breaking changes -- but most of them are just renames, so you shouldn't have any trouble upgrading. (If you do, let me know!)

  The most important changes:

  • world.archetype is gone. The query API is now just .with(...components) and .without(...components).
  • Like in the previous beta, these can be chained indefinitely, but there are some changes to how this is implemented. Most importantly, it does away with the concept of "a waterfall of buckets", which had proven difficult to explain and a source of many wonderful footguns.
  • .where(predicate) now returns a full query object that can be chained further (as opposed to a standalone iterator). Please note that this functionality is still experimental and will still receive upgrades and changes in the future.
  • The event library Miniplex uses has been changed to Eventery, which brings a change in API. Where before you would have done onEntityAdded.add(listener), you will now to onEntityAdded.subscribe(listener).
  • The documentation is moving away from the "archetype" terminology, and is now using "query" instead. If you're coming from 1.0 where everything went through "archetypes", don't worry, they're both conceptually the same thing.

• 1258841: All packages are now built using TypeScript 5.0.

• Updated dependencies [4448080]

• Updated dependencies [1258841]

• Updated dependencies [4448080]

  • @miniplex/[email protected]
  • @miniplex/[email protected]

Patch Changes

• 4448080: Breaking Change: the core Bucket class now uses Eventery for its onEntityAdded and onEntityRemoved events, which has a slightly different API than the library used before, since it uses .subscribe(listener) and .unsubscribe(listener) instead of .add and .remove.
• 1258841: All packages are now built using TypeScript 5.0.