create-dreamer-app 1.0.14 → 1.0.16
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
|
# Disco Dreamer reference
|
|
2
2
|
|
|
3
|
-
A practical guide to building browser games with `discodreamer`. Examples use the public API in version 1.1
|
|
3
|
+
A practical guide to building browser games with `discodreamer`. Examples use the public API in version 1.2.1 and TypeScript with JSX.
|
|
4
4
|
|
|
5
5
|
## How a game runs
|
|
6
6
|
|
|
@@ -8,7 +8,7 @@ Disco Dreamer draws a tree of game objects onto a 2D canvas. Components are func
|
|
|
8
8
|
|
|
9
9
|
Your root function runs again on every animation frame. Each frame, the engine builds the tree, solves collisions, manages sound, draws the tree, and cleans up. A state setter updates stored data immediately; it does not schedule a separate render.
|
|
10
10
|
|
|
11
|
-
- Coordinates use CSS pixels,
|
|
11
|
+
- Coordinates use CSS pixels by default, or scaled game units when configured through `registerRoot`. In both modes, `(0, 0)` is at the canvas's top-left, positive `x` points right, and positive `y` points downward.
|
|
12
12
|
- Child positions are relative to their parent `Scene` or `RigidBody2D`.
|
|
13
13
|
- Siblings draw in ascending `z` order; higher values appear later, on top. This is local to each parent, not a global depth order.
|
|
14
14
|
- Update times and interpolation durations are in milliseconds. Convert `dt` to seconds for movement expressed in units per second.
|
|
@@ -71,6 +71,36 @@ Use `.tsx` files for JSX. Arrays and conditional children are supported, such as
|
|
|
71
71
|
|
|
72
72
|
The examples below are independent excerpts; add their named imports from `discodreamer` to your game file. Asset paths such as `/player.png` are examples: supply files at URLs your app serves.
|
|
73
73
|
|
|
74
|
+
### `registerRoot(Root, config?)`
|
|
75
|
+
|
|
76
|
+
Registers the single root function and starts the game loop. The config argument is optional; omitting it uses `{ units: "pixels" }`. Pixel mode has no scaling factor. Scale mode requires an explicit, finite, positive `scaling` value:
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
registerRoot(Game); // Defaults to CSS-pixel coordinates.
|
|
80
|
+
// Or explicitly select a coordinate mode:
|
|
81
|
+
registerRoot(Game, { units: "pixels" });
|
|
82
|
+
registerRoot(Game, { units: "scale", scaling: 0.01 });
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
These are alternative registration examples; call `registerRoot` only once per game. The config is a union of `{ units: "pixels" }` and `{ units: "scale"; scaling: number }`:
|
|
86
|
+
|
|
87
|
+
| Field | Values | Behavior |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `units` | `"pixels"` or `"scale"` | Selects CSS pixels or scaled game units |
|
|
90
|
+
| `scaling` | Finite number greater than `0` | Required and validated only in scale mode; fraction of the canvas's shorter CSS dimension occupied by one game unit |
|
|
91
|
+
|
|
92
|
+
In scale mode, the engine recalculates the CSS-pixel size of one game unit before building the tree each frame:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
unit = Math.min(canvas.clientWidth, canvas.clientHeight) * scaling;
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
With `scaling: 0.01`, one game unit occupies 1% of the shorter canvas dimension, so that dimension fits 100 game units. An `800 × 600` CSS-pixel canvas has `unit = 6` and a game viewport of approximately `133.33 × 100`; a rectangle with `width={10}` draws 60 CSS pixels wide. With `scaling: 0.02`, the shorter dimension fits 50 game units.
|
|
99
|
+
|
|
100
|
+
Positions, display widths and heights, circle radii, and font sizes use the selected coordinate units. Resizing changes the size of a scaled unit while stored positions and sizes retain their numeric values. Source image dimensions and sprite-sheet frame sizes remain source pixels; specify sprite display dimensions explicitly when needed for your chosen scale.
|
|
101
|
+
|
|
102
|
+
Viewport dimensions and pointer coordinates use the same units as drawing. Device pixel ratio is handled internally for canvas resolution; no DPR conversion is needed in game code. In pixel mode, `unit` is `1` and no `scaling` field is needed. If the calculated unit is zero or non-finite, the engine falls back to `1` for that frame.
|
|
103
|
+
|
|
74
104
|
## State and keys
|
|
75
105
|
|
|
76
106
|
### `gameState(key, initialValue)`
|
|
@@ -86,6 +116,19 @@ setScore((previous) => previous + 1);
|
|
|
86
116
|
|
|
87
117
|
`initialValue` initializes a new state slot; changing it on later frames does not reset existing state. Setters accept either a replacement or a function of the previous value. Replace objects rather than mutating them.
|
|
88
118
|
|
|
119
|
+
For lazy initialization, pass a synchronous function returning the initial value (`T | (() => T)`). It runs only when the resolved state slot is created:
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
const [position, setPosition, getPosition] = gameState("player.position", () => {
|
|
123
|
+
const { width, height } = gameViewport();
|
|
124
|
+
return { x: width / 2, y: height / 2 };
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Pass `() => buildValue()` to defer work until initialization. Passing `buildValue()` instead evaluates it on every hook call, even when the state already exists. A viewport-based initializer sets the starting position; it does not reposition existing state after resizing. If cleanup removes the slot and it is later recreated, its initializer runs again. For shared `$` keys, only the call creating the slot runs its initializer.
|
|
129
|
+
|
|
130
|
+
Function arguments are treated as initializers, and function arguments to the setter are treated as updaters. To store a callback as data, wrap it in an object, for example `gameState("action", { run: () => console.log("Go") })`.
|
|
131
|
+
|
|
89
132
|
Keys identify persistent data across frames. Give each stateful hook and each body instance a stable, descriptive key. For repeated entities, include an entity ID, such as `` `enemy.${id}.health` ``.
|
|
90
133
|
|
|
91
134
|
Internally, ordinary keys receive numbered slots for consecutive stateful calls using the same key. Their order must stay consistent. Reusing a key after a different ordinary key starts its numbering again, which can alias an earlier slot. The simplest application pattern is to use a distinct key for each hook and avoid sharing keys with component internals. Keep stateful hook calls in a consistent order each frame.
|
|
@@ -174,7 +217,7 @@ Draws left-aligned, top-aligned text in the supplied `color`, or white by defaul
|
|
|
174
217
|
| `value` | Required | Text string to draw |
|
|
175
218
|
| `x`, `y`, `z` | `0` | Position and sibling draw order |
|
|
176
219
|
| `color` | `"white"` | Text fill color as a canvas color string, such as `"red"` or `"#ff00ff"` |
|
|
177
|
-
| `fontSize` | `25` | Font size in
|
|
220
|
+
| `fontSize` | `25` | Font size in the selected coordinate units |
|
|
178
221
|
| `font` | `""` (renders as `sans-serif`) | Font family name, such as a name registered with `addCustomFont` |
|
|
179
222
|
| `width` | `Infinity` | Maximum canvas text draw width |
|
|
180
223
|
|
|
@@ -274,7 +317,7 @@ A stateful moving body. Put drawing components and one or more `Bounds` inside i
|
|
|
274
317
|
| `onChange` | Unset | Callback receiving `{ position, velocity }` |
|
|
275
318
|
| `children` | `[]` | Visuals and bounds attached to the body |
|
|
276
319
|
|
|
277
|
-
Physics treats one world unit as one centimeter. The renderer displays one unit as one CSS pixel.
|
|
320
|
+
Physics treats one world unit as one centimeter. The renderer displays one unit as one CSS pixel in pixel mode, or at the configured scale in scale mode. Scaling changes the visual size of the world without changing the numeric physics inputs or simulation units.
|
|
278
321
|
|
|
279
322
|
Choose one place for interaction settings per body:
|
|
280
323
|
|
|
@@ -398,7 +441,7 @@ The snapshot's data fields remain the values captured when `snapshot()` was call
|
|
|
398
441
|
|
|
399
442
|
### `gameUpdate(handler)`
|
|
400
443
|
|
|
401
|
-
Calls `handler(dt, frame, viewport)` immediately whenever the hook is evaluated. Used once in a component that runs every frame, it runs once per frame. `frame` starts at `0`; `dt` starts at `0` and then reflects the interval measured at the previous cleanup. `viewport` contains `{ width, height }` in CSS pixels.
|
|
444
|
+
Calls `handler(dt, frame, viewport)` immediately whenever the hook is evaluated. Used once in a component that runs every frame, it runs once per frame. `frame` starts at `0`; `dt` starts at `0` and then reflects the interval measured at the previous cleanup. `viewport` contains `{ width, height }` in the selected coordinate units: CSS pixels by default, or game units in scale mode.
|
|
402
445
|
|
|
403
446
|
```ts
|
|
404
447
|
gameUpdate((dt, frame, viewport) => {
|
|
@@ -435,7 +478,7 @@ Reads current input; call it each frame. It invokes the listener immediately for
|
|
|
435
478
|
| `touchStart` | `{ x, y }` | Primary pointer press on the canvas |
|
|
436
479
|
| `touchEnd` | `{ x, y }` | Primary pointer release or cancellation |
|
|
437
480
|
|
|
438
|
-
Key names use `KeyboardEvent.key`, for example `"ArrowLeft"`, `"a"`, or `" "` for space. Despite the `touch` names, pointer input supports mouse, touch, and pen, tracking one active pointer. Positions are relative to the canvas content area in CSS
|
|
481
|
+
Key names use `KeyboardEvent.key`, for example `"ArrowLeft"`, `"a"`, or `" "` for space. Despite the `touch` names, pointer input supports mouse, touch, and pen, tracking one active pointer. Positions are relative to the canvas content area in the selected coordinate units. In scale mode, canvas-relative CSS-pixel positions are divided by the current unit size; DPR does not enter this conversion.
|
|
439
482
|
|
|
440
483
|
```ts
|
|
441
484
|
gameEvent("keyDown", ({ key }) => {
|
|
@@ -448,7 +491,7 @@ gameEvent("touchStart", ({ x, y }) => {
|
|
|
448
491
|
|
|
449
492
|
### `gameViewport()`
|
|
450
493
|
|
|
451
|
-
Returns the canvas's current
|
|
494
|
+
Returns the canvas's current size as `{ width, height }` in the selected coordinate units. In pixel mode these are CSS dimensions; in scale mode they are CSS dimensions divided by the current unit size. With `scaling: 0.01` and a nonzero canvas size, the shorter dimension is 100 game units. Use this for responsive placement; the engine handles the canvas backing resolution for device pixel ratio.
|
|
452
495
|
|
|
453
496
|
```ts
|
|
454
497
|
const { width, height } = gameViewport();
|
|
@@ -514,7 +557,7 @@ The ID retains the resolved value's type for `gameAsyncThen`; widening it to pla
|
|
|
514
557
|
|
|
515
558
|
Timers use wall-clock milliseconds and invoke handlers synchronously when `when` is called. They do not schedule browser timer callbacks. Call the hook and its returned `when` function each frame, and call `start` only when you want to start or restart the timer. Keep each hook's key stable to preserve its state across frames. Timer state is removed by the normal state cleanup when the hook is no longer used.
|
|
516
559
|
|
|
517
|
-
### `
|
|
560
|
+
### `gameTimeout(key)`
|
|
518
561
|
|
|
519
562
|
Returns the readonly tuple `[start, when, clear, timeRemaining]`.
|
|
520
563
|
|
|
@@ -531,7 +574,7 @@ The timeout starts inactive. By default, `when` clears it before calling the han
|
|
|
531
574
|
|
|
532
575
|
```ts
|
|
533
576
|
const [startTimeout, whenTimeout, clearTimeout, timeRemaining] =
|
|
534
|
-
|
|
577
|
+
gameTimeout("notice.timeout");
|
|
535
578
|
|
|
536
579
|
gameEvent("keyDown", ({ key }) => {
|
|
537
580
|
if (key === "n") startTimeout(2000);
|