create-dreamer-app 1.0.5 → 1.0.7

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.7",
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");
177
+ ```
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);
156
228
  ```
157
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`
@@ -227,7 +301,7 @@ function PhysicsExample() {
227
301
 
228
302
  ### `gameRef<RigidBody2DSnapshot>(key)`
229
303
 
230
- Reads a body's live stored state. Pass the returned `key` to the body's `ref`, and check `ready` before calling `snapshot()`:
304
+ Reads and updates a body's live stored state. Pass the returned `key` to the body's `ref`, and check `ready` before calling `snapshot()`:
231
305
 
232
306
  ```tsx
233
307
  function TrackedBody() {
@@ -245,7 +319,31 @@ function TrackedBody() {
245
319
  }
246
320
  ```
247
321
 
248
- Import `RigidBody2DSnapshot` with `import type`. The ref normally becomes ready on a later frame after the body attaches. A snapshot contains local position, velocity, and mass; it is a read interface, not a setter.
322
+ Import `RigidBody2DSnapshot` with `import type`. The ref normally becomes ready on a later frame after the body attaches. A snapshot contains local `position`, `velocity`, `mass`, and an `update` method:
323
+
324
+ ```ts
325
+ update: (handler: (prev: BodyState) => BodyState) => void;
326
+ ```
327
+
328
+ The handler receives a deep copy of the latest stored body state and must return the complete next state. `BodyState` contains `{ x, y, velocity, mass }`: use local `x` and `y` when updating position, rather than the snapshot's `position` field. Spread `prev` to preserve fields you are not changing.
329
+
330
+ For example, when game logic needs to reposition a body and change its velocity:
331
+
332
+ ```ts
333
+ if (body.ready) {
334
+ const snapshot = body.snapshot();
335
+
336
+ snapshot.update(prev => ({ ...prev, x: 100, y: 200 }));
337
+ snapshot.update(prev => ({
338
+ ...prev,
339
+ velocity: { ...prev.velocity, y: -300 },
340
+ }));
341
+ }
342
+ ```
343
+
344
+ Updates write to storage synchronously. Each handler receives the latest state, including changes from earlier updates, so the second update above preserves the first update's position. The deep copy includes nested objects such as `velocity`; mutating the handler's `prev` does not mutate live state before the handler returns. Return the next state even if you modify that copy directly.
345
+
346
+ The snapshot's data fields remain the values captured when `snapshot()` was called. Changing those fields does not update the body; use `update`, then call `body.snapshot()` again to read fresh values. Normal physics continues from the updated state, and changing the body's `x`, `y`, `velocity`, or `mass` props can still reset it as described above.
249
347
 
250
348
  ## Update, effect, and input hooks
251
349
 
@@ -394,6 +492,6 @@ A sound key must be unique across the entire tree. Keeping the same key and sour
394
492
 
395
493
  ## Public API scope
396
494
 
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.
495
+ 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
496
 
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.
497
+ 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.4"
26
26
  }
27
27
  }