Preparing search index...

    Class Entity

    a Generic Object Entity

    since 18.1.0 — use Sprite or Renderable combined with Body instead.

    Entity introduced an unnecessary extra layer: it wrapped a child Renderable (typically a Sprite) inside a parent object that also held a Body. This design led to a number of long-standing issues:

    • Anchor point confusion — Entity used its own anchor point to position the child renderable relative to the body bounds, which behaved differently from the standard Renderable anchor point. This caused persistent alignment bugs with bounds and rendering (see issues #848, #834, #754, #580, #922).
    • Indirect API — animations, flipping, tinting, and other visual operations had to go through this.renderable instead of being called directly, making the API more verbose and error-prone.
    • Custom rendering pipeline — Entity overrode preDraw/draw with a custom coordinate system that differed from the rest of the engine, making it harder to reason about positioning and transforms.

    The Sprite + Body approach

    The recommended replacement is to extend Sprite (for animated/image-based objects) or Renderable (for custom-drawn objects) directly, and attach a Body in the constructor. This approach:

    • Uses the standard rendering pipeline — no custom preDraw or coordinate system surprises.
    • Provides a direct API — call this.flipX(), this.setCurrentAnimation(), this.tint directly.
    • Aligns with industry conventions — attaching a physics body to a renderable is the standard pattern used by other game engines.
    • Gives full control over body shape and position within the sprite frame.
    class PlayerSprite extends me.Sprite {
        constructor(x, y, settings) {
            // create the Sprite using atlas animation frames
            super(x, y, {
                ...game.texture.getAnimationSettings([
                    "walk0001.png", "walk0002.png", "walk0003.png"
                ]),
                anchorPoint: { x: 0.5, y: 1.0 }
            });

            // add a physic body (use Tiled shapes if available, or define your own)
            this.body = new me.Body(this,
                settings.shapes || new me.Rect(0, 0, settings.width, settings.height)
            );
            this.body.collisionType = me.collision.types.PLAYER_OBJECT;
            this.body.setMaxVelocity(3, 15);
            this.body.setFriction(0.4, 0);

            // define animations (called directly on the sprite, not on this.renderable)
            this.addAnimation("walk", ["walk0001.png", "walk0002.png", "walk0003.png"]);
            this.setCurrentAnimation("walk");
        }

        update(dt) {
            // input handling, animations, etc. — all directly on `this`
            if (me.input.isKeyPressed("right")) {
                this.body.force.x = this.body.maxVel.x;
                this.flipX(false);
            }
            return super.update(dt);
        }

        onCollision(response, other) {
            return true; // solid
        }
    }

    class EnemySprite extends me.Sprite {
        constructor(x, y, settings) {
            super(x, y, Object.assign({
                image: "enemy_spritesheet",
                framewidth: 32,
                frameheight: 32,
            }, settings));

            // add a physic body
            this.body = new me.Body(this, new me.Rect(0, 0, this.width, this.height));
            this.body.collisionType = me.collision.types.ENEMY_OBJECT;
            this.body.setMaxVelocity(1, 1);
            this.body.gravityScale = 0;

            this.addAnimation("walk", [0, 1, 2, 3]);
            this.addAnimation("dead", [4]);
            this.setCurrentAnimation("walk");
        }

        onCollision(response, other) {
            return false;
        }
    }

    class CustomBall extends me.Renderable {
        constructor(x, y, radius) {
            super(x, y, radius * 2, radius * 2);
            this.radius = radius;

            // add a physic body with a circular shape
            this.body = new me.Body(this, new me.Ellipse(radius, radius, radius * 2, radius * 2));
            this.body.collisionType = me.collision.types.ENEMY_OBJECT;
            this.body.setMaxVelocity(4, 4);
            this.body.gravityScale = 0;
            this.body.force.set(
                me.Math.randomFloat(-4, 4),
                me.Math.randomFloat(-4, 4)
            );
        }

        update(dt) {
            return super.update(dt);
        }

        draw(renderer) {
            renderer.setColor("#FF0000");
            renderer.fillEllipse(
                this.width / 2, this.height / 2,
                this.radius, this.radius
            );
        }

        onCollision(response, other) {
            // bounce off on collision
            this.body.force.x = -this.body.force.x;
            this.body.force.y = -this.body.force.y;
            return false;
        }
    }
    • Sprite
    • Renderable
    • Body

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    alive alpha alwaysUpdate ancestor anchorPoint autoTransform blendMode body currentTransform edges floating GUID id indices isDirty isKinematic isPersistent mask name onVisibilityChange points pos shader type updateWhenPaused _deprecationWarned

    Accessors

    bottom centerX centerY depth height inViewport isFlippedX isFlippedY isFloating left parentApp renderable right tint top width

    Methods

    angleTo centerOn clone contains containsRectangle copy distanceTo draw equals flipX flipY getAbsolutePosition getBounds getIndices getOpacity isConvex isFinite lookAt onBodyUpdate onCollision onDeactivateEvent onDestroyEvent overlaps postDraw preDraw recalc resize rotate scale scaleV setOpacity setShape setSize setVertices shift to2d toIso toPolygon transform translate union updateBounds

    Constructors

    • Parameters

      • x: number

        the x coordinates of the entity object

      • y: number

        the y coordinates of the entity object

      • settings: {
            anchorPoint?: any;
            collisionMask?: number;
            frameheight?: number;
            framewidth?: number;
            height: number;
            id?: string;
            image?:
                | string
                | (new (width?: number, height?: number) => HTMLImageElement);
            name?: string;
            shapes?: Rect[] | Polygon[] | Line[] | Ellipse[];
            type?: string;
            width: number;
        }

        Entity properties, to be defined through Tiled or when calling the entity constructor

        • OptionalanchorPoint?: any

          Entity anchor point

        • OptionalcollisionMask?: number

          Mask collision detection for this object

        • Optionalframeheight?: number

          height of a single frame in the given spritesheet

        • Optionalframewidth?: number

          width of a single frame in the given spritesheet

        • height: number

          the physical height the entity takes up in game

        • Optionalid?: string

          object unique IDs

        • Optionalimage?: string | (new (width?: number, height?: number) => HTMLImageElement)

          resource name of a spritesheet to use for the entity renderable component

        • Optionalname?: string

          object entity name

        • Optionalshapes?: Rect[] | Polygon[] | Line[] | Ellipse[]

          the initial list of collision shapes (usually populated through Tiled)

        • Optionaltype?: string

          object type

        • width: number

          the physical width the entity takes up in game

      Returns Entity

      since 18.1.0 — see the class-level documentation for migration examples

    Properties

    alive: boolean

    dead/living state of the entity
    default value : true

    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>
    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

    body: Body

    the renderable physic body

    // 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
             me.game.viewport.follow(this.pos, me.game.viewport.AXIS.BOTH);
         }

         ...

    }
    currentTransform: Matrix2d

    the renderable default transformation matrix

    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
    GUID: string

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

    id: number

    object unique ID (as defined in Tiled)

    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
    mask: Polygon | Rect | Ellipse | Line | RoundRect

    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}
    ]);
    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!");
        }
    };
    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.

    pos: Vector2d

    origin point of the Polygon

    shader: any

    an optional shader, to be used instead of the default built-in one, when drawing this renderable (WebGL only). Use ShaderEffect for a simplified API that only requires a fragment apply() function, or GLShader for full control over vertex and fragment shaders. In Canvas mode, this property is ignored.

    undefined

    // grayscale effect — converts the sprite to black and white
    mySprite.shader = new ShaderEffect(renderer, `
        vec4 apply(vec4 color, vec2 uv) {
            float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
            return vec4(vec3(gray), color.a);
        }
    `);

    // pulsing brightness effect — makes the sprite glow rhythmically
    const effect = new ShaderEffect(renderer, `
        uniform float uTime;
        vec4 apply(vec4 color, vec2 uv) {
            float pulse = 0.8 + 0.2 * sin(uTime * 3.0);
            return vec4(color.rgb * pulse, color.a);
        }
    `);
    mySprite.shader = effect;
    // update the uniform each frame
    effect.setUniform("uTime", time);

    // to remove a custom shader
    mySprite.shader = undefined;
    type: string = "Rectangle"

    The shape type (used internally).

    updateWhenPaused: boolean

    Whether to update this object when the game is paused.

    false

    Static_deprecationWarned

    _deprecationWarned: boolean = false

    Accessors

    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
      }

    • 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

    • onCollision callback, triggered in case of collision, when this renderable body is colliding with another one

      Returns boolean

      true if the object should respond to the collision (its position and velocity will be corrected)

      // colision handler
      onCollision(response) {
          if (response.b.body.collisionType === me.collision.types.ENEMY_OBJECT) {
              // makes the other object solid, by substracting the overlap vector to the current position
              this.pos.sub(response.overlapV);
              this.hurt();
              // not solid
              return false;
          }
          // Make the object solid
          return true;
      },

    • Prepare the rendering context before drawing (automatically called by melonJS). This will apply any defined transforms, anchor point, tint or blend mode and translate the context accordingly to this renderable position.

      Parameters

      • renderer: any

        a renderer object

      Returns void

      • Renderable#draw
      • Renderable#postDraw

    • 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.

      Returns Renderable

      Reference to this object for method chaining

    Settings

    Member Visibility

    On This Page

    Why Entity is deprecatedThe Sprite + Body approachMigration Guide
    Constructors
    Properties
    Accessors
    Methods