create-dreamer-app 1.0.14 → 1.0.15
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.
|
|
3
|
+
A practical guide to building browser games with `discodreamer`. Examples use the public API in version 1.2.0 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,33 @@ 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. Omitting `config` uses `{ units: "pixels", scaling: 0.01 }`, so existing games use CSS-pixel coordinates. To enable scaled game units:
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
registerRoot(Game, { units: "scale", scaling: 0.01 });
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
When supplying a config, include both fields:
|
|
83
|
+
|
|
84
|
+
| Field | Values | Behavior |
|
|
85
|
+
| --- | --- | --- |
|
|
86
|
+
| `units` | `"pixels"` or `"scale"` | Selects CSS pixels or scaled game units |
|
|
87
|
+
| `scaling` | Finite number greater than `0` | Fraction of the canvas's shorter CSS dimension occupied by one game unit in scale mode; validated in both modes |
|
|
88
|
+
|
|
89
|
+
In scale mode, the engine recalculates the CSS-pixel size of one game unit before building the tree each frame:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
unit = Math.min(canvas.clientWidth, canvas.clientHeight) * scaling;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
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.
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
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 `scaling` does not affect rendering. If the calculated unit is zero or non-finite, the engine falls back to `1` for that frame.
|
|
100
|
+
|
|
74
101
|
## State and keys
|
|
75
102
|
|
|
76
103
|
### `gameState(key, initialValue)`
|
|
@@ -86,6 +113,19 @@ setScore((previous) => previous + 1);
|
|
|
86
113
|
|
|
87
114
|
`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
115
|
|
|
116
|
+
For lazy initialization, pass a synchronous function returning the initial value (`T | (() => T)`). It runs only when the resolved state slot is created:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
const [position, setPosition, getPosition] = gameState("player.position", () => {
|
|
120
|
+
const { width, height } = gameViewport();
|
|
121
|
+
return { x: width / 2, y: height / 2 };
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
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.
|
|
126
|
+
|
|
127
|
+
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") })`.
|
|
128
|
+
|
|
89
129
|
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
130
|
|
|
91
131
|
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 +214,7 @@ Draws left-aligned, top-aligned text in the supplied `color`, or white by defaul
|
|
|
174
214
|
| `value` | Required | Text string to draw |
|
|
175
215
|
| `x`, `y`, `z` | `0` | Position and sibling draw order |
|
|
176
216
|
| `color` | `"white"` | Text fill color as a canvas color string, such as `"red"` or `"#ff00ff"` |
|
|
177
|
-
| `fontSize` | `25` | Font size in
|
|
217
|
+
| `fontSize` | `25` | Font size in the selected coordinate units |
|
|
178
218
|
| `font` | `""` (renders as `sans-serif`) | Font family name, such as a name registered with `addCustomFont` |
|
|
179
219
|
| `width` | `Infinity` | Maximum canvas text draw width |
|
|
180
220
|
|
|
@@ -274,7 +314,7 @@ A stateful moving body. Put drawing components and one or more `Bounds` inside i
|
|
|
274
314
|
| `onChange` | Unset | Callback receiving `{ position, velocity }` |
|
|
275
315
|
| `children` | `[]` | Visuals and bounds attached to the body |
|
|
276
316
|
|
|
277
|
-
Physics treats one world unit as one centimeter. The renderer displays one unit as one CSS pixel.
|
|
317
|
+
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
318
|
|
|
279
319
|
Choose one place for interaction settings per body:
|
|
280
320
|
|
|
@@ -398,7 +438,7 @@ The snapshot's data fields remain the values captured when `snapshot()` was call
|
|
|
398
438
|
|
|
399
439
|
### `gameUpdate(handler)`
|
|
400
440
|
|
|
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.
|
|
441
|
+
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
442
|
|
|
403
443
|
```ts
|
|
404
444
|
gameUpdate((dt, frame, viewport) => {
|
|
@@ -435,7 +475,7 @@ Reads current input; call it each frame. It invokes the listener immediately for
|
|
|
435
475
|
| `touchStart` | `{ x, y }` | Primary pointer press on the canvas |
|
|
436
476
|
| `touchEnd` | `{ x, y }` | Primary pointer release or cancellation |
|
|
437
477
|
|
|
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
|
|
478
|
+
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
479
|
|
|
440
480
|
```ts
|
|
441
481
|
gameEvent("keyDown", ({ key }) => {
|
|
@@ -448,7 +488,7 @@ gameEvent("touchStart", ({ x, y }) => {
|
|
|
448
488
|
|
|
449
489
|
### `gameViewport()`
|
|
450
490
|
|
|
451
|
-
Returns the canvas's current
|
|
491
|
+
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
492
|
|
|
453
493
|
```ts
|
|
454
494
|
const { width, height } = gameViewport();
|
|
@@ -514,7 +554,7 @@ The ID retains the resolved value's type for `gameAsyncThen`; widening it to pla
|
|
|
514
554
|
|
|
515
555
|
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
556
|
|
|
517
|
-
### `
|
|
557
|
+
### `gameTimeout(key)`
|
|
518
558
|
|
|
519
559
|
Returns the readonly tuple `[start, when, clear, timeRemaining]`.
|
|
520
560
|
|
|
@@ -531,7 +571,7 @@ The timeout starts inactive. By default, `when` clears it before calling the han
|
|
|
531
571
|
|
|
532
572
|
```ts
|
|
533
573
|
const [startTimeout, whenTimeout, clearTimeout, timeRemaining] =
|
|
534
|
-
|
|
574
|
+
gameTimeout("notice.timeout");
|
|
535
575
|
|
|
536
576
|
gameEvent("keyDown", ({ key }) => {
|
|
537
577
|
if (key === "n") startTimeout(2000);
|