@fabi-play/engine 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,76 @@
+Fabi Play Kit License
+Version 1.0 (DRAFT, not yet reviewed by a lawyer)
+
+Copyright (c) 2026 Fabi Play. All rights reserved.
+
+This license applies to the Fabi Play Kit: the packages @fabi-play/protocol, @fabi-play/motion,
+@fabi-play/avatars, @fabi-play/sdk and @fabi-play/engine, in source and built form, as published on npm, served
+from https://cdn.fabiplay.app or found in this repository, including their code, type declarations, documentation,
+avatar artwork and other assets (together, the "Kit").
+
+1. Free of charge, for Fabi Play only
+
+   Fabi Play grants you a worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to
+   use, copy, and modify the Kit, and to distribute it as part of a Permitted Work, solely to make, test, run and
+   distribute Permitted Works.
+
+   A "Permitted Work" is a game, tool, or other software made to run on, be published on, or support the
+   development of games for the Fabi Play platform (https://fabiplay.app), including games submitted to Fabi Play
+   and tools used to build, test or preview them.
+
+2. What is not allowed
+
+   You may not, without Fabi Play's prior written permission:
+
+   a. use the Kit, or any part or modified version of it, in software that is not a Permitted Work, including in
+      any other game platform, product or service;
+   b. distribute the Kit, or a modified version of it, on its own or as a library, SDK, engine or framework for
+      others to build with, other than as part of a Permitted Work (installing it from npm or loading it from
+      https://cdn.fabiplay.app is not a distribution by you);
+   c. sell, rent or sublicense the Kit itself;
+   d. remove or alter this license, copyright notices, or the license banners in the built files;
+   e. use the avatars, the mascot "Fabi", or the name, logos or other trademarks of Fabi Play, except as the Kit
+      does when it runs inside a Permitted Work. This license grants no trademark rights;
+   f. use the Kit to circumvent, interfere with or misrepresent the Fabi Play platform, its safety, privacy or
+      parental controls, or its rules for games.
+
+3. Visible, not open source
+
+   The Kit's code is published so that developers can read it, debug with it and build Permitted Works. Being
+   visible does not make it open source; no rights are granted beyond those stated here.
+
+4. Your works
+
+   You keep all rights in your own code and content. This license does not give Fabi Play any rights in your
+   Permitted Works; publishing a game on Fabi Play is governed by Fabi Play's separate developer terms.
+
+5. Feedback
+
+   If you send Fabi Play suggestions or changes for the Kit, Fabi Play may use them without obligation to you.
+
+6. Termination
+
+   This license ends automatically if you break its terms. If you fix the breach within 30 days of becoming aware
+   of it, the license is reinstated, unless Fabi Play has already told you in writing that it is terminated. On
+   termination you must stop using and distributing the Kit. Permitted Works already distributed to end users in
+   compliance with this license may continue to be used by those end users.
+
+7. No warranty
+
+   THE KIT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FABI PLAY OR ITS CONTRIBUTORS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE KIT OR THE USE OR OTHER DEALINGS IN THE KIT.
+
+9. Changes to this license
+
+   Fabi Play may publish new versions of this license. Each version of the Kit is governed by the license version
+   it is distributed with, unless you choose to accept a later version.
+
+10. Contact
+
+   For permissions beyond this license: https://fabiplay.app

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @fabi-play/engine
 
-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.
+A small 2D engine for [Fabi Play](https://fabiplay.app) games: a 720-unit stage, sprites, shapes, text, particles,
+tweens, sound, the players' hands and avatars, on WebGL (1 or 2) or Canvas 2D.
+
+## npm
+
+```sh
+npm install @fabi-play/sdk @fabi-play/engine
+```
+
+```ts
+import { connect } from '@fabi-play/sdk'
+import { createEngine } from '@fabi-play/engine'
+
+const play = await connect()
+const engine = await createEngine({ play })
+engine.stage.add(engine.avatars())
+engine.start()
+play.ready()
+```
+
+`@fabi-play/sdk` is a peer dependency (the engine draws the avatars with the SDK's copy). ESM only, types included.
+
+Bundlers that resolve the `development` export condition (Vite and webpack in development) get
+`dist/index.development.js`: readable, with development checks (a warning when a node is used after `destroy()` or
+after a node pool's `release()`). Production builds get `dist/index.js`, without them. Bundling the engine's source instead (inside
+the workspace), the checks are off unless the bundler defines `__DEV__` as `true`.
+
+## Script tag
+
+Load the SDK first, then the engine, each pinned with its SRI hash
+(`https://cdn.fabiplay.app/engine/<version>/integrity.json`):
+
+```html
+<script src="https://cdn.fabiplay.app/sdk/0.1.0/fabi-play.umd.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
+<script src="https://cdn.fabiplay.app/engine/0.1.0/fabi-play-engine.lite.umd.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
+<script>
+  FabiEngine.createEngine({ play: FabiPlay }).then((engine) => engine.start())
+</script>
+```
+
+| File | What |
+| --- | --- |
+| `fabi-play-engine.lite.umd.min.js` | recommended: takes the avatars and smoothing from the SDK's script (global `FabiEngine`) |
+| `fabi-play-engine.umd.min.js` | everything inside |
+| `*.umd.js` | the same, readable, with the development checks (warnings for nodes used after `destroy()` or a pool's `release()`) |
+| `fabi-play-engine[.lite].js` | the classic scripts (IIFE): set `window.FabiEngine` |
+| `fabi-play-engine[.lite].d.ts` | types for script-tag games (`FabiEngine.Sprite`, …) |
+
+Docs: https://docs.fabiplay.app/engine/overview/.
+
+## Filters
+
+Any node can go through filters: colour filters, blur and drop shadows draw the same on WebGL and Canvas 2D; custom
+shaders are WebGL only. Each factory is its own export, so a game bundles only the ones it imports.
+
+```ts
+import { blur, dropShadow, shader, tint } from '@fabi-play/engine'
+
+card.filters = [dropShadow(0, 8, 6, 'rgba(0,0,0,0.35)')]
+const flash = tint('#fff', 0)
+enemy.filters = [flash]
+engine.tween(flash, { amount: 1 }, 0.05).then(() => engine.tween(flash, { amount: 0 }, 0.2))
+if (engine.supports.shaders) flag.filters = [shader({ fragment: '…', uniforms: { uAmp: 0.004 } })]
+```
+
+`tint`, `brightness`, `contrast`, `saturate`, `grayscale`, `sepia`, `hueRotate`, `invert`, `colorMatrix`, `blur`,
+`dropShadow`, `shader`. Blur radii are capped per tier (32 / 16 / 0 units: off on the low tier);
+`engine.supports` says what draws here. Guide: https://docs.fabiplay.app/engine/filters/.
+
+## Node pools
+
+For games that spawn many nodes a second: `nodePool(factory, { max, reset })` gives nodes back reset to how the
+factory made them, instead of destroying and making them again. An import of its own (`FabiEngine.nodePool` on
+script tags).
+
+```ts
+import { nodePool } from '@fabi-play/engine'
+
+const coins = nodePool(() => engine.shape({ type: 'circle', r: 16, fill: '#FBD46A' }), { max: 40 })
+const coin = layer.add(coins.get({ x: 200, y: -20 }))
+engine.tween(coin, { y: 740 }, 2, 'linear').then(() => coins.release(coin))
+```
+
+## Size
+
+`pnpm size` checks every build against `size-budget.json` (gzip -9), and what a game importing only `createEngine`
+bundles from the npm build. The first release (0.1.0) carries filters, node pools, the WebGL state cache, structural
+cache keys and an allocation-free hot path: the npm `index.js` went from 30.3 to 40.1 KB gzip during its
+development, the script tags by the same ~10 KB (they carry everything). A bundled game pays only for what it
+imports: with `createEngine` alone, 32.9 KB (29.1 before). The filter runtime (the GL passes and programs, the
+Canvas 2D plans) comes in with the first filter factory a game imports: one factory adds 3.6 KB, all twelve 5.2 KB.
+`nodePool` is an import of its own: 0.7 KB. The 3.8 KB every game pays (the WebGL state cache, layer bounds,
+structural cache keys, the allocation-free hot path, the filter hook and `engine.supports`) are explained in the
+budget file's `notes`.
+
+## License
+
+Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).