@excaliburjs/plugin-sdf-text 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +25 -0
- package/dist/cli.js +294 -0
- package/dist/excalibur-sdf-text.js +712 -0
- package/dist/excalibur-sdf-text.js.map +1 -0
- package/dist/excalibur-sdf-text.min.js +498 -0
- package/dist/excalibur-sdf-text.min.js.map +1 -0
- package/dist/types/index.d.ts +4 -0
- package/dist/types/sdf-font.d.ts +227 -0
- package/dist/types/sdf-text-plugin.d.ts +13 -0
- package/dist/types/sdf-text-renderer.d.ts +79 -0
- package/dist/types/sdf-text.d.ts +59 -0
- package/package.json +68 -4
- package/readme.md +112 -0
- package/README.md +0 -3
package/readme.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Excalibur SDF Text Plugin
|
|
2
|
+
|
|
3
|
+
`@excaliburjs/plugin-sdf-text`
|
|
4
|
+
|
|
5
|
+
Signed distance field text for [Excalibur](https://excaliburjs.com): one atlas, crisp text at any size, rotation or zoom, drawn by a batched WebGL renderer. It is also a worked example of an Excalibur `Plugin` that installs a custom `RendererPlugin` on the graphics context.
|
|
6
|
+
|
|
7
|
+
Why SDF text? `ex.Text` rasterizes with the 2D canvas, which looks great at the size it was rasterized at and goes soft when scaled or zoomed. A distance field atlas is generated once (at load time or ahead of time with the CLI) and the fragment shader reconstructs a sharp edge at whatever size you draw. You lose the browser's text shaping (ligatures, multi-colored emoji, bold and italic synthesized per draw), you gain resolution independence, batching, and the same output on every OS.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @excaliburjs/plugin-sdf-text
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Requires `excalibur@^1.0.0` and WebGL (the renderer is a no-op on the 2D canvas fallback).
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import * as ex from 'excalibur';
|
|
21
|
+
import { SDFFont, SDFText, SDFTextPlugin } from '@excaliburjs/plugin-sdf-text';
|
|
22
|
+
|
|
23
|
+
// Generates a 64px atlas from the browser's serif font at load time (or pass a `fontFile`)
|
|
24
|
+
const font = new SDFFont({ fontFamily: 'Georgia, serif', fontSize: 64, color: ex.Color.White });
|
|
25
|
+
|
|
26
|
+
const game = new ex.Engine({
|
|
27
|
+
plugins: [new SDFTextPlugin()] // registers the renderer on the WebGL graphics context
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
await game.start(new ex.Loader([font]));
|
|
31
|
+
|
|
32
|
+
const text = new SDFText({
|
|
33
|
+
sdf: font,
|
|
34
|
+
text: 'Crisp at any size',
|
|
35
|
+
size: 180, // bigger than the atlas is fine
|
|
36
|
+
textAlign: 'center',
|
|
37
|
+
maxWidth: 600
|
|
38
|
+
});
|
|
39
|
+
game.add(new ex.Actor({ pos: ex.vec(100, 100), graphic: text }));
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`SDFText` is a regular `ex.Graphic`: use it anywhere a sprite goes, scale, rotate and tint it, give it `opacity`, and combine it with other graphics in a `GraphicsGroup`. Its `width` and `height` are measured from the atlas so actor bounds and offscreen culling work.
|
|
43
|
+
|
|
44
|
+
### SDFFont options
|
|
45
|
+
|
|
46
|
+
| option | default | notes |
|
|
47
|
+
| --- | --- | --- |
|
|
48
|
+
| `fontFamily` | required | a system font, or the family name you give `fontFile` |
|
|
49
|
+
| `fontFile` | none | ttf/otf/woff to load before generating |
|
|
50
|
+
| `fontSize` | 48 | size the atlas is generated at, roughly the biggest size you will draw |
|
|
51
|
+
| `fontWeight` / `fontStyle` | 400 / normal | |
|
|
52
|
+
| `alphabet` | printable ASCII | a string, or unicode code point ranges like `[[0x20, 0xff]]` |
|
|
53
|
+
| `color` | black | default color for text drawn with this font |
|
|
54
|
+
|
|
55
|
+
### SDFText options
|
|
56
|
+
|
|
57
|
+
`text`, `size`, `color`, `visibleCharacters` (typewriter effects), `textAlign` (`left` | `center` | `right`), `maxWidth` (wraps on spaces), `lineHeight` (multiple of `size`, default 1.2), plus every `GraphicOptions` field (`opacity`, `scale`, `rotation`, `origin`, ...).
|
|
58
|
+
|
|
59
|
+
## Pre-generated atlases
|
|
60
|
+
|
|
61
|
+
Generating in the browser costs a few hundred milliseconds for a 64px ASCII atlas. For big alphabets or large sizes, bake the atlas ahead of time with the CLI (uses [skia-canvas](https://github.com/samizdatco/skia-canvas), an optional dependency) and ship the image and metadata with your game:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
# after npm install @excaliburjs/plugin-sdf-text
|
|
65
|
+
npx ex-generate-sdf ./fonts/PixelifySans-Regular.ttf PixelifySans ./public/pixelfont 64
|
|
66
|
+
# writes ./public/pixelfont.png and ./public/pixelfont.json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Or one-off without adding it to your game's dependencies (`--package` tells `npx` which package provides the command):
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
npx --package @excaliburjs/plugin-sdf-text ex-generate-sdf ./fonts/PixelifySans-Regular.ttf PixelifySans ./public/pixelfont 64
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
ex-generate-sdf <font-file> <font-family> <out-name> [font-size=64] [alphabet-start-hex=20 alphabet-end-hex=7E]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The CLI ships as type-stripped ESM and needs Node 24 or newer (it is not bundled into the library); the library itself is a prebuilt ESM bundle and runs anywhere your game does.
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
const pixel = new SDFAtlas({ atlasPath: '/pixelfont.png', metadataPath: '/pixelfont.json' });
|
|
83
|
+
await game.start(new ex.Loader([pixel]));
|
|
84
|
+
new SDFText({ sdf: pixel, text: 'from a baked atlas', size: 32 });
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Using the renderer directly
|
|
88
|
+
|
|
89
|
+
The plugin is a thin wrapper. If you manage renderers yourself:
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
const context = game.graphicsContext as ex.ExcaliburGraphicsContextWebGL;
|
|
93
|
+
context.lazyRegister('ex.sdf-text-renderer', () => new SDFTextRenderer());
|
|
94
|
+
|
|
95
|
+
// later, inside a Graphic's _drawImage
|
|
96
|
+
context.draw<SDFTextRenderer>('ex.sdf-text-renderer', font, 'hello', ex.vec(x, y), 32, { color: ex.Color.Red });
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Glyphs from every `SDFText` in a frame are batched into one draw call per atlas edge setting, up to the GPU's texture unit limit.
|
|
100
|
+
|
|
101
|
+
## Development
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
npm install
|
|
105
|
+
npm start # example app
|
|
106
|
+
npm run build # dist/excalibur-sdf-text.js, .min.js and types
|
|
107
|
+
npm test # headless smoke test (needs `npx playwright install chromium`)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Credits
|
|
111
|
+
|
|
112
|
+
Distance fields are generated with [@mapbox/tiny-sdf](https://github.com/mapbox/tiny-sdf). Example fonts: JetBrains Mono (OFL), Roboto (Apache 2.0), Pixelify Sans (OFL).
|
package/README.md
DELETED