Build your truck library

This repository contains the code to load the BYT viewer into an existing React project.

Installation

1. Set up model and material libraries in your public directory according to instructions
2. Include this library into your project

npm i tmhe-buildyourtruck-lib

Use the viewer

1. Import the viewer component from the library

 import { BYTViewer } from "tmhe-buildyourtruck-lib";

2. Add the BYTViewer component to your document

<BYTViewer className="w-full h-full" />

3. You can communicate with the viewer by emitting events, similarly you can listen for events coming from the viewer

• Include the emit function and useBYTViewer hook

 import { emit, useBYTViewer } from "tmhe-buildyourtruck-lib"

• Call the functions via the emit function. Your dev environment should give you code intellisense if you're using typescript. Otherwise the specs are listed below

 emit("eventName", eventParameters)

• Listen for events by calling useBYTViewer() with the correct event name

 useBYTViewer(eventName, eventHandler);

For each event, you need to call useBYTViewer

4. Call the setConfig function to preload all materials & textures used for all models.

5. Wait until the config is loaded, your app can listen for the configLoaded event. You can also listen for the progress updates.

 useBYTViewer("configLoaded", () => {});

6. Call the loadModel function to load a model. When the model is finished loading and parsed it will trigger the modelLoaded event. You can also listen for the progress updates.

emit("loadModel", modelToLoad);
...
useBYTViewer("modelLoaded", () => {});

Full list of functions & events

You can include Typescript types from tmhe-buildyourtruck-lib/dist/types

Functions

| function name | parameters | description | | --------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | setConfig | { decoderPath: string; materialsPath: string; modelsPath: string; states?: IdUpdate[] } | Configure the viewer so it knows where to find the materials, textures & model data files (Ommit the final trailing /). IdUpdate is an array of IDs you want to send on startup (see toggleId below). Decoderpath is the location of the DRACO decoder used to parse the highly compressed model files. | | loadModel | string | Load specific 3D model | | toggleId | { ID: string } | Send an ID to update the model. IDs are resolved into specific updates (toggle, material/position update(s)) | | setActiveCamera | CAMERA_TYPE | Switch the current camera. CAMERA_TYPE is an enum but accepts number too. INSIDE=0, OUTSIDE=1 | | resetCamera | none | Reset the current camera position and rotation to it's default / initial position | | showBackground | boolean | Show a clay-rendered background of a warehouse. Default is off |

Unused functions (for reference): toggleElement, toggleState, updateMaterial, sendId. These functions are not documented and not wired up at this moment as they require an in-depth knowledge of the 3D Node tree

Methods and events marked as __internal should not be used

Events

| event name | parameters | description | | -------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | configProgress | { progress: number; } | Percentage loaded of material library (0-1) | | configLoaded | none | Material library is loaded successfully. It's required to wait for this otherwise the model will not look correctly | | modelProgress | { progress: number; } | Percentage loaded of the model (0-1) | | modelLoaded | none | The model is fully loaded and being parsed. Depending on the device it'll take another 1-4s to parse the model and set it's intial look. | | cameraSwitched | { activeCam: CAMERA_TYPE } | The camera was switched. CAMERA_TYPE is an enum. INSIDE=0, OUTSIDE=1 |

Deployment

The library can be integrated into your project as is. The location of the external asset dependencies are defined at runtime. The paths to these assets can be relative or absolute to the location of the app URL. You can choose to use separate paths or put everything inside 1 directory.

1. Draco directory (config.decoderPath):
   Should contain a subdirectory gltf with the following files *

   • draco_decoder.js
   • draco_decoder.wasm
   • draco_wasm_wrapper.js

2. Materials directory (config.materialsPath):

   • File Material-library.glb
   • Directory textures *

3. Models directory (config.modelsPath):
   Should contain a subdirectory for each model. Inside should have these 2 files

   • Config.json
   • Model.glb

* These assets can be copied from the library directory (node_modules/tmhe-buildyourtruck-lib/public).