The <needle-engine> web-component comes with a nice collection of built-in attributes that can be used to modify the look and feel of the loaded scene without the need to add or edit the three.js scene directly.
The table below shows a list of the most important ones:

AttributeDescription
Loading
srcPath to one or multiple glTF or glb files.
Supported types are string, string[] or a stringified array (, separated)
dracoDecoderPathURL to the draco decoder
dracoDecoderTypedraco decoder type. Options are wasm or js. See three.js documentationopen in new window
ktx2DecoderPathURL to the KTX2 decoder
Rendering
skybox-imageURL to a skybox image (background image)
environment-imageoptional, URL to a environment image (environment light)
Interaction
autoplayadd or set to true to auto play animations e.g. <needle-engine autoplay
camera-controlsadd or set to true to automatically add OrbitControls if no camera controls are found in the scene
auto-rotateadd to enable auto-rotate (only used with camera-controls)
Events
loadstartName of the function to call when loading starts. Note that the arguments are (ctx:Context, evt:Event). You can call evt.preventDefault() to hide the default loading overlay
progressName of the function to call when loading updates. onProgress(ctx:Context, evt: {detail: {context:Context, name:string, index:number, count:number, totalProgress01:number}) { ... }
loadfinishedName of the function to call when loading finishes
Loading DisplayAvailable options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing
loading-styleOptions are light or dark
loading-background-colorPRO — Change the loading background color (e.g. =#dd5500)
loading-text-colorPRO — Change the loading text color
loading-logo-srcPRO — Change the loading logo image
primary-colorPRO — Change the primary loading color
secondary-colorPRO — Change the secondary loading color
hide-loading-overlayPRO — Do not show the loading overlay, added in Needle Engine > 3.17.1
Internal
hashUsed internally, is appended to the files being loaded to force an update (e.g. when the browser has cached a glb file). Should not be edited manually.

Examples

<!-- Setting the path to a custom glb to be loaded -->
<needle-engine src="path/to/your.glb"></needle-engine>
<!-- Overriding where the draco decoder is located -->
<needle-engine src="path/to/your.glb" dracoDecoderPath="path/to/draco/folder"></needle-engine>

Setting environment images, playing animation and automatic camera controls. See it live on stackblitzopen in new window

<needle-engine
      camera-controls
      auto-rotate
      autoplay
      skybox-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      environment-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      src="https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/DamagedHelmet/glTF-Embedded/DamagedHelmet.gltf"
      >
      </needle-engine>

Receiving an event when the needle-engine context has finished loading:

<needle-engine loadfinished="onLoadFinished"> </needle-engine>
<script>
    function onLoadFinished() {
        console.log("Needle Engine has finished loading");
    }
</script>

Custom Loading Style (PRO)

You can easily modify how Needle Engine looks by setting the appropriate attributes on the <needle-engine> web component. Please see the table above for details.

custom loading
See code on githubopen in new window