create-dreamer-app 1.0.13 → 1.0.14
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.0
|
|
3
|
+
A practical guide to building browser games with `discodreamer`. Examples use the public API in version 1.1.0 and TypeScript with JSX.
|
|
4
4
|
|
|
5
5
|
## How a game runs
|
|
6
6
|
|
|
@@ -149,7 +149,8 @@ Displays an image or a sprite-sheet animation. Supply exactly one of `src` or `a
|
|
|
149
149
|
| `animation` | Result of `gameAnimation` |
|
|
150
150
|
| `x`, `y`, `z` | Position and sibling draw order; default `0` |
|
|
151
151
|
| `width`, `height` | Display size; defaults to image dimensions or animation frame size |
|
|
152
|
-
| `rotation` | Degrees around the
|
|
152
|
+
| `rotation` | Degrees around the pivot point; default `0` |
|
|
153
|
+
| `pivot` | Normalized rotation point; default `{ x: 0.5, y: 0.5 }` (center) |
|
|
153
154
|
|
|
154
155
|
```tsx
|
|
155
156
|
<Sprite src="/player.png" x={100} y={80} width={64} height={64} />
|
|
@@ -157,6 +158,13 @@ Displays an image or a sprite-sheet animation. Supply exactly one of `src` or `a
|
|
|
157
158
|
|
|
158
159
|
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.
|
|
159
160
|
|
|
161
|
+
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:
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
<Sprite src="/sword.png" x={100} y={80}
|
|
165
|
+
pivot={{ x: 0.5, y: 0.9 }} rotation={45} />
|
|
166
|
+
```
|
|
167
|
+
|
|
160
168
|
### `Text`
|
|
161
169
|
|
|
162
170
|
Draws left-aligned, top-aligned text in the supplied `color`, or white by default. Uses `sans-serif` unless a font family is supplied.
|
|
@@ -258,7 +266,8 @@ A stateful moving body. Put drawing components and one or more `Bounds` inside i
|
|
|
258
266
|
| `forces` | `[]` | Force vectors in newtons, applied each frame |
|
|
259
267
|
| `drag` | `0` | Exponential velocity damping per second |
|
|
260
268
|
| `restitution` | `1` | Bounce factor; `0` removes bounce; a pair uses the lower factor |
|
|
261
|
-
| `
|
|
269
|
+
| `interactionMode` | `"body"` | Selects whether interaction settings belong to the body or its bounds |
|
|
270
|
+
| `layer` | Unset | Layer name used by other colliders' filters; body mode only |
|
|
262
271
|
| `collidesWith` | `[]` | Layers eligible for physical collision |
|
|
263
272
|
| `hitsWith` | `[]` | Layers to report overlap with, without requiring physical response |
|
|
264
273
|
| `ref` | Unset | Key returned by `gameRef` |
|
|
@@ -267,6 +276,13 @@ A stateful moving body. Put drawing components and one or more `Bounds` inside i
|
|
|
267
276
|
|
|
268
277
|
Physics treats one world unit as one centimeter. The renderer displays one unit as one CSS pixel.
|
|
269
278
|
|
|
279
|
+
Choose one place for interaction settings per body:
|
|
280
|
+
|
|
281
|
+
- In `interactionMode="body"` (the default), set `layer`, `collidesWith`, and `hitsWith` on `RigidBody2D`. All its bounds use these settings. Supplying any of these settings on an owned bound, including an empty array, throws an error during physics collection.
|
|
282
|
+
- In `interactionMode="bounds"`, set those properties on individual `Bounds`. Body-level interaction settings are forbidden by the prop types. Each bound uses its own settings, with no fallback to the body.
|
|
283
|
+
|
|
284
|
+
The mode selects interaction settings only. Bounds still belong to the body; movement, mass, restitution, and contact-hook identity remain at body level.
|
|
285
|
+
|
|
270
286
|
Keep `x`, `y`, `velocity`, and `mass` props stable to let the simulation evolve. Changing any of these inputs resets the body's stored position, velocity, and mass to the currently supplied values. For movement that does not reset the body, use forces. `onChange` runs initially and on tracked changes; velocity comparisons use a threshold of `1` unit/s, while position changes also trigger it.
|
|
271
287
|
|
|
272
288
|
### `Bounds`
|
|
@@ -282,14 +298,26 @@ Defines collision geometry owned by its containing body. Choose either rectangle
|
|
|
282
298
|
|
|
283
299
|
Rectangle bounds use their top-left corner; circle bounds use their center. `position` is a local offset (default `{ x: 0, y: 0 }`). Optional `outline` displays the geometry for debugging; `style` controls its fill/stroke and `z` controls its visual sibling order. Bounds are invisible by default. Standalone bounds outside a body do not participate in physics.
|
|
284
300
|
|
|
301
|
+
In bounds mode, `layer`, `collidesWith`, and `hitsWith` are optional. An omitted layer is unset; omitted interaction lists behave as `[]`. These settings replace body-level configuration entirely. For example, give a static body one solid bound and a separate sensor:
|
|
302
|
+
|
|
303
|
+
```tsx
|
|
304
|
+
<RigidBody2D key="platform" y={300} mass={0} interactionMode="bounds">
|
|
305
|
+
<Bounds width={200} height={20}
|
|
306
|
+
layer="ground" collidesWith={["player"]} />
|
|
307
|
+
<Bounds width={200} height={40} position={{ x: 0, y: -40 }}
|
|
308
|
+
layer="sensor" hitsWith={["player"]} />
|
|
309
|
+
</RigidBody2D>
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
A player with `layer="player"` and `collidesWith={["ground"]}` can physically collide with the ground. The sensor reports hits through `gameHit("platform", ...)` without causing physical response.
|
|
313
|
+
|
|
285
314
|
### `gameCollision(key, handler)` and `gameHit(key, handler)`
|
|
286
315
|
|
|
287
|
-
Call these each frame with the body's public `key`.
|
|
316
|
+
Call these each frame with the body's public `key`. Each handler receives `(otherKey: string, otherLayer: string, ownLayer: string | undefined)`. `otherKey` is the other body's public key; `otherLayer` and `ownLayer` are the effective layers of the two contacting bounds, selected according to each body's interaction mode. Existing callbacks accepting only two arguments remain valid.
|
|
288
317
|
|
|
289
|
-
-
|
|
290
|
-
-
|
|
291
|
-
-
|
|
292
|
-
- Hits are directional: only the observing body's `hitsWith` needs to include the other body's layer. The observing body does not need its own layer.
|
|
318
|
+
- Physical collisions require both contacting bounds' effective `collidesWith` lists to include the other's effective layer. Both layers are defined for a physical collision.
|
|
319
|
+
- Hits are directional: only the observing bound's effective `hitsWith` needs to include the other bound's effective layer. `otherLayer` is always defined; `ownLayer` can be `undefined` for a hit.
|
|
320
|
+
- For each observing body key, events are grouped by the other body's public key and both effective layers. Multiple contacts with the same combination produce one callback per frame; distinct layer pairs produce separate callbacks, even when the other body is the same.
|
|
293
321
|
- Hits alone do not separate bodies or change their velocities.
|
|
294
322
|
- Hooks read the previous frame's contact results because the current collision pass happens after tree construction. Contacts are reported repeatedly while detected; these are not enter/exit events.
|
|
295
323
|
|
|
@@ -299,8 +327,10 @@ function PhysicsExample() {
|
|
|
299
327
|
if (otherLayer === "world") console.log("Ball contacted world body:", otherKey);
|
|
300
328
|
});
|
|
301
329
|
|
|
302
|
-
gameHit("ball", (otherKey, otherLayer) => {
|
|
303
|
-
if (otherLayer === "world")
|
|
330
|
+
gameHit("ball", (otherKey, otherLayer, ownLayer) => {
|
|
331
|
+
if (otherLayer === "world") {
|
|
332
|
+
console.log("Ball overlapped world body:", otherKey, "using layer:", ownLayer);
|
|
333
|
+
}
|
|
304
334
|
});
|
|
305
335
|
|
|
306
336
|
return (
|
|
@@ -550,7 +580,7 @@ Use an ordinary key for `gameInterval`, not a `$` literal key: the interval stor
|
|
|
550
580
|
|
|
551
581
|
Creates an animation descriptor for `Sprite`. `animations` is an ordered array of `[condition, frames, options?]`; the first true condition wins. A condition can be a boolean or a function returning a boolean. Frame numbers are zero-based, counted left to right and then top to bottom across the sheet.
|
|
552
582
|
|
|
553
|
-
Config requires `src` and `size
|
|
583
|
+
Config requires `src` and `size`, which describes each frame in source pixels. Use a number for square frames (`size: 32`) or an object for rectangular frames (`size: { width: 32, height: 48 }`). Frames must form a regular grid with no spacing or margins; width determines the number of columns, and height determines row offsets. Optional `fps` defaults to `24`; `loop` defaults to `true`. A frame group's `{ loop }` overrides that default. Switching the selected group restarts its timing.
|
|
554
584
|
|
|
555
585
|
Each frame group's optional third item also accepts `fps`, for example `{ fps: 12 }` or `{ fps: 12, loop: false }`. A group's `fps` overrides the config's `fps`; when omitted, the group inherits the config rate (or the default of `24`). Use a positive FPS for normal playback. The group's rate controls both frame progression and completion timing.
|
|
556
586
|
|
|
@@ -567,6 +597,19 @@ function AnimatedPlayer({ moving }: { moving: boolean }) {
|
|
|
567
597
|
|
|
568
598
|
The moving group plays at 12 FPS; the fallback group inherits 8 FPS from config. Switching groups restarts playback at the newly selected group's rate.
|
|
569
599
|
|
|
600
|
+
For rectangular frames, configure the source dimensions independently from the display size:
|
|
601
|
+
|
|
602
|
+
```tsx
|
|
603
|
+
const animation = gameAnimation("character.animation", [
|
|
604
|
+
[true, [0, 1, 2, 3]],
|
|
605
|
+
], { src: "/character-sheet.png", size: { width: 32, height: 48 } });
|
|
606
|
+
|
|
607
|
+
// Display each 32 × 48 source frame at twice its size:
|
|
608
|
+
return <Sprite animation={animation} width={64} height={96} />;
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
If `Sprite` display dimensions are omitted, they default to the source frame dimensions. Numeric `size` values continue to work unchanged.
|
|
612
|
+
|
|
570
613
|
Use a final `true` condition as a fallback. A non-looping group holds its final frame. Call `animation.onAnimationFinish(handler)` each frame to handle its completion transition; it is not a persistent listener. Keep the source URL unchanged for an animation key, and use a positive frame size that fits the sheet.
|
|
571
614
|
|
|
572
615
|
### `gameImage(src)`
|