Doc updates and rebuild

README.md

@@ -52,11 +52,11 @@ See [history.md](docs/history.md) for full changes and migration for each versio
 Recent changes:
 
  * `v0.33`: 
+   * Much improved [API docs](https://fenomas.github.io/noa/API/)
    * Terrain now supports texture atlases! See `registry.registerMaterial`.
    * Added a fast way to specify that a worldgen chunk is entirely air/dirt/etc.
    * Modernized keybinds to use [KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) strings, and changed several binding state properties
-   * Updated several lighting defaults to work well with Babylon shadows
-   * Engine now emits when adding/removing terrain meshes, so client can e.g. manage a ShadowGenerator
+   * Bunch of internal improvements to support shadows - see [examples](https://github.com/fenomas/noa-examples)
 
  * `v0.32`: Fixes npm versioning issue - no code changes.
  * `v0.31`: 

dist/src/components/shadow.d.ts

@@ -1,4 +1,5 @@
-export default function _default(noa: any, dist: any): {
+/** @param {import('../index').Engine} noa  */
+export default function _default(noa: import('../index').Engine, distance?: number): {
     name: string;
     order: number;
     state: {

dist/src/index.d.ts

@@ -13,10 +13,6 @@
  * child modules ({@link Rendering}, {@link Container}, etc).
  * See docs for each module for their options.
  *
- * @emits tick(dt)
- * @emits beforeRender(dt)
- * @emits afterRender(dt)
- * @emits targetBlockChanged(blockDesc)
 */
 export class Engine extends EventEmitter {
     /**
@@ -30,6 +26,7 @@ export class Engine extends EventEmitter {
      *    playerWidth: 0.6,
      *    playerStart: [0, 10, 0],
      *    playerAutoStep: false,
+     *    playerShadowComponent: true,
      *    tickRate: 30,           // ticks per second
      *    maxRenderRate: 0,       // max FPS, 0 for uncapped
      *    blockTestDistance: 10,
@@ -40,6 +37,20 @@ export class Engine extends EventEmitter {
      *    originRebaseDistance: 25,
      * }
      * ```
+     *
+     * **Events:**
+     *  + `tick => (dt)`
+     *    Tick update, `dt` is (fixed) tick duration in ms
+     *  + `beforeRender => (dt)`
+     *    `dt` is the time (in ms) since the most recent tick
+     *  + `afterRender => (dt)`
+     *    `dt` is the time (in ms) since the most recent tick
+     *  + `targetBlockChanged => (blockInfo)`
+     *    Emitted each time the user's targeted world block changes
+     *  + `addingTerrainMesh => (mesh)`
+     *    Alerts client about a terrain mesh being added to the scene
+     *  + `removingTerrainMesh => (mesh)`
+     *    Alerts client before a terrain mesh is removed.
     */
     constructor(opts?: {});
     /** Version string, e.g. `"0.25.4"` */
@@ -166,7 +177,7 @@ export class Engine extends EventEmitter {
      * Sets the voxel ID at the specified position.
      * Does not check whether any entities are in the way!
      */
-    setBlock(id: any, x: any, y?: number, z?: number): any;
+    setBlock(id: any, x: any, y?: number, z?: number): void;
     /**
      * Adds a block, unless there's an entity in the way.
     */
@@ -234,15 +245,15 @@ export class Engine extends EventEmitter {
         _localPosition: number[];
     };
 }
-import { EventEmitter } from "events";
-import { Container } from "./lib/container";
-import { Inputs } from "./lib/inputs";
-import { Registry } from "./lib/registry";
-import { World } from "./lib/world";
-import { Rendering } from "./lib/rendering";
-import { Physics } from "./lib/physics";
-import { Entities } from "./lib/entities";
-import { Camera } from "./lib/camera";
-import TerrainMesher from "./lib/terrainMesher";
-import ObjectMesher from "./lib/objectMesher";
-import vec3 from "gl-vec3";
+import { EventEmitter } from 'events';
+import { Container } from './lib/container';
+import { Inputs } from './lib/inputs';
+import { Registry } from './lib/registry';
+import { World } from './lib/world';
+import { Rendering } from './lib/rendering';
+import { Physics } from './lib/physics';
+import { Entities } from './lib/entities';
+import { Camera } from './lib/camera';
+import { TerrainMesher } from './lib/terrainMesher';
+import { ObjectMesher } from './lib/objectMesher';
+import vec3 from 'gl-vec3';

dist/src/lib/camera.d.ts

@@ -3,7 +3,7 @@
  * mouse sensitivity, and so on.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  * ```js
  * var defaults = {
  *     inverseX: false,

dist/src/lib/chunk.d.ts

@@ -1,11 +1,11 @@
-export default Chunk;
 /** @param {import('../index').Engine} noa */
-declare function Chunk(noa: import('../index').Engine, requestID: any, ci: any, cj: any, ck: any, size: any, dataArray: any, fillVoxelID?: number): void;
-declare class Chunk {
+export function Chunk(noa: import('../index').Engine, requestID: any, ci: any, cj: any, ck: any, size: any, dataArray: any, fillVoxelID?: number): void;
+export class Chunk {
     /** @param {import('../index').Engine} noa */
     constructor(noa: import('../index').Engine, requestID: any, ci: any, cj: any, ck: any, size: any, dataArray: any, fillVoxelID?: number);
     noa: import("../index").Engine;
     isDisposed: boolean;
+    userData: any;
     requestID: any;
     voxels: any;
     i: any;
@@ -25,6 +25,7 @@ declare class Chunk {
     _neighbors: any;
     _neighborCount: number;
     _timesMeshed: number;
+    /** @internal */
     _blockHandlerLocs: LocationQueue;
     _updateVoxelArray(dataArray: any, fillVoxelID?: number): void;
     get(i: any, j: any, k: any): any;
@@ -33,7 +34,7 @@ declare class Chunk {
     updateMeshes(): void;
     dispose(): void;
 }
-declare namespace Chunk {
+export namespace Chunk {
     function _createVoxelArray(size: any): any;
 }
-import { LocationQueue } from "./util";
+import { LocationQueue } from './util';

dist/src/lib/container.d.ts

@@ -4,9 +4,13 @@
  *
  * This module wraps `micro-game-shell`, which does most of the implementation.
  *
- * @emits DOMready
- * @emits gainedPointerLock
- * @emits lostPointerLock
+ * **Events**
+ *  + `DOMready => ()`
+ *    Relays the browser DOMready event, after noa does some initialization
+ *  + `gainedPointerLock => ()`
+ *    Fires when the game container gains pointerlock.
+ *  + `lostPointerLock => ()`
+ *    Fires when the game container loses pointerlock.
  */
 export class Container extends EventEmitter {
     /** @internal */
@@ -36,5 +40,5 @@ export class Container extends EventEmitter {
     */
     setPointerLock(lock?: boolean): void;
 }
-import { EventEmitter } from "events";
-import { MicroGameShell } from "micro-game-shell";
+import { EventEmitter } from 'events';
+import { MicroGameShell } from 'micro-game-shell';

dist/src/lib/entities.d.ts

@@ -9,7 +9,7 @@
  * folder for examples.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  *
  * ```js
  * var defaults = {
@@ -159,4 +159,4 @@ export class Entities extends ECS {
     */
     add(position?: any, width?: number, height?: number, mesh?: any, meshOffset?: any, doPhysics?: boolean, shadow?: boolean): number;
 }
-import ECS from "ent-comp";
+import ECS from 'ent-comp';

dist/src/lib/inputs.d.ts

@@ -7,7 +7,7 @@
  * for full docs.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  *
  * ```js
  *   defaultBindings: {
@@ -26,4 +26,4 @@ export class Inputs extends GameInputs {
     /** @internal */
     constructor(noa: any, opts: any, element: any);
 }
-import { GameInputs } from "game-inputs";
+import { GameInputs } from 'game-inputs';

dist/src/lib/objectMesher.d.ts

@@ -1,15 +1,21 @@
-export default ObjectMesher;
-/** @param {import('../index').Engine} noa*/
-declare function ObjectMesher(noa: import('../index').Engine): void;
-declare class ObjectMesher {
-    /** @param {import('../index').Engine} noa*/
+/**
+ * @internal
+ * @param {import('../index').Engine} noa
+*/
+export function ObjectMesher(noa: import('../index').Engine): void;
+export class ObjectMesher {
+    /**
+     * @internal
+     * @param {import('../index').Engine} noa
+    */
     constructor(noa: import('../index').Engine);
     rootNode: TransformNode;
+    allBaseMeshes: any[];
     initChunk: (chunk: any) => void;
     setObjectBlock: (chunk: any, blockID: any, i: any, j: any, k: any) => void;
     buildObjectMeshes: () => void;
     disposeChunk: (chunk: any) => void;
     tick: () => void;
     _rebaseOrigin: (delta: any) => void;
 }
-import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';

dist/src/lib/physics.d.ts

@@ -7,7 +7,7 @@
  * for full docs.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  *
  * ```js
  * {
@@ -26,4 +26,4 @@ export class Physics extends VoxelPhysics {
     */
     constructor(noa: import('../index').Engine, opts: any);
 }
-import { Physics as VoxelPhysics } from "voxel-physics-engine";
+import { Physics as VoxelPhysics } from 'voxel-physics-engine';

dist/src/lib/registry.d.ts

@@ -3,7 +3,7 @@
  * materials, properties, and events.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  *
  * ```js
  * var defaults = {
@@ -38,7 +38,7 @@ export class Registry {
      * @param {string} name of this material
      * @param {Partial<MaterialOptions>} [options]
      */
-    registerMaterial: (name?: string, options?: Partial<MaterialOptions>, ...args: any[]) => number;
+    registerMaterial: (name?: string, options?: Partial<MaterialOptions>) => number;
     /**
      * block solidity (as in physics)
      * @param id
@@ -77,6 +77,7 @@ export class Registry {
     /**
      * Given a texture URL, does any material using that
      * texture need alpha?
+     * @internal
      * @returns {boolean}
      */
     _textureNeedsAlpha: (tex?: string) => boolean;

dist/src/lib/rendering.d.ts

@@ -3,16 +3,16 @@
  * Manages all rendering, and the BABYLON scene, materials, etc.
  *
  * This module uses the following default options (from the options
- * object passed to the [[Engine]]):
+ * object passed to the {@link Engine}):
  * ```js
  * {
  *     showFPS: false,
  *     antiAlias: true,
  *     clearColor: [0.8, 0.9, 1],
- *     ambientColor: [1, 1, 1],
+ *     ambientColor: [0.5, 0.5, 0.5],
  *     lightDiffuse: [1, 1, 1],
  *     lightSpecular: [1, 1, 1],
- *     groundLightColor: [0.5, 0.5, 0.5],
+ *     lightVector: [1, -1, 0.5],
  *     useAO: true,
  *     AOmultipliers: [0.93, 0.8, 0.5],
  *     reverseAOmultiplier: 1.0,
@@ -40,19 +40,29 @@ export class Rendering {
     revAoVal: any;
     /** @internal */
     meshingCutoffTime: number;
-    /** @internal */
-    _scene: Scene;
-    /** @internal */
-    _engine: Engine;
+    /** the Babylon.js Engine object for the scene */
+    engine: Engine;
+    /** the Babylon.js Scene object for the world */
+    scene: Scene;
+    /** a Babylon.js DirectionalLight that is added to the scene */
+    light: DirectionalLight;
+    /** the Babylon.js FreeCamera that renders the scene */
+    camera: FreeCamera;
+    /**
+     * Constructor helper - set up the Babylon.js scene and basic components
+     * @internal
+     */
+    _initScene(canvas: any, opts: any): void;
     /** @internal */
     _octreeManager: SceneOctreeManager;
-    initScene(canvas: any, opts: any): void;
+    /** @internal */
     _cameraHolder: TransformNode;
-    _camera: FreeCamera;
+    /** @internal */
     _camScreen: import("@babylonjs/core/Meshes").Mesh;
+    /** @internal */
     _camScreenMat: StandardMaterial;
+    /** @internal */
     _camLocBlock: number;
-    _light: HemisphericLight;
     /** The Babylon `scene` object representing the game world. */
     getScene(): Scene;
     /** @internal */
@@ -66,21 +76,28 @@ export class Rendering {
     /** @internal */
     highlightBlockFace(show: any, posArr: any, normArr: any): void;
     /**
-     * Add a mesh to the scene's octree setup so that it renders.
+     * Adds a mesh to the engine's selection/octree logic so that it renders.
      *
      * @param mesh the mesh to add to the scene
-     * @param isStatic pass in true if mesh never moves (i.e. change octree blocks)
+     * @param isStatic pass in true if mesh never moves (i.e. never changes chunks)
      * @param pos (optional) global position where the mesh should be
      * @param containingChunk (optional) chunk to which the mesh is statically bound
      */
     addMeshToScene(mesh: any, isStatic?: boolean, pos?: any, containingChunk?: any): void;
+    /**
+     * Use this to toggle the visibility of a mesh without disposing it or
+     * removing it from the scene.
+     *
+     * @param {import('@babylonjs/core/Meshes').Mesh} mesh
+     * @param {boolean} visible
+     */
+    setMeshVisibility(mesh: import("@babylonjs/core/Meshes").Mesh, visible?: boolean): void;
     /**
      * Create a default standardMaterial:
      * flat, nonspecular, fully reflects diffuse and ambient light
+     * @returns {StandardMaterial}
      */
     makeStandardMaterial(name: any): StandardMaterial;
-    /** Exposed hook for if the client wants to do something to newly created materials */
-    postMaterialCreationHook(mat: any): void;
     /** @internal */
     prepareChunkForRendering(chunk: any): void;
     /** @internal */
@@ -92,10 +109,10 @@ export class Rendering {
     /** @internal */
     debug_MeshCount(): void;
 }
-import { Scene } from "@babylonjs/core/scene";
-import { Engine as Engine_1 } from "@babylonjs/core/Engines/engine";
-import { SceneOctreeManager } from "./sceneOctreeManager";
-import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
-import { FreeCamera } from "@babylonjs/core/Cameras/freeCamera";
-import { StandardMaterial } from "@babylonjs/core/Materials/standardMaterial";
-import { HemisphericLight } from "@babylonjs/core/Lights/hemisphericLight";
+import { Engine as Engine_1 } from '@babylonjs/core/Engines/engine';
+import { Scene } from '@babylonjs/core/scene';
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight';
+import { FreeCamera } from '@babylonjs/core/Cameras/freeCamera';
+import { SceneOctreeManager } from './sceneOctreeManager';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';

dist/src/lib/sceneOctreeManager.d.ts

@@ -1,7 +1,9 @@
+/** @internal */
 export class SceneOctreeManager {
+    /** @internal */
     constructor(rendering: any, blockSize: any);
     rebase: (offset: any) => void;
-    includesMesh: (mesh: any) => any;
     addMesh: (mesh: any, isStatic: any, pos: any, chunk: any) => void;
     removeMesh: (mesh: any) => void;
+    setMeshVisibility: (mesh: any, visible?: boolean) => void;
 }