Node3D

npm install @node-3d/core

• WebGL-like interface. Real OpenGL though.
• Three.js compatible environment.
• Use node modules and compiled addons: CUDA, OpenCL, etc.
• Window control. Multiwindow applications.
• Read/write files and network directly with Node.js.
• Cross-platform: Windows x64/ARM64, Linux x64/ARM64, macOS x64/ARM64.

Compatibility with three.js allows porting the existing JS code. The real OpenGL backend is used, not ANGLE. This makes it possible to use GL resource IDs to set up interoperation with CUDA or OpenCL. This is the most important feature of this project and why it was created in the first place.

It is possible to create full applications and games using this framework. For example, see Space Simulation Toolkit.

1. Setup the project directory:

   mkdir my-project
   cd my-project
   npm init -y
   npm install @node-3d/core three
   touch index.mjs

2. Paste the code and see if it works:

   import * as THREE from 'three';
   
   import { Screen, addThreeHelpers, init } from '@node-3d/core';
   
   const { loop } = init({ isGles3: true, isWebGL2: true, title: 'Node3D' });
   addThreeHelpers(THREE);
   
   const screen = new Screen({ three: THREE, fov: 70, z: 35 });
   screen.scene.background = new THREE.Color(0x333333);
   
   screen.scene.add(new THREE.AmbientLight(0xc1c1c1, 0.5));
   
   const sun = new THREE.DirectionalLight(0xffffff, 2);
   sun.position.set(-1, 0.5, 1);
   screen.scene.add(sun);
   
   const geometry = new THREE.TorusKnotGeometry(10, 1.85, 256, 20, 2, 7);
   const material = new THREE.MeshToonMaterial({ color: 0x6cc24a });
   const mesh = new THREE.Mesh(geometry, material);
   screen.scene.add(mesh);
   
   loop((now) => {
   	mesh.rotation.x = now * 0.0005;
   	mesh.rotation.y = now * 0.001;
   	screen.draw();
   });

3. See docs and examples: @node-3d/core.

4. Take a look at Three.js examples.

Node3D render loops are scheduled through the native GLFW/uv-loop path, not a recursive JavaScript setImmediate loop. For ordinary rendering, use vsync: true and let Node3D pace frame starts against the current monitor refresh rate.

vsync and swapInterval values follow this policy:

• false or 0 renders unpaced with glfwSwapInterval(0).
• true uses the synced path.
• negative numbers request adaptive sync where available, otherwise normal sync.
• positive numbers request normal sync.

For synced paths, the native layer gates render callbacks in all window modes: windowed, borderless, and fullscreen. Callbacks still receive actual monotonic time, so input, animation, physics, and game logic stay connected to real time. Applications that need to cap rare long pauses should clamp deltas or use a fixed-step accumulator in their own simulation code.

Core examples are organized by source:

• packages/core/examples/core/ contains Node3D-authored examples, diagnostics, stress tests, and shared helpers.
• packages/core/examples/three/ contains examples copied or closely adapted from official Three.js examples.
• packages/core/examples/pixi/ contains examples copied or closely adapted from official Pixi examples.

Future vendor examples should use their own directory, such as examples/babylonjs/, while Node3D-specific probes stay under examples/core/.

1. Core - key components to run WebGL and Three.js code on Node.js.

   • @node-3d/core - extensible browser-like Node.js runtime for multimedia apps.
   • @node-3d/addon-tools - helpers for Node.js addons.
   • @node-3d/glfw - native window control.
   • @node-3d/image - image loading, can mimic web Image.
   • @node-3d/segfault - catches and logs the native-level crash messages: segmentation fault, etc.
   • @node-3d/webgl - a thin, minimalistic WebGL implementation.

2. Dependency packages - carry precompiled binaries, dynamic libraries, and/or C++ headers.

   • @node-3d/deps-bullet - Bullet Physics binaries and headers.
   • @node-3d/deps-freeimage - FreeImage binaries and headers.
   • @node-3d/deps-labsound - LabSound binaries and headers.
   • @node-3d/deps-opengl - OpenGL, GLFW, GLEW binaries and headers.
   • @node-3d/deps-qmlui - QmlUi binaries and headers.
   • @node-3d/deps-qt-core - Qt binaries for console apps.
   • @node-3d/deps-qt-gui - Qt binaries for GUI apps.
   • @node-3d/deps-qt-qml - Qt binaries for QML apps.
   • @node-3d/deps-uiohook - binaries and headers to use libuiohook with npm.

3. Native addons - provide Node.js bindings to native graphics, compute, audio, input, and physics libraries.

   • @node-3d/bullet - rigid-body subset of Bullet Physics.
   • @node-3d/cuda - addon for running NVIDIA CUDA programs on GPU.
   • @node-3d/iohook - global input hook bindings.
   • @node-3d/opencl - addon for running OpenCL programs on GPU.
   • @node-3d/qml - Node3D-QML interoperation.
   • @node-3d/steam-api - Steamworks API bindings.
   • @node-3d/uv-loop - libuv idle scheduling for GLFW-backed frame loops.
   • @node-3d/webaudio - a WebAudio implementation.

4. Plugins - high-level Node3D packages that compose addon capabilities with @node-3d/core. A plugin uses the core context and primitives to expose features that combine the Node3D environment with the addon(s) it wraps.

   For example:

   import * as THREE from 'three';
   import { gl, init, addThreeHelpers } from '@node-3d/core';
   import { init as initQml } from '@node-3d/plugin-qml';
   
   const cwd = import.meta.dirname;
   const { doc } = init({ isGles3: true, isWebGL2: true });
   addThreeHelpers(THREE);
   const { QmlOverlay } = initQml({ doc, gl, cwd, three: THREE });
   
   // ...
   const overlay = new QmlOverlay({ file: `${cwd}/qml/gui.qml` });
   scene.add(overlay.mesh);

   • @node-3d/plugin-bullet - extends 3D Core with Bullet Physics.
   • @node-3d/plugin-qml - extends 3D Core with QML graphics.
   • @node-3d/plugin-webaudio - extends 3D Core with an audio interface.

5. QML helpers - reusable QML assets and controls for packages that use QML.

   • @node-3d/qml-colorhelpers - color picker and color display components.
   • @node-3d/qml-fontawesome - FontAwesome 6+ icons for QML.
   • @node-3d/qml-themedui - themed QML UI components.

Native addon release archives are built for Windows x64/ARM64, Linux x64/ARM64, and macOS x64/ARM64 where the package supports those platforms.

Most addons rely on Node-API for ABI compatibility across Node.js versions. Addons that call Node's embedded libuv directly can require Node-major-specific binaries. These packages use release tags shaped as <package-version>-<node-major>, with odd Node.js majors falling back to the previous even/LTS line and out-of-range majors falling back to the nearest configured line.

Bugs and enhancements are tracked as GitHub issues. You can also create an issue on a specific repository of Node3D.

Project-level decisions are recorded in Architecture Decision Records.

This repository is also a Git superproject for the Node3D package repositories. Clone with packages, or initialize them after cloning:

npm run packages:update

Install all npm workspace packages from this repository root:

npm install

For metadata-only installs that should not run native package postinstall scripts:

npm install --ignore-scripts

Run a script across every package that defines it:

npm run test:watch --workspaces --if-present
npm run packages:test
npm run packages:lint
npm run build:ci

Run a script in one package:

npm --workspace @node-3d/core run test:watch
npm --workspace @node-3d/webgl run build:ci

Print the local dependency graph:

npm run packages:graph

On PowerShell installations that block npm.ps1, use npm for the same commands.

• Use a clear and descriptive title.
• Describe the desired enhancement / problem.
• Provide examples to demonstrate the issue.
• If the problem involves a crash, provide its trace log.

• Do not include issue numbers in the PR title.
• Commits use the present tense ("Add feature" not "Added feature").
• Commits use the imperative mood ("Move cursor to..." not "Moves cursor to...").
• File System
  • Only lowercase in file/directory names.
  • Words are separated with dashes.
  • If there is an empty directory to be kept, place an empty .keep file inside.

Node3D can be used commercially. You don't have to pay for Node3D or any of its third-party libraries.

Node3D modules have their own code licensed under MIT, meaning "I've just put it here, do what you want, have fun". Some modules have separately licensed third-party software in them. For instance, @node-3d/deps-freeimage carries the FreeImage binaries and headers, and those are the property of their respective owners, and are licensed under FIPL terms (but free to use anyway).

All such cases are explained in README.md per project in question.