melonJS
    Preparing search index...

    Class Mesh

    A renderable object for displaying textured triangle meshes. Supports loading from Wavefront OBJ models (via loader.preload with type "obj") or from raw geometry data (vertices, uvs, indices). Includes a built-in perspective projection and supports 3D transforms through the standard Renderable API (rotate, scale, translate). Works on both WebGL (hardware depth testing) and Canvas (painter's algorithm) renderers.

    Pivot — transforms are applied about the mesh's local origin (0, 0, 0), NOT a normalized anchor point. Unlike a Sprite (whose Renderable#anchorPoint recenters a width×height box), a mesh has real vertex coordinates, so rotation and scale pivot around the model origin the geometry is authored against — the standard convention for 3D meshes. Place the origin where you want the pivot at authoring time (or nest the mesh under a transformed parent to pivot elsewhere). Consequently, on the Camera3d world-space path the mesh opts out of the anchor offset entirely (see Renderable#applyAnchorTransform); the legacy 2D path still honors anchorPoint for backward compatibility.

    Hierarchy (View Summary)

    Index

    Constructors

    • Parameters

      • x: number

        the x screen position of the mesh object

      • y: number

        the y screen position of the mesh object

      • settings: {
            cullBackFaces?: boolean;
            height?: number;
            indices?: number[] | Uint16Array<ArrayBufferLike>;
            material?: string;
            model?: string;
            normalize?: boolean;
            rightHanded?: boolean;
            scale?: number;
            texture?: string | HTMLImageElement | TextureAtlas;
            textureRepeat?: string;
            uvs?: number[] | Float32Array<ArrayBufferLike>;
            vertices?: number[] | Float32Array<ArrayBufferLike>;
            width: number;
        }

        Configuration parameters for the Mesh object

        • OptionalcullBackFaces?: boolean

          enable backface culling

        • Optionalheight?: number

          display height in pixels (normalized models only; ignored when normalize: false)

        • Optionalindices?: number[] | Uint16Array<ArrayBufferLike>

          triangle vertex indices (alternative to settings.model)

        • Optionalmaterial?: string

          name of a preloaded MTL material (via loader.preload with type "mtl"). When provided, the diffuse texture (map_Kd), tint color (Kd), and opacity (d) are automatically applied.

        • Optionalmodel?: string

          name of a preloaded OBJ model (via loader.preload with type "obj")

        • Optionalnormalize?: boolean

          fit the source geometry into a [-0.5, 0.5] unit cube before scaling, so width/height behave like a Sprite. Set false to keep the geometry's real-world coordinates — required when several meshes share one coordinate space (e.g. nodes of an imported glTF scene) so their relative scale and layout are preserved.

        • OptionalrightHanded?: boolean

          treat the source as right-handed (Y-up, e.g. glTF) under the Camera3d world path. The default Y-up→Y-down bridge negates Y only (a reflection, which mirrors the scene left/right); true negates Y and Z (a rotation) so chirality is preserved and the result matches the authoring tool. See Mesh#rightHanded.

        • Optionalscale?: number

          world-space scale (pixels per source unit) for the Camera3d path; defaults to width. Set this when width/height describe the renderable's world bounds (frustum culling) rather than the geometry scale — see Mesh#meshScale.

        • Optionaltexture?: string | HTMLImageElement | TextureAtlas

          the texture to apply (image name, HTMLImageElement, or TextureAtlas). If omitted and settings.material is provided, the texture is resolved from the MTL material's map_Kd.

        • OptionaltextureRepeat?: string

          texture wrap mode ("repeat" / "repeat-x" / "repeat-y" / "no-repeat") applied to the resolved texture. Use "repeat" when the geometry's UVs fall outside the [0, 1] range and rely on the texture tiling (e.g. glTF assets, whose default sampler wrap is REPEAT) — otherwise the texture clamps to its edge texels and looks flat. Ignored for the white-pixel fallback. Note: REPEAT on a non-power-of-two texture requires WebGL 2.

        • Optionaluvs?: number[] | Float32Array<ArrayBufferLike>

          texture coordinates as u,v pairs (alternative to settings.model)

        • Optionalvertices?: number[] | Float32Array<ArrayBufferLike>

          vertex positions as x,y,z triplets (alternative to settings.model)

        • width: number

          display width in pixels. With normalization on (the default) the model is scaled to fit this size; with normalize: false this is the uniform pixels-per-unit scale applied to the raw geometry.

      Returns Mesh

      // create from OBJ + MTL (texture auto-resolved from material)
      let mesh = new me.Mesh(0, 0, {
      model: "fox",
      material: "fox",
      width: 200,
      height: 200,
      });

      // create from OBJ with explicit texture (no MTL needed)
      let mesh = new me.Mesh(0, 0, {
      model: "cube",
      texture: "cube_texture",
      width: 200,
      height: 200,
      });

      // create from raw geometry that already carries its own world scale
      // (e.g. a glTF scene node) — keep real coordinates, no mirror
      let node = new me.Mesh(0, 0, {
      vertices: positions, // Float32Array of x,y,z triplets
      uvs: texcoords, // Float32Array of u,v pairs
      indices: tris, // Uint16Array of triangle indices
      texture: baseColorImage,
      width: 32, // pixels per unit
      normalize: false,
      rightHanded: true,
      });

      // 3D rotation using the standard rotate() API
      mesh.rotate(Math.PI / 4, new me.Vector3d(0, 1, 0)); // rotate around Y axis

      // 2D rotation (Z axis, same as Sprite)
      mesh.rotate(Math.PI / 4);

    Properties

    _indicesOriginal: number[]
    _indicesReversed: any
    _useWorldSpace: boolean | undefined
    _worldSpace: boolean | undefined
    alpha: number

    Define the renderable opacity
    Set to zero if you do not wish an object to be drawn

    • Renderable#setOpacity
    • Renderable#getOpacity
    1.0
    
    alwaysUpdate: boolean

    Whether the renderable object will always update, even when outside of the viewport

    false
    
    ancestor: Container | Entity

    a reference to the parent object that contains this renderable

    undefined
    
    anchorPoint: ObservablePoint

    The anchor point is used for attachment behavior, and/or when applying transformations.
    The coordinate system places the origin at the top left corner of the frame (0, 0) and (1, 1) means the bottom-right corner

    a Renderable's anchor point defaults to (0.5,0.5), which corresponds to the center position.

    Note: Object created through Tiled will have their anchorPoint set to (0, 0) to match Tiled Level editor implementation. To specify a value through Tiled, use a json expression like json:{"x":0.5,"y":0.5}.

    <0.5,0.5>
    
    applyAnchorTransform: boolean

    Whether Renderable#preDraw applies the Renderable#anchorPoint offset to the renderer transform.

    When true (the default), the renderable is shifted by -anchorPoint × (width, height) so its anchor — not its top-left corner — aligns with its position. Correct for sprites and other 2D renderables.

    Set to false for a renderable that emits its own final world coordinates and takes its origin from geometry rather than a bounds box — e.g. a Mesh on the Camera3d world-space path (a 3D mesh is positioned by its transform and has no anchor). The WebGL mesh batcher reuses this same renderer transform as its view matrix, so applying the normalized anchor there would shift every mesh by half its OWN bounds box; because scene meshes size that box per node, props and the platforms they rest on would drift apart and overlap.

    true
    

    Mesh#preDraw

    autoTransform: boolean

    When enabled, an object container will automatically apply any defined transformation before calling the child draw method.

    true
    
    // enable "automatic" transformation when the object is activated
    onActivateEvent: function () {
    // reset the transformation matrix
    this.currentTransform.identity();
    // ensure the anchor point is the renderable center
    this.anchorPoint.set(0.5, 0.5);
    // enable auto transform
    this.autoTransform = true;
    ....
    }
    blendMode: string

    the blend mode to be applied to this renderable (see renderer setBlendMode for available blend mode)

    "normal"
    
    • CanvasRenderer#setBlendMode
    • WebGLRenderer#setBlendMode
    body: PhysicsBody

    the renderable physics body — the handle returned by the active PhysicsAdapter's addBody (or constructed imperatively via new Body(...)). Typed as the portable PhysicsBody interface; cast to the adapter-specific concrete type (MatterAdapter.Body, BuiltinAdapter.Body, or the legacy Body class) to reach native fields.

    // define a new Player Class
    class PlayerEntity extends me.Sprite {
    // constructor
    constructor(x, y, settings) {
    // call the parent constructor
    super(x, y , settings);

    // define a basic walking animation
    this.addAnimation("walk", [...]);
    // define a standing animation (using the first frame)
    this.addAnimation("stand", [...]);
    // set the standing animation as default
    this.setCurrentAnimation("stand");

    // add a physic body
    this.body = new me.Body(this);
    // add a default collision shape
    this.body.addShape(new me.Rect(0, 0, this.width, this.height));
    // configure max speed, friction, and initial force to be applied
    this.body.setMaxVelocity(3, 15);
    this.body.setFriction(0.4, 0);
    this.body.force.set(3, 0);
    this.isKinematic = false;

    // set the display to follow our position on both axis
    app.viewport.follow(this.pos, app.viewport.AXIS.BOTH);
    }

    ...

    }
    bodyDef: object | undefined

    Declarative body definition consumed by the active PhysicsAdapter when this renderable is added to a container. Adapter API only — leave undefined if you build a body imperatively via this.body = new Body(...).

    When set, the parent container forwards it to world.adapter.addBody(this, this.bodyDef), which constructs the underlying physics body (matter, builtin SAT, …) and assigns the engine-portable wrapper to this.body. This is the engine-portable path: the same bodyDef produces an equivalent body under any adapter.

    Typical fields: type ("static"/"dynamic"/"kinematic"), shapes, collisionType, collisionMask, restitution, frictionAir, density, gravityScale, isSensor, maxVelocity, fixedRotation. See BodyDefinition.

    undefined
    
    cullBackFaces: boolean

    whether to cull back-facing triangles

    true
    
    currentTransform: Matrix3d

    the renderable transformation matrix (4x4). For standard 2D use, only the 2D components are used (rotate around Z, scale X/Y, translate X/Y). For 3D use (e.g. Mesh), the full 4x4 matrix supports rotation around any axis, 3D translation, and perspective projection. Use the rotate(), scale(), and translate() methods rather than modifying this directly.

    edges: Vector2d[]

    The edges here are the direction of the nth edge of the polygon, relative to the nth point. If you want to draw a given edge from the edge value, you must first translate to the position of the starting point.

    floating: boolean

    If true, this renderable will be rendered using screen coordinates, as opposed to world coordinates. Use this, for example, to define UI elements.

    false
    
    groups: {
        count: number;
        materialName: string | null;
        opacity: number;
        start: number;
        tint: Color;
    }[]

    Per-material submesh groups, populated when the OBJ contains multiple usemtl directives AND a matching MTL is bound via the material setting. Each entry slices the shared indices buffer; field shape (start, count, materialName) matches the glTF "groups" convention.

    Under the per-vertex color baking path (tier 2), the tint / opacity fields here are informational — the actual rendered color is baked into vertexColors at construction time. Mutating groups[i].tint after construction has no visible effect; use mesh.tint for runtime color multiplication, or rebuild the Mesh with new material settings.

    GUID: string

    (G)ame (U)nique (Id)entifier"
    a GUID will be allocated for any renderable object added
    to an object container (including the app.world container)

    indices: number[]

    a list of indices for all vertices composing this polygon

    isDirty: boolean

    when true the renderable will be redrawn during the next update cycle

    true
    
    isKinematic: boolean

    If true then physic collision and input events will not impact this renderable

    true
    
    isPersistent: boolean

    make the renderable object persistent over level changes

    false
    
    lit: boolean

    Whether this mesh is lit by the active stage's Light3d lights. When true it renders through the lit mesh batcher (diffuse shading from the scene's lights, using Mesh#originalNormals); when false (the default) it uses the lean unlit path and pays no lighting cost. The glTF loader sets this on scene meshes when the scene has lights. Only meaningful under a Camera3d + WebGL.

    false
    

    A mask limits rendering elements to the shape and position of the given mask object. So, if the renderable is larger than the mask, only the intersecting part of the renderable will be visible.

    undefined
    
    // apply a mask in the shape of a Star
    myNPCSprite.mask = new me.Polygon(myNPCSprite.width / 2, 0, [
    // draw a star
    {x: 0, y: 0},
    {x: 14, y: 30},
    {x: 47, y: 35},
    {x: 23, y: 57},
    {x: 44, y: 90},
    {x: 0, y: 62},
    {x: -44, y: 90},
    {x: -23, y: 57},
    {x: -47, y: 35},
    {x: -14, y: 30}
    ]);
    meshScale: number

    Uniform world-space scale (pixels per source unit) applied along the Camera3d world path. Defaults to width. Scene loaders (e.g. glTF) set this independently of width / height so those can describe the renderable's world-space bounds (used for frustum culling) while the geometry is still scaled by this factor — width alone can't serve both roles for a non-normalized scene mesh.

    settings.width
    
    name: string

    The name of the renderable

    ""
    
    onVisibilityChange: Function

    an event handler that is called when the renderable leave or enter a camera viewport

    undefined
    
    this.onVisibilityChange = function(inViewport) {
    if (inViewport === true) {
    console.log("object has entered the in a camera viewport!");
    }
    };
    originalNormals: Float32Array<ArrayBufferLike> | undefined

    the source per-vertex normals (x,y,z triplets), or undefined if the mesh was built without them. Supplied by the glTF loader; used for lit shading under a Camera3d (see Light3d).

    originalVertices: Float32Array<ArrayBufferLike>

    the original (untransformed) vertex positions as x,y,z triplets

    points: Vector2d[]

    Array of points defining the Polygon
    Note: If you manually change points, you must call recalcafterwards so that the changes get applied correctly.

    origin point of the Polygon

    postEffects: any[]

    the list of post-processing shader effects applied to this renderable (WebGL only). Effects are applied in order. Use addPostEffect, getPostEffect, and removePostEffect to manage effects, or assign directly. In Canvas mode, this property is ignored.

    []
    
    // add effects via helper methods
    mySprite.addPostEffect(new DesaturateEffect(renderer));
    mySprite.addPostEffect(new VignetteEffect(renderer));
    // assign directly
    mySprite.postEffects = [new SepiaEffect(renderer), new VignetteEffect(renderer)];
    projectionMatrix: Matrix3d

    Projection matrix applied automatically before the model transform in draw(). Defaults to a perspective projection (45° FOV, camera at z=-2.5) suitable for viewing unit-cube-sized geometry. Set to identity for orthographic (flat) projection. Most users don't need to modify this — the default works for standard OBJ models.

    rightHanded: boolean

    Treat the source geometry as right-handed (Y-up, e.g. glTF) under the Camera3d world path. The default (false) Y-up→Y-down bridge negates Y only — a reflection, which mirrors the scene left/right. When true, the bridge negates Y and Z (a 180° rotation about X, determinant +1) so chirality is preserved and the result matches the authoring tool (no mirror); triangle winding is left untouched since a rotation doesn't invert it.

    false
    
    texture: any
    type: string = "Rectangle"

    The shape type (used internally).

    updateWhenPaused: boolean

    Whether to update this object when the game is paused.

    false
    
    uvs: Float32Array<ArrayBufferLike>

    texture coordinates as u,v pairs

    vertexColors: Uint32Array<ArrayBufferLike>

    Per-vertex color buffer (one packed Uint32 per vertex) populated for multi-material meshes. The mesh batcher reads from this when present, pushing the per-vertex color as the aColor attribute — so multi-material rendering needs no extra draw calls per material vs single-material rendering (the batcher still chunks very large meshes across multiple draws to fit its vertex/index buffer limits, same as the single-material path). Multiplied at render time by the global mesh.tint, so runtime tint mutation still works as expected (flash, fade, team color, etc.).

    Vertices were split per-material at parse time (each material has its own dedup scope in the OBJ parser), so every vertex belongs to exactly one material group and carries that group's color unambiguously.

    vertexCount: number

    number of vertices

    vertices: Float32Array<ArrayBufferLike>

    the projected vertex positions, updated each draw call

    visibleInAllCameras: boolean

    If true, this floating renderable will be rendered by all cameras (e.g. background image layers). If false (default), floating elements are only rendered by the default camera (e.g. UI/HUD elements). Only applies to floating renderables in multi-camera setups.

    false
    

    Accessors

    • get isFloating(): boolean

      Whether the renderable object is floating (i.e. used screen coordinates), or contained in a floating parent container

      Returns boolean

      Renderable#floating

    • get tint(): Color

      define a tint for this renderable. a (255, 255, 255) r, g, b value will remove the tint effect.

      Returns Color

      (255, 255, 255)
      
      // add a red tint to this renderable
      this.tint.setColor(255, 128, 128);
      // remove the tint
      this.tint.setColor(255, 255, 255);
    • set tint(value: Color): void

      Parameters

      • value: Color

      Returns void

    Methods

    • Returns true if the polygon contains the given point.
      (Note: it is highly recommended to first do a hit test on the corresponding
      bounding rect, as the function can be highly consuming with complex shapes)

      Parameters

      • x: number

        x coordinate or a vector point to check

      • y: number

        y coordinate

      Returns boolean

      True if the polygon contain the point, otherwise false

      if (polygon.contains(10, 10)) {
      // do something
      }
      // or
      if (polygon.contains(myVector2d)) {
      // do something
      }
    • Returns true if the polygon contains the given point.
      (Note: it is highly recommended to first do a hit test on the corresponding
      bounding rect, as the function can be highly consuming with complex shapes)

      Parameters

      Returns boolean

      True if the polygon contain the point, otherwise false

      if (polygon.contains(10, 10)) {
      // do something
      }
      // or
      if (polygon.contains(myVector2d)) {
      // do something
      }
    • Draw the mesh (automatically called by melonJS). Picks between two projection paths based on the camera that was active when this mesh was added to the world (captured in Mesh#onActivateEvent):

      • Camera3d → world-space output via Mesh#_projectVerticesWorld. Vertices land in world coordinates at (pos.x, pos.y, depth); the camera's perspective handles the final projection per-frame on the GPU. Triangle winding is reversed once at first draw so back-face culling stays correct under the Y-flip.
      • Camera2d (or no camera) → legacy self-projection via Mesh#projectionMatrix × Renderable#currentTransform, emitting vertices in pixel-ish space directly. Backwards-compatible with single-mesh-in-a-2D-scene usage.

      Multi-material meshes need no extra drawMesh calls per material vs single-material — each material's diffuse color is baked into vertexColors at construction time and pushed through the renderer's per-vertex aColor (WebGL) or per-triangle solid-fill (Canvas) path. The WebGL batcher may still chunk very large meshes across multiple drawElements calls to fit its vertex/index buffer limits.

      The active path is picked from the viewport passed in by Container.draw, NOT from the activation-time _useWorldSpace flag. The flag is kept as a fallback only for callers that invoke draw(renderer) without a viewport (tests, batched builds). Without the per-draw read, a stage with multiple cameras (Camera3d main + Camera2d minimap, say) would run the wrong projection on whichever camera didn't match activation.

      Parameters

      Returns void

    • return the renderable absolute position in the game world. The returned vector is a Vector3d so the z component is summed across the ancestor chain too — important for Camera3d's frustum culling, which previously read obj.depth (local pos.z) and mis-culled children nested under a container with its own non-zero depth.

      Returns Vector3d

    • The mesh's world-space 3D axis-aligned bounding box, as projected by the most recent draw. This is the 3D analog of Renderable#getBounds (which returns a flat 2D box from width/height and so cannot describe a mesh's real extent).

      Under a Camera3d the mesh projects its vertices into world space every frame (see Mesh#_projectVerticesWorld), so the returned box tracks the live transform / animation. Under the 2D path the projected vertices are screen-space, so the box is only meaningful after a Camera3d draw — use Renderable#getBounds for the 2D case.

      The same AABB3d instance is returned each call (recomputed in place), so copy it (.clone()) if you need to keep it.

      Returns AABB3d

      the world-space bounding box (reused instance)

    • Get post-processing shader effects. When called with a class, returns the first effect matching the given class. When called without arguments, returns the full effects array.

      Parameters

      • OptionaleffectClass: Function

        the effect class to search for

      Returns any

      the matching effect, the effects array, or undefined

      const desat = sprite.getPostEffect(DesaturateEffect);
      const allEffects = sprite.getPostEffect();
    • Returns true if the vertices composing this polygon form a convex shape (vertices must be in clockwise order).

      Returns boolean | null

      true if the vertices are convex, false if not, null if not computable

    • Legacy collision callback — fires every frame this renderable body is overlapping another body. Kept for backward compatibility with code written against pre-19.5 melonJS; semantics are unchanged from the 19.4 contract.

      NOTE — onCollision is NOT equivalent to Renderable.onCollisionActive. The two handlers exist side by side and have intentionally different contracts:

      onCollision (legacy) onCollisionActive (modern)
      Cadence for dynamic-dynamic pairs 2× per frame per side 1× per frame per side
      response.a semantics Fixed per pair (first body in detector call) Always the receiver (response.a === this)
      response.b semantics Fixed per pair Always the partner (response.b === other)
      response.normal / response.depth ✓ — normal.y < -0.7 = "push me up"
      return false to skip push-out ✓ (honored by SAT) ✗ — use bodyDef.isSensor or setSensor instead

      If you're writing new code, prefer onCollisionActive. Keep onCollision only when its every-frame, return-false, fixed-a/b semantics are what you want.

      Parameters

      • _response: any
      • _other: any

      Returns boolean

      true if the object should respond to the collision (its position and velocity will be corrected); the return value is only honored by the builtin SAT adapter.

      // legacy collision handler — note the receiver-side check on response.a
      onCollision(response) {
      if (response.b.body.collisionType === me.collision.types.ENEMY_OBJECT) {
      this.pos.sub(response.overlapV);
      this.hurt();
      return false; // skip the SAT push-out
      }
      return true;
      }
    • OnDestroy Notification function
      Called by engine before deleting the object. Stage.destroy(app) forwards the active Application, so subclasses that wire teardown against the app object can override as onDestroyEvent(app).

      Parameters

      • ..._args: any[]

        forwarded by destroy(...args); Stage passes the Application instance

      Returns void

    • Rotate this renderable by the specified angle (in radians). When called with just an angle, rotates around the Z axis (2D rotation). When called with an angle and a Vector3d axis, rotates around that axis in 3D.

      Parameters

      • angle: number

        The angle to rotate (in radians)

      • Optionalv: any

        the axis to rotate around (defaults to Z axis for 2D)

      Returns Renderable

      Reference to this object for method chaining

    • scale the renderable around his anchor point. Scaling actually applies changes to the currentTransform member which is used by the renderer to scale the object when rendering. It does not scale the object itself. For example if the renderable is an image, the image.width and image.height properties are unaltered but the currentTransform member will be changed.

      Parameters

      • x: number

        a number representing the abscissa of the scaling vector.

      • Optionaly: number = x

        a number representing the ordinate of the scaling vector.

      • Optionalz: number = 1

        a number representing the depth of the scaling vector.

      Returns Renderable

      Reference to this object for method chaining

    • set new value to the Polygon

      Parameters

      • x: number

        position of the Polygon

      • y: number

        position of the Polygon

      • points: PolygonVertices | LineVertices

        array of vector or vertices defining the Polygon

      Returns Mesh

      this instance for object chaining

    • Render the mesh at its current state (transforms, projection, tint) to an offscreen canvas. The returned canvas can be used with renderer.drawImage(), as a Sprite image source, or converted to an ImageBitmap via createImageBitmap().

      Returns HTMLCanvasElement

      an offscreen canvas containing the rendered mesh

      // snapshot the mesh and create a Sprite from it
      const canvas = mesh.toCanvas();
      const sprite = new me.Sprite(100, 100, { image: canvas });

      // or draw directly
      renderer.drawImage(mesh.toCanvas(), 100, 100);
    • Render the mesh at its current state to an ImageBitmap. Useful for creating textures or sprites from the rendered mesh.

      Returns Promise<ImageBitmap>

      a promise that resolves to an ImageBitmap of the rendered mesh

      const bitmap = await mesh.toImageBitmap();
      const sprite = new me.Sprite(100, 100, { image: bitmap });