chunklands/chunklands

3D Game in NodeJS/OpenGL

Chunklands

This page is designed for developers.

If you want to read more of the project, goals, etc. please have a look at chunklands.de.

Notice: Breaking change

Former Chunklands architecture (single-threaded) had performance issues. POC of executor-architecture was merged into master to see daily process on master.

Still the set of features is not fully implemented, but we decided to merge it now.

It will take some time to support all old features. Please also consider the documentation to be out-dated.

Technologies

Installation

Requirements:

• node.js 14+
• clang-10+
• cmake 3.0+ (for glfw)

Linux

make setup

MacOS

make setup

MacOS ships apple clang. It's likely to be incompatible, so another vendor-free clang version is needed.

brew install llvm

# add this to your .env file
cat .env
# CLANG_BIN=/usr/local/opt/llvm/bin/clang
# CLANG_TIDY_BIN=/usr/local/opt/llvm/bin/clang-tidy

Windows:

not supported, sorry

Development

Build / Run

Variant 1 - dev build, watch and run

1. watch files and build dev

npm run dev

2. start game

npm start

Variant 2 - dev build and run

build dev and run

npm run build:dev && npm start

Variant 3 - prod build and run

build prod and run

npm run build:prod && npm start

or simply:

npm run play

Other commands

Clean

remove /build directory

make clean

Links

• GitHub Issues
• GitHub Project

Progress

Current status:

chunklands's Issues

window resize, viewport update

render text to screen

• show fps

block-type registration (after #23)

implement minimal open-closed registrar for block-types:

• require all js files from src/blocks e.g. src/blocks/dirt.js
• each js file exports the block-definition (either data, or callbacks, let's see what's better)
• block definition/data:
  • vertex data, normals
  • hidesNeighbor: boolean (if all neighbors on the 6 faces have it true, block doesn't need to be rendered)

Windows support

TextureBaker: texture is overlapping

• texture merge will overlap
• bug in algorithm

chunkloading: limit per loop

• only N chunks should be updated per loop
• N can be a constant, or calculated as a time-window, e.g. start with 10, if loop is real-time, increase, if loop delays render, decrease amount

Create basic Scene class, render flat plane, moving around with "wasd" keys

more realistic terrain generation

chunkloading priority

• order chunks from near to far for updates
• distance can be cheap chess/manhattan-distance (no euclidean distance).

adapt shader, add diffuse blending

• add vertex normals
• add hard-coded directed light
• add z-buffer test, clear z-buffer bits
• result: see faces and edges of the cubes

Use submodules instead of CMake `ExternalProject`

make block disappear after click

reimplement `F` for gravitation in JS

• glfw key press should emit an event in JS
• expose scene fly mode to JS

experimental: Worker level generator

• level generation can become very expensive, should be decoupled from main process
• make generateChunk async with callback

use clang, drop cmake

Add OpenGL Proc binder `glad`

implement texture loader from many small png files, using one big opengl texture (after #26)

show cursor and highlight block

worldgen: create a realistic world

• a mountain
• a sandy beach
• some water ...

make SSAO configurable

especially SSOA needs lot of render time. It should be possible to turn it off and on

Update projection matrix on window resize

flying ego perspective player control with "wasd" keys and mouse

optimization: don't render hidden blocks

small optimization:

• only applies to the inside of a chunk not across chunk borders
• just to reduce vertex count (currently 23m for render distance 2 = 5x5x5 chunks)

improve game loop, split into "render" and "update"

decouple update from render

• update should be at fixed frequency
• render can have unlimited frequency
• investigate on key press events strange delay or event overflow. E.g. pressing "w" 2s makes player move 4s (sticky keys proper implemented, etc.?)

optimization: don't render hidden faces

• we have opaque = true to not render hidden blocks
• we need vertexData to have faces metadata (e.g. vertex index ranges define a face)
• we need need more metadata for opaque, e.g.

enum Occlusion {
  OCCLUDES_TOP,
  OCCLUDES_RIGHT,
  ... ,
  OPAQUE = OCCLUDES_TOP | OCCLUDES_BOTTOM | ...
}

implement `World` and `WorldGenerator`

• scene renders world
• world
  • save player position
  • renders and stores chunks
  • requests chunks from world generator
• world generator
  • build chunk data

optimization: don't render hidden faces

game metrics

• render pipeline metrics => every shader
• computation metrics => chunk generation, gl* calls for memory, e.g. glBufferData etc. (notice don't use wall clock time as GL is async, glQueryBegin(GL_TIME_ELAPSED, ...) ).

optimization: chunk prefetch

With #11 we improved internal chunk rendering, but chunks will render all surrounding faces. To get rid of that, we need to prefetch chunks around rendered chunks:

• split Chunk::Prepare into sth. like PrepareModel with calculating block types and PrepareView for creating vertex buffer etc.
• Chunk should hold information about whether model/view is prepared
• introduce PREFETCH_DISTANCE
• idea: make chunkloading need 3 game loop iterations to make chunks be ready for rendering
  1. PrepareModel
  2. PrepareView, only if adjacent chunks have prepared models
  3. Render
• don't make any Prepare* call trigger other chunk Prepare* in order to prevent infinite recursion
• small optimization: create Prepare* limits, so that not too many operations happen in one loop (implicit done with reverse Prepare order, that chunks are tested first for rendering, then model prepare)

world generator should spawn multi-blocks e.g. houses, trees, etc.

Environment class

• no direct exports of methods, but wrap in Environment class
• initialize
• loadProcs
• terminate

Create window class with basic features

collision detection with flying control

MacOS support

chunkloading: profiling

• some optimization done
• chunk loading is smoother than ever, but still not smooth enough
• we need profiling, where performance goes
• check gl* calls, loops, etc. top -> down profiling

Render a simple scene (after #9)

• render multiple chunks (a cube with 3x3x3 chunks)
• generate chunk data from a simple world generator (some added sines waves set the ground)

dynamic chunkloading with render distance (after #10)

• update fixed set of rendered chunks to dynamic range (chunk render distance)
• mechanism to request a chunk (sync)
• add chunk to scene (according to render distance)
• remove chunk from scene (according to render distance)

chunkloading retain area

chunks should not immediately be unloaded if out of prefetch area

• render distance < prefetch distance
• prefetch distance <= retain distance

add textures, use one texture with fixed uvs

Render a chunk (no textures)

• simple data structure (16x16x16)
• block types (0 = AIR, 1 = GRASS/DIRT)
• initialize with hard-coded data
• create vb from data structure (use block geometry as reference data)
• no hidden faces optimization

Add key callback to window class

improvement: move chunkloading to JS

File loader for blocks (in JS):

From e.g. Blender we can export .obj files with Material Data. Investigate on how this could be useful for us or how do we create new blocks with uv data? Any format many 3D studios support which is easy for us to use?

Move main loop to native module

optimization: don't render chunks outside view frustum

investigate on MacOS issues

• check cmake setup
• check render flickering

add gravity, toggle flight mode

jumping will be part of another story. it would be possible to qnd implement it, but it doesn't make sense at the moment. we can fly and go around.

add some badges and documention

Create basic NAPI setup

introduce more blocks and multiblocks. add them to world generator

Blocks:

• Dirt
• Grass
• Stone
• Gravel
• Wood
• Gold
• Iron
• Diamond
• Coal
• Snow