LookAtMySuitBot/js/node_modules/prismarine-world/docs/API.md

API

World

The API is split in 2 :

• the World which is async
• the World.sync which is sync

The characteristics of the async world is that it will always return something when getting a block, but as a promise. To achieve this it may load columns from anvil files or other storage. On the other hand the sync world will not always return blocks and may return null, but it will return the block directly with no promise.

The set operations have similar characteristics : the async world will always set the blocks and return a promise, whereas the sync world will not always set the blocks, but do the action now and not return a promise.

The 2 world are linked and stay in sync together.

The async world may be more natural for servers (although the sync world can also be used there) The sync world makes more sense for clients as there is not necessarily somewhere to load more data from (but in some cases this may be incorrect too, think multi player clients)

World([generateChunk,[storageProvider]],[savingInterval])

Create a world instance, takes an optional generateChunk(chunkX, chunkZ) function that will get called when a chunk at chunkX and chunkZ need to be generated. Takes a second optional arguments : storageProvider containing the regions. If provided, prismarine-world will first try to load the map from these regions, and then try to generate the world if the chunk isn't saved. savingInterval default to 50ms.

"blockUpdate" (oldBlock, newBlock)

Fires when a block updates. Both oldBlock and newBlock provided for comparison.

Note that oldBlock may be null.

"blockUpdate:(x, y, z)" (oldBlock, newBlock)

Fires for a specific point. Both oldBlock and newBlock provided for comparison.

Note that oldBlock may be null.

"chunkColumnLoad" (point)

"chunkColumnUnload" (point)

Fires when a chunk has updated. point is the coordinates to the corner of the chunk with the smallest x, y, and z values.

World.initialize(iniFunc,length,width,height=256,iniPos=new Vec3(0,0,0))

Initialize the world with a given blocks cube. Useful to load quickly a schematic.

• iniFunc is a function(x,y,z) that returns a prismarine-block
• length, width and height are the size to iterate on
• iniPos is the position where to start the iteration

Returns a promise containing an array of {chunkX,chunkZ}

World.raycast(from, direction, range, matcher = null)

Raycast in the world.

• from - Vec3, position to raycast from
• direction - Vec3, direction of the ray, must be normalized
• range - max distance to raycast
• matcher - optional function with a block parameter, return true if the raycast should stop at this block, false otherwise

World.getColumns()

Return all loaded columns

World.unloadColumn(chunkX,chunkZ)

Unload column from memory

All the following methods are async and return a promise.

World.setColumn(chunkX,chunkZ,chunk)

Set chunk at chunkX and chunkZ

World.getColumn(chunkX,chunkZ)

Return the column at chunkX and chunkZ

World.getBlock(pos)

Get the Block at pos

World.setBlock(pos,block)

Set the Block at pos

World.getBlockStateId(pos)

Get the block state at pos

World.getBlockType(pos)

Get the block type at pos

World.getBlockData(pos)

Get the block data (metadata) at pos

World.getBlockLight(pos)

Get the block light at pos

World.getSkyLight(pos)

Get the block sky light at pos

World.getBiome(pos)

Get the block biome id at pos

World.setBlockStateId(pos, stateId)

Set the block state stateId at pos

World.setBlockType(pos, id)

Set the block type id at pos

World.setBlockData(pos, data)

Set the block data (metadata) at pos

World.setBlockLight(pos, light)

Set the block light at pos

World.setSkyLight(pos, light)

Set the block sky light at pos

World.setBiome(pos, biome)

Set the block biome id at pos

World.waitSaving()

Returns a promise that is resolved when all saving is done.

World.sync(asyncWorld)

Build a sync world, will delegate all the saving work to the async one

It exposes the same methods as World but all methods are sync.

Iterators

Iterators are used to iterate over blocks. Use cases include finding specific blocks quickly and computing a ray cast.

ManhattanIterator (x, y, maxDistance)

2D rectangular spiral iterator, useful to iterate on columns that are centered on bot position

next()

return null or the next position (Vec3)

OctahedronIterator (start, maxDistance)

start is a Vec3

next()

return null or the next position (Vec3)

RaycastIterator (pos, dir, maxDistance)

pos and dir are Vec3

RaycastIterator iterates along a ray starting at pos in dir direction. It steps exactly 1 block at a time, returning the block coordinates and the face by which the ray entered the block.

next()

return null or the next position (Vec3)

SpiralIterator2d (pos, maxDistance)

pos is Vec3

maxDistance is number

Iterates outwards along x and z axis in a cubic spiral. First position returned is the starting position. Every step is 1 step away form the previous and next point.

next()

return null or the next position (Vec3)

NUMBER_OF_POINTS

Number of points the iterator will return.