@typeonce/ritmo-pixi 0.14.0 → 0.15.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,49 @@
1
1
  # @typeonce/ritmo-pixi
2
2
 
3
+ ## 0.15.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ ```ts
10
+ const { relation: Attached } = Descriptor.Hierarchy(
11
+ "Game/Attached",
12
+ "Game/Attachments"
13
+ );
14
+ const Render = RenderSync.system(Game, {
15
+ name: "Game/Render",
16
+ renderable: Body,
17
+ transform: Position,
18
+ registry: Sprites,
19
+ hierarchy: Attached,
20
+ create,
21
+ apply,
22
+ });
23
+ ```
24
+
25
+ - 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`).
26
+ - `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.
27
+ - `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`).
28
+ - **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:
29
+
30
+ ```diff
31
+ NodeRegistry.make<Mesh>({
32
+ - attach: (mesh) => scene.add(mesh),
33
+ - detach: (mesh) => scene.remove(mesh)
34
+ + attach: (mesh, parent) => (parent ?? scene).add(mesh),
35
+ + detach: (mesh) => mesh.removeFromParent()
36
+ })
37
+ ```
38
+
39
+ - **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.
40
+ - **Breaking: `PixiNodeRegistry.make`'s nodes must have `addChild` and `removeChild`.** Pixi display objects already do; a test double adds the two methods.
41
+
42
+ ### Patch Changes
43
+
44
+ - Updated dependencies [b58d75b]
45
+ - @typeonce/ritmo-render@0.15.0
46
+
3
47
  ## 0.14.0
4
48
 
5
49
  ### 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,7 +3,10 @@
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
@@ -19,20 +22,35 @@
19
22
  import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry";
20
23
  /**
21
24
  * The container surface the registry needs; Pixi's `Container` satisfies it.
25
+ * `addChild` must take the child out of the container it is in, as Pixi's
26
+ * does.
22
27
  */
23
28
  export interface ContainerLike<Child> {
24
29
  addChild(child: Child): unknown;
25
30
  removeChild(child: Child): unknown;
26
31
  }
27
32
  /**
28
- * The node surface the registry needs; every Pixi display object satisfies it.
33
+ * The node surface the registry needs beside `ContainerLike`; every Pixi
34
+ * display object satisfies it. `destroy` must also take the node out of its
35
+ * parent node, as Pixi's does.
29
36
  */
30
37
  export interface Destroyable {
31
38
  destroy(options?: unknown): void;
32
39
  }
33
40
  /**
34
- * Creates a registry whose nodes are children of one container and are
35
- * destroyed (with their children) when removed.
41
+ * The container `make` accepts: one whose children are containers too, or a
42
+ * message naming the fix.
36
43
  */
37
- export declare const make: <Node extends Destroyable>(parent: ContainerLike<Node>) => NodeRegistry.NodeRegistry<Node>;
44
+ export type HoldsChildren<Node> = [
45
+ Node
46
+ ] extends [ContainerLike<Node>] ? ContainerLike<Node> : "each node must be a container (addChild and removeChild), so it can hold its child entities' nodes";
47
+ /**
48
+ * Creates a registry whose nodes are children of one container, or of their
49
+ * parent entity's node, and are destroyed (with their children) when
50
+ * removed. Nodes are containers themselves (`ContainerLike`) so that they can
51
+ * hold child entities' nodes; with a `hierarchy`, make the parents' nodes
52
+ * Pixi `Container`s, since Pixi warns when a leaf (a `Sprite`, a `Graphics`)
53
+ * holds children.
54
+ */
55
+ export declare const make: <Node extends Destroyable>(container: HoldsChildren<Node>) => NodeRegistry.NodeRegistry<Node>;
38
56
  //# 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;;;;;;;;;;;;;;;;;;;;GAoBG;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,7 +3,10 @@
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
@@ -19,16 +22,24 @@
19
22
  // oxlint-disable-next-line ritmo/keep-simulation-headless -- this package is the Pixi adapter for the render registry, render code by definition
20
23
  import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry";
21
24
  /**
22
- * Creates a registry whose nodes are children of one container and are
23
- * destroyed (with their children) when removed.
25
+ * Creates a registry whose nodes are children of one container, or of their
26
+ * parent entity's node, and are destroyed (with their children) when
27
+ * removed. Nodes are containers themselves (`ContainerLike`) so that they can
28
+ * hold child entities' nodes; with a `hierarchy`, make the parents' nodes
29
+ * Pixi `Container`s, since Pixi warns when a leaf (a `Sprite`, a `Graphics`)
30
+ * holds children.
24
31
  */
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
- });
32
+ export const make = (container) => {
33
+ // `HoldsChildren` proved that the container and every node hold nodes.
34
+ const root = container;
35
+ return NodeRegistry.make({
36
+ attach: (node, parent) => {
37
+ (parent ?? root).addChild(node);
38
+ },
39
+ detach: (node) => {
40
+ root.removeChild(node);
41
+ node.destroy({ children: true });
42
+ }
43
+ });
44
+ };
34
45
  //# 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;;;;;;;;;;;;;;;;;;;;GAoBG;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.15.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.15.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@typeonce/ritmo": "0.14.0"
54
+ "@typeonce/ritmo": "0.15.0"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=20"
@@ -3,7 +3,10 @@
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
@@ -21,6 +24,8 @@ import * as NodeRegistry from "@typeonce/ritmo-render/NodeRegistry"
21
24
 
22
25
  /**
23
26
  * The container surface the registry needs; Pixi's `Container` satisfies it.
27
+ * `addChild` must take the child out of the container it is in, as Pixi's
28
+ * does.
24
29
  */
25
30
  export interface ContainerLike<Child> {
26
31
  addChild(child: Child): unknown
@@ -28,23 +33,41 @@ export interface ContainerLike<Child> {
28
33
  }
29
34
 
30
35
  /**
31
- * The node surface the registry needs; every Pixi display object satisfies it.
36
+ * The node surface the registry needs beside `ContainerLike`; every Pixi
37
+ * display object satisfies it. `destroy` must also take the node out of its
38
+ * parent node, as Pixi's does.
32
39
  */
33
40
  export interface Destroyable {
34
41
  destroy(options?: unknown): void
35
42
  }
36
43
 
37
44
  /**
38
- * Creates a registry whose nodes are children of one container and are
39
- * destroyed (with their children) when removed.
45
+ * The container `make` accepts: one whose children are containers too, or a
46
+ * message naming the fix.
40
47
  */
41
- export const make = <Node extends Destroyable>(parent: ContainerLike<Node>): NodeRegistry.NodeRegistry<Node> =>
42
- NodeRegistry.make({
43
- attach: (node) => {
44
- parent.addChild(node)
48
+ export type HoldsChildren<Node> =
49
+ [Node] extends [ContainerLike<Node>]
50
+ ? ContainerLike<Node>
51
+ : "each node must be a container (addChild and removeChild), so it can hold its child entities' nodes"
52
+
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.
60
+ */
61
+ export const make = <Node extends Destroyable>(container: HoldsChildren<Node>): NodeRegistry.NodeRegistry<Node> => {
62
+ // `HoldsChildren` proved that the container and every node hold nodes.
63
+ const root = container as ContainerLike<Node>
64
+ return NodeRegistry.make<Node>({
65
+ attach: (node, parent) => {
66
+ ((parent ?? root) as ContainerLike<Node>).addChild(node)
45
67
  },
46
68
  detach: (node) => {
47
- parent.removeChild(node)
69
+ root.removeChild(node)
48
70
  node.destroy({ children: true })
49
71
  }
50
72
  })
73
+ }