Can I load a speckle stream in Threejs application?

I’m thinking of building a web-based game that speckle stream can be used as a background model. Can I load a speckle stream in Threejs application?

Hi Chloe!

Of course, Speckle’s viewer is built with Three.js and you should be able to easily load Speckle objects in your scene using our Object Loader library.
Our docs on using it are very scarce at the moment but we’re hoping to improve them soon!


Beyond the object loader, you’ll probably also need the converter. We should defintively make this a proper threejs loader in the future to serve this kind of use cases :grimacing:

IIRC, @kgoulding/@haitheredavid actually did wrap the speckle parts in a proper threejs loader! Maybe they can share some of the experience (and pain) of doing so :slight_smile:

1 Like

We put together a sketch or two that uses react-three-fiber, but I don’t recall if there was anything with just three. This isn’t my area of expertise, so I can’t say much about the process but I remember the result of integrating the a speckle stream with the converter and objectloader was pretty simple. But @kgoulding can shine a bit more light on this since he’s much more familiar with three.

We do have some plans for a sprint in the near future to start building out some goods for speckle and r3f :smiley:


It wasn’t too painful actually - but did require a bit of a hacky approach. The loader typically requires a URL, but in this case we’re using a JSON-encoded string containing a speckle token alongside a speckle object URL.

ViewerObjectLoader.js (2.6 KB)
SpeckleLoader.js (1.3 KB)


Thank you @kgoulding ! I tried to download the files, but can’t…

So I need both(ViewerObjectLoader.js &SpeckleLoader.js) to load a speckle stream? It would be great if you can share some code snippets as examples, thanks!

@chloesun + @kgoulding it might be because uploading js files might trigger discoure’s hax0r radar; we could try with a zip file/embedding them as code snippets :grimacing:

1 Like

import ObjectLoader from '@speckle/objectloader'
import Converter from './Converter'
Guess I also need to include objectLoader and Converter?
These are the correct files?

1 Like

Yes, those look like the ones


Thanks @kgoulding , sorry more questions…
How to generate a speckle token, and what is a speckle object URL, something like this serverUrl/streams/streamId? I need to load the entire scene of a stream.

hey chloe!

instructions for creating a token can be found here in

an object url is the direct url to the object on your server in the form serverUrl/streams/<streamId>/objects/<objectID> which you can get by clicking into objects from the web

eg: a facade panel on the speckle haus stream looks like this:

click here to see it in the web

all commits have a root object which is the id you see in the referencedObject field of the commit. you can use this object if you need the whole commit. eg for the above stream, it would be:

click here to see this object in the web


Thanks a lot @izzylys !

1 Like

const objectUrl = "";
const speckleToken = "randomtoken";

const model = new SpeckleLoader(objectUrl, speckleToken);

This is what I tried to load speckle stream, and I got the message error three.min.js:517 THREE.Object3D.add: object not an instance of THREE.Object3D. What could possibly go wrong?

Here’s how we do it in the viewer example/testing ground app (you can test it live by running npm run serve inside the viewer package folder):

import Viewer from './modules/Viewer'
window.v = new Viewer( { container: document.getElementById( 'renderer' ) } ) // note you'll need a div with the id set to renderer in your document

window.loadData = async function loadData() {
  const objUrl = "etc"
  await v.loadObject( url )

// in the html somewhere
<button class="" onclick="loadData()">Load Object</button>

Note most of the interaction logic is in app.js if you go digging for it.

Let us know if this is something that works for you!

1 Like

Finally got the stream rendered in the threejs scene. I had to deliberately remove the point and line objects( geometry.boundingSphere is undefined.), otherwise it can’t render( performing a raycast in the render function). How can I place the speckle model in the scene properly, like on top of the grid?


Threejs defaults to Y up; you probably will want to swap to have in your scene Z as up for the camera you use (iirc something like yourCamera.up.set(0, 0, 1);

1 Like

Explore a playful way to showcase projects


:eyes: You know this begs for a little gif, not to mention a demo link :eyes:

1 Like

need more development for a demo…wip