Skip to content

Latest commit

 

History

History
1157 lines (744 loc) · 22.1 KB

API.md

File metadata and controls

1157 lines (744 loc) · 22.1 KB
Raw

GlobalDescription
Noa

Root class of the noa engine

Extends: EventEmitter
Camera

Manages the camera, exposes camera position, direction, mouse sensitivity.
Container

Wraps game-shell module and manages HTML container, canvas, etc.
Entities

Wrangles entities. Aliased as noa.ents.

This class is an instance of ECS, and as such implements the usual ECS methods. It's also decorated with helpers and accessor functions for getting component existence/state.

Expects entity definitions in a specific format - see source components folder for examples.
Inputs

Abstracts key/mouse input. For docs see andyhall/game-inputs
Physics

Wrapper module for the physics engine. For docs see andyhall/voxel-physics-engine
Registry

for registering block types, materials & properties
Rendering

Manages all rendering, and the BABYLON scene, materials, etc.
World

Manages the world and its chunks

Extends EventEmitter

GlobalDescription
names

Hash containing the component names of built-in components.
hasPhysics
cameraSmoothed
hasMesh
hasPosition
getPositionData

GlobalDescription
isPlayer(id)
_localGetPosition(id)
getPosition(id)
_localSetPosition(id)
setPosition(id,)
setEntitySize(id,)

Noa

Root class of the noa engine

Extends: EventEmitter

Emits:

  • tick(dt)
  • beforeRender(dt)
  • afterRender(dt)
  • targetBlockChanged(blockDesc)

new Engine()

Main engine object. Takes a big options object full of flags and settings as a parameter.

var opts = {
    debug: false,
    silent: false,
    playerHeight: 1.8,
    playerWidth: 0.6,
    playerStart: [0, 10, 0],
    playerAutoStep: false,
    tickRate: 33, // ms per tick - not ticks per second
    blockTestDistance: 10,
    stickyPointerLock: true,
    dragCameraOutsidePointerLock: true,
    skipDefaultHighlighting: false,
    originRebaseDistance: 25,
}
var NoaEngine = require('noa-engine')
var noa = NoaEngine(opts)

All option parameters are, well, optional. Note that the root opts parameter object is also passed to noa's child modules (rendering, camera, etc). See docs for each module for which options they use.

noa.version

version string, e.g. "0.25.4"

noa.worldName

String identifier for the current world. (It's safe to ignore this if your game doesn't need to swap between levels/worlds.)

noa.container : Container

container (html/div) manager

noa.inputs : Inputs

inputs manager - abstracts key/mouse input

noa.registry : Registry

block/item property registry

noa.world : World

world manager

noa.rendering : Rendering

Rendering manager

noa.physics : Physics

physics engine - solves collisions, properties, etc.

noa.entities : Entities

Entity manager / Entity Component System (ECS) Aliased to noa.ents for convenience.

noa.playerEntity

Entity id for the player entity

noa.camera : Camera

Manages camera, view angle, etc.

noa.blockTargetIdCheck

function for which block IDs are targetable. Defaults to a solidity check, but can be overridden

noa.targetedBlock

Dynamically updated object describing the currently targeted block. Gets updated each tick, to null if not block is targeted, or to an object like:

{
   blockID,   // voxel ID
   position,  // the (solid) block being targeted
   adjacent,  // the (non-solid) block adjacent to the targeted one
   normal,    // e.g. [0, 1, 0] when player is targting the top face of a voxel
}

noa.globalToLocal()

Precisely converts a world position to the current internal local frame of reference.

See /doc/positions.md for more info.

Params:

  • global: input position in global coords
  • globalPrecise: (optional) sub-voxel offset to the global position
  • local: output array which will receive the result

noa.localToGlobal()

Precisely converts a world position to the current internal local frame of reference.

See /doc/positions.md for more info.

Params:

  • local: input array of local coords
  • global: output array which receives the result
  • globalPrecise: (optional) sub-voxel offset to the output global position

If both output arrays are passed in, global will get int values and globalPrecise will get fractional parts. If only one array is passed in, global will get the whole output position.

noa.setPaused(paused)

Pausing the engine will also stop render/tick events, etc.

Params

  • paused

noa.getBlock(x,y,z)

Params

  • x,y,z

noa.setBlock(x,y,z)

Params

  • x,y,z

noa.addBlock(id,x,y,z)

Adds a block unless obstructed by entities

Params

  • id,x,y,z

noa.pick(pos, vec, dist, blockTestFunction)

Raycast through the world, returning a result object for any non-air block

Params

  • pos - (default: to player eye position)
  • vec - (default: to camera vector)
  • dist - (default: noa.blockTestDistance)
  • blockTestFunction - (default: voxel solidity)

Returns: null, or an object with array properties: position, normal, _localPosition.

See /doc/positions.md for info on working with precise positions.

noa._localPick(pos, vec, dist, blockTestFunction)

Do a raycast in local coords. See /doc/positions.md for more info.

Params

  • pos
  • vec
  • dist
  • blockTestFunction

Camera

Manages the camera, exposes camera position, direction, mouse sensitivity.

noa.camera.sensitivityX

Horizontal mouse sensitivity. Same scale as Overwatch (typical values around 5..10)

noa.camera.sensitivityY

Vertical mouse sensitivity. Same scale as Overwatch (typical values around 5..10)

noa.camera.inverseX

Mouse look inverse (horizontal)

noa.camera.inverseY

Mouse look inverse (vertical)

noa.camera.heading

Camera yaw angle (read only)

Returns the camera's rotation angle around the vertical axis. Range: 0..2π

noa.camera.pitch

Camera pitch angle (read only)

Returns the camera's up/down rotation angle. Range: -π/2..π/2. (The pitch angle is clamped by a small epsilon, such that the camera never quite points perfectly up or down.

noa.camera.cameraTarget

Entity ID of a special entity that exists for the camera to point at.

By default this entity follows the player entity, so you can change the player's eye height by changing the follow component's offset:

var followState = noa.ents.getState(noa.camera.cameraTarget, 'followsEntity')
followState.offset[1] = 0.9 * myPlayerHeight

For customized camera controls you can change the follow target to some other entity, or override the behavior entirely:

// make cameraTarget stop following the player
noa.ents.removeComponent(noa.camera.cameraTarget, 'followsEntity')
// control cameraTarget position directly (or whatever..)
noa.ents.setPosition(noa.camera.cameraTarget, [x,y,z])

noa.camera.zoomDistance

How far back the camera is zoomed from the camera target

noa.camera.zoomSpeed

How quickly the camera moves to its zoomDistance (0..1)

noa.camera.currentZoom

Current actual zoom distance. This differs from zoomDistance when the camera is in the process of moving towards the desired distance, or when it's obstructed by solid terrain behind the player.

noa.camera.getTargetPosition()

Camera target position (read only)

This returns the point the camera looks at - i.e. the player's eye position. When the camera is zoomed all the way in, this is equivalent to camera.getPosition().

noa.camera.getPosition()

Returns the current camera position (read only)

noa.camera.getDirection()

Returns the camera direction vector (read only)

Camera~opts

noa.camera uses the following options (from the root noa(opts) options):

{
  inverseX: false,
  inverseY: false,
  sensitivityX: 15,
  sensitivityY: 15,
  initialZoom: 0,
  zoomSpeed: 0.2,
}

Container

Wraps game-shell module and manages HTML container, canvas, etc.

Emits:

  • event:DOMready

Entities

Wrangles entities. Aliased as noa.ents.

This class is an instance of ECS, and as such implements the usual ECS methods. It's also decorated with helpers and accessor functions for getting component existence/state.

Expects entity definitions in a specific format - see source components folder for examples.

noa.ents.addComponentAgain(id,name,state)

Params

  • id,name,state

noa.ents.isTerrainBlocked(x,y,z)

Params

  • x,y,z

noa.ents.getEntitiesInAABB(box)

Params

  • box

noa.ents.add(position, width, mesh)

Helper to set up a general entity, and populate with some common components depending on arguments.

Parameters: position, width, height [, mesh, meshOffset, doPhysics, shadow]

Params

  • position
  • width - .
  • mesh

Inputs

Abstracts key/mouse input. For docs see andyhall/game-inputs

Physics

Wrapper module for the physics engine. For docs see andyhall/voxel-physics-engine

Registry

for registering block types, materials & properties

noa.registry.registerBlock()

Register (by integer ID) a block type and its parameters.

id param: integer, currently 1..255. This needs to be passed in by the client because it goes into the chunk data, which someday will get serialized.

options param: Recognized fields for the options object:

  • material: can be:
    • one (String) material name
    • array of 2 names: [top/bottom, sides]
    • array of 3 names: [top, bottom, sides]
    • array of 6 names: [-x, +x, -y, +y, -z, +z] If not specified, terrain won't be meshed for the block type
  • solid: (true) solidity for physics purposes
  • opaque: (true) fully obscures neighboring blocks
  • fluid: (false) whether nonsolid block is a fluid (buoyant, viscous..)
  • blockMeshes: (null) if specified, noa will create an instance of the mesh instead of rendering voxel terrain
  • fluidDensity: (1.0) for fluid blocks
  • viscosity: (0.5) for fluid blocks
  • onLoad(): block event handler
  • onUnload(): block event handler
  • onSet(): block event handler
  • onUnset(): block event handler
  • onCustomMeshCreate(): block event handler

noa.registry.registerMaterial(name, color, textureURL, texHasAlpha, renderMaterial)

Register (by name) a material and its parameters.

Params

  • name
  • color
  • textureURL
  • texHasAlpha
  • renderMaterial - an optional BABYLON material to be used for block faces with this block material

noa.registry.getBlockSolidity(id)

block solidity (as in physics)

Params

  • id

noa.registry.getBlockOpacity(id)

block opacity - whether it obscures the whole voxel (dirt) or can be partially seen through (like a fencepost, etc)

Params

  • id

noa.registry.getBlockFluidity(id)

block is fluid or not

Params

  • id

noa.registry.getBlockProps(id)

Get block property object passed in at registration

Params

  • id

Rendering

Manages all rendering, and the BABYLON scene, materials, etc.

noa.rendering.getScene

The Babylon scene object representing the game world.

noa.rendering.addMeshToScene(mesh:, isStatic:, position:, chunk:)

Add a mesh to the scene's octree setup so that it renders.

Params

  • mesh: - the mesh to add to the scene
  • isStatic: - pass in true if mesh never moves (i.e. change octree blocks)
  • position: - (optional) global position where the mesh should be
  • chunk: - (optional) chunk to which the mesh is statically bound

noa.rendering.removeMeshFromScene()

Undoes everything addMeshToScene does

Rendering~opts

noa.rendering uses the following options (from the root noa(opts) options):

{
  showFPS: false,
  antiAlias: true,
  clearColor: [0.8, 0.9, 1],
  ambientColor: [1, 1, 1],
  lightDiffuse: [1, 1, 1],
  lightSpecular: [1, 1, 1],
  groundLightColor: [0.5, 0.5, 0.5],
  useAO: true,
  AOmultipliers: [0.93, 0.8, 0.5],
  reverseAOmultiplier: 1.0,
  preserveDrawingBuffer: true,
}

World

Manages the world and its chunks

Extends EventEmitter

Emits:

  • worldDataNeeded(id, ndarray, x, y, z,event: worldName)
  • chunkAdded(chunk)
  • chunkBeingRemoved(id, ndarray,event: userData)

noa.world.getBlockID(x,y,z)

Params

  • x,y,z

noa.world.getBlockSolidity(x,y,z)

Params

  • x,y,z

noa.world.getBlockOpacity(x,y,z)

Params

  • x,y,z

noa.world.getBlockFluidity(x,y,z)

Params

  • x,y,z

noa.world.getBlockProperties(x,y,z)

Params

  • x,y,z

noa.world.getBlockObjectMesh(x,y,z)

Params

  • x,y,z

noa.world.setBlockID(id, x,y,z)

Params

  • id,x,y,z

noa.world.isBoxUnobstructed(x,y,z)

Params

  • x,y,z

noa.world.setChunkData(id, array, userData)

client should call this after creating a chunk's worth of data (as an ndarray)
If userData is passed in it will be attached to the chunk

Params

  • id
  • array
  • userData

noa.world.invalidateVoxelsInAABB()

Tells noa to discard voxel data within a given AABB (e.g. because the game client received updated data from a server). The engine will mark all affected chunks for disposal, and will later emit new worldDataNeeded events (if the chunk is still in draw range). Note that chunks invalidated this way will not emit a chunkBeingRemoved event for the client to save data from.

names

Hash containing the component names of built-in components.

hasPhysics

Params

  • id

cameraSmoothed

Params

  • id

hasMesh

Params

  • id

hasPosition

Params

  • id

getPositionData

Params

  • id

isPlayer(id)

Params

  • id

_localGetPosition(id)

Params

  • id

getPosition(id)

Params

  • id

_localSetPosition(id)

Params

  • id

setPosition(id,)

Params

  • id, - positionArr

setEntitySize(id,)

Params

  • id, - xs, ys, zs