- Notifications
You must be signed in to change notification settings - Fork10
💬 Text plugin for Zdog - works with any .ttf font!
License
jaames/zfont
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A text plugin for theZdog 3D engine! Renders TrueType fonts viaTypr.js |jaames.github.io/zfont
Features |Caveats |Demo |Installation |Usage |API |Zdog.Font |Zdog.Text |Zdog.TextGroup |Todo |Building
- Built on top ofTypr.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!
- 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
A live demo can be foundhere, there's also some more in-depth examples onCodepen!
$ npm install zfont --save
If you are using a module bundler like Webpack or Rollup, import Zfont into your project:
// Using ES6 module syntaximportZfontfrom'zfont';// Using CommonJS modulesconstZfont=require('zfont');
<scriptsrc="https://cdn.jsdelivr.net/npm/zfont/dist/zfont.min.js"></script>
When manually including the library like this, it will be globally available onwindow.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><!-- ... --><scriptsrc="./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 it's initialized, theZdog.Font,Zdog.Text andZdog.TextGroup classes will be available:
Zfont.init(Zdog);
(Pssst! If you prefer to dive in, check out thebasic demo over on Codepen)
To draw some text in a Zdog scene, first we need to set up a newZdog.Font object with the .ttf url for our desired font, then we can create a newZdog.Text object and add it to the illustration like any other shape:
// Initialize ZfontZfont.init(Zdog);// Create a Zdog illustrationletillo=newZdog.Illustration({element:'.zdog-canvas'});// Set up a font to useletmyFont=newZdog.Font({src:'./path/to/font.ttf'});// Create a text object// This is just a Zdog.Shape object with a couple of extra parameters!newZdog.Text({addTo:illo,font:myFont,value:'Hey, Zdog!',fontSize:64,color:'#fff'});// Animation loopfunctionanimate(){illo.updateRenderGraph();requestAnimationFrame(animate);}animate();
BothZdog.Text andZdog.TextGroup support multiline text, by inserting a newline character (\n) wherever you wish to add a line break:
newZdog.Text({ ...value:'The quick brown fox\njumps over the\nlazy zdog',});
For better readability you may prefer to use an array of strings for thevalue option. In this case, each string in the array will be treated as a seperate line of text:
newZdog.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 aZdog.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 loopfunctionanimate(){illo.updateRenderGraph();requestAnimationFrame(animate);}// Zdog.waitForFonts() returns a Promise which is resolved once all the fonts added to the scene so far have been loadedZdog.waitForFonts().then(()=>{// Once the fonts are done, start the animation loopanimate();})
Represents a font that can be used by an instance of eitherZdog.Text orZdog.TextGroup.
letfont=newZdog.Font({src:'./path/to/font.ttf'})
| Param | Details | Default |
|---|---|---|
src | Font URL path. This can be a.ttf or.otf font, check out theTypr.js repo for more details about font support | '' |
Get the measurements for the specified stringtext when rendered atfontSize (measured in pixels), similar toCanvasRenderingContext2D.measureText().
Returns an object withwidth,height,descender,ascender.
Returns an array ofZdog path commands for the specified stringtext, when rendered atfontSize (measured in pixels).
- (
x,y,z) is the origin point of the path alignXis the horizontal text alignment (equivalent to the CSStext-alignproperty); either"left","center"or"right".alignYis the vertical text alignment; either"top","middle"or"bottom".
Returns a Promise which resolves once this font has finished loading.
An object used for rendering text. It inherits everything from theZdog.Shape class.
newZdog.Text({addTo:illo,font:font,value:'Hey, Zdog!',textAlign:'center',textBaseline:'middle',color:'#5222ee',stroke:1,})
Zdog.Text inherits all the options from theZdog.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 CSStext-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 theZdog.Shape class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically.
TheZdog.Font instance being used for this text.
Text value as a string.
Font size, measured in pixels.
Horizontal text alignment, equivalent to the CSStext-align property. This can be either'left','center' or'right'
Vertical text alignment, equivalent to the HTML5 canvas'textBaseline property. This can be either'top','middle' or'bottom'
This class is very similar toZdog.Text, except it acts as aZdog.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.
newZdog.TextGroup({addTo:illo,font:font,value:'Hey, Zdog!',textAlign:'center',color:'#5222ee',stroke:2,})
Zdog.TextGroup inherits all the options from theZdog.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 CSStext-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 theZdog.Group class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically.
TheZdog.Font instance being used for this text.
Text value as a string.
Font size, measured in pixels.
Horizontal text alignment, equivalent to the CSStext-align property. This can be either'left','center' or'right'
Vertical text alignment, equivalent to the HTML5 canvas'textBaseline property. This can be either'top','middle' or'bottom'
Text color, equivalent toShape.color. Setting this will update the color for all of the group's children.
Text fill, equivalent toShape.fill. Setting this will update the fill for all of the group's children.
Text stroke, equivalent toShape.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}
- Google Fonts & Typekit integration?
- Support for different text directions, e.g. right-to-left
- Support for fallback fonts
- Support for color (SVG) fonts
$ npm install
$ npm start
$ npm run build
2019James Daniel