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
  {
2
2
  "name": "create-dreamer-app",
3
- "version": "1.0.14",
3
+ "version": "1.0.16",
4
4
  "description": "The scaffolding application for using Disco Dreamer.",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -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.0 and TypeScript with JSX.
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, with `(0, 0)` at the canvas's top-left, positive `x` to the right, and positive `y` downward.
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 pixels |
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 pixels.
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 CSS size as `{ width, height }`. Use this for responsive placement; the engine handles the canvas backing resolution for device pixel ratio.
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
- ### `gameTimeOut(key)`
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
- gameTimeOut("notice.timeout");
577
+ gameTimeout("notice.timeout");
535
578
 
536
579
  gameEvent("keyDown", ({ key }) => {
537
580
  if (key === "n") startTimeout(2000);
@@ -22,6 +22,6 @@
22
22
  "vite": "^8.3.2"
23
23
  },
24
24
  "dependencies": {
25
- "discodreamer": "^1.1.0"
25
+ "discodreamer": "^1.2.1"
26
26
  }
27
27
  }