create-dreamer-app 1.0.18 → 1.1.0
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 +1 -1
- package/template/DISCO_DREAMER_REFERENCE.md +54 -4
- package/template/package.json +7 -2
- package/template/vite.config.js +1 -0
- package/test/cli.test.js +0 -106
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.4.0 and TypeScript with JSX.
|
|
4
4
|
|
|
5
5
|
## How a game runs
|
|
6
6
|
|
|
@@ -147,9 +147,17 @@ The first call initializes the shared slot; later calls do not reset it. Literal
|
|
|
147
147
|
|
|
148
148
|
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.
|
|
149
149
|
|
|
150
|
-
### `createDynamicId()`
|
|
150
|
+
### `createDynamicId()` / `createDynamicId(count)`
|
|
151
151
|
|
|
152
|
-
Returns a fresh string ID
|
|
152
|
+
Returns a fresh string ID, or an array of fresh IDs when given a count.
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
const id = createDynamicId(); // string
|
|
156
|
+
const ids = createDynamicId(3); // string[]
|
|
157
|
+
const [playerId, enemyId] = createDynamicId(2);
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Generate IDs when spawning entities, store them with those entities, and reuse them across frames. Calling this function every frame generates new identities each time. A count of zero or a negative count returns an empty array.
|
|
153
161
|
|
|
154
162
|
## Drawing components
|
|
155
163
|
|
|
@@ -728,6 +736,48 @@ If `Sprite` display dimensions are omitted, they default to the source frame dim
|
|
|
728
736
|
|
|
729
737
|
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.
|
|
730
738
|
|
|
739
|
+
### `preloadImage(src)`
|
|
740
|
+
|
|
741
|
+
Starts loading an image before it is needed for drawing. Returns `void`. Repeated calls with the same source reuse the cached image.
|
|
742
|
+
|
|
743
|
+
```ts
|
|
744
|
+
preloadImage("/background.png");
|
|
745
|
+
preloadImage("/player.png");
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
Preloaded images share the cache used by `Sprite` and `gameAnimation`. Call this during setup to start loading assets early.
|
|
749
|
+
|
|
750
|
+
### `gameImageStatus(src)`
|
|
751
|
+
|
|
752
|
+
Returns the current status of an image without starting a load:
|
|
753
|
+
|
|
754
|
+
| Status | Meaning |
|
|
755
|
+
| --- | --- |
|
|
756
|
+
| `"unset"` | The source has not been requested. |
|
|
757
|
+
| `"loading"` | Loading has started, but the image is not ready. |
|
|
758
|
+
| `"ready"` | The image is loaded and available for drawing. |
|
|
759
|
+
| `"error"` | The image failed to load. |
|
|
760
|
+
|
|
761
|
+
```tsx
|
|
762
|
+
// During setup:
|
|
763
|
+
preloadImage("/player.png");
|
|
764
|
+
|
|
765
|
+
// Inside the game component, evaluated each frame:
|
|
766
|
+
const status = gameImageStatus("/player.png");
|
|
767
|
+
|
|
768
|
+
if (status === "error") {
|
|
769
|
+
return <Text value="Could not load the player image." />;
|
|
770
|
+
}
|
|
771
|
+
|
|
772
|
+
if (status !== "ready") {
|
|
773
|
+
return <Text value="Loading..." />;
|
|
774
|
+
}
|
|
775
|
+
|
|
776
|
+
return <Sprite src="/player.png" />;
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
Failed images remain cached as `"error"`; calling `preloadImage` again does not retry them.
|
|
780
|
+
|
|
731
781
|
### `gameImage(src)`
|
|
732
782
|
|
|
733
783
|
Returns a cached `HTMLImageElement` when loaded, otherwise `null`. Useful for checking dimensions or readiness. `Sprite` and `gameAnimation` already use it internally.
|
|
@@ -827,6 +877,6 @@ wrap([10, 20], 20); // 10
|
|
|
827
877
|
|
|
828
878
|
## Public API scope
|
|
829
879
|
|
|
830
|
-
The public components are `Scene`, `Sprite`, `Text`, `Rect`, `Circ`, `RigidBody2D`, `TouchArea`, `Bounds`, and `Sound`. The hooks described above, including `gameTouchArea`, plus `DreamFactory`, `registerRoot`, `createComparator`, `createDynamicId`, `sendMessage`, `addCustomFont`, `getFontStatus`, `isFontLoaded`, the vector helpers, and `wrap` are also exported.
|
|
880
|
+
The public components are `Scene`, `Sprite`, `Text`, `Rect`, `Circ`, `RigidBody2D`, `TouchArea`, `Bounds`, and `Sound`. The hooks described above, including `gameTouchArea`, plus `DreamFactory`, `registerRoot`, `createComparator`, `createDynamicId`, `preloadImage`, `sendMessage`, `addCustomFont`, `getFontStatus`, `isFontLoaded`, the vector helpers, and `wrap` are also exported.
|
|
831
881
|
|
|
832
882
|
Public type exports are `SceneProps`, `GameObject`, `Viewport`, `Vector2d`, `RigidBody2DSnapshot`, `GameRefResult`, `EventType`, and `TouchAreaEvent`. `GameRef` is no longer publicly exported. Other implementation files, including `Img`, `Txt`, browser input handlers, touch-area collection helpers, and the unfinished global helpers, are not public package exports.
|
package/template/package.json
CHANGED
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"scripts": {
|
|
7
7
|
"dev": "vite",
|
|
8
|
+
"dev:tunnel": "npx concurrently -k --raw \"npm run dev -- --strictPort\" \"npm run tunnel\"",
|
|
9
|
+
"tunnel": "npx cloudflared tunnel --url http://localhost:3000 2>&1 | node -e \"const seen = new Set(); require('node:readline').createInterface({ input: process.stdin }).on('line', line => { console.log(line); const url = line.match(/https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/); if (url && !seen.has(url[0])) { seen.add(url[0]); require('qrcode-terminal').generate(url[0], { small: true }); } });\"",
|
|
8
10
|
"typecheck": "tsc --noEmit",
|
|
9
11
|
"build": "npm run typecheck && vite build",
|
|
10
12
|
"preview": "vite preview"
|
|
@@ -18,10 +20,13 @@
|
|
|
18
20
|
"license": "ISC",
|
|
19
21
|
"devDependencies": {
|
|
20
22
|
"@types/node": "^26.6.4",
|
|
23
|
+
"cloudflared": "^0.7.3",
|
|
24
|
+
"concurrently": "^10.0.7",
|
|
25
|
+
"qrcode-terminal": "^0.12.0",
|
|
21
26
|
"typescript": "^7.0.2",
|
|
22
27
|
"vite": "^8.3.2"
|
|
23
28
|
},
|
|
24
29
|
"dependencies": {
|
|
25
|
-
"discodreamer": "^1.
|
|
30
|
+
"discodreamer": "^1.4.0"
|
|
26
31
|
}
|
|
27
|
-
}
|
|
32
|
+
}
|
package/template/vite.config.js
CHANGED
package/test/cli.test.js
DELETED
|
@@ -1,106 +0,0 @@
|
|
|
1
|
-
const assert = require("node:assert/strict");
|
|
2
|
-
const fs = require("node:fs/promises");
|
|
3
|
-
const os = require("node:os");
|
|
4
|
-
const path = require("node:path");
|
|
5
|
-
const { spawnSync } = require("node:child_process");
|
|
6
|
-
const { test } = require("node:test");
|
|
7
|
-
|
|
8
|
-
const cli = path.resolve(__dirname, "../index.js");
|
|
9
|
-
const reference = "DISCO_DREAMER_REFERENCE.md";
|
|
10
|
-
|
|
11
|
-
async function workspace(t) {
|
|
12
|
-
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "dreamer-cli-"));
|
|
13
|
-
t.after(() => fs.rm(directory, { recursive: true, force: true }));
|
|
14
|
-
return directory;
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
function run(cwd, args) {
|
|
18
|
-
const result = spawnSync(process.execPath, [cli, ...args], {
|
|
19
|
-
cwd,
|
|
20
|
-
encoding: "utf8",
|
|
21
|
-
timeout: 10000,
|
|
22
|
-
});
|
|
23
|
-
assert.ifError(result.error);
|
|
24
|
-
return result;
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
test("default app includes the reference and updates the package name", async (t) => {
|
|
28
|
-
const cwd = await workspace(t);
|
|
29
|
-
const result = run(cwd, ["my-app", "--skip-install"]);
|
|
30
|
-
assert.equal(result.status, 0, result.stderr);
|
|
31
|
-
assert.equal(await fs.readFile(path.join(cwd, "my-app", reference), "utf8"),
|
|
32
|
-
await fs.readFile(path.resolve(__dirname, "../template", reference), "utf8"));
|
|
33
|
-
const manifest = JSON.parse(await fs.readFile(path.join(cwd, "my-app/package.json"), "utf8"));
|
|
34
|
-
assert.equal(manifest.name, "my-app");
|
|
35
|
-
});
|
|
36
|
-
|
|
37
|
-
for (const flag of ["--ref-only", "-ro"]) {
|
|
38
|
-
test(`${flag} copies only the reference into the current existing project`, async (t) => {
|
|
39
|
-
const cwd = await workspace(t);
|
|
40
|
-
await fs.writeFile(path.join(cwd, "package.json"), '{"name":"existing"}\n');
|
|
41
|
-
const result = run(cwd, [flag]);
|
|
42
|
-
assert.equal(result.status, 0, result.stderr);
|
|
43
|
-
assert.deepEqual((await fs.readdir(cwd)).sort(), [reference, "package.json"]);
|
|
44
|
-
assert.equal(await fs.readFile(path.join(cwd, "package.json"), "utf8"), '{"name":"existing"}\n');
|
|
45
|
-
assert.doesNotMatch(result.stdout, /npm install|npm run dev|Installing dependencies/);
|
|
46
|
-
});
|
|
47
|
-
|
|
48
|
-
test(`${flag} supports a new nested destination without npm name restrictions`, async (t) => {
|
|
49
|
-
const cwd = await workspace(t);
|
|
50
|
-
const result = run(cwd, ["docs/Reference Notes", flag]);
|
|
51
|
-
assert.equal(result.status, 0, result.stderr);
|
|
52
|
-
assert.deepEqual(await fs.readdir(path.join(cwd, "docs/Reference Notes")), [reference]);
|
|
53
|
-
});
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
for (const flag of ["--exclude-reference", "-er"]) {
|
|
57
|
-
test(`${flag} excludes the reference while copying the app`, async (t) => {
|
|
58
|
-
const cwd = await workspace(t);
|
|
59
|
-
const result = run(cwd, [flag, "my-app", "--skip-install"]);
|
|
60
|
-
assert.equal(result.status, 0, result.stderr);
|
|
61
|
-
await assert.rejects(fs.access(path.join(cwd, "my-app", reference)), { code: "ENOENT" });
|
|
62
|
-
await fs.access(path.join(cwd, "my-app/package.json"));
|
|
63
|
-
await fs.access(path.join(cwd, "my-app/src/index.tsx"));
|
|
64
|
-
});
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
test("reference-only refuses to overwrite an existing reference", async (t) => {
|
|
68
|
-
const cwd = await workspace(t);
|
|
69
|
-
await fs.writeFile(path.join(cwd, reference), "custom reference");
|
|
70
|
-
const result = run(cwd, ["--ref-only"]);
|
|
71
|
-
assert.equal(result.status, 1);
|
|
72
|
-
assert.match(result.stderr, /Reference already exists/);
|
|
73
|
-
assert.equal(await fs.readFile(path.join(cwd, reference), "utf8"), "custom reference");
|
|
74
|
-
});
|
|
75
|
-
|
|
76
|
-
test("conflicting modes fail before creating files for all aliases", async (t) => {
|
|
77
|
-
const cwd = await workspace(t);
|
|
78
|
-
for (const refFlag of ["--ref-only", "-ro"]) {
|
|
79
|
-
for (const excludeFlag of ["--exclude-reference", "-er"]) {
|
|
80
|
-
const result = run(cwd, ["my-app", refFlag, excludeFlag]);
|
|
81
|
-
assert.equal(result.status, 1);
|
|
82
|
-
assert.match(result.stderr, /cannot be used together/);
|
|
83
|
-
}
|
|
84
|
-
}
|
|
85
|
-
assert.deepEqual(await fs.readdir(cwd), []);
|
|
86
|
-
});
|
|
87
|
-
|
|
88
|
-
test("existing app safeguards and argument validation still apply", async (t) => {
|
|
89
|
-
const cwd = await workspace(t);
|
|
90
|
-
await fs.writeFile(path.join(cwd, "keep.txt"), "keep");
|
|
91
|
-
for (const args of [[".", "--skip-install"], [".", "-er", "--skip-install"]]) {
|
|
92
|
-
const result = run(cwd, args);
|
|
93
|
-
assert.equal(result.status, 1);
|
|
94
|
-
assert.match(result.stderr, /not an empty directory/);
|
|
95
|
-
}
|
|
96
|
-
assert.match(run(cwd, ["--unknown"]).stderr, /Unknown option/);
|
|
97
|
-
assert.match(run(cwd, ["a", "b", "-ro"]).stderr, /only one project directory/);
|
|
98
|
-
assert.deepEqual(await fs.readdir(cwd), ["keep.txt"]);
|
|
99
|
-
});
|
|
100
|
-
|
|
101
|
-
test("help documents both reference modes and aliases", async (t) => {
|
|
102
|
-
const result = run(await workspace(t), ["--help"]);
|
|
103
|
-
assert.equal(result.status, 0, result.stderr);
|
|
104
|
-
assert.match(result.stdout, /-ro, --ref-only/);
|
|
105
|
-
assert.match(result.stdout, /-er, --exclude-reference/);
|
|
106
|
-
});
|