Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,6 @@ docs/ecs-lib/api/typescript.md

emsdk-cache/
.vscode
.tsdocs

references/
.direnv
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/editor/protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "How a running game and the NanoForge editor talk to each other"
---

# Editor protocol

When the editor starts a game, it passes two event emitters in `RunOptions.editor`:

- `fromEditor`: editor → engine commands. `EditorLibrary` drains it at the start of every tick, including paused ticks.
Expand Down
20 changes: 0 additions & 20 deletions docs/docs/getting-started/1-index.mdx

This file was deleted.

9 changes: 5 additions & 4 deletions docs/docs/getting-started/documentation.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
---
title: "Documentation"
icon: "book"
description: "Overview of the engine documentation"
description: "How the engine documentation is written and published"
---

# Documentation
The engine documentation lives in the engine repository and is published to this site automatically at each engine release.

The documentation for the engine is separated across the different libraries of the engine. Everything is then gathered into this site and published from the repository automatically.
- **Pages** are the `.mdx` files in `docs/docs`. Their order and groups come from `docs/docs/navigation.json`: every page is listed there exactly once.
- **API references** are generated from the TSDoc comments of each package by `pnpm run docs` (TypeDoc), into `docs/references`. They are never written by hand.

This documentation is written in reStructuredText and is now being migrated to MDX so it is easier to maintain alongside the rest of the site. Sphinx is used to generate the rendered documentation.
To change a page, edit it in the engine repository. Links between pages are relative to the file, like `./how-to-use` or `../network/index`.
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "Getting started with the engine"
---

# Introduction to using the Engine

Whether you work on this engine as a developer or you want to use it, you will want a test project. This page is a walkthrough for setting up a basic project.

## As a developer on the engine
Expand Down
19 changes: 19 additions & 0 deletions docs/docs/getting-started/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
title: "Engine"
icon: "book"
description: "Nanoforge engine documentation"
---

This documentation covers the engine, its packages, and the surrounding usage guides.

## Start Here

- [Documentation](./documentation)
- [How to Use](./how-to-use)

## Packages

- [Registry](../registry/index)
- [Network](../network/index)
- [Graphics 3D](../graphics-3d/index)
- [Editor protocol](../editor/protocol)
2 changes: 0 additions & 2 deletions docs/docs/graphics-3d/advanced.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "wand-magic-sparkles"
description: "Full Three.js access, cameras, picking and editor events in @nanoforge-dev/graphics-3d"
---

# Graphics 3D: advanced

The library adds no layer between you and Three.js. Everything below is plain Three.js on the objects of `Context.graphics`.

## Importing Three.js
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/graphics-3d/editor-proposal.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "pen-ruler"
description: "Proposal for the editor's 3D Scene screen and plugin needs, for the editor's requirements session"
---

# Graphics 3D: editor proposal

Input for the editor's requirements session on 3D (see `editor/CLAUDE.md`: a plugin starts with a requirements session and a spec in `docs/specs/<plugin>.md`). Nothing here is built on the editor side yet.

**Goal:** a beginner edits a 3D scene without code, in the same way the 2D Scene screen works today.
Expand Down
4 changes: 1 addition & 3 deletions docs/docs/graphics-3d/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@ icon: "cube"
description: "Render a 3D scene with @nanoforge-dev/graphics-3d, built on Three.js"
---

# Graphics 3D

`@nanoforge-dev/graphics-3d` renders a 3D scene in the game's container with [Three.js](https://threejs.org/). It was chosen in the [3D graphics library benchmark](../lib-graphic-3d).
`@nanoforge-dev/graphics-3d` renders a 3D scene in the game's container with [Three.js](https://threejs.org/). It was chosen in the [3D graphics library benchmark](../lib-graphic-3d/index).

- **Client only.** `__init` throws on a server (no container).
- **One graphics library per app.** It uses the `graphics` key, like graphics-2d, so an app registers one or the other.
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/graphics-3d/performance.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "gauge"
description: "Drawing many objects with @nanoforge-dev/graphics-3d"
---

# Graphics 3D: performance

Each `Mesh` costs one draw call per frame. In the [benchmark POC](../lib-graphic-3d/poc), 2,000 meshes run at the display rate, while 20,000 run at about 12 FPS.

When a frame has more than 2,000 draw calls, the library logs this warning once:
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/babylon-js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "cube"
description: "Babylon.js in the 3D graphics library benchmark: verdict, integration notes and evidence per criterion"
---

# Babylon.js

Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown.

| | |
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "cube"
description: "Comparison of 3D libraries with WebGPU and a WebGL fallback, for the game and the editor"
---

# 3D graphics library benchmark

NanoForge needs a 3D graphics library next to `graphics-2d` (Konva). It must render with WebGPU and fall back to WebGL by itself, perform well, and be accessible. It is used by the game and by the editor (Scene screen, entity drag, screenshots, pop-out window).

Benchmark run on 2026-11-05.
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/luma-gl.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "cube"
description: "luma.gl in the 3D graphics library benchmark: verdict and evidence per criterion"
---

# luma.gl

Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown.

| | |
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/playcanvas.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "cube"
description: "PlayCanvas in the 3D graphics library benchmark: verdict and evidence per criterion"
---

# PlayCanvas

Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown.

| | |
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/poc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "flask"
description: "In-browser proof of concept for the two finalists, Three.js and Babylon.js"
---

# 3D benchmark POC

In-browser proof of concept for the two finalists of the [3D graphics library benchmark](./index): [Three.js](./three-js) and [Babylon.js](./babylon-js). It fills the criteria that docs alone could not answer: B1, B3, D5, D6, and checks C2 and C3 in a real browser.

Run on 2026-11-05.
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/lib-graphic-3d/three-js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "cube"
description: "Three.js in the 3D graphics library benchmark: verdict, integration notes and evidence per criterion"
---

# Three.js

Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown.

| | |
Expand Down
51 changes: 51 additions & 0 deletions docs/docs/navigation.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
[
{
"group": "Getting started",
"pages": [
"getting-started/index",
"getting-started/how-to-use",
"getting-started/documentation"
]
},
{
"group": "Registry",
"pages": ["registry/index", "registry/writing-web-assembly"]
},
{
"group": "Network",
"pages": [
"network/index",
"network/network-client",
"network/network-server",
"network/network-peer",
"network/packet-framing",
"network/network-client-api",
"network/network-server-api"
]
},
{
"group": "Graphics 3D",
"pages": ["graphics-3d/index", "graphics-3d/advanced", "graphics-3d/performance"]
},
{
"group": "Editor",
"pages": ["editor/protocol"]
},
{
"group": "Design notes",
"pages": [
"graphics-3d/editor-proposal",
{
"group": "3D graphics library benchmark",
"pages": [
"lib-graphic-3d/index",
"lib-graphic-3d/three-js",
"lib-graphic-3d/babylon-js",
"lib-graphic-3d/playcanvas",
"lib-graphic-3d/luma-gl",
"lib-graphic-3d/poc"
]
}
]
}
]
2 changes: 0 additions & 2 deletions docs/docs/network/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "Overview of the engine networking docs"
---

# Network Overview

This page describes the engine's networking libraries: `network-server` and `network-client`. Together they provide a small, pragmatic networking layer used by the example `pong-network` game. The same apps can also run without a game server, hosted by one of the players.

## Goals
Expand Down
4 changes: 1 addition & 3 deletions docs/docs/network/network-client-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,8 @@ icon: "book"
description: "API reference for the client networking package"
---

# network-client API

`NetworkClientLibrary` is exposed on `ctx.network`. Its methods take an optional
`{ channel }` to pick one of the four [channels](packet-framing):
`{ channel }` to pick one of the four [channels](./packet-framing):
`Channel.ReliableOrdered`, `Channel.ReliableUnordered`,
`Channel.UnreliableOrdered` or `Channel.UnreliableUnordered`.

Expand Down
8 changes: 3 additions & 5 deletions docs/docs/network/network-client.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@ icon: "book"
description: "How the client-side networking package works"
---

# Client Networking (network-client)

This document describes how the `network-client` package connects to a `network-server` instance and the concrete APIs used from client-side code.

## Overview

A client connects to a single server instance and sends every packet on one of
four [channels](packet-framing), picked with the `channel` option:
four [channels](./packet-framing), picked with the `channel` option:

- `Channel.ReliableOrdered` (the default) and `Channel.ReliableUnordered`,
carried by a TCP WebSocket, for control commands such as join, play, and input.
Expand Down Expand Up @@ -84,6 +82,6 @@ ctx.network.packets.send(Play); // no payload to give

## Notes

- See [Network Client API](network-client-api) for the full list of available functions,
- See [Network Client API](./network-client-api) for the full list of available functions,
and for how each kind of payload is encoded.
- For the channels and how packets are framed on each, see [Packet Channels](packet-framing).
- For the channels and how packets are framed on each, see [Packet Channels](./packet-framing).
2 changes: 0 additions & 2 deletions docs/docs/network/network-peer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "Run the same client and server apps without a game server: one player hosts"
---

# Peer-to-peer Networking

A game made of a client app and a server app can run **without a game server**.
The first player to open the game hosts it: their browser tab runs the server
app next to their client app. The other players join that tab over WebRTC, on
Expand Down
6 changes: 2 additions & 4 deletions docs/docs/network/network-server-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "API reference for the server networking package"
---

# network-server API

## ClientId

`string`: an opaque, random identifier (UUID) of a client session. A client
Expand All @@ -14,7 +12,7 @@ connected over both TCP and UDP has the same `ClientId` on both servers.
## Methods

`NetworkServerLibrary` is exposed on `ctx.network`. Its methods take an optional
`{ channel }` to pick one of the four [channels](packet-framing):
`{ channel }` to pick one of the four [channels](./packet-framing):
`Channel.ReliableOrdered`, `Channel.ReliableUnordered`,
`Channel.UnreliableOrdered` or `Channel.UnreliableUnordered`.

Expand Down Expand Up @@ -93,7 +91,7 @@ Returns: `ClientInfo | undefined` (`undefined` once the client is gone)
## packets (`ctx.network.packets`)

Typed packets, declared with `definePacket` (see the
[network-client API](network-client-api)). Packets of a type
[network-client API](./network-client-api)). Packets of a type
are routed to its listeners and to `read`, never to `getReceivedPackets`.

### on(packet, listener)
Expand Down
10 changes: 4 additions & 6 deletions docs/docs/network/network-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "How the server-side networking package works"
---

# Server Networking (network-server)

This document explains the `network-server` package implementation and the APIs used from server-side code.

## Overview
Expand All @@ -18,7 +16,7 @@ The server listens on configured ports and accepts client connections. A single
`Channel.UnreliableOrdered` and `Channel.UnreliableUnordered`, carried by WebRTC data
channels, for low-latency state updates.

See [Packet Channels](packet-framing) for what each channel guarantees.
See [Packet Channels](./packet-framing) for what each channel guarantees.

## Client identification

Expand Down Expand Up @@ -79,7 +77,7 @@ const decodedPackets = firstClientPackets.map((packet) => packet.json());
## Typed packets

The server uses the same packet types as the client, from the shared protocol
file (see [Typed packets](network-client#typed-packets)). Its listeners and
file (see [Typed packets](./network-client#typed-packets)). Its listeners and
`read` also get the sender.

```ts
Expand All @@ -103,5 +101,5 @@ the `validate` option of `definePacket`.

## Notes

- See [Network Server API](network-server-api) for the full list of available functions.
- For the channels and how packets are framed on each, see [Packet Channels](packet-framing).
- See [Network Server API](./network-server-api) for the full list of available functions.
- For the channels and how packets are framed on each, see [Packet Channels](./packet-framing).
4 changes: 1 addition & 3 deletions docs/docs/network/packet-framing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "The four delivery channels and how packets are framed on each"
---

# Packet Channels

Every packet is sent on one of four channels, picked with the `channel` option
of the network methods, for example
`ctx.network.sendData(data, { channel: Channel.UnreliableOrdered })`. Without
Expand Down Expand Up @@ -37,7 +35,7 @@ Every packet starts with the name of its packet type: one length byte, then the
name in UTF-8, then the payload.

- **Typed packets** (`ctx.network.packets.send`, see
[Typed packets](network-client#typed-packets)) carry the name given to
[Typed packets](./network-client#typed-packets)) carry the name given to
`definePacket`, and their payload is the `JSON.stringify` text of the data,
or nothing for a packet without payload.
The receiver routes them to the listeners and `read` of that type.
Expand Down
2 changes: 0 additions & 2 deletions docs/docs/registry/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "Registry and WebAssembly notes"
---

# Registry

The registry class is written in C++ and exposed to WebAssembly using Emscripten. That choice keeps the performance benefits of C++ for entity and component management while still making the code available to web applications.

## Design Choices
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ icon: "book"
description: "Guidance for WebAssembly modules"
---

# Writing Web Assembly

## Code Splitting

When writing WebAssembly modules, it is important to consider code splitting for readability and maintainability. We try to split binding and logic into separate files wherever possible. That keeps the codebase organized and makes it easier to navigate.
Expand Down
Loading
Loading