melonJS
    Preparing search index...

    Class Trigger

    Trigger an event when colliding with another object. Supports both fade and mask-based transitions when loading a new level.

    Hierarchy (View Summary)

    Index
    constructor
    alpha alwaysUpdate ancestor anchorPoint applyAnchorTransform autoTransform blendMode body bodyDef color currentTransform duration edges fading floating gotolevel GUID id indices isDirty isKinematic isPersistent mask name onVisibilityChange points pos postEffects transition transitionShape triggerSettings type updateWhenPaused visibleInAllCameras
    bottom centerX centerY depth height inViewport isFlippedX isFlippedY isFloating left parentApp right shader tint top width
    addPostEffect angleTo centerOn clearPostEffects clone contains containsRectangle copy distanceTo draw equals flipX flipY getAbsolutePosition getBounds getIndices getLocalTransform getOpacity getPostEffect getWorldTransform isConvex isFinite lookAt onActivateEvent onCollision onCollisionStart onDeactivateEvent onDestroyEvent overlaps postDraw preDraw recalc removePostEffect resize rotate scale scaleV setOpacity setShape setSize setVertices shift to2d toIso toPolygon transform translate triggerEvent union update updateBounds

    • Parameters

      • x: number

        the x coordinates of the trigger area

      • y: number

        the y coordinates of the trigger area

      • settings: {
            color?: any;
            container?: any;
            duration?: number;
            event?: string;
            flatten?: boolean;
            height?: number;
            onLoaded?: Function;
            setViewportBounds?: boolean;
            shape?: any;
            shapes?: Rect[] | Polygon[] | Line[] | Ellipse[];
            to?: string;
            transition?: string;
            width?: number;
        }

        trigger settings

        • Optionalcolor?: any

          Transition color (also accepts legacy fade property)

        • Optionalcontainer?: any

          Target container. See level.load

        • Optionalduration?: number

          Transition duration (in ms)

        • Optionalevent?: string

          the type of event to trigger (only "level" supported for now)

        • Optionalflatten?: boolean

          Flatten all objects into the target container. See level.load

        • Optionalheight?: number

          height of the trigger area

        • OptionalonLoaded?: Function

          Level loaded callback. See level.load

        • OptionalsetViewportBounds?: boolean

          Resize the viewport to match the level. See level.load

        • Optionalshape?: any

          Mask shape for "mask" transition type (e.g. an Ellipse for iris, a Polygon for diamond/star)

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

          collision shape(s) that will trigger the event

        • Optionalto?: string

          level to load if level trigger

        • Optionaltransition?: string

          Transition type: "fade" for a color fade, "mask" for a shape-based mask transition

        • Optionalwidth?: number

          width of the trigger area

      Returns Trigger

      // fade transition (default)
      world.addChild(new Trigger(x, y, {
          shapes: [new Rect(0, 0, 100, 100)],
          color: "#000",
          duration: 250,
          to: "mymap2",
      }));

      // mask transition with iris (ellipse) shape
      world.addChild(new Trigger(x, y, {
          shapes: [new Rect(0, 0, 100, 100)],
          transition: "mask",
          shape: new Ellipse(0, 0, 1, 1),
          color: "#000",
          duration: 500,
          to: "mymap2",
      }));

      // mask transition with diamond polygon
      world.addChild(new Trigger(x, y, {
          shapes: [new Rect(0, 0, 100, 100)],
          transition: "mask",
          shape: new Polygon(0, 0, [
              { x: 0, y: -1 }, { x: 1, y: 0 },
              { x: 0, y: 1 }, { x: -1, y: 0 },
          ]),
          color: "#000",
          duration: 400,
          to: "mymap2",
      }));
    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}, or (since 19.9) a plain string preset such as bottom.
    At construction time, settings.anchorPoint also accepts the named presets "center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right" on every renderable that consumes it (Sprite, Entity, Collectable, ImageLayer, Text, BitmapText, Sprite3d and subclasses).

    <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 — any of the modes listed on CanvasRenderer#setBlendMode, honoured identically by every renderer

    "normal"
    • CanvasRenderer#setBlendMode
    • WebGLRenderer#setBlendMode

    body

    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, app.viewport.AXIS.BOTH);
         }

         ...

    }
    bodyDef: {
        collisionMask: number;
        collisionType: number;
        isSensor: boolean;
        shapes: Rect[];
        type: string;
    }

    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
    color: any
    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.

    duration: number | undefined
    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.

    fading: boolean
    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
    gotolevel: string | undefined
    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)

    id: any
    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

    postEffects: any[]

    the list of post-processing shader effects applied to this renderable (GPU backends — WebGL and WebGPU). Effects are applied in order. Use addPostEffect, getPostEffect, and removePostEffect to manage effects, or assign directly. On the Canvas renderer effects stay inert (the scene keeps rendering un-effected).

    []

    // 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)];
    transition: string
    transitionShape: any
    triggerSettings: { event: string }
    type: any

    The shape type (used internally).

    updateWhenPaused: boolean

    Whether to update this object when the game is paused.

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

    • 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 this renderable (automatically called by melonJS). All draw operations for renderable are made respectively to the position or transforms set or applied by the preDraw method. The main draw loop will first call preDraw() to prepare the context for drawing the renderable, then draw() to draw the renderable, and finally postDraw() to clear the context. If you override this method, be mindful about the drawing logic: preDraw applies this renderable's transforms, tint and anchor offset, but does not translate to this.pos. The renderer arrives positioned at the parent container's origin, so draw relative to this.pos — drawing at (0, 0) places the shape at the container's origin instead.

      Parameters

      Returns void

      • Renderable#preDraw
      • Renderable#postDraw

    • Where this renderable IS in the game world — its own pos plus every ancestor's, as a Vector3d so the z component is summed across the 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).

      Reach for this for anything positional: culling, distance checks, hit tests, placing one renderable relative to another. It is cheap, and it is what the engine's own culling uses.

      Reach for Renderable#getWorldTransform instead when a position is not enough — when rotation, scale or flip along the ancestor chain matters, or when you need to map an arbitrary point rather than just the origin. This method sums translations only, so under a rotated or scaled ancestor it reports where the renderable's pivot is and nothing about how its content is oriented.

      Note the two also frame the question differently. This one is "where am I"; getWorldTransform() is "what space is my content drawn in". For a Container those coincide, because a container offsets its children by its own position. For a leaf they differ by exactly that position, which a leaf applies inside its own draw().

      The returned vector is pooled and reused — copy it if you need to hold onto the value across another call.

      Returns Vector3d

      this renderable's absolute position

      Renderable#getWorldTransform

    • Protected

      The transform this renderable interposes between its ancestor's frame and the frame its own content is drawn in — a mirror of what Renderable#preDraw applies to the renderer, as a matrix.

      This is not Renderable#currentTransform. A renderable's placement is split across two members: pos holds where it is, and currentTransform holds only what rotate() / scale() / translate() accumulate — it never contains the position. preDraw composes the two by conjugation, so a rotation pivots about the renderable's position rather than the origin. On a renderable you never rotated, currentTransform is therefore the identity and says nothing about where its content lands, while this method returns the translation that actually places it.

      Container extends this with the offset it applies to its children, which a leaf renderable does not have: a leaf's own draw() places itself from pos.

      Parameters

      • out: Matrix3d

        matrix to write into; nothing is stored on the renderable itself, so callers own the lifetime

      Returns Matrix3d

      out, for chaining

      Renderable#getWorldTransform

    • 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();

    • The space this renderable's content is drawn IN, as a matrix — the full form of Renderable#getAbsolutePosition, which sums positions up the ancestor chain and therefore cannot represent the rotation, scale or flip accumulated along the way.

      Reach for getAbsolutePosition() instead for ordinary positional work — culling, distance checks, hit tests. It is cheaper and it is what the engine culls with. Use this when a position is not enough:

      • an ancestor is rotated or scaled, so a translation cannot describe the result
      • you need to map an arbitrary point, not just the origin — a corner, a click position, one renderable's coordinates into another's space
      • you need to compose or invert the transform (inv(A) · B converts between two frames, which is how ParticleEmitter.referenceSpace measures particles against a container that is not their parent)

      The two also frame the question differently, and it shows on a leaf. getAbsolutePosition() is "where am I"; this is "what space is my content drawn in". For a Container those coincide, because a container offsets its children by its own position. For a leaf they differ by exactly that position, which a leaf applies inside its own draw(). So with no rotation, scale or flip anywhere, a container's translation column equals its getAbsolutePosition() while a leaf's equals its PARENT's.

      The walk stops at a floating ancestor, because a floating renderable draws in screen space: Container#draw resets the transform outright for those, so the chain genuinely ends there rather than continuing to the root.

      The camera needs no special handling — Camera2d folds its view transform into the root container's currentTransform, so it is picked up like any other level.

      Parameters

      • out: Matrix3d

        matrix to write into; nothing is stored on the renderable itself, so callers own the lifetime

      Returns Matrix3d

      out, for chaining

      Renderable#getAbsolutePosition

      // map a point from one renderable's space into another's
      const from = a.getWorldTransform(new Matrix3d());
      const into = b.getWorldTransform(new Matrix3d()).invert();
      const point = new Vector2d(10, 20);       // in a's space
      from.apply(point);                        // -> world
      into.apply(point);                        // -> b's space

      // just need to know where something is? use the cheaper call
      const where = renderable.getAbsolutePosition();

    • 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

    • Lifecycle hook fired by Container when this renderable is added to a container that is part of the active scene graph. Override to wire up input handlers, register external listeners, or grab adapter references — this.parentApp is guaranteed to be available here. Pair with Renderable#onDeactivateEvent.

      Parameters

      • ..._args: any[]

        the rest parameter exists for subclass-signature compatibility; Container.addChild currently forwards nothing

      Returns void

    • 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: ResponseObject

        the SAT response object; the legacy handler receives this, not the adapter's CollisionResponse, which is why normal and depth are absent from the table above

      • other: Renderable

        the other renderable touching this one (a reference to response.a or response.b)

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

    • Fire the trigger when an entity first enters the trigger zone. Using onCollisionStart rather than onCollision so the event runs exactly once per entry — under the legacy alias this would fire every frame the entity was inside the trigger.

      Returns void

    • OnDestroy Notification function
      Called by engine before deleting the object. Receives whatever destroy(...args) was called with — the production path (Container.removeChildNow) passes nothing. Stage has its own onDestroyEvent, which does forward the active Application.

      Parameters

      • ..._args: any[]

        forwarded by destroy(...args); normally empty

      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 Trigger

      this instance for object chaining

    • Shifts the Polygon to the given position vector.

      Parameters

      • x: number

        The x coordinate or a vector point to shift to.

      • Optionaly: number

        The y coordinate. This parameter is required if the first parameter is a number.

      Returns void

      polygon.shift(10, 10);
      // or
      polygon.shift(myVector2d);

    • Shifts the Polygon to the given position vector.

      Parameters

      Returns void

      polygon.shift(10, 10);
      // or
      polygon.shift(myVector2d);

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods