create-dreamer-app 1.0.10 → 1.0.12
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.0.9 and TypeScript with JSX.
|
|
4
4
|
|
|
5
5
|
## How a game runs
|
|
6
6
|
|
|
@@ -88,9 +88,21 @@ setScore((previous) => previous + 1);
|
|
|
88
88
|
|
|
89
89
|
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
90
|
|
|
91
|
-
Internally, consecutive stateful calls using the same key
|
|
91
|
+
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.
|
|
92
92
|
|
|
93
|
-
|
|
93
|
+
Prefix a `gameState` key with `$` to use it literally, bypassing numbering. The `$` remains part of the stored key. Every call with the same literal key shares one state slot, regardless of call location or loop iteration:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const [, setScore] = gameState("$score", 0);
|
|
97
|
+
setScore((previous) => previous + 1);
|
|
98
|
+
|
|
99
|
+
// Elsewhere in the same frame:
|
|
100
|
+
const [score] = gameState("$score", 0); // Reads the incremented score.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The first call initializes the shared slot; later calls do not reset it. Literal keys do not advance or reset ordinary-key numbering. The `$` rule is implemented in `gameState`, so helpers that call it internally also inherit it. Use ordinary keys for those helpers, especially `gameAnimation`, which needs multiple numbered slots for a single key. Hooks that resolve keys directly, such as `gameEffect`, retain normal numbering.
|
|
104
|
+
|
|
105
|
+
State that is no longer used is removed during frame cleanup. This also applies to `$` keys: sharing a slot does not make it permanent. If an entity disappears for a frame and returns later, expect its state to initialize again.
|
|
94
106
|
|
|
95
107
|
### `createDynamicId()`
|
|
96
108
|
|
|
@@ -420,10 +432,12 @@ Creates an animation descriptor for `Sprite`. `animations` is an ordered array o
|
|
|
420
432
|
|
|
421
433
|
Config requires `src` and `size` (the square frame size in source pixels). Optional `fps` defaults to `24`; `loop` defaults to `true`. A frame group's `{ loop }` overrides that default. Switching the selected group restarts its timing.
|
|
422
434
|
|
|
435
|
+
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.
|
|
436
|
+
|
|
423
437
|
```tsx
|
|
424
438
|
function AnimatedPlayer({ moving }: { moving: boolean }) {
|
|
425
439
|
const animation = gameAnimation("player.animation", [
|
|
426
|
-
[moving, [4, 5, 6, 7]],
|
|
440
|
+
[moving, [4, 5, 6, 7], { fps: 12 }],
|
|
427
441
|
[true, [0, 1, 2, 3]],
|
|
428
442
|
], { src: "/player-sheet.png", size: 32, fps: 8 });
|
|
429
443
|
|
|
@@ -431,6 +445,8 @@ function AnimatedPlayer({ moving }: { moving: boolean }) {
|
|
|
431
445
|
}
|
|
432
446
|
```
|
|
433
447
|
|
|
448
|
+
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.
|
|
449
|
+
|
|
434
450
|
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.
|
|
435
451
|
|
|
436
452
|
### `gameImage(src)`
|