|
1 | | -# MavonEngine |
| 1 | +# MavonEngine — Three.js Game Engine for Browser Games |
2 | 2 |
|
3 | | -A TypeScript game engine with support for single and multiplayer games with an authoritative server. |
| 3 | +MavonEngine is an open-source Three.js game engine built for single player or real-time multiplayer. It combines |
| 4 | +rendering, physics, networking, animation, and debugging into a single cohesive TypeScript package |
| 5 | +— so you're not assembling a stack, you're building a game. |
4 | 6 |
|
5 | 7 | > **Early WIP** — things will change. For documentation visit [mavonengine.com](https://mavonengine.com). |
6 | 8 |
|
7 | | -## Getting started |
8 | | - |
| 9 | +## Get Started |
9 | 10 | ```bash |
10 | 11 | npx @mavonengine/create-bootstrap |
11 | 12 | ``` |
| 13 | + |
12 | 14 | | URL | Description | |
13 | | -|-----|-------------| |
| 15 | +| --- | --- | |
14 | 16 | | http://localhost:5173/ | Client Game | |
15 | 17 | | http://localhost:8050/api/game/health | Server health endpoint | |
16 | 18 |
|
17 | | -The multiplayer template includes the authoritative server setup, networking boilerplate, and a working client/server split out of the box. |
| 19 | +The multiplayer template includes the authoritative server setup, networking boilerplate, and a |
| 20 | +working client/server split out of the box. |
| 21 | + |
| 22 | +## What is MavonEngine? |
| 23 | + |
| 24 | +MavonEngine is a full-stack Three.js game engine built on top of [Three.js](https://threejs.org/) |
| 25 | +for rendering, [Rapier3D](https://rapier.rs/) for physics, and |
| 26 | +[geckos.io](https://github.com/geckosio/geckos.io) for WebRTC-based UDP networking. |
| 27 | + |
| 28 | +Most Three.js game engines focus on single-player or leave multiplayer as an exercise for the |
| 29 | +developer. MavonEngine is designed from the ground up for multiplayer — with a unified server-client |
| 30 | +architecture, authoritative physics, and real-time networking built in, not bolted on. |
| 31 | + |
| 32 | +## How It Works |
| 33 | + |
| 34 | +The core is a headless `BaseGame` class that both client and server extend from. The server runs |
| 35 | +physics and the game loop without rendering. The client extends it with Three.js rendering, camera, |
| 36 | +audio, and input. Because both sides share the same entity classes and loop, game logic is written |
| 37 | +once and shared — the authoritative server syncs state down to clients each tick. |
| 38 | + |
| 39 | +The server runs a simplified hitbox scene alongside the client's full 3D world, enabling |
| 40 | +server-side hit detection, raycasting, and spatial queries without trusting the client. This makes |
| 41 | +it viable for competitive PvP games, open-world multiplayer, and physics-based action games. |
18 | 42 |
|
19 | | -## What is this? |
| 43 | +## Networking |
20 | 44 |
|
21 | | -MavonEngine is a TypeScript game engine built on top of [Three.js](https://threejs.org/) for rendering, [Rapier3D](https://rapier.rs/) for physics, and [geckos.io](https://github.com/geckosio/geckos.io) for WebRTC-based UDP networking. It provides a set of abstractions for the things that come up repeatedly when building 3D games — entity management, state machines, world/chunk streaming, input handling, resource loading, and multiplayer networking. |
| 45 | +The networking model is inspired by Source engine architecture — a tick-based command buffer with |
| 46 | +server-authoritative state, distance-based entity culling, hash-based change detection, and |
| 47 | +bandwidth tracking. The client maintains a WebRTC connection via geckos.io with ping monitoring |
| 48 | +and state reconciliation. |
22 | 49 |
|
23 | | -## Core idea |
| 50 | +## Features |
24 | 51 |
|
25 | | -The central design is a headless `BaseGame` class that both the client and server extend from. The server runs the headless version (physics + game loop, no rendering), while the client extends it with Three.js rendering, camera, audio, and input. Because both sides share the same underlying loop and entity classes, game logic can be written once and shared, with the authoritative server syncing state down to clients each tick. |
| 52 | +- **Three.js rendering** — Custom GLSL shader support, wireframe/armature/physics debug overlays |
| 53 | +- **Rapier3D physics** — Kinematic character controller, collider management, real-time debug visualization |
| 54 | +- **WebRTC networking** — Real-time data channels, bandwidth monitoring, command buffering |
| 55 | +- **Shared entity system** — Write once, run on server and client |
| 56 | +- **Skeletal animation** — GLTF + Draco support, smooth fade transitions, efficient skeleton cloning |
| 57 | +- **Particle system** — Built-in rain and smoke effects, custom shader support |
| 58 | +- **Level editor** — Early WIP, loads directly from the running game instance |
| 59 | +- **Prefab registry** — Community-built assets (grass, water, and more) ready to drop into your scene |
| 60 | +- **Full TypeScript** — Comprehensive types throughout |
26 | 61 |
|
27 | | -## Multiplayer |
| 62 | +## Why a Three.js Game Engine with Multiplayer? |
28 | 63 |
|
29 | | -The networking model is inspired by Source engine networking — a tick-based command buffer queue with server-authoritative state, distance-based entity visibility, and bandwidth tracking. The client manages a WebRTC connection via geckos.io with ping monitoring and state reconciliation. |
| 64 | +Three.js is the most widely used 3D library for the web, but it's a rendering library — not a game |
| 65 | +engine. MavonEngine fills that gap specifically for single or multiplayer: entity management, state machines, |
| 66 | +world/chunk streaming, input handling, resource loading, and authoritative networking are all |
| 67 | +handled for you. |
30 | 68 |
|
31 | 69 | ## Contributing |
32 | 70 |
|
33 | | -This is early-stage software built out of real project needs. APIs will break and some parts are still tightly coupled to specific project setups. Contributions and PRs are welcome — see the [contributing guide](https://mavonengine.com/getting-started/contributing) to get started. |
| 71 | +This is early-stage software built out of real project needs. APIs will change and some parts are |
| 72 | +still tightly coupled to specific setups. Contributions and PRs are welcome — see the |
| 73 | +[contributing guide](https://mavonengine.com/getting-started/contributing) to get started. |
34 | 74 |
|
35 | | -Join the [community](https://mavonengine.com/community) for development discussions. |
| 75 | +Join the [community](https://mavonengine.com/community) for development discussions. |
0 commit comments