|
| 1 | +# @wildwinter/game-subtitles |
| 2 | + |
| 3 | +The JavaScript player from [Game Subtitles](https://github.com/wildwinter/game-subtitles): give it a subtitle and how long it should stay up, and it wraps the text to fit your subtitle box, hyphenates long words in the right places, splits the text into pages, and shows each page for its share of the time. |
| 4 | + |
| 5 | +It measures text in your actual font at runtime, so it copes with any font, box size, or number of lines, including ones the player changes in the settings. Hyphenation comes from soft hyphens (U+00AD) that the Game Subtitles **preprocessor** adds to your localised strings at build time, using the TeX hyphenation rules for each language. The preprocessor, and players for Unity, Unreal, and Godot that behave the same way, are in the [GitHub repository](https://github.com/wildwinter/game-subtitles). |
| 6 | + |
| 7 | +## Install |
| 8 | + |
| 9 | +```bash |
| 10 | +npm install @wildwinter/game-subtitles |
| 11 | +``` |
| 12 | + |
| 13 | +The package is ES modules, with TypeScript types included. For a plain `<script>` tag there is also a build that defines a `GameSubtitles` global, at `@wildwinter/game-subtitles/iife` (`dist/game-subtitles-player.js`). |
| 14 | + |
| 15 | +## Usage |
| 16 | + |
| 17 | +```javascript |
| 18 | +import { SubtitlePlayer, DomRenderer } from '@wildwinter/game-subtitles'; |
| 19 | + |
| 20 | +// Once: a renderer for your subtitle element, and a player that uses it. |
| 21 | +const renderer = new DomRenderer(document.getElementById('subtitle-bar')); |
| 22 | +const player = new SubtitlePlayer({ renderer, maxLines: 2 }); |
| 23 | + |
| 24 | +// For each line of dialogue: |
| 25 | +player.start({ |
| 26 | + text, // a string from the preprocessor's output |
| 27 | + duration: 4.5, // seconds; leave it out to estimate one from the text |
| 28 | + characterName: 'Tam', // optional: shown as "Tam: " at the start of every page |
| 29 | + characterNameColor: '#f0cc88', // optional |
| 30 | + lineColor: '#ffffff', // optional |
| 31 | + onComplete: () => player.stop(), // the last page stays up until you stop the player |
| 32 | +}); |
| 33 | + |
| 34 | +// Every frame, with the seconds since the last frame: |
| 35 | +player.tick(deltaSeconds); |
| 36 | +``` |
| 37 | + |
| 38 | +`start()` lays out the text and shows the first page straight away, stopping any subtitle already playing. Create the player and renderer once and reuse them for every line. |
| 39 | + |
| 40 | +### Without a duration |
| 41 | + |
| 42 | +If you leave out the duration, or pass 0 or less, the player estimates one with `estimateDuration`, which you can also call yourself: |
| 43 | + |
| 44 | +```javascript |
| 45 | +import { estimateDuration } from '@wildwinter/game-subtitles'; |
| 46 | + |
| 47 | +const seconds = estimateDuration(text, { charsPerSecond: 14, minSeconds: 1.5, maxSeconds: 18 }); |
| 48 | +``` |
| 49 | + |
| 50 | +It counts characters (Unicode code points, not counting soft hyphens), divides by the reading rate, and clamps the result; the options shown are the defaults. Counting characters rather than words means languages written without spaces, such as Chinese and Japanese, still get an estimate. The Unity, Unreal, and Godot players use the same rule, so the same text gets the same estimate everywhere. |
| 51 | + |
| 52 | +## Renderers |
| 53 | + |
| 54 | +**`DomRenderer(element)`** draws each line as a `<p>` inside `element`, and measures text in that element's own computed font, so it follows your stylesheet. The character name is a `<span>` with the class `gs-character-name` (exported as `CHARACTER_NAME_CLASS`); style that class and the renderer measures with it too. If you change the element's font at runtime, call `renderer.invalidateFont()`. |
| 55 | + |
| 56 | +**`CanvasRenderer(canvas, font, lineHeight?, characterNameFont?)`** draws onto a canvas. `font` and `characterNameFont` are CSS font strings such as `'16px Arial'`; `lineHeight` defaults to 1.2 times the font size. |
| 57 | + |
| 58 | +**Your own renderer** can be any object with these four methods, so the player works with any engine or drawing layer: |
| 59 | + |
| 60 | +```typescript |
| 61 | +import type { SubtitleRenderer } from '@wildwinter/game-subtitles'; |
| 62 | + |
| 63 | +const renderer: SubtitleRenderer = { |
| 64 | + measureLineWidth(text, useCharacterNameFont) { /* the width of text in your font */ }, |
| 65 | + getContainerWidth() { /* the width available for a line */ }, |
| 66 | + render(lines, characterContext) { /* show the lines; draw "Name: " first if characterContext has a name */ }, |
| 67 | + clear() { /* remove the subtitle */ }, |
| 68 | +}; |
| 69 | +``` |
| 70 | + |
| 71 | +`measureLineWidth` must count trailing spaces, because the player measures `"Name: "` to reserve room for the character name. |
| 72 | + |
| 73 | +## Layout on its own |
| 74 | + |
| 75 | +The functions the player uses are exported too: |
| 76 | + |
| 77 | +```javascript |
| 78 | +import { wrapAndPaginate, allocateTimings } from '@wildwinter/game-subtitles'; |
| 79 | + |
| 80 | +const pages = wrapAndPaginate(text, measureWidth, containerWidth, maxLines); // string[][] |
| 81 | +const timings = allocateTimings(pages, totalSeconds); // seconds per page |
| 82 | +``` |
| 83 | + |
| 84 | +## Licence |
| 85 | + |
| 86 | +MIT. See the [repository](https://github.com/wildwinter/game-subtitles) for the full documentation and the preprocessor. |
0 commit comments