xyz3d-cms v1.0.6

xyz3d-cms

An extensible flat file cms with a 3D interface built on Three.js. The easiest way to create fully 3D websites.

Features:

• GLTF file support - including lighting and materials
• Animation support and animation firing callbacks. Animation types include: "looping, onClick, onHover"
• Clickable models that open iframe or popup window
• JSON file for scene configuration and loading dynamic lights/hdr environments
• Custom Blender plugin for rapid development
• Smooth 3D scene navigation with JS APIs - "xyz3d.changeSceneZoneByName('HomePage')"
• Built in post processing
• Mobile devices supported + gryo based movement
• Easy fallback method for legacy devices
• No database, or complex server setup required. Fully static!
• Three.js "animationLoop" and variables, such as "scene, camera, renderer," exposed for simpler development
• And more! :-)

Installation

<!-- scripts -->
<script async src="https://unpkg.com/es-module-shims@1.7.0/dist/es-module-shims.js"></script>
<script type="importmap">
	{
		"imports": {
			"three": "https://unpkg.com/three@0.150.1/build/three.js",
			"camera-controls": "https://unpkg.com/browse/camera-controls@2.3.1/dist/camera-controls.module.js",
			"xyz3d-cms": "https://unpkg.com/browse/xyz3d-cms@1.0.6/dist/xyz3d-cms.js"
		}
	}
</script>

import XYZ3d from 'xyz3d-cms'
const xyzed = new XYZ3d({ xyz3dParams })

Blender plugin

xyz3d.js-blender-plugin

API

Table of Contents

• new XYZ3d()
  • Parameters
  • Examples
• changeSceneZoneByName('')
  • Parameters
  • Examples
• nextSceneZone()
  • Examples
• setup()
  • Examples
• reset()
  • Examples
• onPointerDownCallback()
  • Parameters
  • Examples
• onHoverOverCallback()
  • Parameters
  • Examples
• onHoverOffCallback()
  • Parameters
  • Examples
• onUpdate()
  • Parameters
  • Examples
• onProgressLoading()
  • Parameters
  • Examples

new XYZ3d(XYZ3dConfig)

Parameters

• XYZ3dConfig Object

  • XYZ3dConfig.debug Boolean Turns on or off debugging which ads an AxisHelper to the scene and logs more details of the scene, this introduces significant startup lag. Default is false.
  • XYZ3dConfig.jsonPath String The path of the 3D scene created with the corresponding plugin.

  • XYZ3dConfig.domElements Object All html IDs required to link the Threejs componenets.

    • XYZ3dConfig.domElements.canvasID String The rendering canvas.
    • XYZ3dConfig.domElements.iframeID String The parent dom object for the content iframe.
    • XYZ3dConfig.domElements.loadingScreenId String The dom object to destroy once the 3d scene is loaded.

  • XYZ3dConfig.camera Object The object containing camera options.

    • XYZ3dConfig.camera.orbit Boolean Turns on or off orbit camera controls. When enabled, gyro and followMouse is disabled automatically. Default is false.
    • XYZ3dConfig.camera.followMouse Boolean Turns on or off camera movement based on hovering pointer position, only for desktop. Default is true.
    • XYZ3dConfig.camera.gyro Boolean Turns on or off camera movement based on gyroscope movement, only for mobile.
    • XYZ3dConfig.camera.fov String Controls camera fov, default is 30.

    • XYZ3dConfig.camera.postEffects Object Controls post effects.

      • XYZ3dConfig.camera.postEffects.enabled Boolean Turns on or off post effects. Default is true.

      • XYZ3dConfig.camera.postEffects.bloom Object Controls bloom post effects.

        • XYZ3dConfig.camera.postEffects.bloom.enabled Boolean Turns on or off bloom post effects. Default is true.

        • XYZ3dConfig.camera.postEffects.bloom.exposure Number Controls bloom post effects exposure. Default is 1.1.

        • XYZ3dConfig.camera.postEffects.bloom.threshold Number Controls bloom post effects threshold. Default is 0.1.
        • XYZ3dConfig.camera.postEffects.bloom.strength Number Controls bloom post effects strength. Default is 2.
        • XYZ3dConfig.camera.postEffects.bloom.radius Number Controls bloom post effects radius. Default is 1.

Examples

const xyz3d = new XYZ3d({
	jsonPath: '../../assets/crypto_scene.json',
	debug: false,
	domElements: {
		canvasID: 'main-canvas',
		iframeID: 'iframe-content',
		loadingScreenID: 'loading-screen',
	},
	camera: {
		orbit: false,
		followMouse: true,
		fov: 30,
		gyro: true,
		postEffects: {
			enabled: true,
			bloom: {
				enabled: true,
				exposure: 1.1,
				threshold: 0.1,
				strength: 2,
				radius: 1,
			},
		},
	},
})

Example Scene JSON

{
	"models": [
		{
			"id": "city 1",
			"position": {
				"x": 0,
				"y": 0,
				"z": 0
			},
			"scale": {
				"x": 1,
				"y": 1,
				"z": 1
			},
			"rotation": {
				"x": 0,
				"y": 0,
				"z": 0,
				"w": 0
			},
			"castShadow": true,
			"receiveShadow": true,
			"path": "/assets/models/city_model.glb",
			"interactablesContent": [
				{
					"type": "link",
					"modelName": "Button_OpenStore",
					"content": "https://www.ebay.com"
				},
				{
					"type": "iframe",
					"modelName": "Button_AboutUs",
					"content": "pages/about.html"
				},
				{
					"type": "goToNextZone",
					"modelName": "Button_GoToNextZone",
					"conent": "1"
				},
				{
					"type": "goToZone",
					"modelName": "LandingScreen_LabelModel",
					"conent": "LandingZone"
				}
			]
		}
	],
	"lights": [
		{
			"id": "point light 1",
			"type": "pointLight",
			"position": {
				"x": 0,
				"y": 0.25,
				"z": 0
			},
			"color": "#FFFF00",
			"intensity": 1,
			"size": 100,
			"castShadow": false
		},
		{
			"id": "ambient light 1",
			"type": "ambientLight",
			"color": "#FFFFFF",
			"intensity": 1.0
		},
		{
			"id": "dir light 1",
			"type": "directionalLight",
			"position": {
				"x": 10,
				"y": 10,
				"z": 10
			},
			"target": {
				"x": 0,
				"y": 0,
				"z": 0
			},
			"color": "#FFFFFF",
			"intensity": 1,
			"castShadow": false
		},
		{
			"id": "bg hdr",
			"type": "hdr",
			"path": "/assets/textures/bg.hdr",
			"backgroundIntensity": 1,
			"backgroundBlurriness": 0
		},
		{
			"id": "bg exr",
			"type": "exr",
			"path": "/assets/textures/1k.exr",
			"backgroundIntensity": 1,
			"backgroundBlurriness": 0
		}
	]
}

changeSceneZoneByName

Moves the camera to the provided scene zone. Scene zones correspond to different pages in a site such as a "Home Page," or an "Ecommerce Storefront"

Parameters

• name String * The name of the scene zone to move to, this is defined inside the blender plugin.
• dampSpeed number The speed at which the camera lerps to the new zone. (optional, default 0.01)

Examples

XYZ3d.changeSceneZoneByName('About')

nextSceneZone

Moves the camera to the next scene zone - this is defined by the index parameter inside the corresponding 3d editor plugin.

Examples

XYZ3d.nextSceneZone()

setup

Runs asynchronous setup.

Examples

XYZ3d.setup()

reset

Resets the camera to the current scene zone position.

Examples

XYZ3d.reset()

onPointerDownCallback

The callback function for when the pointer down event is fired in the 3d scene.

Parameters

• eventData object The intersected 3d model and corresponding html content

Examples

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

onHoverOverCallback

The callback function for when the pointer hover event is fired in the 3d scene.

Parameters

• eventData object The intersected 3d model and corresponding html content

Examples

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

onHoverOffCallback

The callback function for when the pointer hover off event is fired in the 3d scene.

Parameters

• eventData object The intersected 3d model and corresponding html content

Examples

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

onUpdate

The callback function fired every frame

Parameters

• deltaTime number The time the previous frame took in seconds.

Examples

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

onProgressLoading

The callback function fired while the scene is loading.

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.

Examples

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