Constructor
new Render3DPlugin()
Create the global 3D renderer, call in gameInit
- Source
new Render3DPlugin;
render3D.camera.pos = vec3(0, 5, 10);
render3D.camera.lookAt(vec3());
new EngineObject3D(vec3(), buildBox());Members
additive
Properties| Type | Description |
|---|---|
| boolean | Additive blending instead of alpha, in the transparent stage |
- Source
ambientColor
Properties| Type | Description |
|---|---|
| Color | Ambient light color, from above when ambientGroundColor is set |
- Source
ambientGroundColor :Color|undefined
- Color |
undefined
| Type | Description |
|---|---|
| Color | | Ambient light from below: set, the ambient blends from this on faces pointing down to ambientColor on faces pointing up, the way a sky and a ground light a scene; setSky sets both from its colors |
- Source
anisotropy
Properties| Type | Description |
|---|---|
| number | Anisotropic filtering for textures seen at an angle, 1 to 16, 1 is off; needs mipmaps |
- Source
attribValues :Array.<Array.<number>>
- Array.<Array.<number>>
- Source
billboardMesh
Properties| Type | Description |
|---|---|
| Mesh | A square of size 1 facing +Z with the tile across it, the corners in the order drawBillboard writes them; a ParticleEmitter3D draws its particles as instances of it, each with its own matrix |
- Source
boxMesh
Properties| Type | Description |
|---|---|
| Mesh | A box of size 1 that drawBox uses, for any object that is a box; set the object's scale3D and color instead of editing the mesh, which would change every box that uses it |
- Source
camera
Properties| Type | Description |
|---|---|
| Camera3D | The camera |
- Source
cameraDepthFramebuffer :WebGLFramebuffer|undefined
- WebGLFramebuffer |
undefined
- Source
cameraDepthTexture :WebGLTexture|undefined
- WebGLTexture |
undefined
- Source
cameraForward
Properties| Type | Description |
|---|---|
| Vector3 | Camera forward axis this frame |
- Source
cameraRight
Properties| Type | Description |
|---|---|
| Vector3 | Camera right axis this frame |
- Source
cameraUp
Properties| Type | Description |
|---|---|
| Vector3 | Camera up axis this frame |
- Source
capture :Mesh|undefined
- Mesh |
undefined
- Source
currentProgram :WebGLProgram|undefined
- WebGLProgram |
undefined
- Source
depthTest
Properties| Type | Description |
|---|---|
| boolean | Test against the depth buffer, reset to true before each object and callback; a draw with it off goes over what was drawn before it and under what is drawn after, by render order, which ends the batch of meshes before it, so one per object costs a draw per object |
- Source
depthTexture
Properties| Type | Description |
|---|---|
| boolean | Draw the camera's depth into a texture each frame for post processing: PostProcessPlugin hands it to its shader as iChannel2, read with sceneDepth(uv); off by default and free when off, on it draws the solid objects of the default layer once more, depth only |
- Source
depthWrite
Properties| Type | Description |
|---|---|
| boolean | Write to the depth buffer, owned by the stages: on for opaque, off for transparent |
- Source
emissive
Properties| Type | Description |
|---|---|
| number | How much a surface lights itself, set per object by its emissive |
- Source
emissiveMap :TextureInfo|undefined
- TextureInfo |
undefined
| Type | Description |
|---|---|
| TextureInfo | | Emissive map for the next draws, set from each object's emissiveMap |
- Source
emissiveMapColor
Properties| Type | Description |
|---|---|
| Color | Multiplies the emissive map, set from each object's emissiveMapColor |
- Source
fogColor :Color|undefined
- Color |
undefined
| Type | Description |
|---|---|
| Color | | Fog color, uses canvasClearColor when undefined |
- Source
fogEnd
Properties| Type | Description |
|---|---|
| number | Distance from the camera where fog is total, 0 disables fog |
- Source
fogStart
Properties| Type | Description |
|---|---|
| number | Distance from the camera where fog starts |
- Source
frustumCulling
Properties| Type | Description |
|---|---|
| boolean | Skip meshes whose bounding sphere is outside the view |
- Source
frustumPlanes :Array.<Array.<number>>
- Array.<Array.<number>>
- Source
gravity
Properties| Type | Description |
|---|---|
| Vector3 | Added to the velocity3D of every object with a mass each frame, scaled by its gravityScale; sync2D objects use the 2D gravity |
- Source
instanceBuffers :Array.<WebGLBuffer>
- Array.<WebGLBuffer>
- Source
instanceMeshes :Array.<Mesh>
- Array.<Mesh>
- Source
instancing
Properties| Type | Description |
|---|---|
| boolean | Draw every use of a mesh in the opaque stage as one instanced call, mesh.instanced overrides it per mesh |
- Source
isRendering
Properties| Type | Description |
|---|---|
| boolean | True while the 3D pass is running, 3D draws are only valid then |
- Source
lighting
Properties| Type | Description |
|---|---|
| boolean | Apply lighting, when false draws plain vertex color times texture and casts no shadow; off for billboards, lines, ribbons and soft discs, an object sets emissive instead |
- Source
mipmaps
Properties| Type | Description |
|---|---|
| boolean | Sample textures through mipmaps so they do not shimmer in the distance, false uses each texture's own filtering like 2D |
- Source
normalMap :TextureInfo|undefined
- TextureInfo |
undefined
| Type | Description |
|---|---|
| TextureInfo | | Normal map for the next draws, set from each object's normalMap |
- Source
normalScale
Properties| Type | Description |
|---|---|
| number | How strongly the normal map bends the surface, set from each object's normalScale |
- Source
onRenderOpaque :function|undefined
- function |
undefined
| Type | Description |
|---|---|
| function | | Draw solid world here, it runs again for shadows so only draw in it |
- Source
onRenderTransparent :function|undefined
- function |
undefined
| Type | Description |
|---|---|
| function | | Draw see through things here, like glows, billboards and soft shadows |
- Source
pixelated
Properties| Type | Description |
|---|---|
| boolean | Draw state: keep texture pixels hard edged, no mipmaps and no blending between them, set per object by pixelated |
- Source
planeMesh
Properties| Type | Description |
|---|---|
| Mesh | A flat square of size 1 facing +Y, seen from above only, for floors, water and decals; stand it up with the object's rotation3D, and size it with scale3D |
- Source
planeMeshDoubleSided
Properties| Type | Description |
|---|---|
| Mesh | The same square seen and lit from both sides, for signs, cards and leaves |
- Source
program :WebGLProgram|undefined
- WebGLProgram |
undefined
- Source
projectionMatrix
Properties| Type | Description |
|---|---|
| Matrix4 | This frame's projection matrix |
- Source
receiveShadow
Properties| Type | Description |
|---|---|
| boolean | Darken by the shadow map when shadows are on, turn it off for things that should stay lit inside a shadow |
- Source
reflectivity
Properties| Type | Description |
|---|---|
| number | How much the surface reflects the sky, 0 to 1, set from each object's reflectivity |
- Source
renderAfter2D
Properties| Type | Description |
|---|---|
| boolean | Draw the 3D scene on top of the 2D scene instead of under it |
- Source
samplerKey :string|undefined
- string |
undefined
- Source
samplers :Map.<number, WebGLSampler>
- Map.<number, WebGLSampler>
- Source
shader :Shader|undefined
- Shader |
undefined
| Type | Description |
|---|---|
| Shader | | Custom Shader for the next draws, set from each object's shader; undefined draws with the plugin's own |
- Source
shadowBias
Properties| Type | Description |
|---|---|
| number | Stops surfaces shadowing themselves, raise for speckles, lower if shadows drift off |
- Source
shadowCenter :Vector3|undefined
- Vector3 |
undefined
| Type | Description |
|---|---|
| Vector3 | | Center of the shadowed area, read each frame, undefined follows the camera |
- Source
shadowFramebuffer :WebGLFramebuffer|undefined
- WebGLFramebuffer |
undefined
- Source
shadowMapSize
Properties| Type | Description |
|---|---|
| number | Size of the shadow map in pixels, bigger is sharper and slower |
- Source
shadowMatrix
Properties| Type | Description |
|---|---|
| Matrix4 | This frame's light view projection for the shadow map |
- Source
shadowPass
Properties| Type | Description |
|---|---|
| boolean | True while the shadow map is being drawn, draws go to the depth only shader |
- Source
shadowPlanes :Array.<Array.<number>>
- Array.<Array.<number>>
- Source
shadowRange
Properties| Type | Description |
|---|---|
| number | World size the shadow map covers around shadowCenter, smaller is sharper; it is a square facing the light, so it turns as the light does, and about 1.5 times an area's width covers it from any angle |
- Source
shadowShader :WebGLProgram|undefined
- WebGLProgram |
undefined
- Source
shadowSoftness
Properties| Type | Description |
|---|---|
| number | How much to blur the shadow edges |
- Source
shadowTexture :WebGLTexture|undefined
- WebGLTexture |
undefined
- Source
shadows
Properties| Type | Description |
|---|---|
| boolean | Cast real shadows from the sun, off by default and free when off |
- Source
shininess
Properties| Type | Description |
|---|---|
| number | The highlight's exponent, how small and sharp it is: 4 is broad like rubber, 100 sharp like polished metal; set from each object's shininess |
- Source
sky :Mesh|undefined
- Mesh |
undefined
| Type | Description |
|---|---|
| Mesh | | Sky dome from buildSky or setSky, drawn around the camera behind everything |
- Source
smoothShading
Properties| Type | Description |
|---|---|
| boolean | Default for every builder's smooth argument: true for smooth vertex normals, false for flat faces |
- Source
softShadowHeight :number|HeightMap|function
- number |
HeightMap | function
| Type | Description |
|---|---|
| number | | Floor for objects with a softShadow: a height, a HeightMap, or (x, z) => y |
- Source
sortTransparent
Properties| Type | Description |
|---|---|
| boolean | Draw see through things far to near so they blend correctly |
- Source
specular
Properties| Type | Description |
|---|---|
| number | Strength of the highlight where the sun and the Light3D objects reflect, 0 is none and 1 adds a light's full color at its brightest; shininess sets its size |
- Source
sphereMesh
Properties| Type | Description |
|---|---|
| Mesh | A smooth sphere of diameter 1 that drawSphere uses, shared the same way as boxMesh |
- Source
streamBuffer :WebGLBuffer|undefined
- WebGLBuffer |
undefined
- Source
streamTileInfo :TextureInfo|undefined
- TextureInfo |
undefined
- Source
sunColor
Properties| Type | Description |
|---|---|
| Color | Sunlight color |
- Source
sunDirection
Properties| Type | Description |
|---|---|
| Vector3 | Direction toward the sun, where its light comes from, like a directional Light3D; read at each draw, and any length will do, the shading and the shadows normalize it themselves; the sun is the one light that casts shadows |
- Source
transparentQueue :Array.<{distance: number, state: Object, draw: function(): void}>|undefined
- Array.<{distance: number, state: Object, draw: function(): void}> |
undefined
- Source
uniformValues :Object.<string, Array.<number>>
- Object.<string, Array.<number>>
- Source
vao :WebGLVertexArrayObject|undefined
- WebGLVertexArrayObject |
undefined
- Source
viewMatrix
Properties| Type | Description |
|---|---|
| Matrix4 | This frame's view matrix |
- Source
viewProjection
Properties| Type | Description |
|---|---|
| Matrix4 | This frame's combined view projection |
- Source
whiteTexture :WebGLTexture|undefined
- WebGLTexture |
undefined
- Source
Methods
bake(drawFunction) → {Mesh}
Build a mesh once out of draw calls, instead of redrawing the shapes every frame
- Call the same drawStrip, drawQuad and drawBox calls inside, and get a mesh back
- Strips inside a bake ignore their tileInfo, the finished mesh picks the texture when it draws
- drawMesh, drawBox and drawSphere copy their mesh in, moved and tinted, their tileInfo dropped too
- The mesh skips its back faces like any, set doubleSided when what was drawn is open
| Name | Type | Description |
|---|---|---|
drawFunction | function |
- Source
- Type:
- Mesh
drawBillboard(pos, sizeopt, tileInfoopt, coloropt, angleopt, uprightopt) → {void}
Draw a flat square that always faces the camera, unlit so it keeps its own colors
- Draw it from onRenderTransparent or a transparent object so it can fade
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector3 | Center | ||
size | Vector2 | <optional> | World units | |
tileInfo | TileInfo | | <optional> | ||
color | Color | <optional> | ||
angle | number | <optional> | 0 | Rotation in the camera plane, counter clockwise |
upright | boolean | <optional> | false | Stand on world up and only turn to face the camera, for sprites on the ground |
- Source
- Type:
- void
drawBox(pos, sizeopt, coloropt, rotationopt)
Draw a box, untextured, for blocking out a scene without meshes or objects
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector3 | Center | ||
size | Vector3 | | <optional> | 1 | Full size, a number for a cube |
color | Color | <optional> | ||
rotation | Vector3 | <optional> | vec3(pitch, yaw, roll) |
- Source
drawLine(posA, posB, widthopt, coloropt)
Draw a line as a camera facing ribbon, unlit
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
posA | Vector3 | |||
posB | Vector3 | |||
width | number | <optional> | 0.1 | |
color | Color | <optional> |
- Source
drawMesh(mesh, matrixopt, tileInfoopt, coloropt) → {void}
Draw a mesh with the current draw state, batched with its other uses in the opaque stage when instancing is on
| Name | Type | Attributes | Description |
|---|---|---|---|
mesh | Mesh | ||
matrix | Matrix4 | | <optional> | Object transform, or just a position to draw it at |
tileInfo | TileInfo | | <optional> | Texture, mesh uvs map across the tile or the whole texture |
color | Color | <optional> | Tint |
- Source
- Type:
- void
drawQuad(a, b, c, d, tileInfoopt, coloropt)
Draw a quad from four corners in loop order, counter clockwise seen from the front, a is the top left of the texture
| Name | Type | Attributes | Description |
|---|---|---|---|
a | Vector3 | ||
b | Vector3 | ||
c | Vector3 | ||
d | Vector3 | ||
tileInfo | TileInfo | | <optional> | |
color | Color | | <optional> | One for all or one per corner |
- Source
drawRibbon(points, widthopt, tileInfoopt, coloropt, sideopt)
Draw a ribbon along a path, unlit and visible from both sides; width and color can change along it
- The texture runs along the length, u from the first point to the last
- A path that ends where it starts is a loop, and joins with no seam
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
points | Array.<Vector3> | Center line in order, at least two | ||
width | number | | <optional> | 0.1 | Full width, one for all or one per point |
tileInfo | TileInfo | | <optional> | ||
color | Color | | <optional> | One for all or one per point | |
side | Vector3 | | <optional> | Direction across the ribbon, one for all or one per point, default faces the camera |
- Source
drawSky()
Draw render3D.sky around the camera, unlit, unfogged and behind everything, called automatically by the pass
- Source
drawSoftDisc(pos, sizeopt, coloropt, normalopt, sidesopt) → {void}
Draw a disc that fades to transparent at the rim, unlit, for glows, puffs and sky dots
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector3 | Center | ||
size | number | <optional> | 1 | Diameter |
color | Color | <optional> | ||
normal | Vector3 | <optional> | Facing direction, faces the camera by default | |
sides | number | <optional> | 16 |
- Source
- Type:
- void
drawSoftShadow(pos, sizeopt, floorHeightopt, coloropt, liftopt) → {void}
Draw a soft round shadow on the ground under something, much cheaper than a real shadow
- Draw it from onRenderTransparent or from a transparent object
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector3 | Position of the thing casting the shadow | ||
size | number | <optional> | 1 | Diameter |
floorHeight | number | | <optional> | 0 | Height of the ground, a HeightMap, or (x, z) => y to follow terrain |
color | Color | <optional> | ||
lift | number | <optional> | 0.02 | How far above the ground to draw, raise it if the shadow cuts into rough ground |
- Source
- Type:
- void
drawSphere(pos, sizeopt, coloropt)
Draw a sphere, untextured and smooth shaded
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector3 | Center | ||
size | number | <optional> | 1 | Diameter |
color | Color | <optional> |
- Source
drawStrip(points, normalsopt, uvsopt, colorsopt, tileInfoopt) → {void}
Draw a triangle strip, batched into the stream with the current draw state
- Strip order: the first three points make a triangle, then each point makes another with the two before it
- List the first three points counter clockwise as seen from the front, or the face points away and may vanish when back faces are culled
- inside a bake the strip goes into the mesh instead, in the transparent stage it is queued for sorting and the arrays are read when the queue replays, so leave them unchanged until the stage ends
| Name | Type | Attributes | Description |
|---|---|---|---|
points | Array.<Vector3> | In strip order | |
normals | Vector3 | | <optional> | One for all or one per point, default up |
uvs | Vector2 | | <optional> | One for all or one per point, 0-1 across the tile |
colors | Color | | <optional> | One for all or one per point, vertex colors come before the texture |
tileInfo | TileInfo | | <optional> | Texture for this strip |
- Source
- Type:
- void
drawStripUnlit(points, normalsopt, uvsopt, colorsopt, tileInfoopt)
Draw a strip with lighting off, for camera facing shapes where the light direction means nothing
| Name | Type | Attributes | Description |
|---|---|---|---|
points | Array.<Vector3> | Strip order | |
normals | Vector3 | | <optional> | |
uvs | Vector2 | | <optional> | |
colors | Color | | <optional> | |
tileInfo | TileInfo | | <optional> |
- Source
drawTriangle(a, b, c, coloropt)
Draw a triangle, counter clockwise from outside is the front
| Name | Type | Attributes | Description |
|---|---|---|---|
a | Vector3 | ||
b | Vector3 | ||
c | Vector3 | ||
color | Color | <optional> |
- Source
flush()
Draw the pending stream vertices as one strip with the state they were drawn under, called automatically when needed
- Source
flushTransparentQueue()
Draw the queued transparent draws far to near with the state each was drawn under, called automatically at the end of the transparent stage
- Source
isSphereVisible(center, radius) → {boolean}
Is any part of a sphere on screen this frame, the test that skips meshes the camera cannot see
- While the shadow map is drawing it tests the shadow area instead
| Name | Type | Description |
|---|---|---|
center | Vector3 | |
radius | number |
- Source
- Type:
- boolean
pick(from, objectsopt) → {Object|undefined}
Find the nearest object under a screen position or along a ray, for clicking on things
- Each object is tested as the box around its mesh in its own space, or a sprite as the quad it draws, not triangle by triangle
- engineObjectsRaycast3D is the other half of this, every object along a ray instead of the nearest
| Name | Type | Attributes | Description |
|---|---|---|---|
from | Vector2 | | A screen position like mousePosScreen, or a ray to look along | |
objects | Array.<EngineObject> | <optional> | Defaults to every object; only those with a mesh or a sprite count |
- Source
- Type:
- Object |
undefined
playSound(sound, pos3D, volumeopt, pitchopt, randomnessScaleopt, loopopt, pausedopt) → {SoundInstance|undefined}
Play a sound at a 3D position, quieter with distance from the camera and panned by its side, like Sound.play with a 2D position
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
sound | Sound | |||
pos3D | Vector3 | |||
volume | number | <optional> | 1 | |
pitch | number | <optional> | 1 | |
randomnessScale | number | <optional> | 1 | How much to scale pitch randomness |
loop | boolean | <optional> | false | |
paused | boolean | <optional> | false | Start it paused |
- Source
- undefined when out of range or sound is off
- Type:
- SoundInstance |
undefined
playSoundLoop(sound, pos3D, volumeopt, pitchopt, randomnessScaleopt) → {SoundInstance|undefined}
Play a sound on a loop at a 3D position, the same as playSound with loop on
- Its volume and pan are set when it starts, change or stop it through the SoundInstance returned
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
sound | Sound | |||
pos3D | Vector3 | |||
volume | number | <optional> | 1 | |
pitch | number | <optional> | 1 | |
randomnessScale | number | <optional> | 1 | How much to scale pitch randomness |
- Source
- undefined when out of range or sound is off
- Type:
- SoundInstance |
undefined
queueTransparent(pos, draw) → {void}
Queue a draw for the transparent stage, replayed far to near with the current draw state, or draw it now when sorting is off
- The draw runs later, so it should hold copies of any values the caller may change before then
| Name | Type | Description |
|---|---|---|
pos | Vector3 | Where the draw is, for sorting |
draw | function |
- Source
- Type:
- void
renderStages(objects, isDefaultopt)
Draw a layer's objects, solid ones first and see through ones after, called automatically
- The main layer also draws the sky, the render callbacks and the debug shapes
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
objects | Array.<EngineObject3D> | |||
isDefault | boolean | <optional> | true |
- Source
screenToGround(screenPos, groundHeightopt, canvasSizeopt) → {Vector3|undefined}
Where a screen position lands on a flat ground plane, for top down games; use HeightMap.raycast for terrain
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
screenPos | Vector2 | Same space as mousePosScreen | ||
groundHeight | number | <optional> | 0 | World height of the ground plane |
canvasSize | Vector2 | <optional> | Defaults to the main canvas size, as in screenToRay |
- Source
- undefined when the ray misses the plane
- Type:
- Vector3 |
undefined
screenToRay(screenPos, canvasSizeopt) → {Ray3D}
Get the world ray under a screen position, for clicking on things in 3D
- Uses the camera where it is right now, so it is fine to call from gameUpdate
- It brings the view matrices up to date for that canvas, so worldToScreen stays its exact opposite
| Name | Type | Attributes | Description |
|---|---|---|---|
screenPos | Vector2 | Same space as mousePosScreen | |
canvasSize | Vector2 | <optional> | Defaults to the main canvas size |
- Source
- Starts at the camera with a unit direction, or on the near plane when orthographic
- Type:
- Ray3D
setFog(fogStart, fogEnd, fogColoropt)
Set where fog starts and ends, and its color
| Name | Type | Attributes | Description |
|---|---|---|---|
fogStart | number | Distance from the camera where fog starts | |
fogEnd | number | Distance where fog is total, 0 disables fog | |
fogColor | Color | <optional> | Leaves the color alone when not passed, setSky sets it to the horizon |
- Source
setSky(topColoropt, horizonColoropt, bottomColoropt, ambientopt) → {Mesh}
Build a sky dome, set it as the sky, and light the scene by it: the fog takes the horizon color, and the ambient light comes from the top color above and the bottom color below, both at the ambient strength
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
topColor | Color | <optional> | Straight up | |
horizonColor | Color | <optional> | Level with the camera | |
bottomColor | Color | <optional> | Straight down, defaults to the horizon color | |
ambient | number | <optional> | 0.5 | How much of the sky colors lights the scene as ambient, 0 for none |
- Source
- The dome, also in render3D.sky
- Type:
- Mesh
updateMatrices(aspectopt)
Rebuild the view and projection matrices from the camera, called automatically each frame
| Name | Type | Attributes | Description |
|---|---|---|---|
aspect | number | <optional> | Width over height, defaults to the main canvas |
- Source
updateShadowMatrix()
Rebuild the light's view projection around the shadow center, called automatically each frame shadows are on
- Source
worldToClip(pos) → {Vector3|undefined}
Where a world point lands on screen as -1 to 1 across and up, with z as depth
- Uses this frame's camera, call updateMatrices first if the camera just moved
| Name | Type | Description |
|---|---|---|
pos | Vector3 |
- Source
- undefined when behind the camera or closer than the near plane
- Type:
- Vector3 |
undefined
worldToScreen(pos, canvasSizeopt) → {Vector2|undefined}
Project a world point to screen space pixels, same space as mousePosScreen
- The opposite of screenToRay, and it takes the same canvas so the pair agree
| Name | Type | Attributes | Description |
|---|---|---|---|
pos | Vector3 | ||
canvasSize | Vector2 | <optional> | Defaults to the main canvas size, as in screenToRay; the projection is whatever updateMatrices last built, which screenToRay does for its canvas |
- Source
- undefined when behind the camera or closer than the near plane
- Type:
- Vector2 |
undefined