@celljs/ta-games 4.17.0 → 4.18.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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/ta-games",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.18.0",
|
|
4
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
5
|
"keywords": [
|
|
6
6
|
"pi-package"
|
|
@@ -27,8 +27,8 @@
|
|
|
27
27
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
|
-
"@celljs/ta-protocol": "4.
|
|
31
|
-
"@celljs/ta-web": "4.
|
|
30
|
+
"@celljs/ta-protocol": "4.18.0",
|
|
31
|
+
"@celljs/ta-web": "4.18.0",
|
|
32
32
|
"@types/react": "^19.3.0",
|
|
33
33
|
"phaser": "^4.2.1"
|
|
34
34
|
},
|
package/skills/ta-game/SKILL.md
CHANGED
|
@@ -50,12 +50,13 @@ export default function (pi) {
|
|
|
50
50
|
|
|
51
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
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
|
|
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 taller than the window"). 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
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
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
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
57
|
- **Sound** is optional and off until the user turns it on in the game; Phaser unlocks audio after the first tap.
|
|
58
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
|
+
- **What Ta sees and does of it.** The user may ask Ta to play it for them or to show them how: Ta sees the game as a part of the screen and taps, moves the pointer, drags, presses keys and holds on it, as a mouse and a keyboard would (pointer and mouse events on the canvas, keys on its element). So play it by pointer events and keys as above, never by touch events alone, and keep a key for what a tap does where you can. Tell Ta the round: set `score` (a number) and `over` (a boolean) in the registry when they change (`this.registry.set('score', score)`, not every frame when unchanged), and Ta reads them when it looks. `title` of `pi.ui.Game` names it to Ta; the title of the package without.
|
|
59
60
|
- **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
|
|
|
61
62
|
## 3D with Three.js
|
|
@@ -87,7 +88,7 @@ export default function (pi) {
|
|
|
87
88
|
|
|
88
89
|
- `context` has `THREE` (the whole of `three`, r187), its addons here `OrbitControls`, `GLTFLoader` and `SkeletonUtils` (for models, below), `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
90
|
- 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`), nothing loaded from the internet (shapes in code: `BoxGeometry`, `SphereGeometry`, `CylinderGeometry`, `CapsuleGeometry`, `TorusGeometry`, `ExtrudeGeometry` of a `Shape`, textures drawn on a canvas with `CanvasTexture`; or a model kept in the package, below), scores in `pi.storage`, less motion with `reduceMotion`.
|
|
91
|
+
- 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`), nothing loaded from the internet (shapes in code: `BoxGeometry`, `SphereGeometry`, `CylinderGeometry`, `CapsuleGeometry`, `TorusGeometry`, `ExtrudeGeometry` of a `Shape`, textures drawn on a canvas with `CanvasTexture`; or a model kept in the package, below), scores in `pi.storage`, less motion with `reduceMotion`. The loop may give `state()`, returning `{ score, over }`, which Ta reads when it looks at the game (as the registry of a Phaser game); `title` of `pi.ui.Game3D` names it to Ta.
|
|
91
92
|
- 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
93
|
- 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
94
|
- 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.
|
|
@@ -141,7 +142,7 @@ What most often goes wrong from older Three.js:
|
|
|
141
142
|
|
|
142
143
|
## Where a game shows
|
|
143
144
|
|
|
144
|
-
- A page
|
|
145
|
+
- A page taller than the window scrolls under its head, as Ta does for every page. 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'`.
|
|
145
146
|
|
|
146
147
|
- 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.
|
|
147
148
|
- 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).
|
|
@@ -276,6 +276,15 @@ export default function (pi) {
|
|
|
276
276
|
this.dino.setAlpha(rules.state === 'over' ? 0.55 : 1);
|
|
277
277
|
this.drawWorld();
|
|
278
278
|
this.score.setText(String(rules.score).padStart(5, '0'));
|
|
279
|
+
// What Ta tells of the game when it looks at the screen (and plays it for the user); set when it changes.
|
|
280
|
+
for (const [key, value] of [
|
|
281
|
+
['score', rules.score],
|
|
282
|
+
['over', rules.state === 'over'],
|
|
283
|
+
]) {
|
|
284
|
+
if (this.registry.get(key) !== value) {
|
|
285
|
+
this.registry.set(key, value);
|
|
286
|
+
}
|
|
287
|
+
}
|
|
279
288
|
const words = hooks.words();
|
|
280
289
|
this.message.setText(rules.state === 'ready' ? words.start : rules.state === 'over' ? `${words.over}\n${words.best}` : '');
|
|
281
290
|
}
|
|
@@ -260,6 +260,8 @@ export function stackSetup(hooks) {
|
|
|
260
260
|
hooks.change(rules.state, rules.score, false);
|
|
261
261
|
|
|
262
262
|
return {
|
|
263
|
+
// What Ta tells of the game when it looks at the screen (and plays it for the user).
|
|
264
|
+
state: () => ({ score: rules.score, over: rules.state === 'over' }),
|
|
263
265
|
update(seconds) {
|
|
264
266
|
rules.step(seconds);
|
|
265
267
|
if (rules.state === 'running' && rules.moving) {
|