WML Three

starlightViewModes.switchTofunction h(){const t=window.location.hash;document.querySelectorAll(".starlight-view-modes-switcher-a").forEach(e=>{e.href&&(e.href=e.href.split("#")[0]+t)})}h();window.addEventListener("hashchange",h);The WML Three.js library provides a streamlined way to integrate Three.js into your applications. THIS LIBRARY DOES NOT DEPEND ON ANGULAR SO YOU CAN USE IN ANY PROJECT, Astro, React, Svelte, Vue, Next.js, etc. 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.

Installation

Section titled “Installation”Terminal window


npm install -s --verbose @windmillcode/wml-three @windmillcode/wml-components-base three

Roadmap

Section titled “Roadmap”[ ] multiple renderers need to be able to accurately choose the correct object from the mouse[ ] examples with the effect composers[ ] any unifed and comphesive progress loader for all features in a threejs prop

Caveats

Section titled “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 dosometimes it seems there is a resize needed in order to see the threejs scene. you need to set a delay now before calling WMLThreeProps.init because there seems to be an issue with Angular v19 where the height of the element will be 0 before initial navigation of an element. It might be we have to listen for the resize on the element itselfensure you are using the exact version that this package is using or you might get severe type errors, these can be ignored as fundamental changes in three.js features truly require you to change the version but if you can get past types that will be great

Usage

Section titled “Usage”

References

Section titled “References”

`WMLThreeProps`

Section titled “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

Section titled “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 for every renderer in the renderers array.
`initRenderers()`	`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`

Section titled “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 Section titled “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.

`WMLThreeCommonProps`

Section titled “WMLThreeCommonProps”

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`

Section titled “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 \| CSS2DObject>`	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.
`regularMeshes`	`Array<Mesh>`	Returns the array as type Mesh from the `meshes` property.
`gltfMeshes`	`Array<GLTF>`	Returns the array as type GLTF from the `meshes` property.
`css2dMeshes`	`Array<CSS2DObject>`	Returns the array as type CSS2DObject from the `meshes` property.
`instancedMeshes`	`Array<InstancedMesh>`	Returns the array as type InstancedMesh from the `meshes` property.

`WMLThreeCommonObjectProps`

Section titled “WMLThreeCommonObjectProps”

Property	Type	Description
`geometry`	`BufferGeometry`	Getter and setter for the primary geometry of the object.
`material`	`Material \| Material[]`	Getter and setter for the primary material(s) used by the object.
`mesh`	`Object3D \| GLTF \| CSS2DObject`	Getter and setter for the primary mesh or model used by the object.
`regularMesh`	`Mesh`	Getter and setter for the regular mesh from the `meshes` property.
`gltfMesh`	`GLTF`	Getter and setter for the GLTF mesh from the `meshes` property.
`css2dMesh`	`CSS2DObject`	Getter and setter for the CSS2DObject from the `meshes` property.
`instancedMesh`	`InstancedMesh`	Getter and setter for the instanced mesh from the `meshes` property.
`texture`	`WMLThreeTexturesProps`	Getter and setter for the primary texture configuration of the object.

`Methods`

Section titled “Methods”

Name	Signature	Description
`toggleShadow`	`(props: {cast?: boolean, receive?: boolean}) => void`	Toggles the shadow casting and receiving properties of the `regularMesh` based on the provided arguments.
`makeModelLieFlat`	`() => void`	Rotates the `regularMesh` so that it lies flat, intended for use with planes.
`createMesh`	`(geometry: BufferGeometry, material: Material) => Mesh`	Creates and returns a new `Mesh` object using the provided geometry and material.

`WMLThreeLightProps`

Section titled “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`

Section titled “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`

Section titled “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`

Section titled “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.

Name	Signature	Description
`intersectCallback`	`(intersects: Intersection<Object3D<Object3DEventMap>>[]) => void`	Callback function to handle the results of raycasting intersections.

Changelog

Section titled “Changelog”

v18.2.4100 [9/19/24]

Section titled “v18.2.4100 [9/19/24]”first version of library

v18.2.4200 [9/20/24]

Section titled “v18.2.4200 [9/20/24]”[BREAKING CHANGE] all references that started with WMLCommonThree are now WMLThreeCommon all references to addRendererToDOM are now initRenderers

[UPDATE] added CSS2DRenderer support to support html elements in three.js

v18.2.4200 [9/21/24]

Section titled “v18.2.4200 [9/21/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.5001 [9/22/24]

Section titled “v18.2.5001 [9/22/24]”updated package to reflect the version 18.2.5 of @angular/core package

v18.2.6000 [10/1/24]

Section titled “v18.2.6000 [10/1/24]”updated package to reflect the version 18.2.6 of @angular/core package

v18.2.7000 [10/2/24]

Section titled “v18.2.7000 [10/2/24]”updated package to reflect the version 18.2.7 of @angular/core package

v18.2.7001 [10/6/24]

Section titled “v18.2.7001 [10/6/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.7010 [10/9/2024 11:43:22 AM EST]

Section titled “v18.2.7010 [10/9/2024 11:43:22 AM EST]”[UPDATE] projects/wml-three/package.json updated @types/three and three dependencies from 0.168.0 to 0.169.0 . This brings you up to speed with the latest Three.js improvements.

[UPDATE] projects/wml-three/src/lib/models.ts added support for InstancedMesh . Now you can access instancedMeshes and instancedMesh for handling instanced meshes, making your rendering more efficient.

[PATCH] projects/wml-three/src/lib/models.ts added makeModelLieFlat() method. This helps you easily rotate plane meshes to lie flat, useful for flat objects like floors or ground planes.

[PATCH] projects/wml-three/tsconfig.lib.json added skipDefaultLibCheck and skipLibCheck for skipping certain library type checks, which should help with invalid typescript errors

v18.2.7020 [10/10/24]

Section titled “v18.2.7020 [10/10/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.8000 [10/10/24]

Section titled “v18.2.8000 [10/10/24]”updated package to reflect the version 18.2.8 of @angular/core package

v18.2.8000 [10/11/24]

Section titled “v18.2.8000 [10/11/24]”updated package to reflect the version 18.2.8 of @angular/core package

v18.2.8001 [10/11/24]

Section titled “v18.2.8001 [10/11/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.9000 [10/23/24]

Section titled “v18.2.9000 [10/23/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.10000 [10/31/24]

Section titled “v18.2.10000 [10/31/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.11000 [11/7/24]

Section titled “v18.2.11000 [11/7/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.12000 [11/15/24]

Section titled “v18.2.12000 [11/15/24]”updated package to conform with @windmillcode/wml-components-base

v18.2.12001 [11/17/24]

Section titled “v18.2.12001 [11/17/24]”updated package to conform with @windmillcode/wml-components-base

v19.0.0 [11/19/24]

Section titled “v19.0.0 [11/19/24]”updated package to conform with @windmillcode/wml-components-base

v19.0.3 [11/20/24]

Section titled “v19.0.3 [11/20/24]”updated package to conform with @windmillcode/wml-components-base

v19.0.4 [11/26/24]

Section titled “v19.0.4 [11/26/24]”updated package to conform with @windmillcode/wml-components-base

v19.0.1000 [11/26/24]

Section titled “v19.0.1000 [11/26/24]”updated package to conform with @windmillcode/wml-components-base

@windmillcode/wml-three

WML Three

Installation

Roadmap

Caveats

Usage

Getting Started

Animating Elements

Adding An Inspector

Multiple Renderers

Different Light Types

Selecting Objects With Your Mouse

Loading Various Types of Models

Disable Features

Full Example

References

WMLThreeProps

Methods

InspectorOptions

WMLThreeCommonProps

WMLThreeObjectProps

WMLThreeCommonObjectProps

Methods

WMLThreeLightProps

WMLThreeTexturesProps

TextureLoadOption

WMLThreeRayCasterProps

Changelog

v18.2.4100 [9/19/24]

v18.2.4200 [9/20/24]

v18.2.4200 [9/21/24]

v18.2.5001 [9/22/24]

v18.2.6000 [10/1/24]

v18.2.7000 [10/2/24]

v18.2.7001 [10/6/24]

v18.2.7010 [10/9/2024 11:43:22 AM EST]

v18.2.7020 [10/10/24]

v18.2.8000 [10/10/24]

v18.2.8000 [10/11/24]

v18.2.8001 [10/11/24]

v18.2.9000 [10/23/24]

v18.2.10000 [10/31/24]

v18.2.11000 [11/7/24]

v18.2.12000 [11/15/24]

v18.2.12001 [11/17/24]

v19.0.0 [11/19/24]

v19.0.3 [11/20/24]

v19.0.4 [11/26/24]

v19.0.1000 [11/26/24]

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`WMLThreeProps`

`InspectorOptions`

`WMLThreeCommonProps`

`WMLThreeObjectProps`

`WMLThreeCommonObjectProps`

`Methods`

`WMLThreeLightProps`

`WMLThreeTexturesProps`

`TextureLoadOption`

`WMLThreeRayCasterProps`

Weekly Downloads