Matter.Render.create Options in Matter.js

This guide provides a comprehensive overview of the configuration options available in Matter.Render.create() within the Matter.js 2D physics engine. It covers the primary initialization parameters, canvas sizing, visual rendering properties, and built-in visual debugging flags to help you fully customize your physics simulations.

Core Configuration Properties

The Matter.Render.create(options) method initializes a canvas-based renderer for visualizing a physics engine. The options argument accepts the following top-level properties:

• engine: (Matter.Engine) The instance of Matter.Engine to bind to the renderer. This is required for the renderer to read physics bodies, constraints, and composite states.
• element: (HTMLElement) The DOM element into which the renderer injects the newly created <canvas> element. Defaults to document.body if omitted and no existing canvas is provided.
• canvas: (HTMLCanvasElement) A pre-existing canvas element to use for rendering. If provided, element is ignored, and Matter.js will not create a new canvas.
• bounds: (Matter.Bounds) An object defining the active viewport region (min: { x, y }, max: { x, y }). Used for scrolling, zooming, or panning when hasBounds is enabled.
• options: (Object) A nested configuration object defining the visual style, dimensions, and debugging features of the renderer.

Display and Canvas Options (options.options)

The following properties are set inside the nested options object to control the canvas dimension, rendering style, and behavior:

• width: (number) The width of the canvas in pixels. Default is 800.
• height: (number) The height of the canvas in pixels. Default is 600.
• pixelRatio: (number) The pixel ratio to accommodate high-DPI (Retina) displays. Default is 1. Set to window.devicePixelRatio for sharper rendering.
• background: (string) A CSS color string defining the canvas background when wireframe mode is disabled (e.g., '#ffffff' or 'transparent'). Default is '#14151f'.
• wireframeBackground: (string) A CSS color string defining the canvas background when wireframes are enabled. Default is '#14151f'.
• wireframes: (boolean) Toggles wireframe rendering. When set to true, bodies are drawn as simple colored outlines ignoring custom body render fills. Set to false to render solid colors, textures, and sprites. Default is true.
• enabled: (boolean) Specifies whether the renderer is actively rendering frames. Default is true.
• hasBounds: (boolean) Enables the use of the render.bounds property to act as a camera viewport for panning and zooming. Default is false.

Visual Debugging Options (options.options)

Matter.js includes a wide range of visual diagnostics that can be toggled on to inspect the physics world during runtime:

• showDebug: (boolean) Master flag to toggle general debug information overlays.
• showVelocity: (boolean) Renders directional vectors showing the current linear velocity of bodies. Default is false.
• showAngle: (boolean) Renders an indicator line on bodies showing their current rotation angle. Default is false.
• showAxes: (boolean) Displays the internal axes of bodies used for collision detection. Default is false.
• showCollisions: (boolean) Renders collision contact points and normal indicators. Default is false.
• showSeparations: (boolean) Displays separation vectors calculated during collision resolution. Default is false.
• showBroadphase: (boolean) Displays the broadphase collision detection grid or pairs. Default is false.
• showBounds: (boolean) Displays the axis-aligned bounding box (AABB) enclosing each body. Default is false.
• showSleeping: (boolean) Visualizes whether bodies are in a "sleeping" state by changing their opacity or color. Default is true.
• showPositions: (boolean) Displays markers at the precise position coordinates of each body. Default is false.
• showIds: (boolean) Renders the unique numeric ID of each body above its center. Default is false.
• showVertexNumbers: (boolean) Draws the index numbers of vertices forming each body's polygon. Default is false.
• showConvexHulls: (boolean) Renders the convex hull boundaries of compound bodies. Default is false.
• showInternalEdges: (boolean) Visualizes internal edges for bodies generated from concave polygon decompositions. Default is false.

Implementation Example

const render = Matter.Render.create({
  element: document.getElementById('canvas-container'),
  engine: engine,
  options: {
    width: 1024,
    height: 768,
    pixelRatio: window.devicePixelRatio,
    wireframes: false,
    background: '#f4f4f4',
    showVelocity: true,
    showCollisions: true,
    showAngle: false
  }
});

Matter.Render.run(render);