@typeonce/ritmo-pixi 0.14.0 → 0.16.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/CHANGELOG.md CHANGED
@@ -1,5 +1,64 @@
1
1
  # @typeonce/ritmo-pixi
2
2
 
3
+ ## 0.16.0
4
+
5
+ ### Patch Changes
6
+
7
+ - 9b0379e: **Every JSDoc `@example` now compiles against the current API.** Examples are type-checked in CI as a game would import them, so they no longer cite exports that do not exist or call them with the wrong arguments. What changed in meaning:
8
+
9
+ - `Game.Runtime.make(...)` with a constructed resource (a `Clock.resource`, a `Descriptor.ConstructedResource`) returns a `Result` that may fail: the examples check `ok` instead of reading `.value`.
10
+ - A captured input resource is typed from its source: `Descriptor.TransientResource<InputCapture.SnapshotOf<typeof KeyboardInput>>()`, not `Keyboard.Snapshot<...>`.
11
+ - `Netcode.seats(...)` returns a `Result`: check it instead of `.value!`.
12
+ - `Lint.Target<typeof Game.schema, typeof Root>` takes the schema root second.
13
+ - `NodeRegistry.make` infers the node type from `attach`'s parameter, with no explicit generic.
14
+
15
+ - Updated dependencies [9b0379e]
16
+ - @typeonce/ritmo-render@0.16.0
17
+
18
+ ## 0.15.0
19
+
20
+ ### Minor Changes
21
+
22
+ - b58d75b: **Child entities' nodes attach under their parent's node.** `RenderSync.system(Game, { ..., hierarchy: Attached })` takes a `Descriptor.Hierarchy` of the game: a child's node is added under its parent's node instead of the root, so the renderer composes the transforms and `apply` sets the child's local transform. A child moves when its parent changes, is removed, or gains or loses its node, in the same run; parents move before their children. Despawning a parent despawns its children, so their nodes go with it. A parent that only loses its renderable hands its children's nodes back to the root.
23
+
24
+ ```ts
25
+ const { relation: Attached } = Descriptor.Hierarchy(
26
+ "Game/Attached",
27
+ "Game/Attachments"
28
+ );
29
+ const Render = RenderSync.system(Game, {
30
+ name: "Game/Render",
31
+ renderable: Body,
32
+ transform: Position,
33
+ registry: Sprites,
34
+ hierarchy: Attached,
35
+ create,
36
+ apply,
37
+ });
38
+ ```
39
+
40
+ - A `Descriptor.Relation` as `hierarchy` does not compile (`hierarchy must be a Descriptor.Hierarchy relation`), and neither does a relation missing from the schema (`hierarchy must be a relation of the game's schema`).
41
+ - `NodeRegistry` keeps the node tree: `ensure(entity, create, parent?)` creates a node under a parent's node, `reparent(entity, parent)` moves one (and refuses a loop), and `parents` maps each nested node's entity to its parent's. `remove` moves a removed node's children back to the root before detaching it, and `clear` detaches children before their parents.
42
+ - `PixiNodeRegistry.make(container)` adds a node with `(parent ?? container).addChild(node)`. Its nodes must be able to hold children (`addChild` and `removeChild`, as every Pixi display object has); otherwise it does not compile (`each node must be a container`).
43
+ - **Breaking: `RegistryOptions.attach` receives the parent node**, `(node, parent: Node | undefined)`, `undefined` meaning the root, and is also called to move an attached node, so it must take the node out of its current parent. A one-parameter `attach` still compiles but puts every node on the root, so a game passing `hierarchy` sees children unattached. Update a custom registry:
44
+
45
+ ```diff
46
+ NodeRegistry.make<Mesh>({
47
+ - attach: (mesh) => scene.add(mesh),
48
+ - detach: (mesh) => scene.remove(mesh)
49
+ + attach: (mesh, parent) => (parent ?? scene).add(mesh),
50
+ + detach: (mesh) => mesh.removeFromParent()
51
+ })
52
+ ```
53
+
54
+ - **Breaking: a hand-written `NodeRegistry<Node>` object needs `reparent` and `parents`**, and `ensure` takes an optional `parent`. Build registries with `NodeRegistry.make` instead of implementing the interface.
55
+ - **Breaking: `PixiNodeRegistry.make`'s nodes must have `addChild` and `removeChild`.** Pixi display objects already do; a test double adds the two methods.
56
+
57
+ ### Patch Changes
58
+
59
+ - Updated dependencies [b58d75b]
60
+ - @typeonce/ritmo-render@0.15.0
61
+
3
62
  ## 0.14.0
4
63
 
5
64
  ### Patch Changes
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `@typeonce/ritmo-pixi`
2
2
 
3
- Pixi's implementation of the renderer-independent `NodeRegistry` contract. `PixiNodeRegistry.make` attaches nodes to one Pixi container and detaches and destroys them with their children on removal.
3
+ Pixi's implementation of the renderer-independent `NodeRegistry` contract. `PixiNodeRegistry.make` attaches nodes to one Pixi container, or under their parent entity's node when `RenderSync.system` is given a `hierarchy`, and detaches and destroys them with their children on removal (child entities' nodes are moved back to the container first).
4
4
 
5
5
  Import the generic `NodeRegistry` contract and `RenderSync` systems from [`@typeonce/ritmo-render`](https://github.com/typeonce-dev/ritmo/blob/main/packages/render/README.md). The Pixi package exports only its adapter; systems depend on the generic registry service, and the host chooses its implementation.
6
6
 
@@ -20,6 +20,8 @@ const services = Game.Runtime.services(Game.Runtime.service(Sprites, sprites))
20
20
  // Pass Sprites as the registry descriptor to RenderSync.system(Game, ...).
21
21
  ```
22
22
 
23
+ With a `hierarchy`, each child's node is added with `(parent ?? container).addChild(node)`, so Pixi composes the child's local position with its parent's. Pixi warns when a leaf (a `Sprite`, a `Graphics`) holds children, so make the parents' nodes `Container`s that hold their sprites. A registry over nodes that cannot hold children does not compile.
24
+
23
25
  Bring your own `pixi.js` application; the package does not import it.
24
26
 
25
27
  Released together with [`@typeonce/ritmo`](https://github.com/typeonce-dev/ritmo/blob/main/packages/core/README.md), always with the same version.
@@ -3,36 +3,60 @@
3
3
  *
4
4
  * Import the registry contract and render systems from `@typeonce/ritmo-render`.
5
5
  * Construct this adapter in the host and provide it as a normal runtime service.
6
- * Removing a node detaches it and destroys it with its children.
6
+ * A node is added to the container, or under its parent entity's node when
7
+ * `RenderSync.system` is given a `hierarchy`, so Pixi composes the
8
+ * transforms. Removing a node detaches it and destroys it with its children
9
+ * (child entities' nodes are moved back to the container first).
7
10
  *
8
11
  * @module PixiNodeRegistry
9
12
  * @docGroup pixi
10
13
  *
11
14
  * @example
12
15
  * ```ts
16
+ * import { Container, Sprite, Texture } from "pixi.js"
17
+ *
18
+ * declare const enemy: Entity.EntityId<typeof Game.schema>
19
+ * declare const despawned: Entity.EntityId<typeof Game.schema>
20
+ * // ---cut---
21
+ * const actorLayer = new Container()
13
22
  * const sprites = PixiNodeRegistry.make(actorLayer)
14
- * sprites.ensure(match.entity.id, () => new Sprite(texture))
15
- * sprites.remove(despawnedId)
23
+ * sprites.ensure(enemy, () => new Sprite(Texture.WHITE))
24
+ * sprites.remove(despawned)
16
25
  * sprites.clear()
17
26
  * ```
18
27
  */
19
28
  import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry";
20
29
  /**
21
30
  * The container surface the registry needs; Pixi's `Container` satisfies it.
31
+ * `addChild` must take the child out of the container it is in, as Pixi's
32
+ * does.
22
33
  */
23
34
  export interface ContainerLike<Child> {
24
35
  addChild(child: Child): unknown;
25
36
  removeChild(child: Child): unknown;
26
37
  }
27
38
  /**
28
- * The node surface the registry needs; every Pixi display object satisfies it.
39
+ * The node surface the registry needs beside `ContainerLike`; every Pixi
40
+ * display object satisfies it. `destroy` must also take the node out of its
41
+ * parent node, as Pixi's does.
29
42
  */
30
43
  export interface Destroyable {
31
44
  destroy(options?: unknown): void;
32
45
  }
33
46
  /**
34
- * Creates a registry whose nodes are children of one container and are
35
- * destroyed (with their children) when removed.
47
+ * The container `make` accepts: one whose children are containers too, or a
48
+ * message naming the fix.
49
+ */
50
+ export type HoldsChildren<Node> = [
51
+ Node
52
+ ] extends [ContainerLike<Node>] ? ContainerLike<Node> : "each node must be a container (addChild and removeChild), so it can hold its child entities' nodes";
53
+ /**
54
+ * Creates a registry whose nodes are children of one container, or of their
55
+ * parent entity's node, and are destroyed (with their children) when
56
+ * removed. Nodes are containers themselves (`ContainerLike`) so that they can
57
+ * hold child entities' nodes; with a `hierarchy`, make the parents' nodes
58
+ * Pixi `Container`s, since Pixi warns when a leaf (a `Sprite`, a `Graphics`)
59
+ * holds children.
36
60
  */
37
- export declare const make: <Node extends Destroyable>(parent: ContainerLike<Node>) => NodeRegistry.NodeRegistry<Node>;
61
+ export declare const make: <Node extends Destroyable>(container: HoldsChildren<Node>) => NodeRegistry.NodeRegistry<Node>;
38
62
  //# sourceMappingURL=PixiNodeRegistry.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"PixiNodeRegistry.d.ts","sourceRoot":"","sources":["../src/PixiNodeRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,YAAY,MAAM,qCAAqC,CAAA;AAEnE;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IAC/B,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,SAAS,WAAW,UAAU,aAAa,CAAC,IAAI,CAAC,KAAG,YAAY,CAAC,YAAY,CAAC,IAAI,CASvG,CAAA"}
1
+ {"version":3,"file":"PixiNodeRegistry.d.ts","sourceRoot":"","sources":["../src/PixiNodeRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,YAAY,MAAM,qCAAqC,CAAA;AAEnE;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IAC/B,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,IAAI,IAC5B;IAAC,IAAI;CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,GAChC,aAAa,CAAC,IAAI,CAAC,GACnB,oGAAoG,CAAA;AAE1G;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,SAAS,WAAW,aAAa,aAAa,CAAC,IAAI,CAAC,KAAG,YAAY,CAAC,YAAY,CAAC,IAAI,CAY7G,CAAA"}
@@ -3,32 +3,49 @@
3
3
  *
4
4
  * Import the registry contract and render systems from `@typeonce/ritmo-render`.
5
5
  * Construct this adapter in the host and provide it as a normal runtime service.
6
- * Removing a node detaches it and destroys it with its children.
6
+ * A node is added to the container, or under its parent entity's node when
7
+ * `RenderSync.system` is given a `hierarchy`, so Pixi composes the
8
+ * transforms. Removing a node detaches it and destroys it with its children
9
+ * (child entities' nodes are moved back to the container first).
7
10
  *
8
11
  * @module PixiNodeRegistry
9
12
  * @docGroup pixi
10
13
  *
11
14
  * @example
12
15
  * ```ts
16
+ * import { Container, Sprite, Texture } from "pixi.js"
17
+ *
18
+ * declare const enemy: Entity.EntityId<typeof Game.schema>
19
+ * declare const despawned: Entity.EntityId<typeof Game.schema>
20
+ * // ---cut---
21
+ * const actorLayer = new Container()
13
22
  * const sprites = PixiNodeRegistry.make(actorLayer)
14
- * sprites.ensure(match.entity.id, () => new Sprite(texture))
15
- * sprites.remove(despawnedId)
23
+ * sprites.ensure(enemy, () => new Sprite(Texture.WHITE))
24
+ * sprites.remove(despawned)
16
25
  * sprites.clear()
17
26
  * ```
18
27
  */
19
28
  // oxlint-disable-next-line ritmo/keep-simulation-headless -- this package is the Pixi adapter for the render registry, render code by definition
20
29
  import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry";
21
30
  /**
22
- * Creates a registry whose nodes are children of one container and are
23
- * destroyed (with their children) when removed.
31
+ * Creates a registry whose nodes are children of one container, or of their
32
+ * parent entity's node, and are destroyed (with their children) when
33
+ * removed. Nodes are containers themselves (`ContainerLike`) so that they can
34
+ * hold child entities' nodes; with a `hierarchy`, make the parents' nodes
35
+ * Pixi `Container`s, since Pixi warns when a leaf (a `Sprite`, a `Graphics`)
36
+ * holds children.
24
37
  */
25
- export const make = (parent) => NodeRegistry.make({
26
- attach: (node) => {
27
- parent.addChild(node);
28
- },
29
- detach: (node) => {
30
- parent.removeChild(node);
31
- node.destroy({ children: true });
32
- }
33
- });
38
+ export const make = (container) => {
39
+ // `HoldsChildren` proved that the container and every node hold nodes.
40
+ const root = container;
41
+ return NodeRegistry.make({
42
+ attach: (node, parent) => {
43
+ (parent ?? root).addChild(node);
44
+ },
45
+ detach: (node) => {
46
+ root.removeChild(node);
47
+ node.destroy({ children: true });
48
+ }
49
+ });
50
+ };
34
51
  //# sourceMappingURL=PixiNodeRegistry.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"PixiNodeRegistry.js","sourceRoot":"","sources":["../src/PixiNodeRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,iJAAiJ;AACjJ,OAAO,KAAK,YAAY,MAAM,qCAAqC,CAAA;AAiBnE;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAA2B,MAA2B,EAAmC,EAAE,CAC7G,YAAY,CAAC,IAAI,CAAC;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACf,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;IACD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACf,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;QACxB,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAClC,CAAC;CACF,CAAC,CAAA"}
1
+ {"version":3,"file":"PixiNodeRegistry.js","sourceRoot":"","sources":["../src/PixiNodeRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iJAAiJ;AACjJ,OAAO,KAAK,YAAY,MAAM,qCAAqC,CAAA;AA8BnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAA2B,SAA8B,EAAmC,EAAE;IAChH,uEAAuE;IACvE,MAAM,IAAI,GAAG,SAAgC,CAAA;IAC7C,OAAO,YAAY,CAAC,IAAI,CAAO;QAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACtB,CAAC,MAAM,IAAI,IAAI,CAAyB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC1D,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACf,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;YACtB,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;QAClC,CAAC;KACF,CAAC,CAAA;AACJ,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typeonce/ritmo-pixi",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "description": "Pixi container adapter for Ritmo render-node registries",
5
5
  "author": "Sandro Maglione",
6
6
  "license": "MIT",
@@ -48,10 +48,10 @@
48
48
  "provenance": true
49
49
  },
50
50
  "dependencies": {
51
- "@typeonce/ritmo-render": "^0.14.0"
51
+ "@typeonce/ritmo-render": "^0.16.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@typeonce/ritmo": "0.14.0"
54
+ "@typeonce/ritmo": "0.16.0"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=20"
@@ -3,16 +3,25 @@
3
3
  *
4
4
  * Import the registry contract and render systems from `@typeonce/ritmo-render`.
5
5
  * Construct this adapter in the host and provide it as a normal runtime service.
6
- * Removing a node detaches it and destroys it with its children.
6
+ * A node is added to the container, or under its parent entity's node when
7
+ * `RenderSync.system` is given a `hierarchy`, so Pixi composes the
8
+ * transforms. Removing a node detaches it and destroys it with its children
9
+ * (child entities' nodes are moved back to the container first).
7
10
  *
8
11
  * @module PixiNodeRegistry
9
12
  * @docGroup pixi
10
13
  *
11
14
  * @example
12
15
  * ```ts
16
+ * import { Container, Sprite, Texture } from "pixi.js"
17
+ *
18
+ * declare const enemy: Entity.EntityId<typeof Game.schema>
19
+ * declare const despawned: Entity.EntityId<typeof Game.schema>
20
+ * // ---cut---
21
+ * const actorLayer = new Container()
13
22
  * const sprites = PixiNodeRegistry.make(actorLayer)
14
- * sprites.ensure(match.entity.id, () => new Sprite(texture))
15
- * sprites.remove(despawnedId)
23
+ * sprites.ensure(enemy, () => new Sprite(Texture.WHITE))
24
+ * sprites.remove(despawned)
16
25
  * sprites.clear()
17
26
  * ```
18
27
  */
@@ -21,6 +30,8 @@ import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry"
21
30
 
22
31
  /**
23
32
  * The container surface the registry needs; Pixi's `Container` satisfies it.
33
+ * `addChild` must take the child out of the container it is in, as Pixi's
34
+ * does.
24
35
  */
25
36
  export interface ContainerLike<Child> {
26
37
  addChild(child: Child): unknown
@@ -28,23 +39,41 @@ export interface ContainerLike<Child> {
28
39
  }
29
40
 
30
41
  /**
31
- * The node surface the registry needs; every Pixi display object satisfies it.
42
+ * The node surface the registry needs beside `ContainerLike`; every Pixi
43
+ * display object satisfies it. `destroy` must also take the node out of its
44
+ * parent node, as Pixi's does.
32
45
  */
33
46
  export interface Destroyable {
34
47
  destroy(options?: unknown): void
35
48
  }
36
49
 
37
50
  /**
38
- * Creates a registry whose nodes are children of one container and are
39
- * destroyed (with their children) when removed.
51
+ * The container `make` accepts: one whose children are containers too, or a
52
+ * message naming the fix.
40
53
  */
41
- export const make = <Node extends Destroyable>(parent: ContainerLike<Node>): NodeRegistry.NodeRegistry<Node> =>
42
- NodeRegistry.make({
43
- attach: (node) => {
44
- parent.addChild(node)
54
+ export type HoldsChildren<Node> =
55
+ [Node] extends [ContainerLike<Node>]
56
+ ? ContainerLike<Node>
57
+ : "each node must be a container (addChild and removeChild), so it can hold its child entities' nodes"
58
+
59
+ /**
60
+ * Creates a registry whose nodes are children of one container, or of their
61
+ * parent entity's node, and are destroyed (with their children) when
62
+ * removed. Nodes are containers themselves (`ContainerLike`) so that they can
63
+ * hold child entities' nodes; with a `hierarchy`, make the parents' nodes
64
+ * Pixi `Container`s, since Pixi warns when a leaf (a `Sprite`, a `Graphics`)
65
+ * holds children.
66
+ */
67
+ export const make = <Node extends Destroyable>(container: HoldsChildren<Node>): NodeRegistry.NodeRegistry<Node> => {
68
+ // `HoldsChildren` proved that the container and every node hold nodes.
69
+ const root = container as ContainerLike<Node>
70
+ return NodeRegistry.make<Node>({
71
+ attach: (node, parent) => {
72
+ ((parent ?? root) as ContainerLike<Node>).addChild(node)
45
73
  },
46
74
  detach: (node) => {
47
- parent.removeChild(node)
75
+ root.removeChild(node)
48
76
  node.destroy({ children: true })
49
77
  }
50
78
  })
79
+ }