@fabiplay/engine 0.0.0-stage → 0.9.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/LICENSE ADDED
@@ -0,0 +1,78 @@
1
+ Fabi Play Kit License
2
+ Version 1.0 (DRAFT, not yet reviewed by a lawyer)
3
+
4
+ Copyright (c) 2026 Fabi Play. All rights reserved.
5
+
6
+ This license applies to the Fabi Play Kit: the packages @fabiplay/protocol, @fabiplay/motion,
7
+ @fabiplay/avatars, @fabiplay/sdk and @fabiplay/engine, in source and built form, as published on npm, served
8
+ from https://cdn.fabiplay.app or found in this repository, including their code, type declarations, documentation,
9
+ avatar artwork and other assets (together, the "Kit"). Versions up to 0.9.0 were published under the earlier names
10
+ @fabi-play/protocol, @fabi-play/motion, @fabi-play/avatars, @fabi-play/sdk and @fabi-play/engine, which are part
11
+ of the Kit too.
12
+
13
+ 1. Free of charge, for Fabi Play only
14
+
15
+ Fabi Play grants you a worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to
16
+ use, copy, and modify the Kit, and to distribute it as part of a Permitted Work, solely to make, test, run and
17
+ distribute Permitted Works.
18
+
19
+ A "Permitted Work" is a game, tool, or other software made to run on, be published on, or support the
20
+ development of games for the Fabi Play platform (https://fabiplay.app), including games submitted to Fabi Play
21
+ and tools used to build, test or preview them.
22
+
23
+ 2. What is not allowed
24
+
25
+ You may not, without Fabi Play's prior written permission:
26
+
27
+ a. use the Kit, or any part or modified version of it, in software that is not a Permitted Work, including in
28
+ any other game platform, product or service;
29
+ b. distribute the Kit, or a modified version of it, on its own or as a library, SDK, engine or framework for
30
+ others to build with, other than as part of a Permitted Work (installing it from npm or loading it from
31
+ https://cdn.fabiplay.app is not a distribution by you);
32
+ c. sell, rent or sublicense the Kit itself;
33
+ d. remove or alter this license, copyright notices, or the license banners in the built files;
34
+ e. use the avatars, the mascot "Fabi", or the name, logos or other trademarks of Fabi Play, except as the Kit
35
+ does when it runs inside a Permitted Work. This license grants no trademark rights;
36
+ f. use the Kit to circumvent, interfere with or misrepresent the Fabi Play platform, its safety, privacy or
37
+ parental controls, or its rules for games.
38
+
39
+ 3. Visible, not open source
40
+
41
+ The Kit's code is published so that developers can read it, debug with it and build Permitted Works. Being
42
+ visible does not make it open source; no rights are granted beyond those stated here.
43
+
44
+ 4. Your works
45
+
46
+ You keep all rights in your own code and content. This license does not give Fabi Play any rights in your
47
+ Permitted Works; publishing a game on Fabi Play is governed by Fabi Play's separate developer terms.
48
+
49
+ 5. Feedback
50
+
51
+ If you send Fabi Play suggestions or changes for the Kit, Fabi Play may use them without obligation to you.
52
+
53
+ 6. Termination
54
+
55
+ This license ends automatically if you break its terms. If you fix the breach within 30 days of becoming aware
56
+ of it, the license is reinstated, unless Fabi Play has already told you in writing that it is terminated. On
57
+ termination you must stop using and distributing the Kit. Permitted Works already distributed to end users in
58
+ compliance with this license may continue to be used by those end users.
59
+
60
+ 7. No warranty
61
+
62
+ THE KIT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
63
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
64
+
65
+ 8. Limitation of liability
66
+
67
+ TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FABI PLAY OR ITS CONTRIBUTORS BE LIABLE FOR ANY CLAIM,
68
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
69
+ CONNECTION WITH THE KIT OR THE USE OR OTHER DEALINGS IN THE KIT.
70
+
71
+ 9. Changes to this license
72
+
73
+ Fabi Play may publish new versions of this license. Each version of the Kit is governed by the license version
74
+ it is distributed with, unless you choose to accept a later version.
75
+
76
+ 10. Contact
77
+
78
+ For permissions beyond this license: https://fabiplay.app
package/README.md CHANGED
@@ -1,3 +1,114 @@
1
- # Temporary Holding Version
1
+ # @fabiplay/engine
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A small 2D engine for [Fabi Play](https://fabiplay.app) games: a 720-unit stage, sprites, shapes, text, particles,
4
+ tweens, sound, the players' hands and avatars, on WebGL (1 or 2) or Canvas 2D.
5
+
6
+ ## npm
7
+
8
+ ```sh
9
+ npm install @fabiplay/sdk @fabiplay/engine
10
+ ```
11
+
12
+ ```ts
13
+ import { connect } from '@fabiplay/sdk'
14
+ import { createEngine } from '@fabiplay/engine'
15
+
16
+ const play = await connect()
17
+ const engine = await createEngine({ play })
18
+ engine.stage.add(engine.avatars())
19
+ engine.start()
20
+ play.ready()
21
+ ```
22
+
23
+ `@fabiplay/sdk` is a peer dependency (the engine draws the avatars with the SDK's copy). ESM only, types included.
24
+
25
+ Bundlers that resolve the `development` export condition (Vite and webpack in development) get
26
+ `dist/index.development.js`: readable, with development checks (a warning when a node is used after `destroy()` or
27
+ after a node pool's `release()`). Production builds get `dist/index.js`, without them. Bundling the engine's source instead (inside
28
+ the workspace), the checks are off unless the bundler defines `__DEV__` as `true`.
29
+
30
+ ## Script tag
31
+
32
+ Load the SDK first, then the engine, each pinned with its SRI hash
33
+ (`https://cdn.fabiplay.app/engine/<version>/integrity.json`):
34
+
35
+ ```html
36
+ <script src="https://cdn.fabiplay.app/sdk/0.1.0/fabi-play.umd.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
37
+ <script src="https://cdn.fabiplay.app/engine/0.1.0/fabi-play-engine.lite.umd.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
38
+ <script>
39
+ FabiEngine.createEngine({ play: FabiPlay }).then((engine) => engine.start())
40
+ </script>
41
+ ```
42
+
43
+ | File | What |
44
+ | --- | --- |
45
+ | `fabi-play-engine.lite.umd.min.js` | recommended: takes the avatars and smoothing from the SDK's script (global `FabiEngine`) |
46
+ | `fabi-play-engine.umd.min.js` | everything inside |
47
+ | `*.umd.js` | the same, readable, with the development checks (warnings for nodes used after `destroy()` or a pool's `release()`) |
48
+ | `fabi-play-engine[.lite].js` | the classic scripts (IIFE): set `window.FabiEngine` |
49
+ | `fabi-play-engine[.lite].d.ts` | types for script-tag games (`FabiEngine.Sprite`, …) |
50
+
51
+ Docs: https://docs.fabiplay.app/engine/overview/.
52
+
53
+ ## Hands, orientation, safe area
54
+
55
+ `engine.hands()` (stage units), `engine.touched(node)` and the rings of `engine.handMarkers()` are where the hands
56
+ **aim**, with the protocol's `aimPoint`: on a TV or a tablet (landscape) on the avatar's hand, or on the real one over
57
+ the video, as before; on a phone held upright (`engine.orientation === 'portrait'`), where the camera image is small
58
+ at the bottom, the arms' reach around the shoulders stretched to the whole stage, so arms straight up touch near the
59
+ top (y ≈ 0.15 × 720) and arms out reach the sides, held for 300 ms when the camera loses a wrist. The avatars are still
60
+ drawn through the view (`engine.view`), small at the bottom. Games need no change; to draw on the body itself, use the
61
+ SDK's `toScreen(wrist)`.
62
+
63
+ `engine.safeArea` is what a phone's notch and home bar cover, in fractions of the viewport (`{ top, bottom, left,
64
+ right }`, each 0–0.25, zeros on a TV): keep the HUD and targets out of it, e.g. a score at
65
+ `y = engine.safeArea.top * 720 + 24`.
66
+
67
+ ## Filters
68
+
69
+ Any node can go through filters: colour filters, blur and drop shadows draw the same on WebGL and Canvas 2D; custom
70
+ shaders are WebGL only. Each factory is its own export, so a game bundles only the ones it imports.
71
+
72
+ ```ts
73
+ import { blur, dropShadow, shader, tint } from '@fabiplay/engine'
74
+
75
+ card.filters = [dropShadow(0, 8, 6, 'rgba(0,0,0,0.35)')]
76
+ const flash = tint('#fff', 0)
77
+ enemy.filters = [flash]
78
+ engine.tween(flash, { amount: 1 }, 0.05).then(() => engine.tween(flash, { amount: 0 }, 0.2))
79
+ if (engine.supports.shaders) flag.filters = [shader({ fragment: '…', uniforms: { uAmp: 0.004 } })]
80
+ ```
81
+
82
+ `tint`, `brightness`, `contrast`, `saturate`, `grayscale`, `sepia`, `hueRotate`, `invert`, `colorMatrix`, `blur`,
83
+ `dropShadow`, `shader`. Blur radii are capped per tier (32 / 16 / 0 units: off on the low tier);
84
+ `engine.supports` says what draws here. Guide: https://docs.fabiplay.app/engine/filters/.
85
+
86
+ ## Node pools
87
+
88
+ For games that spawn many nodes a second: `nodePool(factory, { max, reset })` gives nodes back reset to how the
89
+ factory made them, instead of destroying and making them again. An import of its own (`FabiEngine.nodePool` on
90
+ script tags).
91
+
92
+ ```ts
93
+ import { nodePool } from '@fabiplay/engine'
94
+
95
+ const coins = nodePool(() => engine.shape({ type: 'circle', r: 16, fill: '#FBD46A' }), { max: 40 })
96
+ const coin = layer.add(coins.get({ x: 200, y: -20 }))
97
+ engine.tween(coin, { y: 740 }, 2, 'linear').then(() => coins.release(coin))
98
+ ```
99
+
100
+ ## Size
101
+
102
+ `pnpm size` checks every build against `size-budget.json` (gzip -9), and what a game importing only `createEngine`
103
+ bundles from the npm build. The first release (0.1.0) carries filters, node pools, the WebGL state cache, structural
104
+ cache keys and an allocation-free hot path: the npm `index.js` went from 30.3 to 40.1 KB gzip during its
105
+ development, the script tags by the same ~10 KB (they carry everything). A bundled game pays only for what it
106
+ imports: with `createEngine` alone, 32.9 KB (29.1 before). The filter runtime (the GL passes and programs, the
107
+ Canvas 2D plans) comes in with the first filter factory a game imports: one factory adds 3.6 KB, all twelve 5.2 KB.
108
+ `nodePool` is an import of its own: 0.7 KB. The 3.8 KB every game pays (the WebGL state cache, layer bounds,
109
+ structural cache keys, the allocation-free hot path, the filter hook and `engine.supports`) are explained in the
110
+ budget file's `notes`.
111
+
112
+ ## License
113
+
114
+ Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).