A text plugin for the Zdog 3D engine! Renders TrueType fonts via Typr.js | jaames.github.io/zfont
Features | Caveats | Demo | Installation | Usage | API | Zdog.Font | Zdog.Text | Zdog.TextGroup | Todo | Building
A live demo can be found here, there's also some more in-depth examples on Codepen!
$ 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');
<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
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>
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);
(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:
// Initialize Zfont
Zfont.init(Zdog);
// 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();
Both Zdog.Text and Zdog.TextGroup support multiline text, by inserting a newline character (\n) wherever you wish to add a line break:
new Zdog.Text({
...
value: 'The quick brown fox\njumps over the\nlazy 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'
'jumps over the',
'lazy zdog'
]
});
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 to 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(() => {
// Once the fonts are done, start the animation loop
animate();
})
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'
})
| 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 | '' |
measureText(text, fontSize)Get the measurements for the specified string text when rendered at fontSize (measured in pixels), similar to CanvasRenderingContext2D.measureText().
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 pathalignX 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.
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,
})
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' |
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.
fontThe Zdog.Font instance being used for this text.
valueText value as a string.
fontSizeFont size, measured in pixels.
textAlignHorizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right'
textBaselineVertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom'
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,
})
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 |
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.
fontThe Zdog.Font instance being used for this text.
valueText value as a string.
fontSizeFont size, measured in pixels.
textAlignHorizontal text alignment, equivalent to the CSS text-align property. This can be either 'left', 'center' or 'right'
textBaselineVertical text alignment, equivalent to the HTML5 canvas' textBaseline property. This can be either 'top', 'middle' or 'bottom'
colorText color, equivalent to Shape.color. Setting this will update the color for all of the group's children.
fillText fill, equivalent to Shape.fill. Setting this will update the fill for all of the group's children.
strokeText stroke, equivalent to Shape.stroke. Setting this will update the stroke for all of the group's children.
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
}
$ npm install
$ npm start
$ npm run build
2019 James Daniel
FAQs
Text plugin for Zdog
The npm package zfont receives a total of 196 weekly downloads. As such, zfont popularity was classified as not popular.
We found that zfont demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.