LittleJS 1.30.1

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:67

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:531

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:46

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
  • 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
  • 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:106

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 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 a level with no block changes nothing
level Level3D

The level, the level editor edits this same object

Returns
  • What each object's type made, a function that made nothing is left out
level3DLoadPrefab(name, url) → Promise<void>asyncrender3dLevel.js:581

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:488

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

Returns
  • What the type made, a Prefab3D for a prefab, undefined when there is no such type
level3DAddPrefab('House', await fetchJSON('house.json'));
level3DSpawn('House', vec3(10, 0, 0), vec3(0, PI/2, 0));
level3DVoxelSetup(tileInfo, setup)render3dLevel.js:145

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:84

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:94

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:137

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:105

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:126

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:119

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