The WML Three.js library provides a streamlined way to integrate Three.js into your Angular applications. It offers a set of classes and utilities that simplify the creation and management of 3D scenes, renderers, cameras, controls, lights, objects, and animations. This library is designed to help developers quickly set up interactive 3D graphics without dealing with the boilerplate code typically associated with Three.js.
[ ] multiple renderer need to accurately choose the correct object from the mouse
[]
Caveats
must set in tsconfig.json compilerOptions
"noImplicitAny": false,
"skipLibCheck": true
also when you know a property exists on an object you must use @ts-ignore and debug the property to make sure until we can have more advanced typescript types, for our classes we provide getters for different types of the same property but for threejs objects thats harder if not impossible to do
Usage
Getting Started
Animating Elements
Adding An Inspector
Multiple Renderers
Different Light Types
Selecting Objects With Your Mouse
Loading Various Types of Models
References
WMLThreeProps
Property
Type
Description
renderers
Array<any | Renderer>
List of renderers used in the application, defaulting to a WebGLRenderer with antialiasing enabled. It is an array because effect composers are renderers
rendererParentElement
HTMLElement
The DOM element to which the renderer’s canvas will be appended. Defaults to document.body.
scenes
Array<Scene>
Array of Three.js scenes. Defaults to a single new Scene.
cameras
Array<Camera>
List of cameras used in the scenes.
controls
Array<Controls<any>>
Array of control mechanisms like OrbitControls for user interaction.
inspectors
Array<InspectorOptions>
Configuration for GUI inspectors like DatGUI or LilGUI, including options for real-time parameter adjustments.
lights
Array<WMLThreeLightProps>
List of light configurations, each containing a THREE.Light object and related properties like helpers and shadow helpers.
rayCasters
Array<WMLThreeRayCasterProps>
Raycaster configurations used for detecting user interactions with objects in the scene.
objects
Array<WMLThreeObjectProps>
List of object configurations, including geometries, materials, meshes, and textures.
clock
Clock
Three.js Clock object used for tracking time in animations.
animateFunctions
Array<Function>
List of custom functions to be called on each frame of the animation loop. Each function receives an object containing the Clock as a parameter.
Methods
Method
Return Type
Description
init(props?)
Promise<void>
Initializes the Three.js environment with optional parameters to enable or disable specific initialization steps like cameras, controls, lights, objects, and animations.
preCheck()
void
Performs preliminary checks to ensure that the environment supports Three.js (e.g., checking for the presence of the document object).
animate()
void
Default animation loop function that calls all functions in animateFunctions and renders the current scene with the current camera.
addRendererToDOM()
void
Appends the renderer’s canvas to the rendererParentElement and sets up initial renderer configurations like size, pixel ratio, and shadow map settings.
initCameras(props?)
void
Initializes cameras with optional parameters like field of view angle, near and far clipping planes.
initControls()
void
Sets up user interaction controls, such as OrbitControls, associated with the current camera and renderer.
initLights()
void
Adds lights to the scene based on the configurations in lights, including optional helpers and shadow helpers for debugging and visualization.
initObjects()
Promise<void>
Loads and adds objects to the scene, handling both regular meshes and loaded assets like textures and GLTF models.
initInspectors()
void
Initializes GUI inspectors for real-time parameter adjustments during development.
initRayCasters()
void
Sets up raycasters for detecting user interactions with objects in the scene, including event listeners for pointer movements.
listenForWindowResize()
void
Adds an event listener to handle window resizing, updating camera aspects and renderer sizes accordingly.
getRendererParentDetails()
{ width: number; height: number; }
Retrieves the dimensions of the rendererParentElement to configure renderer and camera settings.
getCurentScene()
Scene
Returns the current scene being used.
getCurentCamera()
Camera
Returns the current camera being used.
getCurrentRenderer()
Renderer
Returns the current renderer being used.
getCurrentControls()
Controls<any>
Returns the current control mechanism being used.
getCurrentRayCaster()
WMLThreeRayCasterProps
Returns the current raycaster configuration being used.
InspectorOptions
Property
Type
Description
gui
DatGUI | LilGUI
An instance of the GUI inspector to be used for real-time adjustments of properties on three js objects.
values
{ [key: string]: InspectorOption }
Configuration options for the inspector, including values and change handlers.
options
{ [key: string]: any }
Internal state management for the inspector options.
InspectorOption
Property
Type
Description
value
any
The initial value of the option to be controlled via the inspector.
onChange
(value: any, init: boolean) => void
Optional function to be called when the value changes.
min
number
Optional minimum value for numerical controls.
max
number
Optional maximum value for numerical controls.
WMLCommonThreeProps
Property
Type
Description
scene
Scene
Getter and setter for the current scene.
camera
Camera
Getter and setter for the current camera.
renderer
WebGLRenderer
Getter and setter for the current renderer.
control
OrbitControls
Getter and setter for the current control mechanism, specifically OrbitControls.
Method
Return Type
Description
updateCameraPosition(props?)
void
Updates the camera’s position and optionally its orientation using lookAt. Also updates controls if applicable.
WMLThreeObjectProps
Property
Type
Description
geometries
Array<BufferGeometry>
List of geometries to be used in creating meshes.
materials
Array<Material | Material[]>
List of materials or arrays of materials for the meshes.
meshes
Array<Object3D | GLTF>
List of meshes or loaded models to be added to the scene.
textures
Array<WMLThreeTexturesProps>
List of texture configurations to be loaded and applied to materials or meshes.
WMLCommonThreeObjectProps
Property
Type
Description
geometry
BufferGeometry
Getter and setter for the primary geometry.
material
Material | Material[]
Getter and setter for the primary material(s).
mesh
Object3D | GLTF
Getter and setter for the primary mesh or model.
texture
WMLThreeTexturesProps
Getter and setter for the primary texture configuration.
Method
Return Type
Description
toggleShadow(props?)
void
Toggles the shadow casting and receiving properties of the mesh.
WMLThreeLightProps
Property
Type
Description
light
Light
The Three.js light object to be added to the scene.
addHelper
boolean
Flag indicating whether to add a helper object for visualizing the light. The helper class is based on the class of the light property
helper
Object3D
The helper object associated with the light, if any.
addShadowHelper
boolean
Flag indicating whether to add a shadow camera helper for debugging shadows. its class is the CameraHelper
shadowHelper
CameraHelper
The shadow camera helper associated with the light’s shadow camera, if any.
Method
Return Type
Description
toggleShadow(props?)
void
Toggles the shadow casting and receiving properties of the light.
updateCamera()
void
Updates the light’s shadow camera projection matrix and associated helpers.
WMLThreeTexturesProps
Property
Type
Description
manager
LoadingManager
The loading manager to manage multiple texture loading operations.
group
Array<TextureLoadOption>
Array of texture load options, each containing URL, loader, and optional callbacks for load events.
TextureLoadOption
Property
Type
Description
url
string
The URL of the texture to be loaded.
loader
Loader
The loader instance to use for loading the texture.
onLoad
(data: any) => void
Optional callback function to be called upon successful loading.
onProgress
(event: ProgressEvent) => void
Optional callback for progress updates during loading.
onError
(err: unknown) => void
Optional callback to handle errors during loading.
WMLThreeRayCasterProps
Property
Type
Description
raycaster
Raycaster
The Three.js Raycaster instance used for detecting intersections.
mousePosition
Vector2
The normalized mouse position used for raycasting calculations.
hasMouseEnteredRenderer
boolean
Flag to indicate whether the mouse has entered the renderer area, used to optimize raycasting checks.