Xyz3d NPM | npm.io

A powerful Three.js framework for creating stunning 3D websites and landing pages. 🚀 This framework comes with a Blender plugin and supports mobile devices. It offers a range of features including built-in post-effects, raycasting, animations, and more, taking care of complex tasks like loading Blender-made GLTF models, setting up post effects, and providing cross-platform camera controls. With convenient debugging tools, Three.js development becomes a breeze. Once the framework is set up, it returns the essential components: scene, camera, and renderer, allowing you to focus on crafting captivating 3D scenes without worrying about WebGL details.

🎥 Intro video: Watch here

🔮 Live demo: Check it out

🚀 Features: 🚀

Professional Blender to Three.js workflow 🎨
Built-in raycasting 🎯
Trigger mesh/camera animation on hover/clicks 👆
Display HTML inside a popup iframe when clicking a model 🖱️
Built-in camera controls:
- Orbit 🔄
- Parallax based on mouse movement 🖱️
- Gyro tilt 📱
- Touch support 📱
Easy scene swapping and dynamic light adding method based on JSON files 💡🔄
Combine multiple models into one Three.js scene 🧩
Smooth 3D scene navigation with JS APIs: xyz3d.gotoSceneZone('HomePage') ⛳️
Built-in post-processing:
- Bloom 🌼
- FXAA 🖌️
- GammaCorrection 🌈
Fallback HTML pages 📵🖌️

Blender plugin

xyz3d.js-blender-plugin

Examples and Quick Start

Download the examples repo here:
xyz3d.js-examples

API

XYZ3d

Creates an instance of XYZ3d, a helper framework for 3D websites.

Parameters

config Object The configuration object for the XYZ3d instance.
- config.debug Boolean Enables or disables debugging mode. Defaults to false.
- config.jsonPath String The path to the 3D scene created with the blender plugin - see the examples or the bottom of the readme for details on this file.
- config.domElements Object The IDs of the HTML elements which are used by the plugin.
  - config.domElements.canvas String The rendering canvas.
  - config.domElements.popup String The content popup element. A dom element which has an iframe injected into it based on the json file data. Adds and revmoces the following classes .XYZ3d-hidden and .XYZ3d-visible to hide and show the popup. This dom element can be styled to your liking.
- config.camera Object The configuration object for the camera.
  - config.camera.controls Object Enables or disables the camera controls. Defaults to true.
  - config.camera.orbit Boolean Enables or disables orbit camera controls. When enabled, gyro and followMouse are disabled automatically. Defaults to false.
  - config.camera.cameraShiftAmount Number Controls the intensity of X/Y camera movement when orbit is off. Defaults to 0.05.
  - config.camera.followMouse Boolean Enables or disables camera movement based on hovering pointer position, only for desktop. Defaults to true.
  - config.camera.gyro Boolean Enables or disables camera movement based on gyroscope movement, only for mobile. Defaults to true.
  - config.camera.gyroScale Boolean Scales the gyroscope movement of the camera, only for mobile. Defaults to 20.
  - config.camera.fov Number Controls camera field of view. Defaults to 30.
  - config.camera.cameraSmoothTime Number Controls camera movement time in seconds. Defaults to 0.25.
  - config.camera.cameraFramePadding Number Controls the amount of padding from the interactable elements to the sides of the display, to ensure all interactables of the current zone are always in frame. Defaults to 1.
  - config.camera.postEffects Object The configuration object for post effects.
    - config.camera.postEffects.enabled Boolean Enables or disables post effects. Defaults to true.
    - config.camera.postEffects.bloom Object The configuration object for bloom post effects.
      - config.camera.postEffects.bloom.enabled Boolean Enables or disables bloom post effects. Defaults to true.
      - config.camera.postEffects.bloom.exposure Number Controls bloom post effects exposure. Defaults to 1.1.
      - config.camera.postEffects.bloom.threshold Number Controls bloom post effects threshold. Defaults to 0.1.
      - config.camera.postEffects.bloom.strength Number Controls bloom post effects strength. Defaults to 1.
      - config.camera.postEffects.bloom.radius Number Controls bloom post effects radius. Defaults to 1.
    - config.camera.postEffects.antialias Boolean Enables or disables antialiasing post effects. Defaults to true.

Examples

const xyzed = new XYZ3d({
	jsonPath: 'scene.json',
	domElements: {
		canvas: 'main-canvas',
		popup: 'popup-content',
	}
})

gotoSceneZone

This function moves the camera to a scene zone with the given name. The scene zones correspond to different pages in a website or application. The dampSpeed parameter controls the speed at which the camera moves to the new zone.

Parameters

name String * The name of the scene zone to move to, this is defined inside the blender plugin.
dampTime number The speed at which the camera lerps to the new zone. defaults to 0.1 seconds

Examples

XYZ3d.gotoSceneZone('About')

nextSceneZone

Parameters

increment Number the incremental value to move scene zones by, value can be negative or positive. Defaults to 1. (optional, default 1)
dampTime number The speed at which the camera lerps to the new zone. defaults to 0.1 seconds (optional, default null)

Examples

XYZ3d.nextSceneZone()

sceneZoneIndex

maxSceneZoneIndex

setup

Examples

XYZ3d.setup()

reset

Examples

XYZ3d.reset()

onPointerDown

Parameters

eventData object The intersected 3d model and corresponding html content

Examples

XYZ3d.onPointerDown = (event) => { console.log(event) }

onHoverOver

Parameters

eventData object The intersected 3d model and corresponding html content

Examples

XYZ3d.onHoverOver = (event) => { console.log(event) }

onHoverOff

Parameters

eventData object The intersected 3d model and corresponding html content

Examples

XYZ3d.onHoverOff = (event) => { console.log(event) }

onSwipeUp

Examples

XYZ3d.onSwipeUp = () => { console.log('Swipe up detected') }

onSwipeDown

Examples

XYZ3d.onSwipeDown = () => { console.log('Swipe down detected') }

onUpdate

Parameters

deltaTime number The time the previous frame took in seconds.

Examples

XYZ3d.onUpdate = (deltaTime) => { console.log(deltaTime) }

onProgressLoading

Parameters

step number The model index being loaded.
steps number The total models to be loaded.
percent number The percentage loaded of the current model.
stage string The current stage, value is either "Textures" or "Models".

Examples

XYZ3d.onProgressLoading = (step, steps, percent, stage) => { console.log(step, steps, percent, stage) }

XYZ3dConfig.jsonContent

Type: Object

Examples

``` json
   {
     "models": [
       {
         "id": "test 1",
         "enabled": true,
         "path": "assets/models/city_model.glb",
         "position": {
           "x": 0,
           "y": 0,
           "z": 0
         },
         "scale": {
           "x": 1,
           "y": 1,
           "z": 1
         },
         "rotation": { , "//comment_rotation": "quaternion rotation",
           "x": 0,
           "y": 0,
           "z": 0,
           "w": 0
         },
         "shadow": true, "//comment_shadow": "sets both castShadow and receiveShadow to this value",
         "shadowBias": 0.0005,
         "shadowNormalBias": 0.01,
         "shadowRadius": 4.0,
         "frustumCulled": true,
         "interactables": [  , "//comment_interactables": "Assign interaction types here",
           {
             "type": "link", "//comment_link": "When the listed model (under modelName) is clicked it's animations will play, then the link inside 'content' will be opened in a new tab",
             "modelName": "ModelNameGoesHere",
             "content": "https://www.ebay.com"
           },
           {
             "type": "popup" , "//comment_popup": "When the listed model (under modelName) is clicked it's animations will play, then the html dom object contained in the domeElements.popup will have the class .XYZ3d-hidden replaced with .XYZ3d-visible",
             "modelName": "ModelNameGoesHere",
             "content": "pages/about.html"
           },
           {
             "type": "goToNextZone", "//comment_goToNextZone": "When the model is clicked, the camera move to the zoneIndex incremented by the 'content' amount",
             "modelName": "ModelNameGoesHere",
             "conent": "1" , "//comment_content": "This value can be negative, it's the number of zones to change based on the zone index."
           },
           {
             "type": "goToZone",
             "modelName": "ModelNameGoesHere",
             "conent": "LandingZone"
           }
         ]
       }
     ],
     "lights": [ , "//comment_lights": "Lights here are optional, lights inside the gltf file are automatically imported into the scene"
       {
         "id": "bg hdr",
         "type": "hdr",
         "enabled": true,
         "path": "assets/textures/4k.hdr",
         "backgroundIntensity": 1,
         "backgroundBlurriness": 0
       },
       {
         "id": "bg exr",
         "type": "exr",
         "enabled": true,
         "path": "assets/textures/4k.exr",
         "backgroundIntensity": 1,
         "backgroundBlurriness": 0
       },
       {
         "id": "point light 1",
         "type": "pointLight",
         "enabled": true,
         "position": {
           "x": 0,
           "y": 0.25,
           "z": 0
         },
         "color": "#FFFF00",
         "intensity": 1,
         "size": 100,
         "castShadow": false
       },
       {
         "id": "ambient light 1",
         "type": "ambientLight",
         "enabled": true,
         "color": "#FFFFFF",
         "intensity": 1.0
       },
       {
         "id": "dir light 1",
         "type": "directionalLight",
         "enabled": true,
         "position": {
           "x": 10,
           "y": 10,
           "z": 10
         },
         "target": {
           "x": 0,
           "y": 0,
           "z": 0
         },
         "color": "#FFFFFF",
         "intensity": 1,
         "castShadow": false
       }
     ]
   }
```

3d framework typescript three.js webgl

camera-controls path stats-js three vite

@everything-registry/sub-chunk-3194

12 months ago

1 year ago

1 year ago

1 year ago