Render3D. EngineObject3D

EngineObject3D - An EngineObject with a 3D transform and a mesh

  • Set pos3D, rotation3D and scale3D instead of the 2D pos, size and angle
  • Gets update, children, timers, destroy and renderOrder from EngineObject
  • velocity3D is added to pos3D each frame, slowed by damping, and render3D.gravity pulls it once it has a mass
  • Objects face -Z, the same way the camera does, so lookAt turns them to face a point
  • The 2D pos and velocity are still there but nothing draws them
  • These inherited fields are 2D only and do nothing here: angle, angleVelocity, additiveColor, drawSize and mirror; damping, angleDamping, clampSpeed, friction and groundObject work as in 2D, on velocity3D and angleVelocity3D
  • The inherited shader works here as in 2D, and with emissive at 1 its snippet does its own lighting
  • Set sync2D for a 2D game with 3D looks, pos and angle then drive pos3D and rotation3D, which is the one way those 2D fields reach a 3D object
  • setCollision takes the same flags as in 2D, but the solid collision happens in 3D against size3D
  • The solid box turns with rotation3D, so a turned wall or a ramp collides as it looks; resting on one no steeper than groundAngle stands there
  • Its tile and raycast halves are 2D only so they default off here, and a child sits solid collision out
  • A sync2D object collides in 2D instead, which needs the 2D size set as well as size3D
  • setMesh swaps the mesh and frees the old one, for text and terrain that get built again
  • addChild attaches the 3D transform, and pos3D becomes an offset from the parent; attach keeps the child where it is and works the offset out, and removeChild leaves it where it was in the world
  • The 2D offset arguments of addChild do nothing here, set the child's pos3D

Constructor

new EngineObject3D(pos3Dopt, meshopt, tileInfoopt, coloropt)

Create a 3D object and add it to the object list

Parameters:
NameTypeAttributesDescription
pos3DVector3<optional>

World space position

meshMesh<optional>

Mesh to draw, undefined draws nothing

tileInfoTileInfo | TextureInfo<optional>

Texture, mesh uvs map across the tile; a whole TextureInfo becomes the tile that covers it

colorColor<optional>

Tint

Source
Example
class Spinner extends EngineObject3D
{
    constructor(pos) { super(pos, buildBox(), undefined, RED); }
    update() { this.rotation3D.y += .02; }
}

Extends

  • EngineObject

Members

additive

Properties
TypeDescription
boolean

Additive blending, in the transparent stage

Source

angleVelocity3D

Properties
TypeDescription
Vector3

Added to rotation3D each frame by the engine before update, slowed by angleDamping

Source

castShadow

Properties
TypeDescription
boolean

Draw into the shadow map when render3D.shadows is on; sprites and cut out textures cast their outline, an object faded below half its alpha casts nothing, a see through one casts only when textured, and additive objects never cast

Source

collideAsSphere3D

Properties
TypeDescription
boolean

Collide as the sphere that fits size3D instead of as the size3D box, so it rolls around corners

Source

emissive

Properties
TypeDescription
number

How much it lights itself: 0 is lit as normal, 1 is its own color with no shading, for lamps and glowing things, between is partly self lit, and above 1 is brighter than its color, for bloom

Source

emissiveMap :TextureInfo|undefined

Type:
  • TextureInfo | undefined
Properties
TypeDescription
TextureInfo | undefined

A texture of where it glows, added on top of the lit surface so it shows in the dark, like lit windows; read at the color texture's coordinates

Source

emissiveMapColor

Properties
TypeDescription
Color

Multiplies the emissive map, as glTF's emissiveFactor

Source

groundAngle

Properties
TypeDescription
number

The steepest slope it stands on, in radians from level, PI/4 by default: resting on a solid within this of flat sets groundObject and holds it still, steeper it slides down

Source

localMatrix :Matrix4|undefined

Type:
  • Matrix4 | undefined
Properties
TypeDescription
Matrix4 | undefined

The transform from its parent, used in place of pos3D, rotation3D and scale3D when set, for one they cannot hold like a glTF pose with shear; read every frame it is set

Source

matrixParent :EngineObject3D|undefined

Type:
  • EngineObject3D | undefined
Source

mesh :Mesh|undefined

Type:
  • Mesh | undefined
Properties
TypeDescription
Mesh | undefined

Mesh to draw

Source

normalMap :TextureInfo|undefined

Type:
  • TextureInfo | undefined
Properties
TypeDescription
TextureInfo | undefined

A normal map that bends the surface at each texel so it catches the light like bumps and grooves, green pointing up the image as OpenGL and glTF have it; read at the color texture's coordinates, see normalMapFromHeight to make one in code

Source

normalScale

Properties
TypeDescription
number

How strongly the normal map bends the surface, 0 turns it off, as glTF's scale

Source

pixelated

Properties
TypeDescription
boolean

Keep this object's texture pixels hard edged, for pixel art that should not blur or bleed

Source

pos3D

Properties
TypeDescription
Vector3

World space position, local to the parent when attached to an EngineObject3D

Source

receiveShadow

Properties
TypeDescription
boolean

Darkened by the shadow map when render3D.shadows is on

Source

reflectivity

Properties
TypeDescription
number

How much it reflects the sky, 0 none and 1 a mirror of it; the edges seen at a glancing angle reflect more either way, as water and glass do

Source

renderAfter2D :boolean|undefined

Type:
  • boolean | undefined
Properties
TypeDescription
boolean | undefined

Draw this object over the 2D scene, undefined uses render3D.renderAfter2D

Source

rotation3D

Properties
TypeDescription
Vector3

Rotation vec3(pitch, yaw, roll) in radians, local to the parent when attached to an EngineObject3D

Source

scale3D

Properties
TypeDescription
Vector3

Scale, local to the parent when attached to an EngineObject3D

Source

shininess

Properties
TypeDescription
number

The highlight's exponent, how small and sharp it is: 4 is broad like rubber, 16 the default, 100 sharp like polished metal; shows only with specular above 0

Source

softShadow

Properties
TypeDescription
number

Diameter of a soft shadow drawn under the object on render3D.softShadowHeight, 0 for none; scale3D and a parent's scale grow it, so set it once for the unscaled object

Source

specular

Properties
TypeDescription
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

sync2D

Properties
TypeDescription
boolean

Copy the 2D pos and angle into pos3D and rotation3D each frame, for 2D games with 3D looks; set mass to use 2D physics, and pos3D.z stays yours to set or move with velocity3D.z

Source

transparent

Properties
TypeDescription
boolean

Draw in the transparent stage, blended and sorted far to near with depth writes off; on for a sprite

Source

upright

Properties
TypeDescription
boolean

A sprite stands on world up instead of tilting toward the camera

Source

velocity3D

Properties
TypeDescription
Vector3

Added to pos3D each frame by the engine before update, like the 2D velocity, no super call needed; damping and render3D.gravity act on it once the object has a mass

Source

Methods

addChild(child, localPosopt, localAngleopt) → {EngineObject}

Attaches a child, its pos3D, rotation3D and scale3D taken as the offset from this one; returns child for chaining

  • The 2D offset arguments do nothing for an EngineObject3D child, set its pos3D
Parameters:
NameTypeAttributesDescription
childEngineObject
localPosVector2<optional>
localAnglenumber<optional>
Source
Returns:

The child object attached

Type: 
EngineObject

attach(child) → {EngineObject}

Attaches a child without moving it: its pos3D, rotation3D and scale3D become what they have to be under this parent to keep its world transform, where addChild takes them as the offset; returns child for chaining

  • A parent scaled unevenly and a child turned under it make a shear, which those three values cannot hold, so the child comes out as close as they can get; a uniform scale is exact
Parameters:
NameTypeDescription
childEngineObject
Source
Returns:

The child object attached

Type: 
EngineObject

collideWithVoxel(type, cell) → {boolean}

Called by a VoxelMap to ask whether a block stops this object, a hook to let one through or react to it

Parameters:
NameTypeDescription
typenumber

The block's type, 1 to 255

cellVector3

The block's cell in the map

Source
Returns:
  • true to be stopped by it, every block stops it by default
Type: 
boolean

getForward3D() → {Vector3}

Returns the direction the object faces, its -Z axis in the world

Source
Returns:
Type: 
Vector3

getMatrix() → {Matrix4}

Returns a copy of the object's world transform, the parent's included when attached to an EngineObject3D

  • The object keeps its matrix and rebuilds it only when its position, rotation or scale changed, so this is cheap to call
Source
Returns:
Type: 
Matrix4

getRight3D() → {Vector3}

Returns the object's right axis in the world

Source
Returns:
Type: 
Vector3

getUp3D() → {Vector3}

Returns the object's up axis in the world

Source
Returns:
Type: 
Vector3

getWorldPos3D() → {Vector3}

Returns the world position

Source
Returns:
Type: 
Vector3

lookAt(target)

Turn the object so its -Z axis points at a world space target, sets pitch and yaw and clears roll

Parameters:
NameTypeDescription
targetVector3
Source

removeChild(child)

Removes a child from this one, it stays where it is in the world: its pos3D, rotation3D and scale3D become its world values, with the same shear caveat as attach; a child being destroyed is let go as it is

Parameters:
NameTypeDescription
childEngineObject
Source

render()

2D rendering is skipped, the mesh is drawn by render3D during the 3D pass

Source

render3D() → {void}

Draw the object in 3D, called by the 3D pass with the draw state set from this object's flags, draws the mesh by default

Source
Returns:
Type: 
void

setCollision(collideSolidObjectsopt, isSolidopt, collideLevelopt, collideRaycastopt)

Set how this object collides, the same flags as in 2D

  • Solid collision happens in 3D here, against size3D boxes or spheres; a child sits it out
  • The boxes turn with rotation3D, against height maps and voxel maps an object is still its upright box
  • A sync2D object collides in 2D instead, against the 2D size, so set that as well as size3D
Parameters:
NameTypeAttributesDefaultDescription
collideSolidObjectsboolean<optional>
true

Take part in solid collision

isSolidboolean<optional>
true

Block other objects, a pair where neither one blocks passes through; blocking needs collideSolidObjects, so isSolid on its own is not allowed

collideLevelboolean<optional>
true

Collide with the level, the height maps and voxel maps, or the 2D tile layers for a sync2D object

collideRaycastboolean<optional>
false

Raycasts, 2D only; 3D has render3D.pick and engineObjectsRaycast3D

Source

setMesh(meshopt) → {Mesh|undefined}

Draw a different mesh and free the GPU buffer of the one it replaces

  • For a mesh built again when something changes, like a score, a rebuilt terrain or a loaded model
  • A mesh another object is still drawing is left alone, since builders are often shared
  • Freeing one held somewhere else only costs it an upload, the points it was built from stay
Parameters:
NameTypeAttributesDescription
meshMesh<optional>

The mesh to draw from now on, undefined to draw nothing

Source
Returns:
  • The mesh passed in
Type: 
Mesh | undefined

updatePhysics()

Move by the 3D velocities and push out of solids, called automatically each frame before update, like the 2D physics

  • update runs once every object has moved and collided, so bounce off anything else there, it lands before the draw
  • Override this and call super to change how the object moves itself
  • A sync2D object runs the 2D physics as well, and collides there instead
Source

updateTransforms(updateChildrenopt)

Move a child by its own velocities, bring a sync2D object's pos3D up to its 2D pos, then update the children, called automatically each frame

Parameters:
NameTypeAttributesDefaultDescription
updateChildrenboolean<optional>
true

Also update the children's transforms

Source