miniplex-react Documentation unclear

[ndugger]

I have no idea how to use the miniplex-react package properly, because the documentation is not clear. It shows examples using react-three-fiber elements, but not whether or not this then needs to be rendered within a canvas (it does). I thought that I could render my entities anywhere I wanted to, but then use the <Entities> component to actually render them within the <Canvas>, but that doesn't appear to be the case. I'm not sure how to improve the documentation, because I don't understand how the library even functions based on the current documentation, but I'd sure love to use this library if someone could help it make sense.

[rkmiller131]

The documentation was indeed difficult to understand at first; I found it lacking in several areas as well.

But to answer your question, yes - you can only render entities with visible "three" components in the canvas of R3F, and this makes sense because you can't render any other Object3D outside of the canvas either.

Now, that doesn't mean you can't add and manipulate entities and their components outside of the canvas using the other syntax such as ECS.world.add({ ... }). In fact, this is likely what you'll do in other components, helper functions, or systems that you've set up throughout your app that don't necessarily have to be a child of the canvas.

One approach I've used to render objects is through queries and use of the <ECS.Entities /> tag.
For example, somewhere in the app maybe you called:

ECS.world.add({
     ship: {
          health: 100
     }
})

And within the canvas you have a component called <Ships /> from Ships.jsx
This component uses a query to find all the entities in the world with that ships property, and then maps them to a visible Object3D mesh from R3F. For example:

export const Ships = () => {
     const entitiesQuery = useEntities(ECS.world.with('ship'));
     return (
          <ECS.Entities in={entitiesQuery}>
               {(e) => (
                    <ShipEntity health={e.ship.health} entity={e} />
               )}
          </ ECS.Entities>
     )
}

And then from there, your <ShipEntity /> would encompass the R3F mesh:

export const ShipEntity = ({ health, entity }) => {
     return (
          <ECS.Entity entity={entity}>
               <ECS.Component name="three">
                    <NormalR3FShipModel health={health} />
               </ ECS.Component>
          </ ECS.Entity>
     )
}

One thing that was unclear in the documentation was the component named "three" - what the heck was that supposed to be in the entity definition of the world? Turns out it's just an Object3D, nothing complicated.