While working with Three.js on CubeWall and various other projects and experiments I often found myself getting a little frustrated having to repeat various tasks over and over again.
Things like setting up a camera, scene and renderer each time may seem like remedial tasks at first, but just like any new toy you don’t want to have to sit down and read the manual, you want to play, touch and experiment and more often than not, break.
This is what led me to create Threesy.js. It allowed me to automate various Three.js setup requirements so I could start doing the fun stuff.
Stop messing with me
As time progressed and my Three.js requirements changed, I found myself adding more and more to Threesy. Each time adding something that I thought was useful and would help me speed up my development process. Granted some things may not be that useful to some and I could have simply written them in each implementation, but for me it was easier to have all my methods in one place saving on repetition and well, I hope, future RSI.
If you are interested in knowing how to set up Three.js manually I recommend you go through the documentation, or alternatively I find Jerome Etienne’s blog a great source of knowledge and inspiration.
Before you begin, think about this
If you have used Three.js before you would know that certain elements can only be instantiated once, after that they can not be changed only manipulated.
This has to be taken into consideration when using Threesy, because for each necessary Three.js element that is not pre set, Threesy will automatically create using its default settings.
So if you want to preset a specific renderer, or set the amount of lights that are to be available to the renderer at runtime, then you must set these before initializing Threesy.
Eh what can you do?
Threesy contains the following methods to help you with your Three.js development. To help you know what needs to be preset before instantiating Threesy, these will be listed first.
Setting up Threesy
Three.js renderers seem to have some difficulties changing the number of lights available at runtime. The default is 4 so if you need more light be sure to change the maximum number of lights before instantiating the renderer.
/** * set maximum number of lights the renderer can render */ Threesy.maxLights( "Number of Lights in the scene" )
Threesy has integrated Three.js Detector to automatically detect the available renderer for the browser, switching between WebGLRenderer and CanvasRenderer. So if you are using a specific renderer be sure to set it.
/** * Set the renderer, if not set one will automatically be assigned based * on browser support */ Threesy.renderer = "Desired Three.js renderer"
Making a game or application that requires many textures can slow down your application, giving your renderer indigestion trying to digest all your textures at once. To help with this you can use MicroCache as well as many other optimization techniques.
To use MicroCache download the MicroCache.js file, include it in your application and then pass it through to Threesy. A more detailed explanation, as well as other optimization tips can be found on Jerome Etienne’s article “Performance: caching material”.
/** * add MicroCache to cache textures passed to the renderer * @param MicroCache (Object) - MicroCache.js */ Threesy.addMicroCache( new MicroCache() );
If you want to set all the scene properties at once, you can do it with this handy method.
/** * add camera, must be set before initiated otherwise renderer will not be set * @param renderer (Object) - THREE.js renderer * @param camera (Object) - THREE.js camera * @param light (Object) - THREE.js light */ Threesy.setSceneProperties( "Renderer", "Camera", "Light" );
Starting The Action
If you are happy for Threesy to use Three.js’s default settings and automatically choosing your renderer then this is all you need to do to get the party started.
/** * init * @param divContainer (Object) - DOM element * @param width (Number/int) - default 550 - width of the viewport * optional * @param height (Number/int) - default - 400 - height of the viewport * optional */ Threesy.init( divContainer, width, height );
The following methods are to be used once Threesy has been instantiated.
Add to scene
Passing an object reference allows you to keep track of all elements currently added to the scene and remove them by their reference.
/** * Add an object to the scene * @param Object3D (Object) - THREE.js mesh / light / object * @param objRef (String/int) - Reference for the passed object */ Threesy.addToScene( "Object3D", "objRef" );
Remove from scene
/** * REMOVE an object from the scene * @param element (Object) - THREE.js mesh / light / object 3d */ Threesy.removeFromScene( "Object 3D" );
Remove from scene by ID
If you specified an ID as you passed an object into the scene, then you will be able to remove it using its ID.
/** * REMOVE an element from the scene by using its registered id when added to the scene * @param id (String) - Reference of object */ Threesy.removeFromSceneByID( "Object 3D reference " );
/** * trace elements in scene that have been logged with a reference */ Threesy.logScene();
Adding a light
Passing a light reference will help keep track of lights added to the scene. If a reference is not specified a reference will automatically be created and appended to the light object. If remove all is selected, all lights will be removed from the scene before adding any new lights.
/** * add light * @param light (Object) - THREE.js light * @param ref (String/int) - THREE.js light reference * @param removeAll (BOOL) - if to remove all previous lights */ Threesy.addLight( "Three.js Light", "Remove all previous", " add light ref" );
/** * return an array containing all lights * added to the scene * @return (Array) - Three.js light objects */ Threesy.lights();
This allows you to remove a single light by passing it through to the method, specifying its id or removing all lights from the scene.
/** * remove light by id * @param light (Object) - light * @param id (String/int) - light id * @param removeAll (Boolean) - Remove All Lights */ Threesy.removeLight( "Light to remove", "Light reference", "Remove all lights" );
/** * get total lights in the scene * @return (Number) - Number of lights added to the scene */ Threesy.totalLights()
/** * get light by id * @param id (String/int) - THREE.js light reference * @return (Object) - Three.js light object */ Threesy.getLight( "id" );
</pre> /** * trace out lights in scene */ Threesy.logLights(); <pre>
/** * add camera, removes all previous cameras added * @param newCam (Object) - new camera to add to scene */ Threesy.addCamera( "newCam" );
As well as setting up the Three.js and adding various elements, I have also added helper functions.
/** * Slice a THREE.js texture, position the texture using the parameters set * @param texture (Object) - THREE.js Texture * @param offsetX (Number) - cimage x position offset * @param offsetY (Number ) - image y position offset * @param sliceWidth (Number) - width of slice * @param sliceHeight (Number) - height of slice * @param clone (Boolean) - clone texture if true, otherwise reposition the current texture * @param cacheID (String|undefined|null) - cacheID if needed in order to cache the texture using microcache */ Threesy.sliceTexture(" texture", "offsetX", "offsetY", "sliceWidth", "sliceHeight", "clone", "cacheID" )
Detect Object Selected
/** * Detect object that is within the coordinates passed * @param xPos (Number) - X position of the mouse * @param yPos (Number) - Y position of the mouse * @return ( object ) return intersecting objects to mouse choordinates, otherwise undefined */ Threesy.getObjectInBounds( xPos, yPos );
/* * clear the renderer */ Threesy.clearRenderer();
/** * Removes all elements from the scene * Removes all lights * Clears the renderer and nullifies all objects and elements */ Threesy.dispose();
And there you have it, Threesy in all its glory. Of course when using Threesy you don’t have to use all the methods available, you can access the camera, renderer and scene etc. in just the same way you would Three.js, for example “Threesy.scene”. Make sure you download Three.js as this must be available for Threesy to work.