create-dreamer-app 1.0.15 → 1.0.17

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.15",
3
+ "version": "1.0.17",
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.2.0 and TypeScript with JSX.
3
+ A practical guide to building browser games with `discodreamer`. Examples use the public API in version 1.2.2 and TypeScript with JSX.
4
4
 
5
5
  ## How a game runs
6
6
 
@@ -73,18 +73,21 @@ The examples below are independent excerpts; add their named imports from `disco
73
73
 
74
74
  ### `registerRoot(Root, config?)`
75
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:
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
77
 
78
78
  ```ts
79
+ registerRoot(Game); // Defaults to CSS-pixel coordinates.
80
+ // Or explicitly select a coordinate mode:
81
+ registerRoot(Game, { units: "pixels" });
79
82
  registerRoot(Game, { units: "scale", scaling: 0.01 });
80
83
  ```
81
84
 
82
- When supplying a config, include both fields:
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 }`:
83
86
 
84
87
  | Field | Values | Behavior |
85
88
  | --- | --- | --- |
86
89
  | `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 |
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 |
88
91
 
89
92
  In scale mode, the engine recalculates the CSS-pixel size of one game unit before building the tree each frame:
90
93
 
@@ -96,7 +99,7 @@ With `scaling: 0.01`, one game unit occupies 1% of the shorter canvas dimension,
96
99
 
97
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.
98
101
 
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.
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.
100
103
 
101
104
  ## State and keys
102
105
 
@@ -187,8 +190,9 @@ Displays an image or a sprite-sheet animation. Supply exactly one of `src` or `a
187
190
  | --- | --- |
188
191
  | `src` | Image URL for a static sprite |
189
192
  | `animation` | Result of `gameAnimation` |
193
+ | `subregion` | Optional source rectangle `{ x, y, width, height }`; available only with `src` |
190
194
  | `x`, `y`, `z` | Position and sibling draw order; default `0` |
191
- | `width`, `height` | Display size; defaults to image dimensions or animation frame size |
195
+ | `width`, `height` | Display size; defaults to subregion dimensions, animation frame size, or full image dimensions |
192
196
  | `rotation` | Degrees around the pivot point; default `0` |
193
197
  | `pivot` | Normalized rotation point; default `{ x: 0.5, y: 0.5 }` (center) |
194
198
 
@@ -196,6 +200,14 @@ Displays an image or a sprite-sheet animation. Supply exactly one of `src` or `a
196
200
  <Sprite src="/player.png" x={100} y={80} width={64} height={64} />
197
201
  ```
198
202
 
203
+ Use `subregion` to display part of a source image. Its coordinates and dimensions are in source-image pixels, measured from the image's top-left corner. The sprite's `x` and `y` still control its position in the scene; its `width` and `height` scale the selected region when provided. Without display dimensions, this example draws at 16×16:
204
+
205
+ ```tsx
206
+ <Sprite src="/spritesheet.png"
207
+ subregion={{ x: 32, y: 0, width: 16, height: 16 }}
208
+ x={100} y={80} />
209
+ ```
210
+
199
211
  The sprite's position is its unrotated top-left corner. Images are cached by URL, and a sprite draws nothing until its image is ready. Rotation affects drawing, not physics bounds.
200
212
 
201
213
  Pivot coordinates are fractions of the displayed width and height: `{ x: 0, y: 0 }` is the top-left, and `{ x: 1, y: 1 }` is the bottom-right. The pivot applies to both static images and animation frames. Changing it changes the rotation point while preserving the image's unrotated top-left position. For example, rotate a sword near its handle:
@@ -22,6 +22,6 @@
22
22
  "vite": "^8.3.2"
23
23
  },
24
24
  "dependencies": {
25
- "discodreamer": "^1.2.0"
25
+ "discodreamer": "^1.2.2"
26
26
  }
27
27
  }