Engine. EngineObject

LittleJS Object Base Object Class

  • Top level object class used by the engine
  • Automatically adds self to object list
  • Will be updated and rendered each frame
  • Renders as a sprite from a tilesheet by default
  • Can have color and additive color applied
  • 2D Physics and collision system
  • Sorted by renderOrder
  • Objects can have children attached
  • Parents are updated before children, and set child transform
  • Call destroy() to get rid of objects

The physics system used by objects is simple and fast with some caveats...

  • Collision uses the axis aligned size, the object's rotation angle is only for rendering
  • Objects are guaranteed to not intersect tile collision from physics
  • If an object starts or is moved inside tile collision, it will not collide with that tile
  • Collision for objects can be set to be solid to block other objects
  • Objects may get pushed into overlapping other solid objects, if so they will push away
  • A static solid (mass 0) moved by its velocity, like a door or an elevator, pushes objects out of its way
  • Solid objects are more performance intensive and should be used sparingly

Constructor

new EngineObject(posopt, sizeopt, tileInfoopt, angleopt, coloropt, renderOrderopt)

Create an engine object and adds it to the list of objects

Parameters:
NameTypeAttributesDefaultDescription
posVector2<optional>
vec2()

World space position of the object

sizeVector2<optional>
vec2(1)

World space size of the object

tileInfoTileInfo<optional>

Tile info to render object (undefined is untextured)

anglenumber<optional>
0

Angle the object is rotated by

colorColor<optional>
WHITE

Color to apply to tile when rendered

renderOrdernumber<optional>
0

Objects sorted by renderOrder before being rendered

Example
// create an engine object, normally you would first extend the class with your own
const pos = vec2(2,3);
const object = new EngineObject(pos);

Members

additiveColor :Color|undefined

Type:
  • Color | undefined
Properties
TypeDescription
Color | undefined

Additive color to apply when rendered

angle

Properties
TypeDescription
number

Angle to rotate the object

angleDamping

Properties
TypeDescription
number

Fraction of angular velocity kept each frame, 1 keeps all of it, 0 stops at once

angleVelocity

Properties
TypeDescription
number

Angular velocity of the object, in radians per frame

castShadow

Properties
TypeDescription
boolean

Does this object draw into the light system's shadow map; false for a floor layer, a background, a pickup

children :Array.<EngineObject>

Type:
  • Array.<EngineObject>
Properties
TypeDescription
Array.<EngineObject>

List of children of this object

clampSpeed

Properties
TypeDescription
boolean

Limit object speed along x and y axis

collideLevel :boolean

Type:
  • boolean
Properties
TypeDescription
boolean

Object collides with the level, its tile collision layers

collideRaycast

Properties
TypeDescription
boolean

Object collides with raycasts

collideSolidObjects

Properties
TypeDescription
boolean

Object collides with solid objects

collideTiles :boolean

Type:
  • boolean
Deprecated
  • since 1.20, use collideLevel

color

Properties
TypeDescription
Color

Color to apply when rendered

damping

Properties
TypeDescription
number

Fraction of velocity kept each frame, 1 keeps all of it, 0 stops at once

destroyed

Properties
TypeDescription
boolean

Has object been destroyed?

drawSize :Vector2|undefined

Type:
  • Vector2 | undefined
Properties
TypeDescription
Vector2 | undefined

Size of object used for drawing, uses size if not set

emissive

Properties
TypeDescription
number

With the light system, how much it lights itself: 0 lit only by the lights, 1 full brightness in its own colors whatever the lights do, between partly; drawn into the lightmap through renderEmissive, as 3D's emissive. Exact for solid pixels; a partly transparent one is self lit by its alpha too, so a half alpha pixel shows at a quarter and a fading emissive sprite fades a little faster

friction

Properties
TypeDescription
number

Fraction of sliding speed kept each frame on the ground, 1 is no friction, 0 stops at once, the more slippery of the object and its ground is used

gravityScale

Properties
TypeDescription
number

How much to scale gravity by for this object

groundObject :EngineObject|undefined

Type:
  • EngineObject | undefined
Properties
TypeDescription
EngineObject | undefined

Object we are standing on, if any

isSolid

Properties
TypeDescription
boolean

Object collides with and blocks other objects

localAngle

Properties
TypeDescription
number

Local angle if child

localPos :Vector2|undefined

Type:
  • Vector2 | undefined
Properties
TypeDescription
Vector2 | undefined

Position relative to the parent, only while attached to one

mass

Properties
TypeDescription
number

How heavy the object is, static if 0: a static object moves by its velocity but does not collide on its own, the moving ones collide with it

mirror

Properties
TypeDescription
boolean

Should the rendered tile flip along the y axis. Affects rendering and the local→world transform of attached children (a mirrored parent flips its children's localPos.x and localAngle). Does not affect this object's own physics, collision, or localToWorld/worldToLocal.

parent :EngineObject|undefined

Type:
  • EngineObject | undefined
Properties
TypeDescription
EngineObject | undefined

Parent of object if in local space

persistent

Properties
TypeDescription
boolean

Object is skipped by engineObjectsDestroy, for things that outlive a level like a camera

  • Calling destroy on it still destroys it, and its children go with it either way

pos

Properties
TypeDescription
Vector2

World space position of the object

renderOrder

Properties
TypeDescription
number

Objects are sorted by render order

restitution

Properties
TypeDescription
number

How bouncy the object is when colliding (0-1)

shader :Shader|undefined

Type:
  • Shader | undefined
Properties
TypeDescription
Shader | undefined

Custom shader to render with, undefined for the engine's own

size

Properties
TypeDescription
Vector2

World space width and height of the object

spawnTime

Properties
TypeDescription
number

Track when object was created

tileInfo :TileInfo|undefined

Type:
  • TileInfo | undefined
Properties
TypeDescription
TileInfo | undefined

Tile info to render object (undefined is untextured)

velocity

Properties
TypeDescription
Vector2

Velocity of the object, in world units per frame

Methods

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

Attaches a child to this with a local transform, returns child for chaining

Parameters:
NameTypeAttributesDefaultDescription
childEngineObject
localPosVector2<optional>
vec2()
localAnglenumber<optional>
0
Returns:

The child object added

Type: 
EngineObject

applyAcceleration(acceleration)

Apply acceleration to this object (adjust velocity, not affected by mass)

  • Does nothing on a static object (mass 0), set its velocity instead
Parameters:
NameTypeDescription
accelerationVector2

applyAngularAcceleration(acceleration)

Apply angular acceleration to this object

  • Does nothing on a static object (mass 0), set its angleVelocity instead
Parameters:
NameTypeDescription
accelerationnumber

applyForce(force)

Apply force to this object (adjust velocity, affected by mass)

  • Does nothing on a static object (mass 0), set its velocity instead
Parameters:
NameTypeDescription
forceVector2

attach(child) → {EngineObject}

Attaches a child to this without moving it: the local transform is worked out from where the child is now, where addChild takes one; a child of something else is moved over, returns child for chaining

Parameters:
NameTypeDescription
childEngineObject
Returns:

The child object attached

Type: 
EngineObject

collideWithObject(object, pushopt) → {boolean}

Called by the engine to check if an object collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.

  • Both objects of a touching pair are asked once a frame, whichever order they update in; an object that destroys itself here is gone at the end of the frame and is still asked about the pairs left this frame, so a bullet that should hit one thing checks its own destroyed flag first
Parameters:
NameTypeAttributesDescription
objectEngineObject

the object to test against

pushVector3<optional>

what it would take to move this object clear, a Vector3 from the 3D plugin, undefined in 2D

Returns:
  • true if the collision should be resolved by modifying it's position and velocity
Type: 
boolean

collideWithTile(tileData, pos) → {boolean}

Called to check if a tile collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.

  • Called for each solid tile the physics tests, which can be several times a frame for the same tile, and for positions it only tries, so keep it free of side effects or guard them to once a frame
  • this.pos has already moved, so a check on where it came from, like a one way platform, needs the position saved in update, as the platformer example does
Parameters:
NameTypeDescription
tileDatanumber

the value of the tile at the position

posVector2

the tile's bottom left corner in world space

Returns:
  • true if the collision should be resolved by modifying it's position and velocity
Type: 
boolean

destroy(immediateopt)

Destroy this object, destroy its children, detach its parent, and mark it for removal

Parameters:
NameTypeAttributesDefaultDescription
immediateboolean<optional>
false

true removes attached effects like particle emitters at once, false lets them finish first

getAliveTime() → {number}

How long since the object was created

Returns:
Type: 
number

getMirrorSign() → {number}

Get the direction of the mirror

Returns:

-1 if this.mirror is true, or 1 if not mirrored

Type: 
number

getRight(scaleopt) → {Vector2}

Get this object's right vector

Parameters:
NameTypeAttributesDefaultDescription
scalenumber<optional>
1

length of the vector

Returns:
Type: 
Vector2

getSpeed() → {number}

Get the speed of this object

Returns:
Type: 
number

getUp(scaleopt) → {Vector2}

Get this object's up vector

Parameters:
NameTypeAttributesDefaultDescription
scalenumber<optional>
1

length of the vector

Returns:
Type: 
Vector2

isOverlapping(pos, sizeopt) → {boolean}

Check if overlapping a point or aligned bounding box

Parameters:
NameTypeAttributesDefaultDescription
posVector2

Center of box

sizeVector2<optional>
vec2()

Size of box, uses a point if undefined

Returns:
Type: 
boolean

isOverlappingObject(object) → {boolean}

Check if this object's box overlaps another object's box

Parameters:
NameTypeDescription
objectEngineObject
Returns:
Type: 
boolean

localToWorld(pos)

Convert from local space to world space

Parameters:
NameTypeDescription
posVector2

local space point

localToWorldVector(vec)

Convert from local space to world space for a vector (rotation only)

Parameters:
NameTypeDescription
vecVector2

local space vector

removeChild(child)

Removes a child from this one, it stays where it is in the world

Parameters:
NameTypeDescription
childEngineObject

render()

Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder

renderDebugInfo()

Render debug info for this object

renderEmissive()

Draw this object's shape into the light system's lightmap, called during its light pass when emissive is above 0; what it draws shows in its own colors that much brighter. Calls render() by default so the whole object glows; override to glow a part, like a robot's eyes

renderLight()

Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default.

renderShadow()

Draw this object into the light system's shadow map, called during its shadow pass when castShadow is set. Calls render() by default so the object casts its own shape; override to cast a different one, like a blob at a character's feet so its body stays lit; screen space WebGL draws in render() are skipped during the pass

setCollision(collideSolidObjectsopt, isSolidopt, collideLevelopt, collideRaycastopt)

Set how this object collides

Parameters:
NameTypeAttributesDefaultDescription
collideSolidObjectsboolean<optional>
true

Does it collide with solid objects?

isSolidboolean<optional>
true

Does it collide with and block other objects? (expensive in large numbers)

collideLevelboolean<optional>
true

Does it collide with the level, its tile collision layers?

collideRaycastboolean<optional>
true

Does it collide with raycasts?

toString() → {string}

Returns string containing info about this object for debugging

Returns:
Type: 
string

update()

Update the object, called automatically by engine once each frame. Does nothing by default.

updatePhysics()

Update the object physics, called automatically by engine once each frame. Can be overridden to stop or change how physics works for an object.

updateTransforms(updateChildrenopt)

Update the object transform, called automatically by engine even when paused

Parameters:
NameTypeAttributesDefaultDescription
updateChildrenboolean<optional>
true

Also update the children's transforms

worldToLocal(pos)

Convert from world space to local space

Parameters:
NameTypeDescription
posVector2

world space point

worldToLocalVector(vec)

Convert from world space to local space for a vector (rotation only)

Parameters:
NameTypeDescription
vecVector2

world space vector