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 stringThe type the objects have in the level
mesh MeshShared by every object of the type
tileInfo TileInfo optionalIts texture
color Color optionalIts color, an object's own color property goes over it
meshCollision boolean optional, default falseWhether 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);
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 stringThe type its instances have in a level
prefab Level3DPrefabIts 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]}]});
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 stringThe 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 optionalProperties of each one made, the level editor shows inputs for them
tileInfo TileInfo optionalAn icon for the level editor
level3DAddType('Crate', Crate, {health: 3});
level3DAddType('PlayerStart', (pos)=> playerStart = pos);
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 Level3DThe 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
Load a prefab from a file the level editor saved and add it
name stringThe type its instances have in a level
url string
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 stringThe type's name
pos3D Vector3 optionalrotation3D Vector3 optionalIn radians, as an object has it
scale3D Vector3 optionalTimes the scale the type makes it with
properties ObjectProperties optionalOver 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});
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 optionalThe 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
A 3D level as it is saved, what level3DLoad takes and the 3D level editor edits
littlejs3D number optionalThe format's version, 1
objects Array<Level3DObject> optionalWhat it places, none when left out
scene Level3DScene optionalThe sky, sun, fog and the rest it sets
voxels Level3DVoxels optionalA block map
terrain Level3DTerrain optionalA height map
prefabs Object<string, Level3DPrefab> optionalThe level's own prefabs by name
An object a 3D level places, see level3DLoad
type stringThe name its type was added with
id number optionalIts id in the level, the editor gives each one
pos Array<number> optionalWhere it is, 0, 0, 0 when left out
rotation Array<number> optionalPitch, yaw and roll in degrees
scale Array<number> optionalTimes the scale its type makes it with
properties Object<string, any> optionalWhat differs from its type's defaults; a Color is a hex string and a
vector an array
A prefab, a small level placed many times, see level3DAddPrefab
objects Array<Level3DObject> optionalAbout its own origin
attached boolean optionalIts parts are children of the instance, moving with it as one body
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> optionalHex colors straight up, at the horizon and straight down
ambient number optionalHow much the sky lights the scene, .5 when not given
sunDirection Array<number> optionalPointing toward the sun
sunColor string optionalA hex color
fog Array<number> optionalWhere it starts and ends
fogColor string optionalA hex color, the sky's horizon when not given
shadows boolean optionallensFlare boolean optionalThe sun's lens flare
skyBox Array<string> optionalSix image urls, as loadCubeMap takes them
environment Array<string> optionalSix image urls for reflections
A 3D level's terrain, made a HeightMap
pos Array<number> optionalIts center
size Array<number>Its size in the world along x and z
height number optionalHow tall a full height is, 1 when not given
color string optionalA hex color
heights Array<Array<number>>Rows of 0 to 1 from -z to +z, each from -x to +x
paint Object optionalHex 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
A 3D level's block map, made a VoxelMap
pos Array<number> optionalIts corner
size Array<number>Its cells along x, y and z
blocks Array<number> optionalRuns of a count and a type, along x, then y, then z