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:
Attribute | Description |
---|---|
Loading | |
src | Path to one or multiple glTF or glb files. Supported types are string , string[] or a stringified array (, separated) |
dracoDecoderPath | URL to the draco decoder |
dracoDecoderType | draco decoder type. Options are wasm or js . See three.js documentation |
ktx2DecoderPath | URL to the KTX2 decoder |
Rendering | |
background-color | optional, hex color to be used as a background color. Examples: rgb(255, 200, 100) , #dddd00 |
background-image | optional, URL to a skybox image (background image) or a preset string: studio , blurred-skybox , quicklook , quicklook-ar |
background-blurriness | optional, bluriness value between 0 (no blur) and 1 (max blur) for the background-image . Example: background-blurriness="0.5" |
environment-image | optional, URL to a environment image (environment light) or a preset string: studio , blurred-skybox , quicklook , quicklook-ar |
contactshadows | optional, render contact shadows |
tone-mapping | optional, supported values are none , linear , neutral , agx |
tone-mapping-exposure | optional number e.g. increase exposure with tone-mapping-exposure="1.5" , requires tone-mapping to be set |
Interaction | |
autoplay | add or set to true to auto play animations e.g. <needle-engine autoplay |
camera-controls | add or set to true to automatically add OrbitControls if no camera controls are found in the scene |
auto-rotate | add to enable auto-rotate (only used with camera-controls ) |
Events | |
loadstart | Name 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 |
progress | Name of the function to call when loading updates. onProgress(ctx:Context, evt: {detail: {context:Context, name:string, index:number, count:number, totalProgress01:number}) { ... } |
loadfinished | Name of the function to call when loading finishes |
Loading Display | Available options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing |
loading-style | Options are light or dark |
loading-background-color | PRO — Change the loading background color (e.g. =#dd5500 ) |
loading-text-color | PRO — Change the loading text color |
loading-logo-src | PRO — Change the loading logo image |
primary-color | PRO — Change the primary loading color |
secondary-color | PRO — Change the secondary loading color |
hide-loading-overlay | PRO — Do not show the loading overlay, added in Needle Engine > 3.17.1 |
Internal | |
hash | Used 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 stackblitz
<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.