Three.js

This document provides a guide for integrating Polygon Streaming web player for Three.js using the NPM package directly.

This is a guide to use Polygon Streaming web player for Three.js using the NPM package directly.

Getting Started - Sample Project

You can download a sample project to get started from this link:

https://stream.viverse.com/assets/streamablemodel/2.4.6/threejs/PolygonStreaming-Threejs-Example.zip

To run the example you first need to make sure you have Node.js installed. Then run the following in a terminal:

npm install
npm run dev

It will open a browser window and display the 3D model.

Code Explanation and Usage

Import the StreamController from the package:

import { StreamController } from '@polygon-streaming/web-player-threejs';

Instantiate the stream controller:

const streamController = new StreamController(camera, renderer, scene, controls.target, {
  cameraType: 'nonPlayer',
  triangleBudget: 5000000,
  mobileTriangleBudget: 3000000,
  minimumDistance: 0.01,
  distanceFactor: 1.1,
  maximumQuality: 15000,
  closeUpDistanceFactor: 5
  closeUpDistance: 3,
  iOSMemoryLimit: 440
});

Add a streaming model, passing it a model URL and a Group to act as a model parent:

const modelParent = new THREE.Group();
modelParent.position.set(0, 1, 0);
scene.add(modelParent);
streamController.addModel('the URL of your model to be streamed (Asset ID)', modelParent, {
  qualityPriority: 1,
  initialTrianglePercent: 0.1,
  castShadows: true,
  receiveShadows: true,
  forceDoubleSided: false,
  useAlpha: true,
  environmentMap: null,
  hashCode: ''
});

Call the stream controller's update method in the animation loop:

function animate() {
  controls.update();
  renderer.render(scene, camera);
  streamController.update();
}
renderer.setAnimationLoop(animate);

Now you have everything setup to start streaming your 3D models inside your Three.js application.

Using Your Own 3D Model

• Upload your 3D model to the online console: https://stream.viverse.com/console

• To get the model URL go to the models section of the console: https://stream.viverse.com/console/models and click on the three dots next to your model and select "Copy asset ID".

• Paste this URL as the first parameter of streamController.addModel() method.

Streaming Controller Parameters

Parameter	Description
camera (required)	The camera used in the scene.
renderer (required)	The WebGL renderer used in the scene.
scene (required)	The scene object.
cameraTarget (required)	The camera target which is a Vector3. If you are using orbit controls it would be controls.target.
options (optional)	You need to provide an object of options. The available options are listed below.

Options

All options are optional.

Option	Description	Default Value
cameraType	'nonPlayer': A camera that is not attached to a player e.g. a camera that orbits an object. 'player': A camera that is attached to a player.	'nonPlayer'
triangleBudget	The maximum amount of triangles that you want to be in the scene at any single point.	5000000
mobileTriangleBudget	The triangle budget used on a mobile device. If it is set to 0 it will use the non-mobile triangle budget.	3000000
minimumDistance	The smallest possible distance to the camera.	0.01
distanceFactor	Preference for nearby objects over objects further away. Values above one mean a preference for nearby objects. Values below one mean a preference for objects further away. One is neutral.	1.1
maximumQuality	Stops improving geometry that exceeds the maximum quality. This can be used to stop far away objects from showing more detail which can be wasteful. Setting it to 0 means there is no maximum quality.	15000
closeUpDistanceFactor	The distance factor used when close-up to an object. Should be higher than the standard distance factor.	5
closeUpDistance	The distance where it starts using close-up distance factor. Set it to 0 to not use close-up distance factor.	3
iOSMemoryLimit	The maximum amount of memory in MB that meshes and textures can consume on iOS devices to avoid the page crashing. Use -1 for no limit.	440

addModel Parameters

Parameter	Description
URL (required)	URL of the XRG model. If it doesn't end with .xrg it will append model.xrg to the URL.
model parent (required)	The scene object that the streaming model will be attached to.
options (optional)	You need to provide an object of options. The available options are listed below.

Options

All options are optional.

Option	Description	Default Value
qualityPriority	How much to prioritize the quality of this model relative to the quality of other models in the scene. This parameter does nothing if this is the only model in the scene.	1
initialTrianglePercent	Percentage of triangle budget to initialize the model with.	0.1
castShadows	Whether the model should cast shadows.	true
receiveShadows	Whether the model should receive shadows.	true
forceDoubleSided	Render the model double sided regardless of the setting in the model file.	false
useAlpha	Whether to render semi-transparency in materials. You might turn this off to increase performance but all your materials will render opaque.	true
environmentMap	A cube map environment texture.	null
hashCode	Hash code to validate streaming model	''