render3dplugin

The three.js renderer: the scene, the camera, shadows, ambient occlusion, bloom and tone mapping.

#Putting it in a scene

"prefabs": {
  "render3d": {
    "camera": { "fov": 62, "near": 0.1, "far": 2000, "at": [0, 8, 20], "look": [0, 0, 0] },
    "pixelRatio": 2,
    "tone": "neutral",
    "exposure": 1,
    "shadows": "soft",
    "background": "#87a9c4",
    "ao": { "on": true, "radius": 0.5, "thickness": 1, "falloff": 1, "scale": 1, "intensity": 1, "samples": 16 },
    "bloom": { "strength": 0.4, "radius": 0.5, "threshold": 1 }
  }
}

#Properties

Read from prefabs.render3d. Only camera is required; a setting left out keeps three.js's own.

.camera : { fov, near, far, at, look }

A perspective camera with the canvas's aspect, at at, looking at look.

.tone : 'neutral' | 'none'

Default none.

.exposure : number = 1

.shadows : 'soft' | 'hard' | 'none'

Default none.

.background : colour

.pixelRatio : number = 1

Caps the screen's pixel density. The canvas stays the engine's width and height on the page and draws that many pixels times the ratio.

.ao : { on, radius, thickness, falloff, scale, intensity, samples }

Ambient occlusion, three.js's GTAO. Off unless on is true.

.bloom : { strength, radius, threshold }

Anything brighter than threshold glows. radius is 0 to 1.

#Drawn between steps

Each frame, just before it draws, every object of the scene and of the overlay, and the camera, is put between where the last two steps left it, as far as the page's clock is past the last step: its position in a straight line, its turn the short way round, and its scale. Once the frame is drawn each is put back where it was set. An InstancedMesh's copies are drawn where they are set.

userData.teleport : boolean

Set by a look on any object of the scene or the overlay, or on the camera.

True on a frame draws the object where it is set on that frame and on every later frame of that step, never between, for an object put somewhere new rather than moved along its way: a door to elsewhere, a respawn, the camera that goes with them. Without it, an object put 40 metres on is drawn sliding the 40 metres over one step. Set back to false on a later frame, the object is drawn between steps again from the next step, starting from where it was put. Left true, it is never drawn between. Each object has its own flag: a child moved with its parent needs none, and a child moved by itself needs its own.

#Methods

On the page, through plugins.render3d.

dress( material, { surface? } ) : material

Applies every registered splice to the material. surface is shader code for that material alone, applied before the splices.

splice( key, { uniforms?, vertex?, fragment? } )

Shader code for every dressed material. Each entry of vertex and fragment is GLSL inserted after #include <chunk> of that name. One splice per key.

pass( key, pass )

A three.js post-processing pass, run on the frame's light after the AO and before the bloom and tone mapping. Its depth is set to the scene's depth texture each frame.

finish( key, pass )

A pass run after tone mapping, on the screen's final sRGB colours.

ratio( r?, look = 'smooth' )

Draws r pixels per canvas pixel. look is 'blocks' to show each pixel as a hard square. Called with no arguments, it goes back to pixelRatio.

project( [x, y, z] ) : { x, y, behind }

The canvas position in pixels from the top left. behind is true behind the camera, nearer than near or past far.

claim( owner ) : boolean

True if owner now holds the camera, false if something else does. release( owner ) gives it up and claimed() returns the holder.

drew( f ) : () => void

Calls f every frame with { camera, rows, meshes }, the world positions as drawn. rows is keyed by row id, meshes by three.js id. Works with no canvas mounted. The return value stops it.

#Properties of the plugin

Also on plugins.render3d.

scene : THREE.Scene

overlay : { scene, camera }

A second scene drawn over the first with the depth cleared, for a cockpit or a held tool. Its camera follows the main one's position, turn, field of view and aspect, and keeps its own near and far.

camera : THREE.PerspectiveCamera | undefined

Undefined until the first tick.

renderer, canvas, composer

The WebGL renderer, the canvas and the effect composer. composer is undefined when nothing needs one, and is replaced when an effect joins.

THREE, GLTFLoader, SkeletonUtils

The three.js module and its two loaders.

#Used by

• skydome3d
  Splices its weather into every dressed material, and sets the exposure each frame.
• dither3d
  A finish pass, and a ratio of blocks.
• chasecamera3d
  Claims the camera.

#In the guide