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
|
@@ -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
|
|
150
|
+
Draws white, left-aligned, top-aligned text. Uses `sans-serif` unless a font family is supplied.
|
|
151
151
|
|
|
152
|
-
|
|
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
|
|
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 `
|
|
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.
|