@celljs/ta-games 0.0.0-stage → 4.11.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/README.en.md +47 -0
- package/README.md +46 -2
- package/host/index.mjs +65 -0
- package/package.json +58 -4
- package/skills/ta-game/SKILL.md +127 -0
- package/skills/ta-game/examples/dino-run/package.json +22 -0
- package/skills/ta-game/examples/dino-run/web.js +389 -0
- package/skills/ta-game/examples/stack/package.json +22 -0
- package/skills/ta-game/examples/stack/web.js +423 -0
- package/skills/ta-game/phaser/LICENSE.md +22 -0
- package/skills/ta-game/phaser/actions-and-utilities/SKILL.md +343 -0
- package/skills/ta-game/phaser/animations/SKILL.md +481 -0
- package/skills/ta-game/phaser/audio-and-sound/SKILL.md +453 -0
- package/skills/ta-game/phaser/cameras/SKILL.md +497 -0
- package/skills/ta-game/phaser/cameras/references/REFERENCE.md +128 -0
- package/skills/ta-game/phaser/curves-and-paths/SKILL.md +359 -0
- package/skills/ta-game/phaser/data-manager/SKILL.md +406 -0
- package/skills/ta-game/phaser/events-system/SKILL.md +497 -0
- package/skills/ta-game/phaser/filters-and-postfx/SKILL.md +449 -0
- package/skills/ta-game/phaser/game-object-components/SKILL.md +478 -0
- package/skills/ta-game/phaser/game-object-components/references/REFERENCE.md +76 -0
- package/skills/ta-game/phaser/game-setup-and-config/SKILL.md +485 -0
- package/skills/ta-game/phaser/geometry-and-math/SKILL.md +497 -0
- package/skills/ta-game/phaser/graphics-and-shapes/SKILL.md +473 -0
- package/skills/ta-game/phaser/groups-and-containers/SKILL.md +418 -0
- package/skills/ta-game/phaser/input-keyboard-mouse-touch/SKILL.md +500 -0
- package/skills/ta-game/phaser/input-keyboard-mouse-touch/references/REFERENCE.md +372 -0
- package/skills/ta-game/phaser/loading-assets/SKILL.md +474 -0
- package/skills/ta-game/phaser/loading-assets/references/REFERENCE.md +148 -0
- package/skills/ta-game/phaser/particles/SKILL.md +499 -0
- package/skills/ta-game/phaser/particles/references/REFERENCE.md +17 -0
- package/skills/ta-game/phaser/physics-arcade/SKILL.md +468 -0
- package/skills/ta-game/phaser/physics-matter/SKILL.md +499 -0
- package/skills/ta-game/phaser/render-textures/SKILL.md +441 -0
- package/skills/ta-game/phaser/scale-and-responsive/SKILL.md +371 -0
- package/skills/ta-game/phaser/scenes/SKILL.md +450 -0
- package/skills/ta-game/phaser/scenes/references/REFERENCE.md +78 -0
- package/skills/ta-game/phaser/sprites-and-images/SKILL.md +417 -0
- package/skills/ta-game/phaser/sprites-and-images/references/REFERENCE.md +160 -0
- package/skills/ta-game/phaser/text-and-bitmaptext/SKILL.md +460 -0
- package/skills/ta-game/phaser/tilemaps/SKILL.md +440 -0
- package/skills/ta-game/phaser/time-and-timers/SKILL.md +496 -0
- package/skills/ta-game/phaser/tweens/SKILL.md +414 -0
- package/skills/ta-game/phaser/v3-to-v4-migration/SKILL.md +430 -0
- package/skills/ta-game/phaser/v4-new-features/SKILL.md +384 -0
- package/skills/ta-game/phaser/v4-new-features/references/REFERENCE.md +69 -0
- package/web/index.js +431 -0
package/README.en.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Cell - Ta Games
|
|
2
|
+
|
|
3
|
+
A pi package that comes with Ta (on by default; Settings → Extensions turns it off): games. Ta's web page has two game engines, Phaser 4 for 2D (`pi.ui.Game`) and Three.js for 3D (`pi.ui.Game3D`); on them, this package has:
|
|
4
|
+
|
|
5
|
+
- **The Games page**, under Discover and in Quick open (started on open: loaded only when opened). At the top, every extension that is a game (a package whose `package.json` says `"pi": { "category": "game" }`: the examples, those Ta made, those of the market), opened with a tap (its package says `"lists": ["game"]`, so the games themselves are not under Discover or in the navigation, only here and in Quick open); below, "Have Ta make one": Snake, Breakout, a 3D maze, the scheduled tasks drawn as a little world, each opening a new conversation in which Ta makes it.
|
|
6
|
+
- **Two example games**: Dino Run (2D, Phaser: a pixel dinosaur jumps cacti that come faster and faster, with space or a tap) and Stack (3D, Three.js: a tap drops the block that slides over the tower, what hangs over is cut off). They are ordinary extensions, each one `web.js` of plain JavaScript as Ta writes games, in `skills/ta-game/examples/`. The first time the Games page opens they are copied to `~/.ta/agent/extensions/`, and are then the user's own: turned off, deleted, shared or changed by Ta each on its own; one deleted is not put back by itself, "Install the examples" at the top right of the Games page does. Each keeps its best score in its package data, the same on every device.
|
|
7
|
+
- **The `ta-game` skill**, which teaches Ta to write games and extensions that play like games (a pet in a card of the board, a widget that moves, scores and rewards) with `pi.ui.Game` and `pi.ui.Game3D`: no import and no engine of its own, one code for touch and mouse, the colors of the theme, asleep out of sight, best scores in `pi.storage`, and what most often differs from Phaser 3 to 4 and from older Three.js to r187. Saying "make a Snake game" in a conversation uses it too.
|
|
8
|
+
- **Phaser's topics**: the 28 topics the npm package of Phaser 4 writes for coding agents (scenes, input, tweens, physics, particles...), copied at build time to `skills/ta-game/phaser/` (`scripts/phaser-skills.mjs`). Under the directory of a skill, pi does not take them for skills: they cost nothing in every conversation, and Ta reads them when needed.
|
|
9
|
+
|
|
10
|
+
The least a game with `pi.ui.Game` takes:
|
|
11
|
+
|
|
12
|
+
```js
|
|
13
|
+
export default function (pi) {
|
|
14
|
+
const h = pi.React.createElement;
|
|
15
|
+
function Page() {
|
|
16
|
+
const config = pi.React.useCallback((Phaser, page) => ({
|
|
17
|
+
width: 480,
|
|
18
|
+
height: 270,
|
|
19
|
+
scene: { create() { this.add.circle(240, 135, 14, page.colors.green); } },
|
|
20
|
+
}), []);
|
|
21
|
+
return h('div', { style: { display: 'flex', flexDirection: 'column', height: '100%' } }, h(pi.ui.Game, { config }));
|
|
22
|
+
}
|
|
23
|
+
pi.registerView('ball', { title: 'Ball', render: Page });
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The least a 3D game takes:
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
const setup = ({ THREE, scene, camera, page }) => {
|
|
31
|
+
camera.position.set(3, 3, 5);
|
|
32
|
+
camera.lookAt(0, 0, 0);
|
|
33
|
+
scene.add(new THREE.HemisphereLight(0xffffff, 0x707070, 1.8));
|
|
34
|
+
const cube = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshLambertMaterial({ color: page.colors.green }));
|
|
35
|
+
scene.add(cube);
|
|
36
|
+
return { update(seconds) { cube.rotation.y += seconds; } };
|
|
37
|
+
};
|
|
38
|
+
// h(pi.ui.Game3D, { setup })
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The choice of the engines and the design: docs/design/ta-games.md. The package holds a web extension (`pi.web`), skills (`pi.skills`) and a server side (`pi.host`, which copies the examples), and uses only the public `WebExtensionAPI` and `TaExtensionHost`. The rules of the examples (`DinoRules`, `StackRules`) are apart from what draws them, tested by `web-src/examples.spec.ts`, which loads their `web.js`.
|
|
42
|
+
|
|
43
|
+
## Limits
|
|
44
|
+
|
|
45
|
+
- 3D is Three.js itself and OrbitControls: no loader of models, post-processing or physics.
|
|
46
|
+
- Browsers allow a few WebGL contexts at once (Chrome some 16): with many games shown at once, the first ones lose their picture.
|
|
47
|
+
- Other coding agents (`@celljs/ta-agents`) do not see pi's skills: the message of "Have Ta make one" names the files of both SKILL.md; when asking in a conversation, tell it to read them.
|
package/README.md
CHANGED
|
@@ -1,3 +1,47 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell - Ta Games
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ta 自带的 pi 包(默认开启,可在 Web 客户端的 设置 → 扩展 关闭):游戏。Ta Web 的页面自带两个游戏引擎:2D 的 Phaser 4(`pi.ui.Game`)和 3D 的 Three.js(`pi.ui.Game3D`),这个包在它们之上提供:
|
|
4
|
+
|
|
5
|
+
- **"游戏"页**:在"发现"和快捷打开里(按需启动:点开才加载)。上面列出所有游戏扩展(`package.json` 里写了 `"pi": { "category": "game" }` 的包:示例、Ta 做的、市场装的),点一下打开(包里的 `"lists": ["game"]` 认领这一类,各个游戏不再出现在"发现"和导航栏里,只在这一页和快捷打开里);下面是"让 Ta 做一个":贪吃蛇、打砖块、3D 迷宫、把定时任务画成小世界,点一下就开一个新对话让 Ta 做。
|
|
6
|
+
- **两个示例游戏**:恐龙快跑(2D,Phaser:像素恐龙跳过越来越快的仙人掌,空格键或轻点起跳)和叠方块(3D,Three.js:轻点放下在塔顶滑动的方块,伸出去的部分被切掉)。它们是普通的扩展,只有一个纯 JavaScript 的 `web.js`,和 Ta 写出来的游戏一样,放在 `skills/ta-game/examples/`。第一次打开"游戏"页时复制到 `~/.ta/agent/extensions/`,之后就是用户自己的扩展,可以单独关掉、删除、分享,或让 Ta 修改;删掉的不会再自动装回,"游戏"页右上角的"安装示例游戏"可以重新装。最高分存各自的包数据,各设备同步。
|
|
7
|
+
- **`ta-game` 技能**:教 Ta 用 `pi.ui.Game` 和 `pi.ui.Game3D` 写游戏和游戏风格的扩展(看板卡片里的宠物、会动的小组件、积分与奖励):不 import、不自带引擎、触摸与鼠标一套、跟随主题、看不见时休眠、最高分存 `pi.storage`,以及 Phaser 3 到 4、旧版 Three.js 到 r187 的常见差异。直接在对话里说"做一个贪吃蛇"也会用到它。
|
|
8
|
+
- **Phaser 的主题文档**:Phaser 4 的 npm 包给 coding agent 写的 28 个主题(场景、输入、补间、物理、粒子……),构建时复制到 `skills/ta-game/phaser/`(`scripts/phaser-skills.mjs`)。它们在技能目录下面,pi 不把它们当作技能,不占每次对话的提示,Ta 需要时去读。
|
|
9
|
+
|
|
10
|
+
用 `pi.ui.Game` 的最小写法:
|
|
11
|
+
|
|
12
|
+
```js
|
|
13
|
+
export default function (pi) {
|
|
14
|
+
const h = pi.React.createElement;
|
|
15
|
+
function Page() {
|
|
16
|
+
const config = pi.React.useCallback((Phaser, page) => ({
|
|
17
|
+
width: 480,
|
|
18
|
+
height: 270,
|
|
19
|
+
scene: { create() { this.add.circle(240, 135, 14, page.colors.green); } },
|
|
20
|
+
}), []);
|
|
21
|
+
return h('div', { style: { display: 'flex', flexDirection: 'column', height: '100%' } }, h(pi.ui.Game, { config }));
|
|
22
|
+
}
|
|
23
|
+
pi.registerView('ball', { title: 'Ball', render: Page });
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
3D 的最小写法:
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
const setup = ({ THREE, scene, camera, page }) => {
|
|
31
|
+
camera.position.set(3, 3, 5);
|
|
32
|
+
camera.lookAt(0, 0, 0);
|
|
33
|
+
scene.add(new THREE.HemisphereLight(0xffffff, 0x707070, 1.8));
|
|
34
|
+
const cube = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshLambertMaterial({ color: page.colors.green }));
|
|
35
|
+
scene.add(cube);
|
|
36
|
+
return { update(seconds) { cube.rotation.y += seconds; } };
|
|
37
|
+
};
|
|
38
|
+
// h(pi.ui.Game3D, { setup })
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
选型和设计见 docs/design/ta-games.md。包里有 Web 扩展(`pi.web`)、技能(`pi.skills`)和服务端(`pi.host`,复制示例),只用公开的 `WebExtensionAPI` 和 `TaExtensionHost`。示例的规则(`DinoRules`、`StackRules`)与绘制分开,由 `web-src/examples.spec.ts` 直接加载 `web.js` 来测。
|
|
42
|
+
|
|
43
|
+
## 限制
|
|
44
|
+
|
|
45
|
+
- 3D 只有 Three.js 本体和 OrbitControls:没有模型加载器、后期处理和物理引擎。
|
|
46
|
+
- 浏览器同时能用的 WebGL 上下文有限(Chrome 约 16 个),同时显示很多游戏时最早的会丢失画面。
|
|
47
|
+
- 外部 Agent(`@celljs/ta-agents`)看不到 pi 的技能:"让 Ta 做一个"的消息里写明了两份 SKILL.md 的路径;在对话里直接说时,可以提醒它读这两份文件。
|
package/host/index.mjs
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// web-src/host.ts
|
|
2
|
+
import { cpSync, existsSync, readdirSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
var NAME = "@celljs/ta-games";
|
|
5
|
+
var OFFERED = "examplesOffered";
|
|
6
|
+
|
|
7
|
+
class GamesService {
|
|
8
|
+
host;
|
|
9
|
+
examplesDir;
|
|
10
|
+
constructor(host, examplesDir) {
|
|
11
|
+
this.host = host;
|
|
12
|
+
this.examplesDir = examplesDir;
|
|
13
|
+
}
|
|
14
|
+
dispose() {}
|
|
15
|
+
async examples() {
|
|
16
|
+
const from = await this.from();
|
|
17
|
+
return this.names(from).map((name) => ({ name, installed: existsSync(this.target(name)) }));
|
|
18
|
+
}
|
|
19
|
+
async offerExamples() {
|
|
20
|
+
const from = await this.from();
|
|
21
|
+
const offered = new Set(await this.host.getExtensionData(NAME, OFFERED) ?? []);
|
|
22
|
+
const copied = this.names(from).filter((name) => !offered.has(name) && this.copy(from, name));
|
|
23
|
+
const names = this.names(from);
|
|
24
|
+
if (names.some((name) => !offered.has(name))) {
|
|
25
|
+
await this.host.setExtensionData(NAME, OFFERED, [...new Set([...offered, ...names])]);
|
|
26
|
+
}
|
|
27
|
+
return copied;
|
|
28
|
+
}
|
|
29
|
+
async installExamples() {
|
|
30
|
+
const from = await this.from();
|
|
31
|
+
return this.names(from).filter((name) => this.copy(from, name));
|
|
32
|
+
}
|
|
33
|
+
copy(from, name) {
|
|
34
|
+
const target = this.target(name);
|
|
35
|
+
if (existsSync(target)) {
|
|
36
|
+
return false;
|
|
37
|
+
}
|
|
38
|
+
cpSync(join(from, name), target, { recursive: true });
|
|
39
|
+
return true;
|
|
40
|
+
}
|
|
41
|
+
target(name) {
|
|
42
|
+
return join(this.host.agentDir, "extensions", name);
|
|
43
|
+
}
|
|
44
|
+
names(from) {
|
|
45
|
+
return existsSync(from) ? readdirSync(from, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(join(from, entry.name, "package.json"))).map((entry) => entry.name).sort() : [];
|
|
46
|
+
}
|
|
47
|
+
async from() {
|
|
48
|
+
if (this.examplesDir) {
|
|
49
|
+
return this.examplesDir;
|
|
50
|
+
}
|
|
51
|
+
const root = (await this.host.listPackages()).find((info) => info.name === NAME)?.root;
|
|
52
|
+
if (!root) {
|
|
53
|
+
throw new Error(`${NAME} is not loaded.`);
|
|
54
|
+
}
|
|
55
|
+
return join(root, "skills/ta-game/examples");
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
function activate(host) {
|
|
59
|
+
return new GamesService(host);
|
|
60
|
+
}
|
|
61
|
+
export {
|
|
62
|
+
activate as default,
|
|
63
|
+
NAME,
|
|
64
|
+
GamesService
|
|
65
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/ta-games",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "4.11.0",
|
|
4
|
+
"description": "A pi package for Ta: games and game-like extensions on Phaser and Three.js, the game engines of Ta's web page, with the ta-game skill and the Games page",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"pi-package"
|
|
7
|
+
],
|
|
8
|
+
"homepage": "https://github.com/cellbang/cell",
|
|
9
|
+
"bugs": {
|
|
10
|
+
"url": "https://github.com/cellbang/cell/issues"
|
|
11
|
+
},
|
|
12
|
+
"repository": {
|
|
13
|
+
"type": "git",
|
|
14
|
+
"url": "https://github.com/cellbang/cell.git"
|
|
15
|
+
},
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"files": [
|
|
18
|
+
"web",
|
|
19
|
+
"host",
|
|
20
|
+
"skills",
|
|
21
|
+
"!**/*.map"
|
|
22
|
+
],
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "tsc -b && node scripts/phaser-skills.mjs && bun build web-src/index.tsx --format esm --target browser --outfile web/index.js && bun build web-src/host.ts --format esm --target node --outfile host/index.mjs",
|
|
25
|
+
"clean": "rm -rf lib web host skills/ta-game/phaser *.tsbuildinfo",
|
|
26
|
+
"test": "bun test ./lib",
|
|
27
|
+
"watch": "tsc -b -w --preserveWatchOutput"
|
|
28
|
+
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@celljs/ta-protocol": "4.11.0",
|
|
31
|
+
"@celljs/ta-web": "4.11.0",
|
|
32
|
+
"@types/react": "^19.3.0",
|
|
33
|
+
"phaser": "^4.2.1"
|
|
34
|
+
},
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public"
|
|
37
|
+
},
|
|
38
|
+
"pi": {
|
|
39
|
+
"title": {
|
|
40
|
+
"en": "Games",
|
|
41
|
+
"zh-CN": "游戏"
|
|
42
|
+
},
|
|
43
|
+
"summary": {
|
|
44
|
+
"en": "The Games page lists the extensions that are games and has Ta make more, on the game engines of the page (Phaser for 2D, Three.js for 3D); Dino Run and Stack come as examples.",
|
|
45
|
+
"zh-CN": "\"游戏\"页列出所有游戏扩展,也能让 Ta 再做;游戏用页面内置的引擎(2D 是 Phaser,3D 是 Three.js),自带恐龙快跑和叠方块两个示例。"
|
|
46
|
+
},
|
|
47
|
+
"icon": "Gamepad2",
|
|
48
|
+
"webActivation": "open",
|
|
49
|
+
"lists": [
|
|
50
|
+
"game"
|
|
51
|
+
],
|
|
52
|
+
"web": [
|
|
53
|
+
"./web/index.js"
|
|
54
|
+
],
|
|
55
|
+
"host": "./host/index.mjs",
|
|
56
|
+
"skills": [
|
|
57
|
+
"./skills"
|
|
58
|
+
]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ta-game
|
|
3
|
+
description: Makes a game, or something that plays like one (a pet that lives in a card, a little world of what Ta does, a score, a reward, a puzzle), as a web extension of Ta on the game engines of Ta's web page, Phaser 4 for 2D (pi.ui.Game) and Three.js for 3D (pi.ui.Game3D). Use it whenever the user wants to play something in Ta, or wants an extension to move, react and feel like a game, in 2D or 3D.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Games in Ta
|
|
7
|
+
|
|
8
|
+
A game in Ta is a web extension of a package, as the ta-package skill says: read that skill first, for where the package goes, its `package.json` and the rest of `pi`. This skill adds the engine. Keep the game small: one scene, shapes drawn in code, a few hundred lines.
|
|
9
|
+
|
|
10
|
+
## Two examples
|
|
11
|
+
|
|
12
|
+
Two whole games beside this file are packages written the way this skill says, and come to the user's `extensions/` the first time the Games page opens: `examples/dino-run/` (2D on Phaser: a runner, a pixel sprite drawn in code, a scene class, the best score kept) and `examples/stack/` (3D on Three.js: a tower of blocks, one geometry for all of them, a camera that follows, the score drawn by React over the game). Before writing a game, read the `web.js` of the one of the same engine and follow its shape: the rules in a class apart from what draws them, the page, the styles, the words in two languages. Copy from it rather than from memory of older versions of the engines. To change one of the user's, change its copy in `extensions/`, never the example.
|
|
13
|
+
|
|
14
|
+
## The engines
|
|
15
|
+
|
|
16
|
+
The page has two engines, and an extension imports neither, loads none from a CDN and brings no other: Phaser 4 for 2D (`pi.ui.Game`, below) and Three.js for 3D (`pi.ui.Game3D`, see "3D with Three.js"). Use 2D unless the user asks for 3D or the game is about depth (a maze to tilt, a tower, a world to fly over): 2D is lighter on a phone and Phaser has physics, input, sounds and scenes built in.
|
|
17
|
+
|
|
18
|
+
The page has Phaser 4 (the version of this skill's `phaser/LICENSE.md`) and gives it to web extensions through `pi.ui.Game`: never import Phaser, load it from a CDN or bring another engine. It loads the first time a game starts.
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
export default function (pi) {
|
|
22
|
+
const h = pi.React.createElement;
|
|
23
|
+
function Page() {
|
|
24
|
+
const config = pi.React.useCallback((Phaser, page) => ({
|
|
25
|
+
width: 480,
|
|
26
|
+
height: 270,
|
|
27
|
+
scene: {
|
|
28
|
+
create() {
|
|
29
|
+
const ball = this.add.circle(240, 135, 14, page.colors.green);
|
|
30
|
+
this.input.on('pointerdown', pointer => this.tweens.add({ targets: ball, x: pointer.worldX, y: pointer.worldY, duration: 200 }));
|
|
31
|
+
},
|
|
32
|
+
},
|
|
33
|
+
}), []);
|
|
34
|
+
return h('div', { style: { display: 'flex', flexDirection: 'column', height: '100%' } }, h(pi.ui.Game, { config }));
|
|
35
|
+
}
|
|
36
|
+
pi.registerView('ball', { title: 'Ball', icon: pi.ui.icons.Gamepad2, render: Page });
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`pi.ui.Game` takes `{ config(Phaser, page), onReady?(game), className?, style? }`:
|
|
41
|
+
|
|
42
|
+
- `config` returns Phaser's game config without `parent`. It is read once, when the component mounts; give the component another React `key` to start the game again. A scene can be an object of `preload` / `create` / `update` (as above; its other functions are its methods, `this.build()` in `create`, as if in `extend`), or `class extends Phaser.Scene` written inside `config`, where `Phaser` is defined.
|
|
43
|
+
- What a scene's `init` / `preload` / `create` / `update` throws ends the game and shows the error in its place. Open the page once yourself after you write a game if you can; a game that shows an error is not done.
|
|
44
|
+
- The game fills the component, which fills its parent: give the parent a size (a column of flex with a height, or `aspect-ratio`). With `width` and `height` the game keeps that size and fits in the component, centered (`Scale.FIT`); without them it takes the size of the component and follows it (`Scale.RESIZE`: read `this.scale.width` / `height` and listen to `this.scale.on('resize', ...)`).
|
|
45
|
+
- The renderer is WebGL (`Phaser.AUTO`); there is no banner, and the background is the page's until `backgroundColor` is set.
|
|
46
|
+
- `onReady(game)` gets Phaser's `Game` once its first scene started, to talk to it from React (`game.scene.getScene(key)`, `game.events`).
|
|
47
|
+
- Several games can run at once, in a page, a card and a tab.
|
|
48
|
+
|
|
49
|
+
## A good guest of the page
|
|
50
|
+
|
|
51
|
+
- **Lifecycle.** The game sleeps while it cannot be seen (a page kept in the background, a tab not shown, a card scrolled away) and is destroyed when the component unmounts or the extension stops. So keep time inside Phaser (`this.time.addEvent`, `this.tweens`, `update(time, delta)`), never `setInterval` or `requestAnimationFrame` of your own, and move by `delta` (milliseconds) rather than by frames.
|
|
52
|
+
- **Input.** Pointer events are the mouse and a finger alike: `this.input.on('pointerdown' | 'pointermove' | 'pointerup', ...)`. Everything must be playable with taps or swipes on a phone, without a keyboard (`pi.ui.useDevice().touch` says there is a finger). The keyboard reaches the game only while it has the focus (the user clicked or tapped it), so that typing in the message box is never taken: `this.input.keyboard.on('keydown-SPACE', ...)` or `createCursorKeys()`; never listen on `window` or `document`.
|
|
53
|
+
- **Slides of the game and of Ta.** On a phone Ta has gestures of its own: a slide from the left edge goes back, a slide to the left brings out the workbench, a held finger opens a menu. On the element of `pi.ui.Game` and `pi.ui.Game3D` they give way: only a slide that starts at an edge of the screen (within 24 pixels) is Ta's, everything else that starts on the game is the game's, and neither a held finger, a right click, a pinch nor a double tap does anything of the page. So drag, swipe and hold freely in a game, but keep what is played 24 pixels off the edges of the screen (the padding of the page does), and leave the user a way out that is not a gesture: the page has its back button. By default the browser takes none of its touches (`touch-action: none`): a game played only by taps that sits in a page taller than the screen sets `touch-action: pan-y`, so that a slide up or down scrolls the page (see "A page scrolls itself"). An element of the extension's own that takes touches (a canvas to draw on, a joystick) gets the same with the attribute `data-own-gestures`. A game to play held sideways, or a world to walk in, goes in `pi.ui.FullScreen`: over all of the page and the notch, every touch its own (the edges too), so it needs its back button; keep its buttons inside `env(safe-area-inset-*)` and write `pi.ui.FullScreen ?? Fallback` for an older app.
|
|
54
|
+
- **The theme.** `page` is `{ theme: 'light' | 'dark', colors, touch, reduceMotion }`; `colors` has `main` (the background), `card`, `text`, `secondary`, `muted`, `border`, `accent`, `green` and `red` as numbers (`0xRRGGBB`) for Phaser's `fillStyle`, `circle`, `rectangle`. The game's registry holds the page as `'page'` and sets it again when the theme changes: `this.registry.get('page')` and `this.registry.events.on('changedata-page', (parent, page) => ...)` to paint again. Text colors are CSS strings: `'#' + color.toString(16).padStart(6, '0')`. With `reduceMotion`, no shaking, flashing or large movements that are only for show.
|
|
55
|
+
- **Sharp on any screen.** A game of a fixed size is drawn at that many pixels and scaled: for crisp lines and text, make it `devicePixelRatio` (at most 2) times larger and `this.cameras.main.setZoom(ratio).centerOn(width / 2, height / 2)`, with `resolution: ratio` in the style of each text.
|
|
56
|
+
- **Pictures.** Draw with `this.add.graphics()` (`fillStyle`, `fillRect`, `fillRoundedRect`, `fillCircle`), shapes (`this.add.rectangle`, `circle`, `star`), textures made in code (`graphics.generateTexture(key, w, h)`, or `this.textures.createCanvas(key, w, h)` and its 2D context, then `refresh()`), and emoji in `this.add.text`. Load no image or sound from the internet: a phone or a computer without a network must still play. A small picture of the user's can come from the workspace by `pi.files` as the ta-package skill says. Ta is drawn as its logo, `pi.ui.Avatar`, in React; in a scene, draw it as the game's own character.
|
|
57
|
+
- **Sound** is optional and off until the user turns it on in the game; Phaser unlocks audio after the first tap.
|
|
58
|
+
- **What it keeps.** Best scores, levels and settings go in `pi.storage` (`await pi.storage.get('best')`, `pi.storage.set('best', score)`), the same on every device; set them when a round ends, not every frame. Words of the game follow `pi.ui.language`.
|
|
59
|
+
- **Its size.** A page keeps the frame rate on a phone with up to some thousands of sprites; a card of the board or a widget should stay at tens. Reuse objects (`this.add.group` with `get` / `killAndHide`) rather than making and destroying them every frame.
|
|
60
|
+
|
|
61
|
+
## 3D with Three.js
|
|
62
|
+
|
|
63
|
+
`pi.ui.Game3D` takes `{ setup(context), onReady?(context), className?, style? }`. The page makes the renderer, runs the loop and follows the size; `setup` runs once, puts things in `context.scene` and returns what to do each frame:
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
export default function (pi) {
|
|
67
|
+
const h = pi.React.createElement;
|
|
68
|
+
function Page() {
|
|
69
|
+
const setup = pi.React.useCallback(({ THREE, OrbitControls, scene, camera, element, page }) => {
|
|
70
|
+
camera.position.set(3, 3, 5);
|
|
71
|
+
camera.lookAt(0, 0, 0);
|
|
72
|
+
scene.add(new THREE.HemisphereLight(0xffffff, 0x707070, 1.8));
|
|
73
|
+
const cube = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshLambertMaterial({ color: page.colors.green }));
|
|
74
|
+
scene.add(cube);
|
|
75
|
+
const controls = new OrbitControls(camera, element);
|
|
76
|
+
return {
|
|
77
|
+
update(seconds) { cube.rotation.y += seconds; controls.update(); },
|
|
78
|
+
page(next) { cube.material.color.setHex(next.colors.green); },
|
|
79
|
+
dispose() { controls.dispose(); },
|
|
80
|
+
};
|
|
81
|
+
}, []);
|
|
82
|
+
return h('div', { style: { display: 'flex', flexDirection: 'column', height: '100%' } }, h(pi.ui.Game3D, { setup }));
|
|
83
|
+
}
|
|
84
|
+
pi.registerView('cube', { title: 'Cube', icon: pi.ui.icons.Gamepad2, render: Page });
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- `context` has `THREE` (the whole of `three`, r187), `OrbitControls` (its only addon here), `renderer` (a WebGLRenderer, antialiased, transparent over the page until `scene.background` is set, at the pixel ratio of the screen up to 2), `scene`, `camera` (a PerspectiveCamera of 50° at (0, 0, 5) looking at the origin; set `context.camera` to another one to use it), `element` (for pointer and key events), `page` (as for Phaser, the latest) and `width` / `height`.
|
|
89
|
+
- The loop: `update(seconds, elapsed)` each frame while it can be seen (`seconds` at most 0.1, time asleep not counted), then the page renders `scene` with `camera`, or calls `render()` if the loop has one. `resize(width, height)` when the element changes size (the renderer and a PerspectiveCamera already have it), `page(page)` when the theme or motion changes, `dispose()` before it ends. Move by `seconds`, never by frames; never `requestAnimationFrame`, `setInterval` or `THREE.Clock` of your own.
|
|
90
|
+
- The same rules as for Phaser: a parent with a size (a 3D view wants `aspect-ratio` or the height of a page), listeners on `element` only (`pointerdown` / `pointermove` / `pointerup` for mouse and finger; `keydown` while it has the focus), the colors of `page.colors` (numbers for `color`, `setHex`), no models, textures or sounds from the internet (shapes in code: `BoxGeometry`, `SphereGeometry`, `CylinderGeometry`, `CapsuleGeometry`, `TorusGeometry`, `ExtrudeGeometry` of a `Shape`, textures drawn on a canvas with `CanvasTexture`), scores in `pi.storage`, less motion with `reduceMotion`.
|
|
91
|
+
- What the scene holds when it ends (geometries, materials, their textures, `scene.background`) the page disposes, and it gives the WebGL context back; dispose yourself only what you take out of the scene before, and stop what is not in it (`controls.dispose()` in `dispose`).
|
|
92
|
+
- On a phone: a few hundred meshes at most; share one geometry and one material between meshes alike (or an `InstancedMesh`), `MeshLambertMaterial` or `MeshStandardMaterial`, no shadows unless they matter (`renderer.shadowMap.enabled` and one light that casts them).
|
|
93
|
+
- Text and scores are best drawn by React over the game (an element of `position: absolute` over the parent, `pointer-events: none`), told by the setup through a callback: sharp, in the font of the page, in its language.
|
|
94
|
+
- Collisions by hand: `THREE.Box3` / `Sphere` and `intersectsBox`, a `Raycaster` for what the pointer is on (`raycaster.setFromCamera(ndc, camera)`, `ndc` from the pointer and `element.getBoundingClientRect()`). There is no physics engine.
|
|
95
|
+
|
|
96
|
+
What most often goes wrong from older Three.js:
|
|
97
|
+
|
|
98
|
+
- Only `BufferGeometry`: `THREE.Geometry`, `Face3` and `vertices` are gone.
|
|
99
|
+
- Colors are managed: `renderer.outputEncoding` and `sRGBEncoding` are gone (`outputColorSpace`, `SRGBColorSpace`; a texture of colors drawn on a canvas sets `texture.colorSpace = THREE.SRGBColorSpace`).
|
|
100
|
+
- Lights are physical, `useLegacyLights` and `physicallyCorrectLights` are gone: a hemisphere light of about 1.5 to 2 and a directional one of about 1.5 light a scene of Lambert materials; values of old examples (0.5, 1) leave it dark.
|
|
101
|
+
- `THREE.Clock` is deprecated (r183): the loop gives the time.
|
|
102
|
+
- Addons are not importable (`three/addons/...`): only `context.OrbitControls`; no GLTFLoader, no post-processing, no WebGPU renderer or TSL.
|
|
103
|
+
|
|
104
|
+
## Where a game shows
|
|
105
|
+
|
|
106
|
+
- A page scrolls itself: Ta's main area does not, so the root of a page taller than the window is `{ height: '100%', overflowY: 'auto' }`. On a phone a game as wide as the page is where the finger is: unless it is played by dragging, let a slide up or down scroll the page (`touch-action: pan-y` on the element of the game) and play on a tap as the finger lifts, a slide being cancelled by the browser before. With Phaser, `input: { touch: { capture: false } }` in the config and `this.input.on('pointerup', pointer => pointer.wasTouch && play())` beside `pointerdown` for the mouse; with Three.js, `pointerup` of a pointer whose `pointerType` is not `'mouse'`.
|
|
107
|
+
|
|
108
|
+
- A 3D game shows the same ways; keep one 3D game per page, and none in widgets: each is a WebGL context of its own, and browsers allow a few at once.
|
|
109
|
+
- A game to play: a `page` view (`registerView`), with `"category": "game"` in `pi` (the Games page lists the extensions of that category, and opens their first page; they are not under Discover or in the navigation) and `"webActivation": "open"` when it is played now and then; or a temporary extension (the ta-package skill), when the user only wants to try it. Name its directory and package after the game (`snake`), and give `pi` its `title`, `summary` and `icon` (`Gamepad2` unless another fits).
|
|
110
|
+
- Something that plays like a game beside the work: a `board` card (a few lines high: a pet, a little world of the tasks, a streak), a `panel` card with `ui.setWidget`, or a widget above the message box. Its game reacts to what happens: `pi.on('agent_start' | 'agent_end' | 'tool_execution_end', ...)` for the conversation shown, `pi.ui.useTasks()` for the double's tasks, `pi.packages.callPackageHost('@celljs/ta-cron', 'list')` for scheduled tasks. Hand what React knows to the scene through the registry (`game.registry.set('tasks', tasks)` in an effect, `this.registry.events.on('changedata-tasks', ...)` in the scene).
|
|
111
|
+
|
|
112
|
+
## Phaser 4
|
|
113
|
+
|
|
114
|
+
Most of what you know of Phaser 3 holds, but not all. Before you use a part of the engine you are not sure of, read its file here: `phaser/<topic>/SKILL.md` and the files of its `references/` (the skills Phaser ships for agents). The topics are `game-setup-and-config`, `scenes`, `sprites-and-images`, `graphics-and-shapes`, `text-and-bitmaptext`, `input-keyboard-mouse-touch`, `tweens`, `time-and-timers`, `animations`, `physics-arcade`, `physics-matter`, `particles`, `cameras`, `groups-and-containers`, `tilemaps`, `loading-assets`, `audio-and-sound`, `render-textures`, `filters-and-postfx`, `curves-and-paths`, `geometry-and-math`, `data-manager`, `events-system`, `scale-and-responsive`, `game-object-components`, `actions-and-utilities`, `v4-new-features` and `v3-to-v4-migration`. What most often goes wrong from Phaser 3:
|
|
115
|
+
|
|
116
|
+
- FX, `preFX` / `postFX` and `BitmapMask` are gone: effects and masks are filters (`filters-and-postfx`).
|
|
117
|
+
- `setTintFill(color)` is gone: `setTint(color).setTintMode(Phaser.TintModes.FILL)`.
|
|
118
|
+
- `Phaser.Geom.Point` is gone: `Phaser.Math.Vector2`. `Phaser.Math.TAU` is `2π` now, and `Math.PI2` is gone.
|
|
119
|
+
- `Mesh` and `Plane` are gone; there is no 3D.
|
|
120
|
+
- A `DynamicTexture` or `RenderTexture` draws only when its `render()` is called.
|
|
121
|
+
- Do not use the Canvas renderer, and make no WebGL calls of your own.
|
|
122
|
+
|
|
123
|
+
## Check before you answer
|
|
124
|
+
|
|
125
|
+
1. `node --check web.js`.
|
|
126
|
+
2. Read the config or the setup once more against the rules above: no import, no `window` listeners, no timers of its own, no image, model or sound from the internet, a parent with a size, playable with a finger, the pitfalls of Phaser 4 or of Three.js avoided.
|
|
127
|
+
3. Tell the user in one or two sentences how to play and where the game is (the Games page, and Quick open). No file listings unless asked.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "dino-run",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "Dino Run: Ta's dinosaur jumps cacti that come faster and faster",
|
|
6
|
+
"pi": {
|
|
7
|
+
"title": {
|
|
8
|
+
"en": "Dino Run",
|
|
9
|
+
"zh-CN": "恐龙快跑"
|
|
10
|
+
},
|
|
11
|
+
"summary": {
|
|
12
|
+
"en": "Jump the cacti with space or a tap; the best score is kept on every device.",
|
|
13
|
+
"zh-CN": "空格键或轻点起跳,跳过越来越快的仙人掌;最高分各设备同步。"
|
|
14
|
+
},
|
|
15
|
+
"icon": "Gamepad2",
|
|
16
|
+
"category": "game",
|
|
17
|
+
"webActivation": "open",
|
|
18
|
+
"web": [
|
|
19
|
+
"./web.js"
|
|
20
|
+
]
|
|
21
|
+
}
|
|
22
|
+
}
|