Caution: not all of the functionality of the three.js-based voxel-engine is implemented,
documentation may be outdated, and the API may be unstable. Pull requests to improve this
situation are greatly welcomed.
voxel-engine-stackgl is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
voxeljs: not 100% consistent yet, 'voxel.js' also acceptable, but definitely not 'VoxelJS'.
dims: short for 'dimensions'. Perhaps obvious to some.
yaw: rotation around the vertical axis.
pitch: rotation around a horizontal axis.
Positions
x, z: horizontal plane
y: vertical plane
We try to always use arrays to represent vectors (aka positions)
[x, y, z]
Sometimes you may also see objects used, e.g. {x: 0, y: 0, z: 0}, this is because three.js uses objects for vectors.
Generating voxel worlds
Worlds have many chunks and chunks have many voxels. Chunks are cube shaped and are chunkSize x/y/z (default 32/32/32 - 32768 voxels per chunk). When the game starts it takes the worldOrigin and generates chunkDistance chunks in every x/y/z dimension (chunkDistance default of 2 means the game will render 2 chunks behind you, 2 in front etc for a total of 16 chunks.).
There is one major coordinate system in voxel.js: "game coordinates" (aka world coordinates)
every object added to a three.js scene gets a x/y/z position in game coordinates. in voxel-engine 1 game coordinate is the width of 1 voxel. when generating the world or interacting with individual voxels you can refer to voxels by coordinates. an example coordinate might be [34, -50, 302] which would mean starting from the worldOrigin 34 voxels over, 50 down and 302 forward
There are also some other less used coordinate systems that you should be aware of:
chunk coordinates: logically the same as voxel coordinates but for chunks. you probably won't need to use these as they are just used internally for rendering the world but it is good to know they exist.
local object coordinates: when you add items and other things to the game that aren't voxel terrain you introduce a new relative coordinate system inside each thing. so if you add a player 3d model body and you want to put a hat on the body you could position the hat relative to the body coordinates, etc
When you create a game you can also pass functions that the game will ask for voxel data. Here is an example generate function that makes a randomly textured cube world with a diameter of 20 voxels:
This returns a THREE.js Vector3 object (which just means an object with 'x', 'y', and 'z').
Toggle a block on/off
game.setBlock(pos,0)// offgame.setBlock(pos,1)// ongame.setBlock(pos,2)// on, with another material
Get the chunk at some world coordinates:
gameInstance.voxels.chunkAtPosition(position)
Get the voxel coordinates at some position (relative to that voxels chunk):
gameInstance.voxels.voxelVector(position)
Create a brand new voxel at some position.
Intended for use in first player contexts as it checks if a player is standing in the way of the new voxel. If you don't care about that then just use setBlock:
gameInstance.createBlock(pos, val)
val can be 0 or you can also use any single digit integer 0-9. These correspond to the materials array that you pass in to the game.
Set the value of a voxel at some position:
gameInstance.setBlock(pos, val)
Get the value of a voxel at some position:
gameInstance.getBlock(pos)
If you wanna see the lower level API for voxel data manipulation look at chunker.js inside the voxel module.
if you just type gameInstance.raycastVoxels() it will default to using the current main camera position and direction, and default distance of 10, and epsilon of 1e-8
you will get back an object with the precise position, voxel position, direction, face normal and voxel value of the voxel that you intersected, or false if there was no collision
Create a new voxel adjacent to an existing voxel
first do a .raycastVoxels() then do gameInstance.createAdjacent(raycastResults, materialIndex)
Game events
There are a number of events you can listen to once you've instantiated a game. we use the node.js event emitter library which uses the following syntax for subscribing:
emits when the player moves into range of a chunk that isn't loaded yet. if your game has generateChunks set to true it will automatically create the chunk and render it but if you are providing your own chunk generation then you can use this to hook into the game.
game.on('dirtyChunkUpdate', function(chunk) {})
emits when game updates a chunk, this is usually triggered when a chunk gets edited. if game.setBlock were to get called 50 times on one chunk in between renders, dirtyChunkUpdate will emit once with the chunk the chunk that gets updated
game.on('setBlock', function(pos, val, old) {})
emits whenever game.setBlock gets called
Collisions
Check for collisions between an item and other 'things'
Detects collisions between an item and other items, or voxels.
game.getCollisions(item.mesh.position,item)
This will give you back a 'collisions object' whose keys are positions on the object and values are arrays of the positions of faces that are colliding.
For example, here we have 4 faces colliding with the bottom of our object:
Items are non-voxel objects you can add to your game. e.g. Monsters/Players, Powerups, etc.
Items currently implement their own physics, which is calculated every 'tick' by running an items' item.tick function. It's not very sophisticated.
Items .mesh property is the thing that's actually processed by the THREE.js engine. Other properties of item are used in voxel.js to update the mesh, e.g. item.velocity.y is used every tick to calculate the next position the mesh should be in.
Using the current item physics system, setting item.resting to false will force an item to recalculate it's position.
Example: Creating an Item
// create a mesh and use the internal game material (texture atlas)varmesh=newgame.THREE.Mesh(newgame.THREE.CubeGeometry(1,3,1),// width, height, depthgame.materials.material)// paint the mesh with a specific texture in the atlasgame.materials.paint(mesh,'obsidian')// move the item to some locationmesh.position.set(0,3,-5)varitem=game.addItem({mesh: mesh,size: 1,velocity: {x: 0,y: 0,z: 0}// initial velocity})// use `game.removeItem(item)` to remove
客服电话
APP下载
官方微信
