Text

Text rendering is a crucial part of any game UI. dill-pixel provides several text implementations through Pixi.js, each with its own advantages and use cases.

Basic Text

The most straightforward way to add text is using the basic text implementation:

const text = this.add.text({
  text: 'Hello World',
  style: {
    fontFamily: 'Arial',
    fontSize: 48,
    fill: 'white',
  },
});

Style Options

Basic text supports various style options:

const textStyle = {
  fontFamily: 'Arial', // Web font or system font
  fontSize: 48, // Font size in pixels
  fill: 'white', // Text color
  align: 'center', // Text alignment
  leading: -10, // Line spacing
  textBaseline: 'bottom', // Vertical alignment
  wordWrap: true, // Enable word wrapping
  wordWrapWidth: 500, // Width before wrapping
};

Advantages

• Simple to implement
• Good performance for static text
• Supports basic formatting

Pitfalls

• Limited styling options
• No rich text formatting
• Can be blurry if scaled

HTML Text

For more complex text formatting, use HTML text:

this.add.htmlText({
  text: 'Text with <strong>bold</strong>, <em>italic</em>, and <span style="color: pink">colors</span>.',
  style: {
    align: 'center',
    fontFamily: 'Arial',
    wordWrapWidth: 500,
    wordWrap: true,
    fontSize: 32,
  },
});

Supported HTML Tags

• <strong> or <b> for bold text
• <em> or <i> for italic text
• <u> for underlined text
• <s> for strikethrough text
• <span> with style attributes for custom formatting

Advantages

• Rich text formatting
• Supports HTML-style markup
• Color and style variations within text
• Familiar HTML syntax

Pitfalls

• Higher performance overhead than basic text
• More complex to implement
• Limited HTML tag support
• May have inconsistent rendering across platforms

Bitmap Text

For optimal performance, especially in games with lots of text updates, use bitmap text:

this.add.bitmapText({
  text: 'High Performance Text',
  style: {
    fontFamily: 'MyBitmapFont',
    fontSize: 64,
  },
});

Advantages

• Best performance
• Consistent rendering across platforms
• Perfect for frequently updated text (scores, timers)
• Crisp at any scale

Pitfalls

• Requires pre-generated bitmap fonts
• Limited to characters included in the font
• No dynamic styling
• Fixed color unless using tint
• Larger asset size

Implementation Example

Here’s a complete example showing all three text types:

// in your scene
async initialize() {
  this._layout = this.add.flexContainer({
    flexDirection: 'column',
    alignItems: 'center',
    justifyContent: 'center',
    gap: 30,
    bindToAppSize: true,
  });

  const text = this._layout.add.text({
    text: 'Text (using a web font)',
    style: {
      fontFamily: FONT_KUMBH_SANS,
      fontSize: 48,
      leading: -10,
      textBaseline: 'bottom',
    },
  });

  this._layout.add.htmlText({
    text: 'HTML text with <strong>bold</strong>, <em>italic</em>, <u>underline</u>, <s>strikethrough</s>, and <span style="color:white; background-color: black">some</span> <span style="color: #8ac733">different</span> <span style="color: pink">colors</span>.',
    style: {
      align: 'center',
      fontFamily: FONT_KUMBH_SANS,
      wordWrapWidth: 500,
      wordWrap: true,
      fontSize: 32,
    },
  });

  this._layout.add.bitmapText({
    text: 'Bitmap Font',
    style: {
      fontFamily: FONT_KUMBH_SANS_BLACK,
      fontSize: 64,
    },
  });

---

Font Loading

Web and bitmap fonts need to be loaded via assetpack before they can be used in your game.

Here’s how you might structure your assets folder to include a web and bitmap font version of the same font:

• Directoryassets

  • Directoryrequired{m}

    • Directoryfonts{fix} // ensures assetpack mipmap plugin doesn’t resize any image files inside this folder

      • KumbhSans-Bold{family=KumbhSans}{wf}.ttf
      • KumbhSans-Medium{family=KumbhSans}{wf}.ttf
      • KumbhSans-Regular{family=KumbhSans}{wf}.ttf
      • KumbhSans-SemiBold{family=KumbhSans}{wf}.ttf
      • KumbhSansBlack.fnt // bitmap font (font name inside the file needs to be the same as the file name, and will be the bitmap font family name)
      • KumbhSansBlack.png // bitmap font image

Tip

The {wf} suffix in the file name indicates that the file is a web font.

Tip

The {family} suffix in the file name indicates that the font belongs to the KumbhSans family. This setup allows you to use the same font family name and have access to all the different font weights.

This setup ensures that fonts will be loaded as part of the required assets, and will be available to your game.