feat: add plugin system

[bigmistqke]

Initial implementation of a plugin-system, continuing on #32

Plugin API

Vibe coded with claude on the plugin API choices. It's a bit much with the overloads, but it feels fun to use and the api allows for nice type inference.

/** Without setup */

// Plugin for all:
plugin((element) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... }))

// Conditional plugins:

// Filter all elements extending from Mesh / Camera
plugin(
    [Mesh, Camera], 
    (meshOrCamera) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... })
)

// Filter all elements with a type guard
plugin(
    (element): element is Mesh => element instanceof Mesh, 
    (mesh) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... })
)

/** With setup */

// Plugin for all:
plugin
    .setup((store) => ({ ... })
    .then((element, context) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... }))

// Conditional plugins:

// Filter all elements extending from Mesh / Camera
plugin
    .setup((store) => ({ ... })
    .then(
        [Mesh, Camera], 
        (meshOrCamera, context) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... })
    )

// Filter all elements with a type guard
plugin
    .setup((store) => ({ ... })
    .then(
        (element): element is Mesh => element instanceof Mesh, 
        (mesh, context) => ({ onMouseDown(cb: (event: MouseEvent) => void): ... })
    )

Usage

via createT

const ShakePlugin = plugin([THREE.Camera, THREE.Mesh], element => ({
  shake: (intensity = 0.1) => {
    const originalPosition = element.position.clone()
    useFrame(() => {
      element.position.x = originalPosition.x + (Math.random() - 0.5) * intensity
      element.position.y = originalPosition.y + (Math.random() - 0.5) * intensity
      element.position.z = originalPosition.z + (Math.random() - 0.5) * intensity
    })
  },
}))

const { T, Canvas } = createT(THREE, [ShakePlugin])

return <T.Mesh shake={0.1} />

via prop

return <Entity from={Mesh} plugins={[Shakeplugin]} shake={0.1} />

Event Plugin

Abstracted the event handling that we inherited from react-three-fiber out of core and into a plugin: EventPlugin

[bigmistqke]

In #32 I discussed having <Canvas /> as the base of where the plugins cascade, via context, but this I have not currently implemented as I am not sure it is necessary. The methods currently (declare it in createT or pass it via props) might be sufficient and provide a type-safety that context can not provide.

The setup functions currently do rely on context so they only set once (via a ReactiveMap<Plugin, ReturnType<Plugin>>). This way if I have a canvas that is set with createT(..., [EventPlugin]) and then I have another entity that also uses the same plugin <Entity from={Mesh} plugins={[EventPlugin]} />, they both share the same setup function/context.

But I would personally prefer if nothing relied on where it is mount. Maybe we can follow the approach of Web Components and walk up the tree when it is attached to the scene via useSceneGraph? Something to explore...

[bigmistqke]

Maybe the setup function should be global instead, and not connected to any root. That way they can be initialized from the start and are not context dependent.

The EventPlugin needs some additional consideration and is a good usecase: Make your core features plugins, to validate that you have a powerful and well designed plugin API.!

1. How could EventPlugin work with multiple canvases and a global setup function? How can it know which objects to intersect and which not?
2. EventPlugin adds event listeners to the canvas, so we kind of do need to access the canvas somehow.
   • Do we have a bind-method: plugin.bind(dom => dom.addEventListener(...)).then(...)?
   • If plugins can be passed to any object, how can we know it is connected to the canvas?

Solution

One solution would be for the EventPlugin to do rely on context, but to be very explicit about it:

const { T, Canvas } = createT(THREE, [EventPlugin])

return <Canvas>
    <EventPlugin.Provider>
        ...
    </EventPlugin.Provider>
</Canvas>

Then at least the API communicates what it can and cannot do.
All other plugins will work wether you use declared the component with the plugin outside a <Canvas/>, but the EventPlugin is context bound.

Then maybe we can remove plugin.setup(...) all together: if you want a setup, simply add a context!

We could add API to prevent deep nesting of contexts:

const { T, Canvas } = createT(THREE, [EventPlugin])

return <Canvas contexts={[EventPlugin.Provider]}>
   ...
</Canvas>

[bigmistqke]

Currently i am resolving the methods for each entity to a unique object. This is extra memory overhead per entity.

A solution could be to change the API and resolve the prop dynamically

createEffect(() => {
    for(const key of props){
        // plugin.run returns true if the plugin contained the method
        if(plugins.find(plugin => plugin.run(element, props, key))) return 
        ...
    }
})

If the selector is a createSelector the overhead of doing it during prop resolution would be pretty minimal, most likely.

The API of the plugin should change then, to something like:

const Plugin = plugin([Mesh], 
    { 
        onMouseDown(element, value){ 
            ... 
        }
    }
)
// or
const Plugin = plugin([Mesh], 
    (element, key, value) => {
       ...
    }
)