Class BitmapText

a bitmap font object

Hierarchy (view full)

Constructors

constructor

Properties

GUID _absPos _bounds _flip _inViewport _parentApp _tint alpha alwaysUpdate ancestor anchorPoint autoTransform blendMode body currentTransform floating isDirty isKinematic isPersistent lineHeight mask metrics name onVisibilityChange points pos shader textAlign textBaseline type updateWhenPaused wordWrapWidth

Accessors

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

Methods

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

Constructors

constructor

  • new BitmapText(x, y, settings): BitmapText

  • Parameters

    • x: number

      position of the text object

    • y: number

      position of the text object

    • settings: {
          anchorPoint: any;
          fillStyle: undefined | string | Color;
          font: string | (new (width?: number, height?: number) => HTMLImageElement);
          fontData: undefined | string;
          lineHeight: undefined | number;
          lineWidth: undefined | number;
          size: undefined | number;
          text: undefined | string | string[];
          textAlign: undefined | string;
          textBaseline: undefined | string;
          wordWrapWidth: undefined | number;
      }

      the text configuration

      • anchorPoint: any

        anchor point to draw the text at

      • fillStyle: undefined | string | Color

        a CSS color value used to tint the bitmapText (@see BitmapText.tint)

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

        a font name to identify the corresponing source image

      • fontData: undefined | string

        the bitmap font data corresponding name, or the bitmap font data itself

      • lineHeight: undefined | number

        line spacing height

      • lineWidth: undefined | number

        line width, in pixels, when drawing stroke

      • size: undefined | number

        size a scaling ratio

      • text: undefined | string | string[]

        a string, or an array of strings

      • textAlign: undefined | string

        horizontal text alignment

      • textBaseline: undefined | string

        the text baseline

      • wordWrapWidth: undefined | number

        the maximum length in CSS pixel for a single segment of text

    Returns BitmapText

    Example

    // Use me.loader.preload or me.loader.load to load assets
    me.loader.preload([
        { name: "arial", type: "binary" src: "data/font/arial.fnt" },
        { name: "arial", type: "image" src: "data/font/arial.png" },
    ])
    // Then create an instance of your bitmap font:
    let myFont = new me.BitmapText(x, y, {font:"arial", text:"Hello"});
    // two possibilities for using "myFont"
    // either call the draw function from your Renderable draw function
    myFont.draw(renderer, "Hello!", 0, 0);
    // or just add it to the word container
    me.game.world.addChild(myFont);

Properties

GUID

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)

_absPos

_absPos: undefined | object

_bounds

_bounds: undefined | object

_flip

_flip: {
    x: boolean;
    y: boolean;
}

_inViewport

_inViewport: boolean

_parentApp

_parentApp: any

_tint

_tint: object

alpha

alpha: number

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

See

  • Renderable#setOpacity
  • Renderable#getOpacity

Default

1.0

alwaysUpdate

alwaysUpdate: boolean

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

Default

false

ancestor

ancestor: Container | Entity

a reference to the parent object that contains this renderable

Default

undefined

anchorPoint

anchorPoint: ObservableVector2d

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

Default

<0.5,0.5>

autoTransform

autoTransform: boolean

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

Default

true

Example

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

blendMode: string

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

Default

"normal"

See

  • CanvasRenderer#setBlendMode
  • WebGLRenderer#setBlendMode

body

body: Body

the renderable physic body

Example

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

currentTransform: Matrix2d

the renderable default transformation matrix

floating

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.

Default

false

isDirty

isDirty: boolean

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

Default

true

isKinematic

isKinematic: boolean

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

Default

true

isPersistent

isPersistent: boolean

make the renderable object persistent over level changes

Default

false

lineHeight

lineHeight: number

Set the line spacing height (when displaying multi-line strings).
Current font height will be multiplied with this value to set the line height.

Default

1.0

mask

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

Default

undefined

Example

// 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}
]);

metrics

metrics: TextMetrics

name

name: string

The name of the renderable

Default

""

onVisibilityChange

onVisibilityChange: Function

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

Default

undefined

Example

this.onVisibilityChange = function(inViewport) {
    if (inViewport === true) {
        console.log("object has entered the in a camera viewport!");
    }
};

points

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

pos: Vector2d

origin point of the Polygon

shader

shader: GLShader

(Experimental) an optional shader, to be used instead of the default built-in one, when drawing this renderable (WebGL only)

Default

undefined

textAlign

textAlign: string

Set the default text alignment (or justification),
possible values are "left", "right", and "center".

Default

"left"

textBaseline

textBaseline: string

Set the text baseline (e.g. the Y-coordinate for the draw operation),
possible values are "top", "hanging, "middle, "alphabetic, "ideographic, "bottom"

Default

"top"

type

type: string

the shape type (used internally)

Default

"Polygon"

updateWhenPaused

updateWhenPaused: boolean

Whether to update this object when the game is paused.

Default

false

wordWrapWidth

wordWrapWidth: number

the maximum length in CSS pixel for a single segment of text. (use -1 to disable word wrapping)

Default

-1

Accessors

bottom

centerX

centerY

depth

fillStyle

height

inViewport

  • get inViewport(): boolean

  • Whether the renderable object is visible and within the viewport

    Returns boolean

    Default

    false
  • set inViewport(value): void

  • Parameters

    • value: boolean

    Returns void

isFlippedX

  • get isFlippedX(): boolean

  • returns true if this renderable is flipped on the horizontal axis

    Returns boolean

    See

    Renderable#flipX

isFlippedY

  • get isFlippedY(): boolean

  • returns true if this renderable is flipped on the vertical axis

    Returns boolean

    See

    Renderable#flipY

isFloating

  • get isFloating(): boolean

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

    Returns boolean

    See

    Renderable#floating

left

parentApp

  • get parentApp(): Application

  • returns the parent application (or game) to which this renderable is attached to

    Returns Application

    the parent application or undefined if not attached to any container/app

right

tint

  • get tint(): Color

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

    Returns Color

    Default

    (255, 255, 255)

    Example

    // 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): void

  • Parameters

    Returns void

top

width

Methods

angleTo

centerOn

  • centerOn(x, y): Rect

  • center the rectangle position around the given coordinates

    Parameters

    • x: number

      the x coordinate around which to center this rectangle

    • y: number

      the y coordinate around which to center this rectangle

    Returns Rect

    this rectangle

clone

contains

  • contains(...args): boolean

  • Returns true if the rectangle contains the given point or rectangle

    Parameters

    • Rest...args: any

    Returns boolean

    True if the rectangle contain the given point or rectangle, otherwise false

    Example

    if (rect.contains(10, 10)) {
      // do something
    }
    // or
    if (rect.contains(myVector2d)) {
      // do something
    }
    if (rect.contains(myRect)) {
      // do something
    }

copy

distanceTo

draw

  • draw(renderer, text?, x?, y?): void

  • draw the bitmap font

    Parameters

    • renderer: any

      Reference to the destination renderer instance

    • Optionaltext: string
    • Optionalx: number
    • Optionaly: number

    Returns void

equals

flipX

flipY

getAbsolutePosition

getBounds

getIndices

  • getIndices(): number[]

  • returns a list of indices for all triangles defined in this polygon

    Returns number[]

    an array of vertex indices for all triangles forming this polygon.

getOpacity

isConvex

  • isConvex(): boolean

  • Returns true if the vertices composing this polygon form a convex shape (vertices must be in clockwise order).

    Returns boolean

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

isFinite

  • isFinite(): boolean

  • determines whether all coordinates of this rectangle are finite numbers.

    Returns boolean

    false if all coordinates are positive or negative Infinity or NaN; otherwise, true.

lookAt

measureText

  • measureText(text?): TextMetrics

  • measure the given text size in pixels

    Parameters

    • Optionaltext: string = ...

    Returns TextMetrics

    a TextMetrics object with two properties: width and height, defining the output dimensions

onCollision

  • onCollision(): boolean

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

    Example

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

onDestroyEvent

overlaps

postDraw

preDraw

  • preDraw(renderer): void

  • 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

    Returns void

    See

    • Renderable#draw
    • Renderable#postDraw

recalc

resize

rotate

scale

  • scale(x, y?): Renderable

  • scale the renderable around his anchor point. Scaling actually applies changes to the currentTransform member wich 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

scaleV

set

setOpacity

setShape

  • setShape(x, y, w, h?, ...args): Rect

  • set new value to the rectangle shape

    Parameters

    • x: number

      position of the Rectangle

    • y: number

      position of the Rectangle

    • w: number | Vector2d[]

      width of the rectangle, or an array of vector defining the rectangle

    • Optionalh: number

      height of the rectangle, if a numeral width parameter is specified

    • Rest...args: any

    Returns Rect

    this rectangle

setText

setVertices

shift

  • shift(...args): void

  • Shifts the Polygon to the given position vector.

    Parameters

    • Rest...args: any

    Returns void

    Example

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

to2d

toIso

toPolygon

transform

translate

  • translate(...args): Polygon

  • translate the Polygon by the specified offset

    Parameters

    • Rest...args: any

    Returns Polygon

    Reference to this object for method chaining

    Example

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

union

update

updateBounds

  • updateBounds(absolute?): Bounds

  • update the bounding box for this Bitmap Text.

    Parameters

    • Optionalabsolute: boolean = true

      update the bounds size and position in (world) absolute coordinates

    Returns Bounds

    this Bitmap Text bounding box Rectangle object

Settings

Member Visibility

On This Page

constructorGUID_absPos_bounds_flip_inViewport_parentApp_tintalphaalwaysUpdateancestoranchorPointautoTransformblendModebodycurrentTransformfloatingisDirtyisKinematicisPersistentlineHeightmaskmetricsnameonVisibilityChangepointsposshadertextAligntextBaselinetypeupdateWhenPausedwordWrapWidthbottomcenterXcenterYdepthfillStyleheightinViewportisFlippedXisFlippedYisFloatingleftparentApprighttinttopwidthangleTocenterOnclonecontainscopydistanceTodrawequalsflipXflipYgetAbsolutePositiongetBoundsgetIndicesgetOpacityisConvexisFinitelookAtmeasureTextonCollisiononDestroyEventoverlapspostDrawpreDrawrecalcresizerotatescalescaleVsetsetOpacitysetShapesetTextsetVerticesshiftto2dtoIsotoPolygontransformtranslateunionupdateupdateBounds