# Introduction MavonEngine is a Three.js game engine built on top of [Three.js](https://threejs.org/){rel=""nofollow""} and [Rapier3D](https://rapier.rs/){rel=""nofollow""}, designed to abstract away the common boilerplate needed when bootstrapping 3D browser games — both single-player and multiplayer. The underlying goal is to write logic once and then have it run on both the server & client identically with the needed updates / state synchronization happening when needed. ## What it provides ::card-group :::card --- icon: i-lucide-layers title: Entity System to: https://mavonengine.com/core-concepts/entity-system --- A hierarchical entity architecture for structuring all game objects. ::: :::card --- icon: i-lucide-git-branch title: State Machine to: https://mavonengine.com/core-concepts/state-machine --- A pushdown automaton pattern for managing complex entity behaviors. ::: :::card --- icon: i-lucide-globe title: Networking to: https://mavonengine.com/networking --- Authoritative multiplayer server with WebRTC and tick-based state sync. ::: :::card{icon="i-lucide-atom" title="Physics (Docs Coming soon)"} Rapier3D physics with character controller and debug visualization. ::: :::card{icon="i-lucide-earth" title="Editor (Docs Coming soon)"} Fully fledged level editor for your creations. ::: :: ## Design philosophy The engine tries to abstract away common elements while remaining flexible. Some areas may be opinionated (e.g. audio listener is attached to the camera). If you find these and want to open them up further, pull requests are welcome. Please read [Contributing](https://mavonengine.com/getting-started/contributing) for more ## Core libraries - **[Three.js](https://threejs.org/){rel=""nofollow""}** — Client rendering and scene management - **[Rapier3D](https://rapier.rs/){rel=""nofollow""}** — Server and client-side physics simulation - **[geckos.io](https://github.com/geckosio/geckos.io){rel=""nofollow""}** — UDP via WebRTC for real-time multiplayer # Installation ## Scaffolding Use the `create` command to scaffold a new MavonEngine project. Two templates are available depending on whether you need single-player or multiplayer support. ### Single-player ```bash coming soon ``` ### Multiplayer ```bash npx @mavonengine/create-bootstrap ``` The multiplayer template includes the authoritative server setup, networking boilerplate, and a working client/server split out of the box. # Quick Start ## Single-player setup The minimum setup for a single-player Three.js game requires a `Game` instance. ```typescript import { Game } from '@mavonengine/core' const game = new Game() ``` `Game` is a singleton. Call `Game.instance()` to get the instance. It automatically: - Creates a `` and appends it to the document - Sets up the WebGL renderer, perspective camera, and audio listener - Starts the render loop via `requestAnimationFrame` - Initializes physics (Rapier3D) and the input manager ## Multiplayer setup For multiplayer, the server runs `BaseGame` headlessly and clients run `Game`. See the [Networking](https://mavonengine.com/networking) section for the full setup. ## Development mode Append `#debug` to your URL to enable the debug panel (Tweakpane). In dev mode, the engine also activates the in-editor overlay. ```text http://localhost:3000/#debug ``` ## Next steps - Learn about the [Entity System](https://mavonengine.com/core-concepts/entity-system) to create game objects - Set up [Resource Loading](https://mavonengine.com/resources) to load models and textures - Explore [Networking](https://mavonengine.com/networking) to add multiplayer support # Contributing Contributions are very welcome! To avoid disappointments and ensure effort is well spent, please **[open a discussion](https://mavonengine.com/community) first** before starting work on a new feature or a significant change. Discussing your idea upfront lets us align on scope, design, and whether it fits the project's direction — saving you from investing time in something that may not be merged. ## How to contribute 1. **Open a discussion** in the [community forum](https://mavonengine.com/community), describing what you want to build or change and why. 2. Wait for feedback and a green light from the maintainers. 3. Fork the repository, implement your changes, and open a pull request referencing the discussion. Bug fixes and minor improvements (typos, docs, small corrections) can be submitted directly as a pull request without prior discussion. # AI Useage & Other References I'd say 20% of this code was generated by AI. Sometimes because I was genuinly stuck and just needed to get something working. Other times because the result was close enough to what I would have done anyway. However I am trying to actually get some learning done with this project and not just vibe my way to a result. I would appreciate it if you treated it the same. These docs were initially generated by Claude 4.6. I simply would not have been able to get it all written without taking a year. Please open a pull request if you find stuff that is completely off. I will dig through them section by section to update them. If you are using AI to help you build out a feature please commit with the model as co author in the commit message. For example: ```bash [Terminal] Co-authored-by: Claude Sonnet 4.6 ``` ## References This project is basically a combination of a alot of different resources. Some of the main ones being: - {rel=""nofollow""} - An absolutely great resource for all kinds of networking related content. - {rel=""nofollow""} - This is basically where the `sv_` and `cl_` commands structure came from along with the tickrate setup and command buffer queue. - {rel=""nofollow""} - Great book. Highly recommended. The state machine and event observers are basically taken 1 to 1 from this. - {rel=""nofollow""} - Amazing resource for threejs. Some of the code for example in the render setup class etc. is literally taken from the lessons. Some other great resources I kept jumping back to: - {rel=""nofollow""} - {rel=""nofollow""} Some of the core libraries that this builds on top of: - {rel=""nofollow""} for server & client side physics. - {rel=""nofollow""} UDP using WebRTC for all the realtime data transfer - {rel=""nofollow""} for the client rendering side and the scene is also held on the headless server instance.