meep engine
Get a license
Documentation

Meep engine docs

Documentation is being built progressively. Topics marked draft are stubs. The fastest way to learn the engine remains reading the source — it's well organized and well tested.

Start here → Installation ECS overview

Getting started

  • Getting started A 10-minute tour of the Meep engine, from install to first running simulation.
  • Installation Install the engine and configure your bundler for development and production.

Physics

  • Physics overview Meep ships a rigid-body physics engine in the box — pure JavaScript, built for massive worlds, fully debuggable, and bit-exact across V8 runtimes.
  • Rigid bodies The RigidBody component — body kinds, mass and inertia, forces and impulses, damping, and sleeping.
  • Colliders & shapes The Collider component — collision shapes, surface materials, layer/mask filtering, sensors, contact events, and raycasts.
  • Spatial queries Ask the physics world questions without stepping it — raycasts, shape casts, and overlap tests against the live world.
  • Determinism The fixed-step contract that makes Meep's physics bit-exact across V8 runtimes — and what that buys you.
  • Joints Connecting bodies with the Joint constraint — ball-sockets, hinges, sliders, welds, and world anchors.
  • Constraints Per-DOF limits, springs, and motors on a Joint — end-stops, suspension, and powered axes.
  • Navigation meshes Build a walkable navigation mesh from scene geometry and query shortest paths between two world points.
  • Navigation agents Move an entity along a path using the Path, PathFollower, and PathFollowingSystem components.
  • Fluid simulation A volumetric incompressible-flow solver on a staggered grid, run through ECS — fluid volumes are components, effectors stir them, and gameplay reads the velocity field back out.

Reference

  • Architecture & philosophy The structural decisions that shape Meep — pure ECS, zero allocation, source-available, and code-first — and why each one was made.
  • FAQ Answers to common questions about Meep, licensing, and integration.

AI

  • AI & simulation tools Behavior trees, finite state machines, Monte-Carlo Tree Search, a resource-allocation planner, blackboards, and navmesh pathfinding — decision-making and planning primitives most JavaScript engines don't ship.

Animation

  • Animation graphs How Meep drives skeletal animation through state machines, cross-faded transitions, clip-level notifications, and per-clip blend weights.
  • Skeletons & skinning How Meep maps bones to a humanoid taxonomy, computes precomputed bounding volumes for skinned meshes, and optimizes animation keyframe tracks.
  • Inverse kinematics Meep provides three IK solvers — FABRIK for arbitrary chains, two-bone IK for limbs with a pole target, and one-bone surface alignment for foot placement on terrain.

Audio

  • Audio overview Meep's audio engine is event-driven — authorable sound events, a mixer bus tree, live parameters, and spatial 3D — and you use it through ECS, with one component and one system.
  • Audio events & mixing The authoring surface behind AudioEmitter — clip containers, the mixer bus tree with effects and sends, live parameters, snapshots, ducking, and deterministic playback.

ECS

  • ECS overview How Meep's Entity Component System differs from Unity, Bevy, and the rest — and why.
  • Entities How entities are identified, built and destroyed with the high-level Entity builder and the low-level EntityComponentDataset, and how EntityReference gives you handles that survive ID reuse.
  • Components How components are defined as plain classes, registered with a dataset, attached to and read from entities, and observed as they are added and removed.
  • Systems & scheduling How to write a System, declare component dependencies, use link/unlink for reactive per-entity setup, and how execution order is derived from access declarations.
  • Queries How to iterate over entities that match a component tuple using traverseEntities and traverseComponents, and what the performance characteristics of each are.
  • Hierarchy & attachment How parent-child entity relationships work, how TransformAttachment propagates transforms, and how EntityNode makes building scene-graph hierarchies ergonomic.
  • Scenes How a Scene wraps an EntityComponentDataset into an isolated world, and how SceneManager creates scenes and switches the active one.

Gameplay

  • First-person controller A kinematic-capsule first-person controller — mouse-look and movement, the procedural camera and locomotion feel on top, an opt-in movement-ability set, and read-only state for HUDs and AI.
  • Input devices Meep's unified input layer — keyboard and pointer devices, the InputController component, binding-path syntax, and locational interaction.
  • Control contexts State-machine wrappers that group ECS entities under a named state and activate or deactivate them as one unit when the state is entered or left.

Generation

  • Procedural generation How Meep's marker-and-rule model generates levels — GridData, layers, task pipeline, and where generation fits in the ECS.
  • Cell filters & automata The CellFilter algebra — composable per-cell scalar functions — plus cellular automata rules and distance fields over grid layers.
  • Themes, matchers & rules The theme and biome system, pattern matchers for grid cells and markers, predicate combinators, and weighted random placement.

Math & geometry

  • Math & geometry Vectors, matrices, quaternions, Catmull-Rom splines, simplex and curl noise, and robust geometric predicates in the engine's core math library.
  • Spatial acceleration The engine's memory-tight BVH — 40 bytes per node, SAH insertion, Morton-sorted bulk build, and a suite of ray/frustum/sphere intersection queries.
  • Color management OKLab and Okhsv perceptual color spaces, gamut mapping, color temperature, sRGB/linear conversions, YCbCr, and spectral color-matching functions.

Platform

  • Asset pipeline How Meep loads, caches, and transforms assets — the AssetManager API, built-in loaders, the transformer chain, and CORS configuration.
  • Plugins & options How to load and manage engine plugins at runtime, and how to define and persist hierarchical reactive options with auto-generated UI.
  • Saving & loading How Meep serializes ECS world state to binary, migrates saved data across format versions, and persists it to IndexedDB or an in-memory store.
  • Networking How Meep replicates game state across peers using deterministic action logs, server-authoritative reconciliation, and adaptive interpolation.
  • Game services Achievements, localization, notification queue, and analytics — the platform services Meep ships for tracking progress, translating text, surfacing messages, and recording events.
  • Diagnostics The built-in frame-time performance metrics, the console FPS overlay, and the pluggable logging system with console, void, and Elasticsearch backends.

Rendering

  • Rendering overview Meep builds a clustered Forward+ pipeline on top of Three.js, integrating lights and meshes through the ECS so scenes with many dynamic lights stay fast.
  • Lights & shadows The Light component supports directional, spot, point, and ambient types; LightSystem wires them into Three.js and the Forward+ cluster; shadows use variance shadow maps with frustum-fitted cameras.
  • Meshes & materials ShadedGeometry is the ECS component for a single draw call — a Three.js BufferGeometry + Material pair with flags for shadow participation and visibility, managed by ShadedGeometrySystem.
  • Effects Per-object rendering effects available in Meep — decals, outlines, ribbons/trails, camera shake, and Hi-Z occlusion culling.
  • Virtual texturing Sparse virtual texturing streams high-resolution texture tiles on demand using per-frame GPU feedback, keeping memory use proportional to what is visible.
  • Impostors & LOD Three impostor types — octahedral, card-cluster, and voxel — let distant or numerous objects render as pre-baked proxies at a fraction of the triangle cost.
  • Global illumination How Meep bakes and applies indirect lighting through SH3 light probes arranged in a tetrahedral volume.
  • Sky & environment Meep's physically-based Hosek-Wilkie analytic sky model, runtime cubemap-to-SH3 capture, and the pure-JS Monte-Carlo path tracer used for offline reference renders and probe baking.
  • Particles & VFX Particular, Meep's CPU particle system — emitter shapes, layered simulation steps, billboard rendering, automatic atlas packing, and soft particles — plus the node-based GLSL codegen system.

UI

  • UI toolkit Meep's built-in view/element system — a zero-garbage, DOM-backed UI layer with ECS integration and a panel of GUI controls bound to observed game state.
  • Widgets Ready-made UI widgets — radial menu, GML tooltip parser, currency display, segmented resource bars, radial progress, drag-and-drop, virtual list, modals, and toast notifications.
  • Minimap & previews The WebGL minimap — terrain layers, marker overlays, fog-of-war, and camera frustum — and the embedded MeshPreview and CanvasView widgets for inventory icons and inspectors.

World

  • Terrain Meep's tile-based heightfield terrain — worker-thread LOD mesh generation, unlimited splat-map layers, and a cling-to-terrain component that pins entities to the surface.
  • Water & overlays The Water component renders a depth-aware ocean plane with shore transitions and wave animation; TerrainOverlay paints per-tile RGBA on top of the terrain; and the Clouds subsystem adds procedural moving cloud shadows.