feat: 503 conditional rendering of primitives

[alvarosabu]

Closes #503

• Object prop is not reactive
• Conditional rendering is not working. v-if

[andretchen0]

Glad to have this update!

I only found a small bit of code that looks like it can be simplified. I won't hold up the PR.

[andretchen0]

props.object, object and instance all point to the same JS object here, so it looks like this can be simplified:

    [....]
    if (tag === 'primitive') {
      if (props.object === undefined) logError('Tres primitives need a prop \'object\'')
      instance = props.object as TresObject
      instance.userData.tres__primitive = true
    }
    else {
    [...]

[alvarosabu]

Hey @andretchen0, thanks for checking it, I ended up modifying this part because we need to clone the prop.object to avoid overwriting the original three object when swapping happens.

[andretchen0]

@alvarosabu

Do you need a hand with the failing tests and linter?

[alvarosabu]

It's pretty much done @andretchen0 if you take another look before merging 🙏🏻

[andretchen0]

I don't know if it can be worked around, but cloning the Three objects means that references in setup are lost. Details in the comments.

[andretchen0]

I'm not sure if there's a workaround, but using a clone here means that references in a component's setup won't work.

I've added a comment to playground/src/pages/primitives.vue with some code that demonstrates the problem.

[alvarosabu]

@andretchen0 Thats a good point thanks for raising it, the problem with the reference comes when we try to make the :object reactive to swap the instance, which completely changes the ref.

Not sure how to deal with that.

[andretchen0]

In nodeOps.ts, I mentioned that cloning means that setup references are lost. Below is some demonstration code that can be pasted here.

useRenderLoop().onLoop(() => {
  torus.rotateX(0.01)
  torusKnot.rotateY(0.01)
})

Both torus and torusKnot continue to exist after the clone, but they no longer point to the on-screen objects, so the on-screen objects don't update.

If the objects aren't clone()d in nodeOps, the on-screen shapes will rotate – but other errors pop up.

I don't know if there's a workaround here. Just pointing it out.

[alvarosabu]

@andretchen0 This argument makes me think we should abandon the idea of trying to make :object prop reactive, swiping instances without losing the ref is getting too complicated.

Users could still use primitives with conditional rendering, I wanted primitive to work similar to component but honestly at this point I don't know how to achieve it.

[andretchen0]

@alvarosabu

I don't understand the internals of Tres well enough to have an opinion on the feasibility here.

I'll start reading the source after I finish <AnimatedSprite /> for Cientos.

I wanted primitive to work similar to component but honestly at this point I don't know how to achieve it.

I agree that this is a worthwhile goal. It'd be great if it "just works".

[alvarosabu]

@andretchen0 let me know if you are up to a pair-programming call to discuss the internals when you get free let me know, we definitely can use your knowledge and your quality feedback inside of the custom renderer code. 💚

[andretchen0]

@alvarosabu

Sure thing. That could be fun!

[alvarosabu]

Hey @andretchen0 I created a thread on the core team discord channel discussing this but to give a summary:

I found a way of making it work (animations), the only constraint is that the object passed through :object needs to be of the same type (mesh -> mesh) (group -> group). If we do (mesh -> group), it doesn't work anymore.

Screen_Recording_2024-02-02_at_12.43.44.mov

[andretchen0]

Thanks! I'll go read the Discord.

[andretchen0]

Again, I'm not sure if this can be worked around, but there's still a problem with references in <script>.

[andretchen0]

It seems like this doesn't break references in <script> per se. The :objects still exist. But they're copied. That means something like the following (probably) wouldn't have the user's desired effect in the playground example:

useRenderLoop().onLoop(({elapsed}) => {
  torus.position.y = Math.sin(elapsed)
})

Whenever the primitive object becomes torus, torus is copied, along with its attributes. But the copy doesn't move like torus moves, because it's a different Torus.

[alvarosabu]

@andretchen0 we will need to explicitly mention on the docs that the user needs to animate the ref (primitiveRef) but not the object (torus) following the same DX as they were using a <TorusMesh ref="torusRef" />

Screen.Recording.2024-02-08.at.10.14.03.mov

There are several reasons why we need to clone the object:

• Since we soft-swipe the instances when :object changes (we maintain the reference but copy all the attributes) that would modify the original object from the setup leading to unwanted side effects.
  It is not possible to pass a ref or reactive as @JaimeTorrealba mentioned in the thread. With clone, we can ensure that swiping between models is possible.

This is what happens without the clone

Screen.Recording.2024-02-08.at.10.24.31.mov

It's either has this limitation of having to use the ref coming from the custom renderer to animate or :object can't be reactive and users will need to use v-if and v-else to swipe models:

<primitive v-if="showA" :object="modelA" />
<primitive v-else :object="modelB" />

I balance through the first option.

[andretchen0]

@alvarosabu

I think the PR as it currently stands is an improvement. I don't want to stand in the way of improvements.

I approved the PR.

[andretchen0]

This sort of error is an itch I can't stop scratching, so if you want to keep scratching ...

Since we soft-swipe the instances when :object changes (we maintain the reference but copy all the attributes) that would modify the original object from the setup leading to unwanted side effects.

Can you elaborate on unwanted side effects?

Technical issues aside, there's a point that isn't clear for me conceptually. To illustrate:

<script>
...
const userMesh = new Mesh(...)
userMesh.position.x = 100

const userMesh2 = new Mesh(...)
userMesh2.position.x = 200
</script>

<template>
...
<primitive ref="primitiveRef" :object="userMesh" :position-x="300" />
...
</template>

• Should userMesh's x be 300? (300 is the value in the primitive)
• And later, if the user does primitiveRef.value.object = userMesh2, does that set userMesh2's x to 300?

For R3F, the answer to both is "yes", it seems. Here's a StackBlitz. Notice that the rotation of the TorusRing increments with every frame, but resets whenever it's made the primitive.object. And the Torus would normally be placed at x = 2000, but its x is set to the primitive's value.

That seems like the right solution to me.

[andretchen0]

tres/src/core/nodeOps.ts

Line 197 in 8408351

const newInstance = nodeOps.createElement('primitive', undefined, undefined, {

I understand that this will make a clone, which is required at the moment, but is there a reason why it's necessary to go through nodeOps.createElement? Is it updating something on the Vue side, maybe?

[alvarosabu]

Can you elaborate on unwanted side effects?

One side-effect is that is not possible to pass a ref or reactive as @JaimeTorrealba mentioned in the thread on Discord. With clone, we can ensure that swiping between models is possible.

Should userMesh's x be 300? (300 is the value in the primitive)

Yes, the prop has priority because it will overwrite the mesh positions on the setup.

And later, if the user does primitiveRef.value.object = userMesh2, does that set userMesh2's x to 300?

Users shouldn't overwrite vue template refs, wouldn't it be kind of an antipattern? I also see the users complaining about having to do this extra step of primitiveRef.value.object = userMesh2 vs :object being reactive.

const newInstance = nodeOps.createElement('primitive', undefined, undefined, {

That was to not having to duplicate the same code of the createElement inside of the pathProp since primitives have some special treatment, like localstate flags and such.