How to understand "useBox" in react-three-fiber

Question

I'm interested in learning how to create dynamic objects and group them together entirely in react/JavaScript. I'm looking at the chair and table in this example as my model:

https://codesandbox.io/s/ragdoll-physics-forked-bntr9

At this point, I'm not as concerned about the "physics" but just how to create the three object such as a table that consist of 5 3D-Rectangles.

I downloaded the above example, and this is the code for the table:

function Table() {
  const [seat] = useBox(() => ({ type: 'Static', position: [9, -0.8, 0], args: [2.5, 0.25, 2.5] }))
  const [leg1] = useBox(() => ({ type: 'Static', position: [7.2, -3, 1.8], args: [0.25, 2, 0.25] }))
  const [leg2] = useBox(() => ({ type: 'Static', position: [10.8, -3, 1.8], args: [0.25, 2, 0.25] }))
  const [leg3] = useBox(() => ({ type: 'Static', position: [7.2, -3, -1.8], args: [0.25, 2, 0.25] }))
  const [leg4] = useBox(() => ({ type: 'Static', position: [10.8, -3, -1.8], args: [0.25, 2, 0.25] }))
  return (
    <>
      <Box scale={[5, 0.5, 5]} ref={seat} />
      <Box scale={[0.5, 4, 0.5]} ref={leg1} />
      <Box scale={[0.5, 4, 0.5]} ref={leg2} />
      <Box scale={[0.5, 4, 0.5]} ref={leg3} />
      <Box scale={[0.5, 4, 0.5]} ref={leg4} />
      <Suspense fallback={null}>
        <Mug />
      </Suspense>
    </>
  )
}

And at the top of the program I see this:

import {
  Physics,
  useBox,
  useCompoundBody,
  useCylinder,
  useSphere,
  usePlane,
  useConeTwistConstraint,
  usePointToPointConstraint
} from '@react-three/cannon'

Googling react-three/cannon took me to https://opensourcelibs.com/lib/use-cannon, and the "github" link took me to https://github.com/pmndrs/use-cannon, which I downloaded.

Is there a document to the "useBox", or do I have just have to read code to figure out how it works?

Without some doc, I can only do controlled variations, for example, suppose I just want to make the table legs longer, or the table top bigger? I don't understand what joins the legs to the table, but I figure it must be the position or args:

I tried changing 1.8 to 2.8 as follows: from

const [leg1] = useBox(() => ({ type: 'Static', position: [7.2, -3, 1.8], args: [0.25, 2, 0.25] }))

to

const [leg1] = useBox(() => ({ type: 'Static', position: [7.2, -3, 2.8], args: [0.25, 2, 0.25] }))

and I could see the leg come out from the table top.

I knew all table legs had equal length, so I tried changing some number that was the same for all four legs (then later noticed two had 1.l8 and two had -1.8). I'm also guessing that some set of three parameters must be length, width, height.

Then I tried changing:

  <Box scale={[0.5, 4, 0.5]} ref={leg1} />
  <Box scale={[0.5, 4, 0.5]} ref={leg2} />

to

  <Box scale={[0.5, 6, 0.5]} ref={leg1} />
  <Box scale={[0.5, 6, 0.5]} ref={leg2} />

And that deed indeed length two legs, but up through the top of the table.

So bottom line question is not how to do change the length of the legs, but how to find the documentation.

I searched the pmndrs library for "useBox", and see a many many matches:

I looked at the sources\hooks.ts and found this, which doesn't help me at all:

export function useBox(fn: GetByIndex<BoxProps>, fwdRef: Ref<Object3D> = null, deps?: DependencyList) {
  const defaultBoxArgs: Triplet = [1, 1, 1]
  return useBody('Box', fn, (args = defaultBoxArgs): Triplet => args, fwdRef, deps)
}

Answer 1

At this point, I'm not as concerned about the "physics" but just how to create the three object such as a table that consist of 5 3D-Rectangles.

useBox is physics-only, it comes from the physics library "cannon", not from threejs or r3f. it approximates a shape and links it to arbitrary geometry. the physics engine now manages a literal box, a cube, and subjects it to gravity and other colliders. if your shape resembles something like a sphere you'd use useSphere instead and so on.

the example you have picked to learn either threejs or r3f is a hard one, i would not start with physics. the example on the github main page (https://codesandbox.io/s/rrppl0y8l4?file=/src/App.js) covers some basics, combine this with threejs docs at hand and you will have a much more comfortable learning experience.

a box in threejs (in react notation) is no more than this:

<mesh position={[1, 2, 3]} rotation={[Math.PI / 3, 0, 0]}>
  <boxGeometry />
  <meshBasicMaterial color="red" />
</mesh>

and you form groups like so:

<group>
  <mesh>
    ..

if you want to start with physics later, here are some easier ones:

• falling cubes: https://codesandbox.io/s/simple-physics-demo-z8e6m
• christmas baubles: https://codesandbox.io/s/bestservedbold-christmas-baubles-zxpv7
• arkanoid: https://codesandbox.io/s/arkanoid-under-60-loc-66cd7