LittleJS 1.31.0

Level3D

LittleJS 3D Level Plugin

  • A 3D level is a list of objects, each a type name, a position, and a rotation, scale and properties where they are not the default, kept as plain JSON that can be written by hand
  • level3DAddType names the types a game makes them from, as objectLayersAddType does in 2D
  • level3DLoad makes every object of a level
  • Box, Sphere, Cylinder and Light are built in, to block out and light a level with no code
  • The 3D level editor, in debug builds, edits the level a game loaded

Classes

Functions

Typedefs

Functions

level3DAddMesh(name, mesh, tileInfo, color, meshCollision)render3dLevel.js:97

Add a type that is a mesh and nothing more, a static prop with no class to write, for a built mesh or a model

  • Each object has a color, a solid property, which collides as the box around the mesh, and a meshCollision property, which makes the level's ground and walls of the mesh's own triangles in its place, with a MeshCollider as its child, so what moves over it follows its shape: a ramp, a rock, a bridge
name string

The type the objects have in the level

mesh Mesh

Shared by every object of the type

tileInfo TileInfo optional

Its texture

color Color optional

Its color, an object's own color property goes over it

meshCollision boolean optional, default false

Whether objects of the type collide by the mesh's triangles unless they say not

level3DAddMesh('Tree', treeMesh, tile(4));
level3DAddMesh('Ramp', rampMesh, tile(2), WHITE, true);
level3DAddPrefab(name, prefab)render3dLevel.js:656

Add a prefab: a small level, its objects placed about its own origin, to place many times under one name

  • It is a type from then on: a level's object of that type, the level editor's Place list and level3DSpawn make an instance, a Prefab3D; an instance is made of the prefab as it is then, so the level editor, where a prefab changes, makes its instances again
  • The prefab is a level as the level editor saves it, {objects: [...]}, so the editor is the prefab editor too; only its objects are used, and they may be of other prefabs
  • With attached true in it the parts are children of the instance and move with it as one body, without collision of their own, a prefab inside it too; its handle is at the middle of the box around them and its size3D is that box, so setCollision makes the body solid where it is seen; otherwise each part is an object of its own in the world and collides as one placed by hand does
  • Adding a name again replaces it
name string

The type its instances have in a level

prefab Level3DPrefab

Its objects, about its own origin, and whether they are attached

level3DAddPrefab('Tower', {objects: [{type: 'Box', pos: [0, 1, 0], scale: [2, 2, 2]},
    {type: 'Cylinder', pos: [0, 3, 0]}]});
level3DLoad({objects: [{type: 'Tower', pos: [5, 0, 5]}, {type: 'Tower', pos: [-5, 0, 5], rotation: [0, 45, 0]}]});
level3DAddType(name, make, defaults, tileInfo)render3dLevel.js:75

Add a type of object, so level3DLoad makes one wherever a level has an object of that type

  • The name is a string because minified builds rename classes
  • A class, or any function with a prototype, is made with new make(pos3D, properties); an arrow function is called as make(pos3D, properties), for what is not an object, like a player start
  • properties is the defaults with the object's own values over them, and each of the type's own is also set on what was made; a property the type has no default for is in properties and is not set
  • An object default, plain or of a class, takes a level's object member by member, so a member the level leaves out keeps the default's and {} is the whole default, as 2D's class properties are
  • A list over a list default is read item by item as the default's item there, its last past its end, so a list of vectors or Colors needs a default with one item of that kind, [vec3()], and an empty default, [], takes the items as written, a vector as a plain array
  • Give a class a constructor of its own that takes the position: one that hands every argument on to EngineObject3D would hand it the properties as its mesh
  • An EngineObject3D then gets the object's rotation, and its scale times the scale it was made with
  • A constructor may put the body away from the position it is given, lifted by half its height to stand on its feet: that offset is kept, scaled and turned with the object, through a reload, the 3D editor's moves and landing, and a prefab; one worked out from where it ends up, as sticking itself to the ground, is kept as the offset it had when made, so the editor shows it where a move puts it, not where a reload would
  • Adding a name again replaces it, Box, Sphere, Cylinder and Light too
name string

The type the objects have in the level

make (function(Vector3, ObjectProperties): unknown)|(function(new: unknown, Vector3, ObjectProperties))

A class made at each object's position, or a function called with it

defaults ObjectProperties optional

Properties of each one made, the level editor shows inputs for them

tileInfo TileInfo optional

An icon for the level editor

level3DAddType('Crate', Crate, {health: 3});
level3DAddType('PlayerStart', (pos)=> playerStart = pos);
level3DLoad(level) → Array<any>render3dLevel.js:150

Make the objects of a level, each from the type added for its name

  • The level is an object: {littlejs3D: 1, objects: [{id, type, pos: [x, y, z]}, ...]}, and {} is a new one
  • rotation is pitch, yaw and roll in degrees, scale is a number for each axis, both left out when they are the default, and properties holds what differs from the type's defaults
  • A Color property is a #rrggbb or #rrggbbaa string, a Vector2 or Vector3 an array, as the default says
  • An object whose type was not added is skipped, with a warning in debug builds
  • What a file written by hand gets wrong uses the default: a value that is not of its default's type
  • An object over an object default is merged into it member by member, so {} is the whole default, and a vector member in it is written as an array too
  • A list over a list default is read item by item as the default's item there, its last past its end, an item of another kind keeping the default's with a warning; an empty default takes the items as written
  • An object its type can not make is skipped with an error in debug builds, where asserts throw, and the rest of the level is made
  • A level may hold a map of blocks, in a voxels block: pos, its corner, size, its cells along x, y and z, and blocks, runs of a count and a type along x, then y, then z; it is made a VoxelMap, the first of what is returned, see level3DVoxelSetup for its sheet
  • A level may hold a terrain, in a terrain block: pos, its center, size, its size in the world along x and z, height, how tall a full height is, color, and heights, rows of 0 to 1 from -z to +z, each from -x to +x; it is made a HeightMap, returned with what else was made; paint, when it has it, colors its samples: colors, a list, and cells, runs of a count and a color along the rows, 0 for the terrain's own and 1 the list's first
  • A level may hold prefabs of its own, in a prefabs block, each by its name as level3DAddPrefab takes it; they are added before its objects are made, one the game added itself keeps its place
  • A level may set the scene too, in a scene block beside its objects: sky, three colors for straight up, the horizon and straight down, ambient, how much of them lights the scene, .5 when not given, sunDirection and sunColor, fog, its start and end, fogColor, the horizon color when not given, shadows, lensFlare, the sun's lens flare, and skyBox and environment, each six image urls as loadCubeMap takes them, which load in the background and are set when they have; what the block leaves out stays as the game set it, and the next level, with a block or none, puts back what this block set, each setting the game has not changed since
  • The 3D editor keeps the HeightMap and VoxelMap made here through its edits, so a game may hold them, but a voxel resize or a terrain of another shape is a new map, and a map whose block is taken out is out of the world until an undo: a game that holds one takes it again in onRestart, or looks it up when the one it holds is destroyed or not in engineObjects, as examples/3d does
  • In a 3D editing session what the editor places or makes again, its maps too, joins the list this gives back, and leaves it when taken out, so a game that unloads the level by its list takes the editor's objects with it: keep this array as given, not a filtered or spread copy, for the editor to add to and take from; an object made again takes its old one's place in it and one taken out is spliced, so look an object up again rather than keep its index
level Level3D

The level, the level editor edits this same object

Returns
  • What each object's type made, an object of the game's, so the level can be unloaded by it; a function that made nothing, or gave back a value of the engine's, as a marker's position, is left out
level3DLoadPrefab(name, url) → Promise<void>asyncrender3dLevel.js:706

Load a prefab from a file the level editor saved and add it

name string

The type its instances have in a level

url string
level3DSpawn(type, pos3D, rotation3D, scale3D, properties) → anyrender3dLevel.js:610

Make one object of a type added with level3DAddType, level3DAddMesh or level3DAddPrefab, from code, with no level: a prefab's instance, or a plain type

type string

The type's name

pos3D Vector3 optional
rotation3D Vector3 optional

In radians, as an object has it

scale3D Vector3 optional

Times the scale the type makes it with

properties ObjectProperties optional

Over the type's defaults; a color or a vector may be a Color or a vector, or written as a level file has it, a hex string or an array; a value not of its default's type keeps the default; each is copied for the object, a list or a plain object with what is in it, as a level file's are, so the object has its own and not the one passed; a plain object over an object default is merged into it member by member, and a list over a list default item by item, as a level file's are, and an instance of a class, at any depth, is copied with its copy method, or shared when it has none; keep defaults to numbers, text, true or false, Colors, vectors, and lists and plain objects of those

Returns
  • What the type made, a Prefab3D for a prefab, undefined when there is no such type or it made no object of the game's
level3DAddPrefab('House', await fetchJSON('house.json'));
level3DSpawn('House', vec3(10, 0, 0), vec3(0, PI/2, 0));
level3DSpawn('Crate', vec3(0, 1, 0), undefined, undefined, {color: RED});
level3DVoxelSetup(tileInfo, setup)render3dLevel.js:191

How a level's block map is made: the sheet its blocks show tiles of, and a function to set it up

  • A level's voxels block makes a VoxelMap when the level loads, with texture 0 and the default tile size unless a sheet is given here; a block's type shows that tile of the sheet on every face; a game that has loaded no image gets plain blocks, a color for each type
  • setup is called with each map a level makes, to give block types their own faces or make them see-through
  • Call it before level3DLoad; with no arguments the defaults are back
tileInfo TileInfo optional

The sheet's first tile, as for a VoxelMap

setup function optional
level3DVoxelSetup(tile(0, 16, 1), (map)=> map.setBlockType(1, {top: 0, side: 1, bottom: 2})); // grass

Typedefs

Level3D : ObjectengineEditor.js:93

A 3D level as it is saved, what level3DLoad takes and the 3D level editor edits

littlejs3D number optional

The format's version, 1

objects Array<Level3DObject> optional

What it places, none when left out

scene Level3DScene optional

The sky, sun, fog and the rest it sets

voxels Level3DVoxels optional

A block map

terrain Level3DTerrain optional

A height map

prefabs Object<string, Level3DPrefab> optional

The level's own prefabs by name

Level3DObject : ObjectengineEditor.js:103

An object a 3D level places, see level3DLoad

type string

The name its type was added with

id number optional

Its id in the level, the editor gives each one

pos Array<number> optional

Where it is, 0, 0, 0 when left out

rotation Array<number> optional

Pitch, yaw and roll in degrees

scale Array<number> optional

Times the scale its type makes it with

properties Object<string, any> optional

What differs from its type's defaults; a Color is a hex string and a vector an array

Level3DPrefab : ObjectengineEditor.js:146

A prefab, a small level placed many times, see level3DAddPrefab

objects Array<Level3DObject> optional

About its own origin

attached boolean optional

Its parts are children of the instance, moving with it as one body

Level3DScene : ObjectengineEditor.js:114

A 3D level's scene block, what it sets of the renderer; a setting left out stays as the game set it

sky Array<string> optional

Hex colors straight up, at the horizon and straight down

ambient number optional

How much the sky lights the scene, .5 when not given

sunDirection Array<number> optional

Pointing toward the sun

sunColor string optional

A hex color

fog Array<number> optional

Where it starts and ends

fogColor string optional

A hex color, the sky's horizon when not given

shadows boolean optional
lensFlare boolean optional

The sun's lens flare

skyBox Array<string> optional

Six image urls, as loadCubeMap takes them

environment Array<string> optional

Six image urls for reflections

Level3DTerrain : ObjectengineEditor.js:135

A 3D level's terrain, made a HeightMap

pos Array<number> optional

Its center

size Array<number>

Its size in the world along x and z

height number optional

How tall a full height is, 1 when not given

color string optional

A hex color

heights Array<Array<number>>

Rows of 0 to 1 from -z to +z, each from -x to +x

paint Object optional

Hex colors, and runs of a count and a color along the rows, 0 the terrain's own color and 1 the first of the list

Level3DVoxels : ObjectengineEditor.js:128

A 3D level's block map, made a VoxelMap

pos Array<number> optional

Its corner

size Array<number>

Its cells along x, y and z

blocks Array<number> optional

Runs of a count and a type, along x, then y, then z