A Voxelize world handles the chunk loading and rendering, as well as any 3D objects. This class extends the ThreeJS Scene class. This means that you can add any ThreeJS objects to the world, and they will be rendered. The world also implements NetIntercept, which means it intercepts chunk-related packets from the server and constructs chunk meshes from them. You can optionally disable this by setting shouldGenerateChunkMeshes to false in the options.

There are a couple components that are by default created by the world that holds data:

World.registry: A block registry that handles block textures and block instances.
World.chunks: A chunk manager that stores all the chunks in the world.
World.physics: A physics engine that handles voxel AABB physics simulation of client-side physics.
World.loader: An asset loader that handles loading textures and other assets.
World.sky: A sky that can render the sky and the sun.
World.clouds: A clouds that renders the cubical clouds.

One thing to keep in mind that there are no specific setters like setVoxelByVoxel or setVoxelRotationByVoxel. This is because, instead, you should use updateVoxel and updateVoxels to update voxels.

Example

const world = new VOXELIZE.World();

// Update the voxel at `(0, 0, 0)` to a voxel type `12` in the world across the network.
world.updateVoxel(0, 0, 0, 12)

// Register the interceptor with the network.
network.register(world);

// Register an image to block sides.
world.applyBlockTexture("Test", VOXELIZE.ALL_FACES, "https://example.com/test.png");

// Update the world every frame.
world.update(controls.position);

World

Type parameters

Name	Type
`T`	`any`

Hierarchy

Scene

↳ World

Implements

NetIntercept

Constructors

constructor

• new World<T>(options?): World<T>

Create a new Voxelize world.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`options`	`Partial`<`WorldOptions`>	The options to create the world.

Returns

World<T>

Overrides

Scene.constructor

Properties

chunks

• chunks: Chunks

The manager that holds all chunk-related data, such as chunk meshes and voxel data.

clouds

• clouds: Clouds

The clouds that renders the cubical clouds.

isInitialized

• isInitialized: boolean = false

Whether or not this world is connected to the server and initialized with data from the server.

loader

• loader: Loader

An asset loader to load in things like textures, images, GIFs and audio buffers.

options

• options: WorldOptions

The options to create the world.

physics

• physics: Engine

The voxel physics engine using @voxelize/physics-engine.

registry

• registry: Registry

The block registry that holds all block data, such as texture and block properties.

sky

• sky: Sky

The sky that renders the sky and the sun.

Accessors

deleteRadius

• get deleteRadius(): number

Returns

number

renderRadius

• get renderRadius(): number

Returns

number

• set renderRadius(radius): void

Parameters

Name	Type
`radius`	`number`

Returns

void

time

• get time(): number

Returns

number

• set time(time): void

Parameters

Name	Type
`time`	`number`

Returns

void

Methods

addBlockEntityUpdateListener

▸ addBlockEntityUpdateListener(listener): () => void

Parameters

Name	Type
`listener`	`BlockEntityUpdateListener`<`T`>

Returns

fn

▸ (): void

Returns

void

addBlockUpdateListener

▸ addBlockUpdateListener(listener): () => void

Parameters

Name	Type
`listener`	`BlockUpdateListener`

Returns

fn

▸ (): void

Returns

void

addChunkInitListener

▸ addChunkInitListener(coords, listener): () => void

Add a listener to a chunk. This listener will be called when this chunk is loaded and ready to be rendered. This is useful for, for example, teleporting the player to the top of the chunk when the player just joined.

Parameters

Name	Type	Description
`coords`	`Coords2`	The chunk coordinates to listen to.
`listener`	(`chunk`: `Chunk`) => `void`	The listener to add.

Returns

fn

▸ (): void

Returns

void

applyBlockFrames

▸ applyBlockFrames(idOrName, faceNames, keyframes, fadeFrames?): Promise<void>

Apply a set of keyframes to a block. This will load the keyframes from the sources and start the animation to play the keyframes on the block's texture atlas.

Parameters

Name	Type	Default value	Description
`idOrName`	`string` \| `number`	`undefined`	The ID or name of the block.
`faceNames`	`string` \| `string`[]	`undefined`	The face name or names to apply the texture to.
`keyframes`	[`number`, `string` \| `Color` \| `HTMLImageElement`][]	`undefined`	The keyframes to apply to the texture.
`fadeFrames`	`number`	`0`	The number of frames to fade between each keyframe.

Returns

Promise<void>

applyBlockGif

▸ applyBlockGif(idOrName, faceNames, source, interval?): Promise<void>

Apply a GIF animation to a block. This will load the GIF from the source and start the animation using applyBlockFrames internally.

Parameters

Name	Type	Default value	Description
`idOrName`	`string`	`undefined`	The ID or name of the block.
`faceNames`	`string` \| `string`[]	`undefined`	The face name or names to apply the texture to.
`source`	`string`	`undefined`	The source of the GIF. Note that this must be a GIF file ending with `.gif`.
`interval`	`number`	`66.666667`	The interval between each frame of the GIF in milliseconds. Defaults to `66.666667ms`.

Returns

Promise<void>

applyBlockTexture

▸ applyBlockTexture(idOrName, faceNames, source): void

Apply a texture to a face or faces of a block. This will automatically load the image from the source and draw it onto the block's texture atlas.

Parameters

Name	Type	Description
`idOrName`	`string` \| `number`	The ID or name of the block.
`faceNames`	`string` \| `string`[]	The face names to apply the texture to.
`source`	`string` \| `Color` \| `Texture` \| `HTMLImageElement`	The source of the texture.

Returns

void

applyBlockTextureAt

▸ applyBlockTextureAt(idOrName, faceName, source, voxel): CustomChunkShaderMaterial

Parameters

Name	Type
`idOrName`	`string` \| `number`
`faceName`	`string`
`source`	`string` \| `Color` \| `Texture` \| `HTMLImageElement`
`voxel`	`Coords3`

Returns

CustomChunkShaderMaterial

applyBlockTextures

▸ applyBlockTextures(data): Promise<void[]>

Apply multiple block textures at once. See applyBlockTexture for more information.

Parameters

Name	Type	Description
`data`	{ `faceNames`: `string` \| `string`[] ; `idOrName`: `string` \| `number` ; `source`: `string` \| `Color` }[]	The data to apply the block textures.

Returns

Promise<void[]>

A promise that resolves when all the textures are applied.

customizeBlockDynamic

▸ customizeBlockDynamic(idOrName, fn): void

Parameters

Name	Type
`idOrName`	`string` \| `number`
`fn`	(`pos`: `Coords3`) => { `aabbs`: `AABB`[] ; `faces`: { `corners`: { `pos`: [`number`, `number`, `number`] ; `uv`: `number`[] }[] ; `dir`: [`number`, `number`, `number`] ; `independent`: `boolean` ; `isolated`: `boolean` ; `name`: `string` ; `range`: `UV` }[] ; `isTransparent`: [`boolean`, `boolean`, `boolean`, `boolean`, `boolean`, `boolean`] }

Returns

void

customizeMaterialShaders

▸ customizeMaterialShaders(idOrName, faceName?, data?): CustomChunkShaderMaterial

Parameters

Name	Type	Default value
`idOrName`	`string` \| `number`	`undefined`
`faceName`	`string`	`null`
`data`	`Object`	`undefined`
`data.fragmentShader`	`string`	`undefined`
`data.uniforms?`	`Object`	`undefined`
`data.vertexShader`	`string`	`undefined`

Returns

CustomChunkShaderMaterial

floodLight

▸ floodLight(queue, color, min?, max?): void

Parameters

Name	Type
`queue`	`LightNode`[]
`color`	`LightColor`
`min?`	`Coords3`
`max?`	`Coords3`

Returns

void

getBlockAABBsAt

▸ getBlockAABBsAt(vx, vy, vz): AABB[]

Parameters

Name	Type
`vx`	`number`
`vy`	`number`
`vz`	`number`

Returns

AABB[]

getBlockAABBsByIdAt

▸ getBlockAABBsByIdAt(id, vx, vy, vz): AABB[]

Parameters

Name	Type
`id`	`number`
`vx`	`number`
`vy`	`number`
`vz`	`number`

Returns

AABB[]

getBlockAABBsForDynamicPatterns

▸ getBlockAABBsForDynamicPatterns(vx, vy, vz, dynamicPatterns): AABB[]

Parameters

Name	Type
`vx`	`number`
`vy`	`number`
`vz`	`number`
`dynamicPatterns`	`BlockDynamicPattern`[]

Returns

AABB[]

getBlockAt

▸ getBlockAt(px, py, pz): Block

Get the block type data by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

Block

The block at the given position, or null if it does not exist.

getBlockById

▸ getBlockById(id): Block

Get the block type data by a block id.

Parameters

Name	Type	Description
`id`	`number`	The block id.

Returns

Block

The block data for the given id, or null if it does not exist.

getBlockByName

▸ getBlockByName(name): Block

Get the block type data by a block name.

Parameters

Name	Type	Description
`name`	`string`	The block name.

Returns

Block

The block data for the given name, or null if it does not exist.

getBlockEntityDataAt

▸ getBlockEntityDataAt(px, py, pz): T

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`

Returns

T

getBlockFaceMaterial

▸ getBlockFaceMaterial(idOrName, faceName?, voxel?): CustomChunkShaderMaterial

Parameters

Name	Type
`idOrName`	`string` \| `number`
`faceName?`	`string`
`voxel?`	`Coords3`

Returns

CustomChunkShaderMaterial

getBlockFacesByFaceNames

▸ getBlockFacesByFaceNames(id, faceNames): { corners: { pos: [number, number, number] ; uv: number[] }[] ; dir: [number, number, number] ; independent: boolean ; isolated: boolean ; name: string ; range: UV }[]

Parameters

Name	Type
`id`	`number`
`faceNames`	`string` \| `RegExp` \| `string`[]

Returns

{ corners: { pos: [number, number, number] ; uv: number[] }[] ; dir: [number, number, number] ; independent: boolean ; isolated: boolean ; name: string ; range: UV }[]

getBlockOf

▸ getBlockOf(idOrName): Block

Parameters

Name	Type
`idOrName`	`string` \| `number`

Returns

Block

getChunkByCoords

▸ getChunkByCoords(cx, cz): Chunk

Get a chunk by its 2D coordinates.

Parameters

Name	Type	Description
`cx`	`number`	The x coordinate of the chunk.
`cz`	`number`	The z coordinate of the chunk.

Returns

Chunk

The chunk at the given coordinates, or undefined if it does not exist.

getChunkByName

▸ getChunkByName(name): Chunk

Get a chunk by its name.

Parameters

Name	Type	Description
`name`	`string`	The name of the chunk to get.

Returns

Chunk

The chunk with the given name, or undefined if it does not exist.

getChunkByPosition

▸ getChunkByPosition(px, py, pz): Chunk

Get a chunk that contains a given position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

Chunk

The chunk that contains the position at the given position, or undefined if it does not exist.

getChunkStatus

▸ getChunkStatus(cx, cz): "to request" | "requested" | "processing" | "loaded"

Get the status of a chunk.

Parameters

Name	Type	Description
`cx`	`number`	The x 2D coordinate of the chunk.
`cz`	`number`	The z 2D coordinate of the chunk.

Returns

"to request" | "requested" | "processing" | "loaded"

The status of the chunk.

getIsolatedBlockMaterialAt

▸ getIsolatedBlockMaterialAt(voxel, faceName, defaultDimension?): CustomChunkShaderMaterial

Parameters

Name	Type
`voxel`	`Coords3`
`faceName`	`string`
`defaultDimension?`	`number`

Returns

CustomChunkShaderMaterial

getLightColorAt

▸ getLightColorAt(vx, vy, vz): Color

Get a color instance that represents what an object would be like if it were rendered at the given 3D voxel coordinate. This is useful to dynamically shade objects based on their position in the world. Also used in LightShined.

Parameters

Name	Type	Description
`vx`	`number`	The voxel's X position.
`vy`	`number`	The voxel's Y position.
`vz`	`number`	The voxel's Z position.

Returns

Color

The voxel's light color at the given coordinate.

getMaxHeightAt

▸ getMaxHeightAt(px, pz): number

Get the highest block at a x/z position. Highest block means the first block counting downwards that isn't empty (isEmpty).

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

number

The highest block at the given position, or 0 if it does not exist.

getPreviousValueAt

▸ getPreviousValueAt(px, py, pz, count?): number

Get the previous value of a voxel by a 3D world position.

Parameters

Name	Type	Default value	Description
`px`	`number`	`undefined`	The x coordinate of the position.
`py`	`number`	`undefined`	The y coordinate of the position.
`pz`	`number`	`undefined`	The z coordinate of the position.
`count`	`number`	`1`	By how much to look back in the history. Defaults to `1`.

Returns

number

getSunlightAt

▸ getSunlightAt(px, py, pz): number

Get a voxel sunlight by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

number

The voxel sunlight at the given position, or 0 if it does not exist.

getTorchLightAt

▸ getTorchLightAt(px, py, pz, color): number

Get a voxel torch light by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.
`color`	`LightColor`	The color of the torch light.

Returns

number

The voxel torchlight at the given position, or 0 if it does not exist.

getVoxelAt

▸ getVoxelAt(px, py, pz): number

Get a voxel by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

number

The voxel at the given position, or 0 if it does not exist.

getVoxelRotationAt

▸ getVoxelRotationAt(px, py, pz): BlockRotation

Get a voxel rotation by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

BlockRotation

The voxel rotation at the given position, or the default rotation if it does not exist.

getVoxelStageAt

▸ getVoxelStageAt(px, py, pz): number

Get a voxel stage by a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.

Returns

number

The voxel stage at the given position, or 0 if it does not exist.

initialize

▸ initialize(): Promise<void>

Initialize the world with the data received from the server. This includes populating the registry, setting the options, and creating the texture atlas.

Returns

Promise<void>

isChunkInView

▸ isChunkInView(center, target, direction, threshold): boolean

Parameters

Name	Type
`center`	`Coords2`
`target`	`Coords2`
`direction`	`Vector3`
`threshold`	`number`

Returns

boolean

isWithinWorld

▸ isWithinWorld(cx, cz): boolean

Whether or not if this chunk coordinate is within (inclusive) the world's bounds. That is, if this chunk coordinate is within WorldServerOptions.minChunk and WorldServerOptions.maxChunk.

Parameters

Name	Type	Description
`cx`	`number`	The chunk's X position.
`cz`	`number`	The chunk's Z position.

Returns

boolean

Whether or not this chunk is within the bounds of the world.

makeBlockMesh

▸ makeBlockMesh(idOrName, options?): Group<Object3DEventMap>

Get a mesh of the model of the given block.

Parameters

Name	Type	Description
`idOrName`	`string` \| `number`	-
`options`	`Partial`<{ `crumbs`: `boolean` ; `material`: `"basic"` \| `"standard"` ; `separateFaces`: `boolean` }>	The options of creating this block mesh.

Returns

Group<Object3DEventMap>

A 3D mesh (group) of the block model.

meshChunkLocally

▸ meshChunkLocally(cx, cz, level): Promise<void>

Parameters

Name	Type
`cx`	`number`
`cz`	`number`
`level`	`number`

Returns

Promise<void>

raycastVoxels

▸ raycastVoxels(origin, direction, maxDistance, options?): Object

Raycast through the world of voxels and return the details of the first block intersection.

Parameters

Name	Type	Description
`origin`	`Coords3`	The origin of the ray.
`direction`	`Coords3`	The direction of the ray.
`maxDistance`	`number`	The maximum distance of the ray.
`options`	`Object`	The options for the ray.
`options.ignoreFluids?`	`boolean`	Whether or not to ignore fluids. Defaults to `true`.
`options.ignoreList?`	`number`[]	A list of blocks to ignore. Defaults to `[]`.
`options.ignorePassables?`	`boolean`	Whether or not to ignore passable blocks. Defaults to `false`.
`options.ignoreSeeThrough?`	`boolean`	Whether or not to ignore see through blocks. Defaults to `false`.

Returns

Object

Name	Type
`normal`	`number`[]
`point`	`number`[]
`voxel`	`number`[]

removeLight

▸ removeLight(voxel, color): void

Parameters

Name	Type
`voxel`	`Coords3`
`color`	`LightColor`

Returns

void

setBlockEntityDataAt

▸ setBlockEntityDataAt(px, py, pz, data): void

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`
`data`	`T`

Returns

void

setResolutionOf

▸ setResolutionOf(idOrName, faceNames, resolution): Promise<void>

Apply a resolution to a block. This will set the resolution of the block's texture atlas. Keep in mind that this face or faces must be independent.

Parameters

Name	Type	Description
`idOrName`	`string` \| `number`	The ID or name of the block.
`faceNames`	`string` \| `string`[]	The face name or names to apply the resolution to.
`resolution`	`number` \| { `x`: `number` ; `y`: `number` }	The resolution to apply to the block, in pixels.

Returns

Promise<void>

setSunlightAt

▸ setSunlightAt(px, py, pz, level): void

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`
`level`	`number`

Returns

void

setTorchLightAt

▸ setTorchLightAt(px, py, pz, level, color): void

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`
`level`	`number`
`color`	`LightColor`

Returns

void

setVoxelAt

▸ setVoxelAt(px, py, pz, voxel): void

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`
`voxel`	`number`

Returns

void

setVoxelRotationAt

▸ setVoxelRotationAt(px, py, pz, rotation): void

Set a voxel rotation at a 3D world position.

Parameters

Name	Type	Description
`px`	`number`	The x coordinate of the position.
`py`	`number`	The y coordinate of the position.
`pz`	`number`	The z coordinate of the position.
`rotation`	`BlockRotation`	The rotation to set.

Returns

void

setVoxelStageAt

▸ setVoxelStageAt(px, py, pz, stage): void

Parameters

Name	Type
`px`	`number`
`py`	`number`
`pz`	`number`
`stage`	`number`

Returns

void

update

▸ update(position?, direction?): void

Parameters

Name	Type
`position`	`Vector3`
`direction`	`Vector3`

Returns

void

updateSkyAndClouds

▸ updateSkyAndClouds(position): void

Parameters

Name	Type
`position`	`Vector3`

Returns

void

updateVoxel

▸ updateVoxel(vx, vy, vz, type, options): void

This sends a block update to the server and updates across the network. Block updates are queued to World.chunks.toUpdate and scaffolded to the server WorldClientOptions.maxUpdatesPerUpdate times per tick. Keep in mind that for rotation and y-rotation, the value should be one of the following:

Rotation: PX_ROTATION | NX_ROTATION | PY_ROTATION | NY_ROTATION | PZ_ROTATION | NZ_ROTATION
Y-rotation: 0 to Y_ROT_SEGMENTS - 1.

This ignores blocks that are not defined, and also ignores rotations for blocks that are not Block.rotatable (Same for if block is not Block.yRotatable).

Parameters

Name	Type	Description
`vx`	`number`	The voxel's X position.
`vy`	`number`	The voxel's Y position.
`vz`	`number`	The voxel's Z position.
`type`	`number`	The type of the voxel.
`options`	`Object`	The options for the voxel.
`options.rotation?`	`number`	The major axis rotation of the voxel.
`options.source?`	`"client"` \| `"server"`	Whether the update is from the client or server. Defaults to "client".
`options.stage?`	`number`	The stage of the voxel.
`options.yRotation?`	`number`	The Y rotation on the major axis. Applies to blocks with major axis of PY or NY.

Returns

void

updateVoxels

▸ updateVoxels(updates, source?): void

This sends a list of block updates to the server and updates across the network. Block updates are queued to World.chunks.toUpdate and scaffolded to the server WorldClientOptions.maxUpdatesPerUpdate times per tick. Keep in mind that for rotation and y-rotation, the value should be one of the following:

Rotation: PX_ROTATION | NX_ROTATION | PY_ROTATION | NY_ROTATION | PZ_ROTATION | NZ_ROTATION
Y-rotation: 0 to Y_ROT_SEGMENTS - 1.

This ignores blocks that are not defined, and also ignores rotations for blocks that are not Block.rotatable (Same for if block is not Block.yRotatable).

Parameters

Name	Type	Default value	Description
`updates`	`BlockUpdate`[]	`undefined`	A list of updates to send to the server.
`source`	`"client"` \| `"server"`	`"client"`	-

Returns

void

Example

Type parameters​

Hierarchy​

Implements​

Constructors​

constructor​

Type parameters​

Parameters​

Returns​

Overrides​

Properties​

chunks​

clouds​

isInitialized​

loader​

options​

physics​

registry​

sky​

Accessors​

deleteRadius​

Returns​

renderRadius​

Returns​

Parameters​

Returns​

time​

Returns​

Parameters​

Returns​

Methods​

addBlockEntityUpdateListener​

Parameters​

Returns​

Returns​

addBlockUpdateListener​

Parameters​

Returns​

Returns​

addChunkInitListener​

Parameters​

Returns​

Returns​

applyBlockFrames​

Parameters​

Returns​

applyBlockGif​

Parameters​

Returns​

applyBlockTexture​

Parameters​

Returns​

applyBlockTextureAt​

Parameters​

Returns​

applyBlockTextures​

Parameters​

Returns​

customizeBlockDynamic​

Parameters​

Returns​

customizeMaterialShaders​

Parameters​

Returns​

floodLight​

Parameters​

Returns​

getBlockAABBsAt​

Parameters​

Returns​

getBlockAABBsByIdAt​

Parameters​

Returns​

getBlockAABBsForDynamicPatterns​

Parameters​

Returns​

getBlockAt​

Parameters​

Returns​

getBlockById​

Type parameters

Hierarchy

Implements

Constructors

constructor

Type parameters

Parameters

Returns

Overrides

Properties

chunks

clouds

isInitialized

loader

options

physics

registry

sky

Accessors

deleteRadius

Returns

renderRadius

Returns

Parameters

Returns

time

Returns

Parameters

Returns

Methods

addBlockEntityUpdateListener

Parameters

Returns

Returns

addBlockUpdateListener

Parameters

Returns

Returns

addChunkInitListener

Parameters

Returns

Returns

applyBlockFrames

Parameters

Returns

applyBlockGif

Parameters

Returns

applyBlockTexture

Parameters

Returns

applyBlockTextureAt

Parameters

Returns

applyBlockTextures

Parameters

Returns

customizeBlockDynamic

Parameters

Returns

customizeMaterialShaders

Parameters

Returns

floodLight

Parameters

Returns

getBlockAABBsAt

Parameters

Returns

getBlockAABBsByIdAt

Parameters

Returns

getBlockAABBsForDynamicPatterns

Parameters

Returns

getBlockAt

Parameters

Returns

getBlockById

Parameters