create-dreamer-app 1.0.5 → 1.0.6

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-dreamer-app",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "The scaffolding application for using Disco Dreamer.",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -147,14 +147,88 @@ The sprite's position is its unrotated top-left corner. Images are cached by URL
147
147
 
148
148
  ### `Text`
149
149
 
150
- Draws white, left-aligned, top-aligned text in a sans-serif font.
150
+ Draws white, left-aligned, top-aligned text. Uses `sans-serif` unless a font family is supplied.
151
151
 
152
- Props: required `value: string`; optional `x`, `y`, `z` (default `0`), `fontSize` (default `100`), and `width` (default `Infinity`). A finite `width` limits the canvas text draw width; it does not create wrapping lines.
152
+ | Prop | Default | Purpose |
153
+ | --- | --- | --- |
154
+ | `value` | Required | Text string to draw |
155
+ | `x`, `y`, `z` | `0` | Position and sibling draw order |
156
+ | `fontSize` | `25` | Font size in pixels |
157
+ | `font` | `""` (renders as `sans-serif`) | Font family name, such as a name registered with `addCustomFont` |
158
+ | `width` | `Infinity` | Maximum canvas text draw width |
159
+
160
+ A finite `width` limits the canvas text draw width; it does not create wrapping lines. `font` is a string, not a font file URL. Missing or empty font names use `sans-serif`; a named font that is not yet available uses the browser's fallback until it loads. Fonts already available through CSS or installed on the user's device can also be selected without calling `addCustomFont`.
153
161
 
154
162
  ```tsx
155
163
  <Text x={16} y={16} value="Score: 10" fontSize={24} />
164
+ <Text x={16} y={48} value="Custom font" font="PixelFont" fontSize={32} />
165
+ ```
166
+
167
+ ## Custom fonts
168
+
169
+ ### `addCustomFont(name, fontFile)`
170
+
171
+ Starts loading a font from a URL string and registers it with the browser under `name`. Loading is asynchronous internally, but the helper returns `void`, not a promise. Call it once per font during setup, outside the root function or game loop. Text does not require custom font registration unless you want to load a font file yourself.
172
+
173
+ ```ts
174
+ import { addCustomFont } from "discodreamer";
175
+
176
+ addCustomFont("PixelFont", "/fonts/pixel.woff2");
156
177
  ```
157
178
 
179
+ Supply a URL your app serves. In Vite, you can also import the asset to obtain its URL:
180
+
181
+ ```ts
182
+ import pixelFontUrl from "./assets/pixel.woff2";
183
+
184
+ addCustomFont("PixelFont", pixelFontUrl);
185
+ ```
186
+
187
+ For TypeScript asset imports in a Vite app, include `"types": ["vite/client"]` in that app's `compilerOptions`.
188
+
189
+ The helper uses `FontFace.load()` and adds the loaded face to `document.fonts`. Failed loads are logged to the console and recorded as `"error"`. Registration is not deduplicated: repeated calls with the same name start new loads, so avoid calling it every frame.
190
+
191
+ ### `getFontStatus(name)` and `isFontLoaded(name)`
192
+
193
+ These helpers read the custom font registry immediately; they do not start loading or wait for a font.
194
+
195
+ | `getFontStatus(name)` | Meaning | `isFontLoaded(name)` |
196
+ | --- | --- | --- |
197
+ | `"unknown"` | No registration for this name | `false` |
198
+ | `"loading"` | Font loading is in progress | `false` |
199
+ | `"ready"` | Font loaded and was added to the document | `true` |
200
+ | `"error"` | Font loading or registration failed | `false` |
201
+
202
+ These statuses describe fonts registered through `addCustomFont`, not all fonts available on the device or through CSS. `FontStatus` is an internal type and is not a public named export.
203
+
204
+ You can check readiness each frame to show a loading message instead of drawing with a fallback font:
205
+
206
+ ```tsx
207
+ import {
208
+ addCustomFont,
209
+ getFontStatus,
210
+ isFontLoaded,
211
+ registerRoot,
212
+ Text,
213
+ } from "discodreamer";
214
+
215
+ addCustomFont("PixelFont", "/fonts/pixel.woff2");
216
+
217
+ function FontExample() {
218
+ if (getFontStatus("PixelFont") === "error") {
219
+ return <Text value="Could not load the font." />;
220
+ }
221
+ if (!isFontLoaded("PixelFont")) {
222
+ return <Text value="Loading font..." />;
223
+ }
224
+ return <Text value="Score: 100" font="PixelFont" fontSize={32} />;
225
+ }
226
+
227
+ registerRoot(FontExample);
228
+ ```
229
+
230
+ As with the other examples, a custom JSX setup must configure and import the JSX factory. Font readiness does not guarantee that the file supplies every character; the glyphs and character coverage depend on the font itself.
231
+
158
232
  ## Physics components and contact hooks
159
233
 
160
234
  ### `RigidBody2D`
@@ -394,6 +468,6 @@ A sound key must be unique across the entire tree. Keeping the same key and sour
394
468
 
395
469
  ## Public API scope
396
470
 
397
- The public components are `Scene`, `Sprite`, `Text`, `Rect`, `Circ`, `RigidBody2D`, `Bounds`, and `Sound`. The hooks described above, `DreamFactory`, `registerRoot`, `createComparator`, `createDynamicId`, and `sendMessage` are also exported.
471
+ The public components are `Scene`, `Sprite`, `Text`, `Rect`, `Circ`, `RigidBody2D`, `Bounds`, and `Sound`. The hooks described above, `DreamFactory`, `registerRoot`, `createComparator`, `createDynamicId`, `sendMessage`, `addCustomFont`, `getFontStatus`, and `isFontLoaded` are also exported.
398
472
 
399
- Public type exports are `SceneProps`, `GameObject`, `Viewport`, `Vector2d`, `RigidBody2DSnapshot`, and `EventType`. Other implementation files, including `Img`, `Txt`, and the unfinished global helpers, are not public package exports.
473
+ Public type exports are `SceneProps`, `GameObject`, `Viewport`, `Vector2d`, `RigidBody2DSnapshot`, `GameRef`, `GameRefResult`, and `EventType`. Other implementation files, including `Img`, `Txt`, and the unfinished global helpers, are not public package exports.
@@ -22,6 +22,6 @@
22
22
  "vite": "^8.3.2"
23
23
  },
24
24
  "dependencies": {
25
- "discodreamer": "^1.0.2"
25
+ "discodreamer": "^1.0.3"
26
26
  }
27
27
  }