Requirements

These hooks are all context-sensitive, as they depend on the ThreeKit authentication provided by the <Viewer> component. This means that they can only be used from within separate components from the <Viewer>, and then referenced as children of a <Viewer> component.

The same is true of the react-three-fiber and Three.JS's useThree() and useFrame() hooks, which are also context-sensitive and need to be used in children components of the Canvas, which is created by the component. It is likely that when you need to build your own components with the useAsset() and useScene() hooks you will also need to make use of the useThree() and useFrame() hooks.

useAsset()

This hook allows for the loading of a ThreeKit model asset for assignment to a const/variable. This would allow for easier parsing of its contents and checking for when it finishes loading. It would also enable you to build your own <Asset> component, as shown in the example below.

Prop List

assetId: String - Required

This represents the assetId of either a Catalog Item or a Model Asset from the ThreeKit Platform.

configuration: Configuration - Optional

This prop can be used to request the gltf for a particular variant of the asset. If not specified, it will request the default configuration of the asset as specified in the Platform.

Connect this to a state variable that stores the configuration data, in order to update the Model on every state change.

It is recommended to use the Composable Configurator to drive this configuration.

settings: ExporterSettings - Optional

These settings allow you to choose how the asset's contents should be exported and interpreted by the gltf exporter.

Example

Here is an example of how you could make use of the useAsset() hook to build your own version of the <Asset> component.

import { forwardRef } from "react";
import { type AssetProps, useAsset } from "@threekit/react-three-fiber";
import * as THREE from "three";

export default forwardRef(function Asset(
  props: AssetProps,
  ref: React.Ref<THREE.Object3D>
) {
  const { assetId, configuration, ...r3fProps } = props;
  const threekitAsset = useAsset({ assetId, configuration });

  return (
    <>
      {threekitAsset ? (
        <primitive
          object={threekitAsset.scene}
          caseShadows
          receiveShadows
          {...r3fProps}
          ref={ref}
        />
      ) : null}
    </>
  );
});

useScene()

This hook allows for the loading of a ThreeKit scene asset for assignment to a const/variable. This would allow for easier parsing of its contents and checking for when it finishes loading. It would primarily be useful in allowing you to build your own <Scene> component, as shown in the example.

🚧

Warning!

Loading a scene asset with this hook is insufficient without further processing the contents as shown in the example.

Lights and cameras will not get automatically set in the Canvas by the use of this hook. They would need to be accessed from the resulting scene graph and set using the methods available on the useThree hook from react-three-fiber.