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
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