Skip to content
💬 Text plugin for Zdog - works with any .ttf font!
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets add banner gif Jun 14, 2019
demo landing site: add google analytics Jul 2, 2019
dist landing site: add google analytics Jul 2, 2019
src landing site: add google analytics Jul 2, 2019
.gitattributes Initial commit May 29, 2019
.gitignore V1.2 (#2) Jun 12, 2019
LICENSE Initial commit May 29, 2019
README.md "width" -> "with" (damn it) Jun 16, 2019
deploy.sh V1.2 (#2) Jun 12, 2019
package-lock.json V1.2 (#2) Jun 12, 2019
package.json fix zero-length pass issue in ZdogText Jun 14, 2019
rollup.config.js landing site: add google analytics Jul 2, 2019

README.md


Zfont

A text plugin for the Zdog 3D engine! Renders TrueType fonts via Typr.js |

Features | Caveats | Demo | Installation | Usage | API | Zdog.Font | Zdog.Text | Zdog.TextGroup | Todo | Building


Features

  • Built on top of Typr.js, which supports a wide range of .ttf and .otf fonts with speed and grace
  • Less than 14kB minified and gzipped
  • No need to worry about waiting for fonts to load; text automatically pops into existence once the font is ready
  • Includes support for multiline text
  • Update font, text, color, alignment, etc at any time
  • Bonus utilities for measuring text, waiting for font load & more!

Caveats

  • You have to provide a .ttf to use yourself; it isn't possible to use system fonts
  • Character range is limited to whichever glyphs are supported by your chosen font, and font stacks/fallbacks aren't supported yet

Demo

A live demo can be found here, there's also some more in-depth examples on Codepen!


Installation

Install with NPM

$ npm install zfont --save

If you are using a module bundler like Webpack or Rollup, import Zfont into your project:

// Using ES6 module syntax
import Zfont from 'zfont';

// Using CommonJS modules
const Zfont = require('zfont');

Using the jsDelivr CDN

<script src="https://cdn.jsdelivr.net/npm/zfont/dist/zfont.min.js"></script>

When manually including the library like this, it will be globally available on window.Zfont

Download and Host Yourself

Development version
Uncompressed at around 75kB, with source comments included

Production version
Minified to 45kB

Then add it to the <head> of your page with a <script> tag:

<html>
  <head>
    <!-- ... -->
    <script src="./path/to/zfont.min.js"></script>
  </head>
  <!-- ... -->
</html>

Usage

Register Plugin

After both Zdog and Zfont have been imported/downloaded, we need to initialize the Zfont plugin. Once the it's initialized, the Zdog.Font, Zdog.Text and Zdog.TextGroup classes will be available:

Zfont.init(Zdog);

Hello World

(Pssst! If you prefer to dive in, check out the basic demo over on Codepen)

To draw some text in a Zdog scene, first we need to set up a new Zdog.Font object with the .ttf url for our desired font, then we can create a new Zdog.Text object and add it to the illustration like any other shape:

// Create a Zdog illustration
let illo = new Zdog.Illustration({
  element: '.zdog-canvas'
});

// Set up a font to use
let myFont = new Zdog.Font({
  src: './path/to/font.ttf'
});

// Create a text object
// This is just a Zdog.Shape object with a couple of extra parameters!
new Zdog.Text({
  addTo: illo,
  font: myFont,
  value: 'Hey, Zdog!',
  fontSize: 64,
  color: '#fff'
});

// Animation loop
function animate() {
  illo.updateRenderGraph();
  requestAnimationFrame(animate);
}
animate();

Multiline Text

Both Zdog.Text and Zdog.TextGroup support multiline text. Simply insert a newline character (\n) wherever you wish to add a line break:

new Zdog.Text({
  ...
  value: 'The quick brown fox\njumped over the\nlazy sleeping zdog',
});

For better readability you may prefer to use an array of strings for the value option. In this case, each string in the array will be treated as a seperate line of text:

new Zdog.Text({
  ...
  value: [
    'The quick brown fox'
    'jumped over the',
    'lazy sleeping zdog'
  ]
});

Waiting for Fonts to Load

In most cases you don't have to worry about waiting for fonts to load, as text objects will magically pop into existence once their font is ready for use. However, the plugin also provides a Zdog.waitForFonts() utility function if you need to delay anything until all the fonts in your scene have finished loading.

For example, let's modify the animation loop from the previous example so that it doesn't begin until the fonts are ready:

// Animation loop
function animate() {
  illo.updateRenderGraph();
  requestAnimationFrame(animate);
}
// Zdog.waitForFonts() returns a Promise which is resolved once all the fonts added to the scene so far have been loaded
Zdog.waitForFonts().then(function() {
  // Once the fonts are done, start the animation loop
  animate();
})

API

Zdog.Font

Represents a font that can be used by an instance of either Zdog.Text or Zdog.TextGroup.

let font = new Zdog.Font({
  src: './path/to/font.ttf'
})

Options

Param Details Default
src Font URL path. This can be a .ttf or .otf font, check out the Typr.js repo for more details about font support ''

Methods

measureText(text, fontSize)

Get the measurements for the specified string text when rendered at fontSize (measured in pixels), similar to Canvas​Rendering​Context2D.measure​Text().

Returns an object with width, height, descender, ascender.

getTextPath(text, fontSize, x=0, y=0, z=0, alignX='left', alignY='bottom')

Returns an array of Zdog path commands for the specified string text, when rendered at fontSize (measured in pixels).

  • (x, y, z) is the origin point of the path
  • alignX is the horizontal text alignment (equivalent to the CSS text-align property); either "left", "center" or "right".
  • alignY is the vertical text alignment; either "top", "middle" or "bottom".
waitForLoad()

Returns a Promise which resolves once this font has finished loading.

Zdog.Text

An object used for rendering text. It inherits everything from the Zdog.Shape class.

new Zdog.Text({
  addTo: illo,
  font: font,
  value: 'Hey, Zdog!',
  textAlign: 'center',
  textBaseline: 'middle',
  color: '#5222ee',
  stroke: 1,
})

Options

Zdog.Text inherits all the options from the Zdog.Shape class, plus a couple of extras:

Param Details Default
font Zdog.Font to use for this text. This is required. null
value Text string ''
fontSize Text size, measured in pixels 64
textAlign Horizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right' 'left'
textBaseline Vertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom' 'bottom'

Properties

Zdog.Text inherits all the properties from the Zdog.Shape class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically.

font

The Zdog.Font instance being used for this text.

value

Text value as a string.

fontSize

Font size, measured in pixels.

textAlign

Horizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right'

textBaseline

Vertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom'

Zdog.TextGroup

This class is very similar to Zdog.Text, except it acts as a Zdog.Group instead, and each text glyph is rendered as its own shape. This is helpful for more advanced use-cases where you need control over each character.

new Zdog.TextGroup({
  addTo: illo,
  font: font,
  value: 'Hey, Zdog!',
  textAlign: 'center',
  color: '#5222ee',
  stroke: 2,
})

Options

Zdog.TextGroup inherits all the options from the Zdog.Group class, plus a few extras:

Param Details Default
font Zdog.Font to use for this text. This is required. null
value Text string ''
fontSize Text size, measured in pixels 64
textAlign Horizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right' 'left'
textBaseline Vertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom' 'bottom'
color Text color #333
fill Text fill false
stroke Text stroke stroke

Properties

Zdog.TextGroup inherits all the properties from the Zdog.Group class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically.

font

The Zdog.Font instance being used for this text.

value

Text value as a string.

fontSize

Font size, measured in pixels.

textAlign

Horizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right'

textBaseline

Vertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom'

color

Text color, equivalent to Shape.color. Setting this will update the color for all of the group's children.

fill

Text fill, equivalent to Shape.fill. Setting this will update the fill for all of the group's children.

stroke

Text stroke, equivalent to Shape.stroke. Setting this will update the stroke for all of the group's children.

Zdog.waitForFonts

Returns a Promise which resolves as soon as all the fonts currently added to the scene are loaded and ready for use.

Zdog.waitForFonts().then(function() {
  // Do something once the font is ready
}

Todo

  • Google Fonts & Typekit integration?
  • Support for different text directions, e.g. right-to-left
  • Support for fallback fonts
  • Support for colored (SVG) fonts

Building

Install Dependencies with NPM

$ npm install

Run Devserver

$ npm start

Build production files

$ npm run build

© James Daniel

You can’t perform that action at this time.