meep engine
Get a license
Documentation

Meep engine docs

63 pages covering Meep 3: the ECS, the physics, and Shade, the engine's WebGPU renderer. Start with the ten-minute tour, or with the migration guide if you have a Meep 2 project to port. The source stays the final authority on any detail - it's well organized and well tested.

Start here → Installation ECS overview Migrating from 2.x

Getting started

  • Getting started A 10-minute tour of the Meep engine, from install to a lit cube rendering on WebGPU.
  • Installation Install the engine, meet the WebGPU device floor, and configure your bundler for development and production.

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 The two hierarchies meep keeps - ParentEntity for lifetime, TransformAttachment for space - how their systems index and compose them, and how to find a named node on a loaded model.
  • Scenes How a Scene wraps an EntityComponentDataset into an isolated world, and how SceneManager creates scenes and switches the active one.

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.

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 InputMap bindings, InputController gestures, and keyboard, pointer, gamepad and WebXR devices.
  • 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.

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 notifications and per-clip blend weights - with the clock on the CPU and the deformation on the GPU.
  • Skeletons & skinning How Shade deforms skinned meshes on the GPU - skins, clips and channels as plain CPU data, registered with GPUAnimationManager and spawned per entity from a compiled prefab.
  • Inverse kinematics Entity-target IK goals with joint limits, FABRIK chains, and two-joint limb solvers.

Generation

  • Procedural generation How Meep's marker-and-rule model generates levels - GridData, layers, the task pipeline, generation resources, 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.

World

  • Terrain Tile-based heightfield terrain under Shade - meshlet tile entities with splat materials, streamed into the scene, and a cling-to-terrain component that pins entities to the surface.
  • Water & overlays Author meshlet water surfaces with physical optical media and GPU waves; TerrainOverlay paints per-cell RGBA over the ground.

Rendering

  • Rendering overview Shade is meep's renderer - GPU-driven, visibility-buffer deferred and WebGPU only - and this page maps what that means for game code, how the ECS binds to it, and what a frame contains.
  • Meshes & materials Shade's geometry, material and texture types, the meshlet build that turns one into the other, and the ShadedGeometry component that gives a single primitive a row in the scene.
  • Lights & shadows The Light component, LightSystem, and Shade's photometric light model - candela and lux intensity, GPU froxel clustering, cascaded and atlased shadow maps, and ReSTIR DI.
  • Sky & environment Shade has no skybox - one octahedral environment texture lights the scene and paints the background. Covers the three ways to supply it, the Hosek CPU sky recipe, volumetric fog, and the two path tracers.
  • Global illumination Shade's indirect lighting - the IBL default, the Brick4 sparse volumetric lightmap and its bake, and the VolumetricLightMap component that carries one.
  • Effects Decals, outlines and highlights, camera shake, and the dynamic-mesh path for content whose vertices change every frame.
  • Particles & VFX Author GPU particle simulations with ParticleEffect, explicit state layouts and INIT/UPDATE node graphs.
  • Trails Trail3D - the ECS component that lays a fading world-space tube behind a moving entity, extruded on the CPU and drawn on Shade's dynamic-mesh path.
  • Virtual texturing Shade streams texture pages on demand - opt a material into a VirtualTextureStack and GPU texture memory is bounded by what is on screen instead of by what is loaded.
  • Picking PickingSystem answers "what is drawn under this pixel" for entities marked Pickable - an asynchronous, batched read of the GPU's visibility buffer.
  • Render extensions How an application records its own work into Shade's frame - the six FramePhase injection points, RenderExtension, the typed frame records, declared ordering, and registration through the graphics engine.
  • Frame settings & post-processing Every renderer.feature_* switch with its verified default, the resolution and upscaler controls, the post-process sub-objects, and what ships in the tree without being wired into the frame.

Audio

  • Audio overview Meep's audio is event-driven and ECS-native - an AudioEmitter sounds because it linked, an AudioEventTrigger sounds because the entity received an event, and one shared renderer plays both.
  • Audio events & mixing The authoring surface behind AudioEmitter - clip containers, the mixer bus tree with effects and sends, live parameters, snapshots, ducking, deterministic playback, and converting legacy sound data.

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 Canvas2D minimap - focus area, terrain, markers and fog of war drawn with 2D canvas calls - plus make_model_thumbnail for offscreen model pictures and the CanvasView primitive.

Platform

  • Asset pipeline How Meep loads, caches, and transforms assets - the AssetManager API, the built-in loaders, the transformer chain, and turning a loaded glTF into entities.
  • 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 Fixed-step networking with server-authoritative state, component corrections, action logs, adaptive interpolation, six transport adapters and token-authenticated reconnection.
  • 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, the pluggable logging system, and the device-failure signals that tell you when there is no GPU left to render on.
  • GPU profiling Recording Shade's GPU work to a .sgpt capture - the GPUProfileSession API, the four detail levels and what they cost, reading a capture back, and the lower-level GPUTimer family.
  • Image codecs Meep's pure-JavaScript AVIF encoder and decoder, the threaded encode pool, and the codec chain - PNG in a worker, the browser's decoder, then the in-tree JPEG and AVIF decoders - behind the asset loaders.
  • Testing without a GPU SoftwareGPUDevice - a validating software WebGPU device that lets renderer code be constructed, driven and asserted on under node, with no adapter and no shader execution.

Math & geometry

  • Math & geometry Vectors, matrices, quaternions, ray primitives, mesh topology, splines, 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 The encoded-sRGB vs linear contract, OKLab/Okhsl/Okhsv and gamut clipping, CIELab and YCxCz, PQ, color temperature, and spectral color-matching functions.

Reference

  • Architecture & philosophy The structural decisions that shape Meep - pure ECS, zero allocation, source-available, and code-first - and why each one was made.
  • Migrating from 2.x to 3.x What broke between Meep 2 and Meep 3 - the Shade renderer, WebGPU-only, no three.js - with the full import map, the new constructor shapes, and a worked port of a real demo.
  • FAQ Answers to common questions about Meep, licensing, and integration.