Merge branch 'develop'

* develop: (99 commits) Add metadata flags to noa's generated terrain/object meshes, in case client needs to find/distinguish them Fix bounds checking for terrain meshes that was confusing shadowCasters Doc updates and rebuild Update to BJS 6.1 - fixes some babylon internal type errors Updates **many** jsdoc comments to improve generated docs Renames several internals to public: `rendering._engine` to `engine` `rendering._camera` to `camera` `rendering._scene` to `scene` `rendering._light` to `light` Terrain meshes need positions before the client hears about them Remove duplicate type comments Bump default BJS version to 6.0 Reorganize code around adding/removing/freezing terrain meshes. - `noa` now emits `addingTerrainMesh`, `removingTerrainMesh` - these fire for both regular terrain chunks, and custom block meshes - intention is for client to use these for e.g. implementing BJS shadows - removes previous overwriteable hooks - also expose arrays of current terrain materials, object blocks, in case client needs to see stuff added before its listeners were made Simplify a bit and set visibility via the rendering API Hopefully avoids more GC churn by giving BJS typed arrays (which shouldn't be copied?) Reuse arrays during mesh creation. They get resized often, but this results in noticeably more frequent small GCs rather than infrequent large ones. Change syntax for metadata flags to be consistent Try enabling new babylon performance priority mode Store a list of all current object meshes with instances in the scene add docs Add `rendering.setMeshVisibility`, and make internal version support static meshes Document .33 changes so far Restore per-tick mesh queue timing to count from start of tick event Add hooks for client to know when meshes are added/removed to the scene. Also adds deprecation note about removing material hook ... # Conflicts: # README.md
fenomas · May 19, 2023 · 8ba042f · 8ba042f
2 parents 7a03856 + e6c305e
commit 8ba042f
Show file tree

Hide file tree

Showing 155 changed files with 20,488 additions and 5,087 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -10,7 +10,7 @@ module.exports = {
         "es6": true,
     },
     "parserOptions": {
-        "ecmaVersion": 10,
+        "ecmaVersion": 13,
         "sourceType": "module",
     },
     "rules": {

diff --git a/.jsbeautifyrc b/.jsbeautifyrc
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2021 Andy Hall ([email protected])
+Copyright (c) 2015-2022 Andy Hall ([email protected])
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -4,11 +4,9 @@
 An experimental voxel game engine.
 
 Some projects using `noa`:
- * [bloxd.io](https://bloxd.io/) - multiplayer voxel games with editable worlds, by [Arthur](https://github.com/MCArth)
- * [Minecraft Classic](https://classic.minecraft.net/) - official game from Mojang (I'm as surprised as you are)
+ * [Minecraft Classic](https://classic.minecraft.net/) - from Mojang (I'm as surprised as you are)
  * [VoxelSrv](https://github.com/Patbox/voxelsrv) - a voxel game inspired by Minecraft, by [patbox](https://github.com/Patbox)
  * [CityCraft.io](https://citycraft.io/) - multiplayer voxel cities, by [raoneel](https://github.com/raoneel)
- * [OPCraft](https://github.com/latticexyz/opcraft) - a voxel game running on Ethereum smart contracts, by [Lattice](https://github.com/latticexyz)
  * [noa-examples](https://github.com/fenomas/noa-examples) - starter repo with minimal hello-world and testbed games
 
 
@@ -21,20 +19,16 @@ The easiest way to start building a game with `noa` is to clone the
 on the code there. The comments in the `hello-world` example source walk 
 through how to instantiate the engine, define world geometry, and so forth. 
 The example repo also shows the intended way to import noa's 
-peer depenencies, configure webpack, and so on.
-
-
-
-## Size
-
-The engine is around **250kb** when built in production mode and zipped. 
-Uncompressed, `noa` is ~160kb its peer dependency `babylon.js` is ~900kb.
+peer dependencies, test a world, build for production, etc.
 
 
 ## Docs
 
 See the [API reference](https://fenomas.github.io/noa/API/) 
-for engine classes and methods. 
+for engine classes and methods. But virtually all the docs exist as
+JSDOC-style source comments, so if you're getting code completion and 
+type hints from a modern editor, that's the easiest way to browse the docs.
+
 Documentation PRs are welcome! See the source for details, API docs 
 are generated automatically via `npm run docs`.
 
@@ -53,10 +47,17 @@ please try to be sorta-kinda consistent with what's already there.
 
 ## Change logs
 
-See [history.md](docs/history.md) for changes and migration for each version.
+See [history.md](docs/history.md) for full changes and migration for each version.
 
 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
+   * 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`: 
    * Change the speed of the world! See `noa.timeScale`

diff --git a/dist/src/components/fadeOnZoom.d.ts b/dist/src/components/fadeOnZoom.d.ts
@@ -7,7 +7,6 @@ export default function _default(noa: any): {
     order: number;
     state: {
         cutoff: number;
-        _showing: any;
     };
     onAdd: any;
     onRemove: any;

diff --git a/dist/src/components/physics.d.ts b/dist/src/components/physics.d.ts
@@ -12,39 +12,7 @@ export default function _default(noa: import('..').Engine): {
     renderSystem: (dt: any, states: any) => void;
 };
 export function setPhysicsFromPosition(physState: any, posState: any): void;
-/**
- * @typedef {Object} RigidBody
- * @prop {import('aabb-3d')} aabb
- * @prop {number} mass
- * @prop {number} friction
- * @prop {number} restitution
- * @prop {number} gravityMultiplier
- * @prop {number} airDrag
- * @prop {number} fluidDrag
- * @prop {boolean} autoStep
- * @prop {null | function} onCollide
- * @prop {null | function} onStep
- * @prop {number[]} velocity
- * @prop {number[]} resting
- * @prop {boolean} inFluid
- *
- */
 export class PhysicsState {
-    /** @type {null | RigidBody} */
-    body: null | RigidBody;
+    /** @type {import('voxel-physics-engine').RigidBody} */
+    body: import('voxel-physics-engine').RigidBody;
 }
-export type RigidBody = {
-    aabb: import('aabb-3d');
-    mass: number;
-    friction: number;
-    restitution: number;
-    gravityMultiplier: number;
-    airDrag: number;
-    fluidDrag: number;
-    autoStep: boolean;
-    onCollide: null | Function;
-    onStep: null | Function;
-    velocity: number[];
-    resting: number[];
-    inFluid: boolean;
-};
diff --git a/dist/src/components/shadow.d.ts b/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: {

diff --git a/dist/src/index.d.ts b/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,15 +37,27 @@ 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"` */
     version: string;
     /** @internal */
     _paused: boolean;
     /** @internal */
-    _dragOutsideLock: any;
-    /** @internal */
     _originRebaseDistance: any;
     /** @internal */
     worldOriginOffset: number[];
@@ -67,14 +76,17 @@ export class Engine extends EventEmitter {
     timeScale: number;
     /** Child module for managing the game's container, canvas, etc. */
     container: Container;
-    /** The game's tick rate (ticks per second)
+    /** The game's tick rate (number of ticks per second)
+     * @type {number}
      * @readonly
     */
-    readonly tickRate: any;
-    /** The game's max framerate (use `0` for uncapped) */
-    maxRenderRate: any;
-    /** Inputs manager - abstracts key/mouse input */
-    inputs: import("./lib/inputs").Inputs;
+    readonly tickRate: number;
+    /** The game's max framerate (use `0` for uncapped)
+     * @type {number}
+     */
+    maxRenderRate: number;
+    /** Manages key and mouse input bindings */
+    inputs: Inputs;
     /** A registry where voxel/material properties are managed */
     registry: Registry;
     /** Manages the world, chunks, and all voxel data */
@@ -91,8 +103,10 @@ export class Engine extends EventEmitter {
     playerEntity: number;
     /** Manages the game's camera, view angle, sensitivity, etc. */
     camera: Camera;
-    /** How far to check for a solid voxel the player is currently looking at */
-    blockTestDistance: any;
+    /** How far to check for a solid voxel the player is currently looking at
+     * @type {number}
+    */
+    blockTestDistance: number;
     /**
      * Callback to determine which voxels can be targeted.
      * Defaults to a solidity check, but can be overridden with arbitrary logic.
@@ -129,8 +143,6 @@ export class Engine extends EventEmitter {
     /** @internal */
     _prevTargetHash: number;
     /** @internal */
-    makeTargetHash: (pos: any, norm: any, id: any) => number;
-    /** @internal */
     _pickPos: any;
     /** @internal */
     _pickResult: {
@@ -165,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.
     */
@@ -233,14 +245,15 @@ export class Engine extends EventEmitter {
         _localPosition: number[];
     };
 }
-import { EventEmitter } from "events";
-import { Container } from "./lib/container";
-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';
diff --git a/dist/src/lib/camera.d.ts b/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,
@@ -16,13 +16,13 @@
  * ```
 */
 export class Camera {
-    /** @internal */
-    constructor(noa: any, opts: any);
     /**
      * @internal
-     * @type {import('../index').Engine}
+     * @param {import('../index').Engine} noa
+     * @param {Partial.<CameraDefaults>} opts
     */
-    noa: import('../index').Engine;
+    constructor(noa: import('../index').Engine, opts: Partial<CameraDefaults>);
+    noa: import("../index").Engine;
     /** Horizontal mouse sensitivity. Same scale as Overwatch (typical values around `5..10`) */
     sensitivityX: number;
     /** Vertical mouse sensitivity. Same scale as Overwatch (typical values around `5..10`) */
@@ -31,6 +31,17 @@ export class Camera {
     inverseX: boolean;
     /** Mouse look inverse (vertical) */
     inverseY: boolean;
+    /**
+     * Multiplier for temporarily altering mouse sensitivity.
+     * Set this to `0` to temporarily disable camera controls.
+    */
+    sensitivityMult: number;
+    /**
+     * Multiplier for altering mouse sensitivity when pointerlock
+     * is not active - default of `0` means no camera movement.
+     * Note this setting is ignored if pointerLock isn't supported.
+     */
+    sensitivityMultOutsidePointerlock: number;
     /**
      * Camera yaw angle.
      * Returns the camera's rotation angle around the vertical axis.
@@ -69,17 +80,16 @@ export class Camera {
     */
     cameraTarget: number;
     /** How far back the camera should be from the player's eye position */
-    zoomDistance: any;
+    zoomDistance: number;
     /** How quickly the camera moves to its `zoomDistance` (0..1) */
-    zoomSpeed: any;
+    zoomSpeed: number;
     /** 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.
-     * @readonly
+     * This value will get overwritten each tick, but you may want to write to it
+     * when overriding the camera zoom speed.
     */
-    readonly currentZoom: any;
-    /** @internal */
-    _currentZoom: any;
+    currentZoom: number;
     /** @internal */
     _dirVector: any;
     /** @internal */
@@ -102,7 +112,7 @@ export class Camera {
     getDirection(): any;
     /**
      * Called before render, if mouseLock etc. is applicable.
-     * Consumes input mouse events x/y, updates camera angle and zoom
+     * Applies current mouse x/y inputs to the camera angle and zoom
      * @internal
     */
     applyInputsToCamera(): void;
@@ -114,3 +124,15 @@ export class Camera {
     /** @internal */
     updateAfterEntityRenderSystems(): void;
 }
+declare function CameraDefaults(): void;
+declare class CameraDefaults {
+    inverseX: boolean;
+    inverseY: boolean;
+    sensitivityMult: number;
+    sensitivityMultOutsidePointerlock: number;
+    sensitivityX: number;
+    sensitivityY: number;
+    initialZoom: number;
+    zoomSpeed: number;
+}
+export {};