@sadhaka/loom-engine 0.10.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.
Files changed (219) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +344 -0
  3. package/dist/animation/animation-clip.d.ts +12 -0
  4. package/dist/animation/animation-clip.d.ts.map +1 -0
  5. package/dist/animation/animation-clip.js +85 -0
  6. package/dist/animation/animation-clip.js.map +1 -0
  7. package/dist/animation/animation-state-pool.d.ts +25 -0
  8. package/dist/animation/animation-state-pool.d.ts.map +1 -0
  9. package/dist/animation/animation-state-pool.js +113 -0
  10. package/dist/animation/animation-state-pool.js.map +1 -0
  11. package/dist/asset/sprite-sheet-loader.d.ts +41 -0
  12. package/dist/asset/sprite-sheet-loader.d.ts.map +1 -0
  13. package/dist/asset/sprite-sheet-loader.js +313 -0
  14. package/dist/asset/sprite-sheet-loader.js.map +1 -0
  15. package/dist/audio/audio-bus.d.ts +43 -0
  16. package/dist/audio/audio-bus.d.ts.map +1 -0
  17. package/dist/audio/audio-bus.js +258 -0
  18. package/dist/audio/audio-bus.js.map +1 -0
  19. package/dist/combat/mob-catalog.d.ts +29 -0
  20. package/dist/combat/mob-catalog.d.ts.map +1 -0
  21. package/dist/combat/mob-catalog.js +104 -0
  22. package/dist/combat/mob-catalog.js.map +1 -0
  23. package/dist/components/health.d.ts +28 -0
  24. package/dist/components/health.d.ts.map +1 -0
  25. package/dist/components/health.js +150 -0
  26. package/dist/components/health.js.map +1 -0
  27. package/dist/components/interactable.d.ts +30 -0
  28. package/dist/components/interactable.d.ts.map +1 -0
  29. package/dist/components/interactable.js +94 -0
  30. package/dist/components/interactable.js.map +1 -0
  31. package/dist/components/particle-emitter.d.ts +62 -0
  32. package/dist/components/particle-emitter.d.ts.map +1 -0
  33. package/dist/components/particle-emitter.js +193 -0
  34. package/dist/components/particle-emitter.js.map +1 -0
  35. package/dist/components/pursue.d.ts +23 -0
  36. package/dist/components/pursue.d.ts.map +1 -0
  37. package/dist/components/pursue.js +96 -0
  38. package/dist/components/pursue.js.map +1 -0
  39. package/dist/components/ranged-attack.d.ts +44 -0
  40. package/dist/components/ranged-attack.d.ts.map +1 -0
  41. package/dist/components/ranged-attack.js +120 -0
  42. package/dist/components/ranged-attack.js.map +1 -0
  43. package/dist/components/sprite.d.ts +27 -0
  44. package/dist/components/sprite.d.ts.map +1 -0
  45. package/dist/components/sprite.js +122 -0
  46. package/dist/components/sprite.js.map +1 -0
  47. package/dist/components/transform.d.ts +30 -0
  48. package/dist/components/transform.d.ts.map +1 -0
  49. package/dist/components/transform.js +150 -0
  50. package/dist/components/transform.js.map +1 -0
  51. package/dist/director/director-bridge.d.ts +22 -0
  52. package/dist/director/director-bridge.d.ts.map +1 -0
  53. package/dist/director/director-bridge.js +23 -0
  54. package/dist/director/director-bridge.js.map +1 -0
  55. package/dist/director/director-encounter-system.d.ts +21 -0
  56. package/dist/director/director-encounter-system.d.ts.map +1 -0
  57. package/dist/director/director-encounter-system.js +128 -0
  58. package/dist/director/director-encounter-system.js.map +1 -0
  59. package/dist/director/director-system.d.ts +19 -0
  60. package/dist/director/director-system.d.ts.map +1 -0
  61. package/dist/director/director-system.js +179 -0
  62. package/dist/director/director-system.js.map +1 -0
  63. package/dist/director/event-envelope.d.ts +144 -0
  64. package/dist/director/event-envelope.d.ts.map +1 -0
  65. package/dist/director/event-envelope.js +108 -0
  66. package/dist/director/event-envelope.js.map +1 -0
  67. package/dist/director/knot-context-resource.d.ts +25 -0
  68. package/dist/director/knot-context-resource.d.ts.map +1 -0
  69. package/dist/director/knot-context-resource.js +152 -0
  70. package/dist/director/knot-context-resource.js.map +1 -0
  71. package/dist/director/mock-director-bridge.d.ts +18 -0
  72. package/dist/director/mock-director-bridge.d.ts.map +1 -0
  73. package/dist/director/mock-director-bridge.js +75 -0
  74. package/dist/director/mock-director-bridge.js.map +1 -0
  75. package/dist/director/snapshot-recovery.d.ts +37 -0
  76. package/dist/director/snapshot-recovery.d.ts.map +1 -0
  77. package/dist/director/snapshot-recovery.js +180 -0
  78. package/dist/director/snapshot-recovery.js.map +1 -0
  79. package/dist/director/sse-director-bridge.d.ts +42 -0
  80. package/dist/director/sse-director-bridge.d.ts.map +1 -0
  81. package/dist/director/sse-director-bridge.js +280 -0
  82. package/dist/director/sse-director-bridge.js.map +1 -0
  83. package/dist/engine.d.ts +25 -0
  84. package/dist/engine.d.ts.map +1 -0
  85. package/dist/engine.js +166 -0
  86. package/dist/engine.js.map +1 -0
  87. package/dist/entity.d.ts +17 -0
  88. package/dist/entity.d.ts.map +1 -0
  89. package/dist/entity.js +77 -0
  90. package/dist/entity.js.map +1 -0
  91. package/dist/index.d.ts +85 -0
  92. package/dist/index.d.ts.map +1 -0
  93. package/dist/index.js +64 -0
  94. package/dist/index.js.map +1 -0
  95. package/dist/input/input-manager.d.ts +91 -0
  96. package/dist/input/input-manager.d.ts.map +1 -0
  97. package/dist/input/input-manager.js +349 -0
  98. package/dist/input/input-manager.js.map +1 -0
  99. package/dist/input/tap-to-walk.d.ts +27 -0
  100. package/dist/input/tap-to-walk.d.ts.map +1 -0
  101. package/dist/input/tap-to-walk.js +118 -0
  102. package/dist/input/tap-to-walk.js.map +1 -0
  103. package/dist/input/virtual-dpad.d.ts +34 -0
  104. package/dist/input/virtual-dpad.d.ts.map +1 -0
  105. package/dist/input/virtual-dpad.js +267 -0
  106. package/dist/input/virtual-dpad.js.map +1 -0
  107. package/dist/renderer/camera.d.ts +26 -0
  108. package/dist/renderer/camera.d.ts.map +1 -0
  109. package/dist/renderer/camera.js +39 -0
  110. package/dist/renderer/camera.js.map +1 -0
  111. package/dist/renderer/canvas2d-device.d.ts +26 -0
  112. package/dist/renderer/canvas2d-device.d.ts.map +1 -0
  113. package/dist/renderer/canvas2d-device.js +252 -0
  114. package/dist/renderer/canvas2d-device.js.map +1 -0
  115. package/dist/renderer/graphics-device.d.ts +36 -0
  116. package/dist/renderer/graphics-device.d.ts.map +1 -0
  117. package/dist/renderer/graphics-device.js +12 -0
  118. package/dist/renderer/graphics-device.js.map +1 -0
  119. package/dist/renderer/iso-projection.d.ts +11 -0
  120. package/dist/renderer/iso-projection.d.ts.map +1 -0
  121. package/dist/renderer/iso-projection.js +59 -0
  122. package/dist/renderer/iso-projection.js.map +1 -0
  123. package/dist/resources.d.ts +28 -0
  124. package/dist/resources.d.ts.map +1 -0
  125. package/dist/resources.js +53 -0
  126. package/dist/resources.js.map +1 -0
  127. package/dist/system.d.ts +14 -0
  128. package/dist/system.d.ts.map +1 -0
  129. package/dist/system.js +25 -0
  130. package/dist/system.js.map +1 -0
  131. package/dist/systems/animation-system.d.ts +8 -0
  132. package/dist/systems/animation-system.d.ts.map +1 -0
  133. package/dist/systems/animation-system.js +77 -0
  134. package/dist/systems/animation-system.js.map +1 -0
  135. package/dist/systems/attack-system.d.ts +17 -0
  136. package/dist/systems/attack-system.d.ts.map +1 -0
  137. package/dist/systems/attack-system.js +94 -0
  138. package/dist/systems/attack-system.js.map +1 -0
  139. package/dist/systems/damage-system.d.ts +18 -0
  140. package/dist/systems/damage-system.d.ts.map +1 -0
  141. package/dist/systems/damage-system.js +77 -0
  142. package/dist/systems/damage-system.js.map +1 -0
  143. package/dist/systems/input-system.d.ts +7 -0
  144. package/dist/systems/input-system.d.ts.map +1 -0
  145. package/dist/systems/input-system.js +27 -0
  146. package/dist/systems/input-system.js.map +1 -0
  147. package/dist/systems/interaction-system.d.ts +23 -0
  148. package/dist/systems/interaction-system.d.ts.map +1 -0
  149. package/dist/systems/interaction-system.js +120 -0
  150. package/dist/systems/interaction-system.js.map +1 -0
  151. package/dist/systems/particle-emitter-system.d.ts +8 -0
  152. package/dist/systems/particle-emitter-system.d.ts.map +1 -0
  153. package/dist/systems/particle-emitter-system.js +161 -0
  154. package/dist/systems/particle-emitter-system.js.map +1 -0
  155. package/dist/systems/particle-render-system.d.ts +7 -0
  156. package/dist/systems/particle-render-system.d.ts.map +1 -0
  157. package/dist/systems/particle-render-system.js +53 -0
  158. package/dist/systems/particle-render-system.js.map +1 -0
  159. package/dist/systems/particle-simulation-system.d.ts +8 -0
  160. package/dist/systems/particle-simulation-system.d.ts.map +1 -0
  161. package/dist/systems/particle-simulation-system.js +45 -0
  162. package/dist/systems/particle-simulation-system.js.map +1 -0
  163. package/dist/systems/projectile-render-system.d.ts +7 -0
  164. package/dist/systems/projectile-render-system.d.ts.map +1 -0
  165. package/dist/systems/projectile-render-system.js +35 -0
  166. package/dist/systems/projectile-render-system.js.map +1 -0
  167. package/dist/systems/projectile-system.d.ts +7 -0
  168. package/dist/systems/projectile-system.d.ts.map +1 -0
  169. package/dist/systems/projectile-system.js +114 -0
  170. package/dist/systems/projectile-system.js.map +1 -0
  171. package/dist/systems/pursue-system.d.ts +7 -0
  172. package/dist/systems/pursue-system.d.ts.map +1 -0
  173. package/dist/systems/pursue-system.js +83 -0
  174. package/dist/systems/pursue-system.js.map +1 -0
  175. package/dist/systems/ranged-attack-system.d.ts +7 -0
  176. package/dist/systems/ranged-attack-system.d.ts.map +1 -0
  177. package/dist/systems/ranged-attack-system.js +98 -0
  178. package/dist/systems/ranged-attack-system.js.map +1 -0
  179. package/dist/systems/sprite-render-system.d.ts +9 -0
  180. package/dist/systems/sprite-render-system.d.ts.map +1 -0
  181. package/dist/systems/sprite-render-system.js +108 -0
  182. package/dist/systems/sprite-render-system.js.map +1 -0
  183. package/dist/systems/veil-budget-system.d.ts +7 -0
  184. package/dist/systems/veil-budget-system.d.ts.map +1 -0
  185. package/dist/systems/veil-budget-system.js +37 -0
  186. package/dist/systems/veil-budget-system.js.map +1 -0
  187. package/dist/util/color.d.ts +19 -0
  188. package/dist/util/color.d.ts.map +1 -0
  189. package/dist/util/color.js +45 -0
  190. package/dist/util/color.js.map +1 -0
  191. package/dist/util/math.d.ts +26 -0
  192. package/dist/util/math.d.ts.map +1 -0
  193. package/dist/util/math.js +47 -0
  194. package/dist/util/math.js.map +1 -0
  195. package/dist/util/typed-arrays.d.ts +7 -0
  196. package/dist/util/typed-arrays.d.ts.map +1 -0
  197. package/dist/util/typed-arrays.js +42 -0
  198. package/dist/util/typed-arrays.js.map +1 -0
  199. package/dist/vfx/particle-pool.d.ts +61 -0
  200. package/dist/vfx/particle-pool.d.ts.map +1 -0
  201. package/dist/vfx/particle-pool.js +204 -0
  202. package/dist/vfx/particle-pool.js.map +1 -0
  203. package/dist/vfx/projectile-pool.d.ts +56 -0
  204. package/dist/vfx/projectile-pool.d.ts.map +1 -0
  205. package/dist/vfx/projectile-pool.js +157 -0
  206. package/dist/vfx/projectile-pool.js.map +1 -0
  207. package/dist/world.d.ts +23 -0
  208. package/dist/world.d.ts.map +1 -0
  209. package/dist/world.js +101 -0
  210. package/dist/world.js.map +1 -0
  211. package/dist/zone/zone-catalog.d.ts +17 -0
  212. package/dist/zone/zone-catalog.d.ts.map +1 -0
  213. package/dist/zone/zone-catalog.js +116 -0
  214. package/dist/zone/zone-catalog.js.map +1 -0
  215. package/dist/zone/zone-state.d.ts +18 -0
  216. package/dist/zone/zone-state.d.ts.map +1 -0
  217. package/dist/zone/zone-state.js +52 -0
  218. package/dist/zone/zone-state.js.map +1 -0
  219. package/package.json +56 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Misha Mitiev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,344 @@
1
+ # Loom Engine
2
+
3
+ Browser-first 2D / 2.5D game engine for [TheWorldTable.ai](https://theworldtable.ai).
4
+ Canvas2D primary backend, ECS, render-graph stages, Director-bridge
5
+ SSE integration. No external engine reuse - built from scratch in
6
+ TypeScript.
7
+
8
+ Repo: [sadhaka/loom-engine](https://github.com/sadhaka/loom-engine).
9
+ API docs: [loom-engine.pages.dev](https://loom-engine.pages.dev/).
10
+ The design spec (`LOOM-ENGINE-SPEC.md`) lives in the consuming
11
+ TheWorldTable.ai repo and is the canonical source for phase
12
+ plans and architectural decisions.
13
+
14
+ ## Install
15
+
16
+ ```sh
17
+ npm install @sadhaka/loom-engine
18
+ ```
19
+
20
+ Pre-alpha. ESM-only, browser-first. TypeScript types ship in the
21
+ package (`dist/index.d.ts`). Node 18+ for the build toolchain;
22
+ the runtime targets evergreen browsers (Canvas2D + Web Audio +
23
+ EventSource).
24
+
25
+ ## Documentation
26
+
27
+ API reference (TypeDoc) - generated from the public surface in
28
+ [`src/index.ts`](./src/index.ts) on every push to `main`:
29
+ **https://loom-engine.pages.dev/**
30
+
31
+ Build it locally with `npm run docs` (writes to `./docs/`).
32
+
33
+ See [Docs deploy](#docs-deploy) for the hosting chain and one-time
34
+ activation steps (Cloudflare Pages, since GitHub Pages is unavailable
35
+ on private repos for free user plans).
36
+
37
+ ## Quickstart
38
+
39
+ ```ts
40
+ // 1. Install
41
+ // npm install @sadhaka/loom-engine
42
+ import {
43
+ Engine,
44
+ SpriteRenderSystem,
45
+ InputSystem,
46
+ VeilBudgetSystem,
47
+ SYSTEM_PHASE_INPUT,
48
+ SYSTEM_PHASE_RENDER,
49
+ } from '@sadhaka/loom-engine';
50
+
51
+ // 2. Attach to a canvas. Engine.create wires Canvas2DDevice, World,
52
+ // TransformPool, SpritePool, Time + Camera resources, and the
53
+ // default SpriteRenderSystem in SYSTEM_PHASE_RENDER.
54
+ var canvas = document.querySelector('canvas');
55
+ var engine = Engine.create({ canvas: canvas });
56
+
57
+ // 3. Register the systems your game needs. Order within a phase is
58
+ // deterministic; phases run INPUT -> LOGIC -> PHYSICS -> ANIMATION
59
+ // -> RENDER -> POST_RENDER per frame.
60
+ engine.world.addSystem(new InputSystem(), SYSTEM_PHASE_INPUT);
61
+ engine.world.addSystem(new VeilBudgetSystem(), SYSTEM_PHASE_INPUT);
62
+
63
+ // 4. Drive the frame loop. engine.tick advances Time, beginFrame on
64
+ // the device, world.update across all phases, endFrame.
65
+ function tick(now) {
66
+ engine.tick(now);
67
+ requestAnimationFrame(tick);
68
+ }
69
+ requestAnimationFrame(tick);
70
+ ```
71
+
72
+ ## Status
73
+
74
+ **Pre-alpha, productized as of 0.10.0** (Phase 11B.3 - npm publish
75
+ under MIT). Phases 0 through 9.3 + 11A.2 are shipped; the engine
76
+ runs the public TheWorldTable.ai pre-alpha. Productization is a
77
+ fund-raising and distribution decision, not a stability claim - the
78
+ public API surface will evolve until 1.0.
79
+
80
+ | Phase | Status | Surface |
81
+ |---|---|---|
82
+ | 0 | shipped | scaffolding, package.json, tsconfig, PRIOR-ART log |
83
+ | 1 | shipped | Canvas2D iso renderer, camera, transform pool (SoA) |
84
+ | 2 | shipped | ECS World, system scheduler, resource registry, Engine facade, asset pipeline |
85
+ | 3 | shipped | clip-aware sprite-sheet manifests, AnimationStatePool, AnimationSystem |
86
+ | 4 | shipped | particle pool, emitter component, three-system VFX pipeline, additive blend |
87
+ | 5 | shipped | Web Audio bus mixer with VE-budget gating, unified keyboard / mouse / touch input |
88
+ | 6 | shipped | Director-bridge: SSE event-stream subscription, eventSourceFactory hook, snapshot-recovery |
89
+ | 7 | shipped | Survivor combat layer (projectile pool, hit resolution, damage application) ported onto Loom Engine |
90
+ | 8 | shipped | 2.5D ARPG hub-and-spoke per LOOM-CLASS-SYSTEM-SPEC, plaza narrator, mobile + touch input (virtual D-pad, tap-to-walk) |
91
+ | 9.1 | shipped | perf pass: alloc-churn fixes + bench harness |
92
+ | 9.3 | shipped | TypeDoc public-API site with auto-deploy |
93
+ | 11A.2 | shipped | docs hosting migrated to Cloudflare Pages |
94
+ | 11B.3 | shipped | MIT license + npm publish posture (this release) |
95
+
96
+ See [LOOM-ENGINE-SPEC.md](../docker/LOOM-ENGINE-SPEC.md) Section 7
97
+ for the full phase plan with effort estimates.
98
+
99
+ ## Build
100
+
101
+ ```sh
102
+ npm install
103
+ npm run build # tsc src/ -> dist/
104
+ npm run build:demo # tsc demo/*.ts -> demo/*.js
105
+ npm run build:all # both
106
+ npm run watch # rebuild src on change
107
+ npm run test # tsx tests/*.test.ts
108
+ npm run clean # remove dist + compiled demo
109
+ ```
110
+
111
+ ## Run the demo
112
+
113
+ ```sh
114
+ npm run build:all
115
+ python -m http.server 8765
116
+ # browse http://localhost:8765/demo/index.html
117
+ ```
118
+
119
+ Controls:
120
+ - **Arrow keys / WASD**: pan camera
121
+ - **Click**: burst 24 particles + play SFX chirp (after first click, AudioContext unlocks)
122
+ - **Hover**: stats panel shows the iso tile under the cursor
123
+
124
+ ## Layout
125
+
126
+ ```
127
+ loom-engine/
128
+ src/
129
+ util/ math, color, typed-arrays
130
+ components/ transform, sprite, particle-emitter
131
+ renderer/ graphics-device, canvas2d-device, camera, iso-projection
132
+ animation/ animation-clip, animation-state-pool
133
+ asset/ sprite-sheet-loader
134
+ audio/ audio-bus
135
+ input/ input-manager
136
+ systems/ sprite-render, animation, particle-{simulation,emitter,render}, input, veil-budget
137
+ vfx/ particle-pool
138
+ entity.ts entity allocator (32-bit handle, generation guard)
139
+ world.ts ECS World class
140
+ system.ts System interface + phase constants
141
+ resources.ts ResourceRegistry + Time + VeilBudget
142
+ engine.ts Engine facade
143
+ index.ts public API barrel
144
+ demo/ browser demo (one tile + animated knight + sparkles + click-to-burst)
145
+ tests/ node-based smoke tests (tsx --test)
146
+ assets/ placeholder game assets (knight walk-cycle PNG + JSON)
147
+ tools/ helper scripts (gen-knight.py - Pillow generator)
148
+ PRIOR-ART.md cumulative inspirations log (clean-room defense)
149
+ package.json tsc + tsx as only dev deps
150
+ tsconfig.json ES2022 strict + noUncheckedIndexedAccess
151
+ dist/ tsc output (gitignored)
152
+ node_modules/ npm install output (gitignored)
153
+ ```
154
+
155
+ ## Architecture quick-reference
156
+
157
+ - **ECS** over god-object scene graph - entities are 32-bit handles,
158
+ components live in pools indexed by entity index
159
+ - **Structure-of-arrays** for hot data (TransformPool, SpritePool,
160
+ ParticlePool, ParticleEmitterPool, AnimationStatePool) - tight
161
+ iteration over Float32Arrays, no per-entity object allocation
162
+ - **IGraphicsDevice** abstraction with Canvas2D primary backend
163
+ (WebGL2 reserved for Phase 2+ if profiling demands)
164
+ - **6-phase scheduler** - INPUT -> LOGIC -> PHYSICS -> ANIMATION ->
165
+ RENDER -> POST_RENDER, deterministic registration order within each
166
+ - **VeilBudgetResource** - the patent-defensible novelty hook. Single
167
+ resource with `particleBudget`, `audioBudget`, `shaderBudget`,
168
+ `eventBudget`. VeilBudgetSystem propagates updates to ParticlePool,
169
+ AudioBus, etc. Director-bridge mutates the budget; subsystems read
170
+ - **Frame loop** - `engine.tick(now)` runs in this order:
171
+ 1. compute dt (clamped to 1/30s)
172
+ 2. advance Time resource
173
+ 3. device.beginFrame
174
+ 4. world.update (walks all phases)
175
+ 5. device.endFrame
176
+
177
+ ## Public API surface (Phase 5)
178
+
179
+ ```ts
180
+ import {
181
+ Engine,
182
+ // ECS
183
+ POOL_TRANSFORM, POOL_SPRITE, POOL_ANIMATION, POOL_PARTICLE,
184
+ POOL_EMITTER,
185
+ TransformPool, SpritePool, AnimationStatePool, ParticlePool,
186
+ ParticleEmitterPool,
187
+ SYSTEM_PHASE_INPUT, SYSTEM_PHASE_LOGIC, SYSTEM_PHASE_PHYSICS,
188
+ SYSTEM_PHASE_ANIMATION, SYSTEM_PHASE_RENDER, SYSTEM_PHASE_POST_RENDER,
189
+ // Default systems
190
+ AnimationSystem, SpriteRenderSystem,
191
+ ParticleEmitterSystem, ParticleSimulationSystem, ParticleRenderSystem,
192
+ InputSystem, VeilBudgetSystem,
193
+ // Resources
194
+ RESOURCE_TIME, RESOURCE_CAMERA, RESOURCE_DEVICE,
195
+ RESOURCE_VEIL_BUDGET, RESOURCE_INPUT, RESOURCE_AUDIO_BUS,
196
+ // Renderer
197
+ Canvas2DDevice, ISO_TILE_WIDTH, ISO_TILE_HEIGHT,
198
+ // Asset
199
+ loadSpriteSheet, computeFrameIndex,
200
+ // Audio
201
+ AudioBus, AUDIO_BUDGET_AMBIENT_FLOOR, AUDIO_BUDGET_ESSENTIAL_FLOOR,
202
+ // Input
203
+ InputManager,
204
+ // Math + color
205
+ vec2, vec3, rect, clamp, lerp,
206
+ hexToRgba, rgbaToCssString,
207
+ COLOR_KNOT_STR, COLOR_KNOT_DEX, COLOR_KNOT_INT, COLOR_KNOT_CENTER,
208
+ // Iso
209
+ tileToIso, worldToIso, isoToTile, isoDepthKey,
210
+ } from '@sadhaka/loom-engine';
211
+
212
+ const engine = Engine.create({ canvas });
213
+ engine.world.addSystem(new InputSystem(), SYSTEM_PHASE_INPUT);
214
+ engine.world.addSystem(new VeilBudgetSystem(), SYSTEM_PHASE_INPUT);
215
+ // ... game systems ...
216
+ engine.world.addSystem(new SpriteRenderSystem(), SYSTEM_PHASE_RENDER);
217
+ function tick(now: number) {
218
+ engine.tick(now);
219
+ requestAnimationFrame(tick);
220
+ }
221
+ requestAnimationFrame(tick);
222
+ ```
223
+
224
+ ## Patent strategy
225
+
226
+ The engine's defensible novelty is in the **Loom integration layer**,
227
+ not the rasterizer. Director-driven scene state, Veil Essence economy
228
+ gating render budget, knot-aware encounter generation, event-sourced
229
+ rendering. The renderer underneath uses public-domain techniques
230
+ (sprite batching, isometric projection, ECS) implemented from scratch.
231
+
232
+ See [PRIOR-ART.md](./PRIOR-ART.md) for the cumulative inspirations
233
+ log (public talks, papers, OSS architecture - took / declined per
234
+ source).
235
+
236
+ Every architectural commit names its inspirations in plain text. No
237
+ copy-paste from any external engine source. PRIOR-ART.md is the
238
+ audit trail any future productization or patent dispute would lean on.
239
+
240
+ ## Test coverage
241
+
242
+ 208 / 208 tests pass on Node 24 via `tsx --test`. Coverage spans
243
+ all twelve test files in `tests/`:
244
+
245
+ - `smoke.test.ts` - public API barrel, version stamp
246
+ - `world.test.ts` - ECS world, system scheduling, sprite pool, sprite render, time
247
+ - `asset-loader.test.ts` - sprite-sheet manifest, frame stepper, error discriminator
248
+ - `animation.test.ts` - animation clip math, state pool, AnimationSystem end-to-end
249
+ - `vfx.test.ts` - particle pool, emitter pool, simulation, emitter system, veil budget
250
+ - `audio-input.test.ts` - audio bus + ducking, input manager, input system, budget propagation
251
+ - `director.test.ts` - SSE bridge, eventSourceFactory hook, scene-state derivation
252
+ - `combat.test.ts` - hit resolution, damage application, knockback
253
+ - `projectile.test.ts` - projectile pool, lifetime, collision
254
+ - `arpg.test.ts` - ARPG hub-and-spoke, plaza narrator, encounter scheduling
255
+ - `snapshot-recovery.test.ts` - SnapshotRecoveryHelper for Director reconnect
256
+ - `touch-input.test.ts` - virtual D-pad, tap-to-walk, multi-touch arbitration
257
+
258
+ Run via `npm test`. Each suite is fully node-based; no DOM dependency.
259
+ Browser-only paths (Canvas2DDevice rasterization, AudioContext
260
+ unlock, DOM event listeners) are exercised via the demo's preview
261
+ verification, not unit tests.
262
+
263
+ ## Docs deploy
264
+
265
+ The TypeDoc site at **https://loom-engine.pages.dev/** is served by
266
+ Cloudflare Pages from the `gh-pages` branch of this repo. The chain:
267
+
268
+ 1. Push to `main` triggers `.github/workflows/docs.yml`
269
+ 2. Workflow runs `npm ci`, `npm test`, `npm run docs:ci`, then publishes
270
+ `./docs-build/` to the `gh-pages` branch via `peaceiris/actions-gh-pages`
271
+ 3. Cloudflare Pages watches the `gh-pages` branch and auto-deploys on
272
+ every push, typically within 1-2 min
273
+
274
+ GitHub Pages itself is **not** used: the repo is private and free user
275
+ plans do not include Pages on private repos. The 422 error from the
276
+ Pages create API is the canonical signal: `"Your current plan does not
277
+ support GitHub Pages for this repository."`
278
+
279
+ ### Re-creating the deploy from scratch
280
+
281
+ If the Cloudflare Pages project is ever deleted or the repo is forked
282
+ to a new owner, re-activate as follows:
283
+
284
+ 1. Cloudflare dashboard -> **Workers & Pages** -> **Create** -> **Pages** ->
285
+ **Connect to Git**
286
+ 2. Authorize Cloudflare on the GitHub account that owns the repo
287
+ (only the engine repo needs to be granted access)
288
+ 3. Select `loom-engine`, name the project `loom-engine` (default URL
289
+ becomes `loom-engine.pages.dev`)
290
+ 4. **Production branch**: `gh-pages`
291
+ 5. **Build command**: leave empty (the gh-pages branch is already a
292
+ built static site)
293
+ 6. **Build output directory**: `/` (root)
294
+ 7. Save and deploy. First deploy reads whatever is currently on
295
+ `gh-pages`; subsequent deploys auto-trigger on push to that branch
296
+ 8. Optional: assign a custom domain (e.g. `engine.theworldtable.ai`)
297
+ under the project's **Custom domains** tab. CF DNS for
298
+ `theworldtable.ai` is already on the same account, so this is a
299
+ one-click CNAME add
300
+
301
+ If the workflow ever stops updating `gh-pages` (CF Pages will keep
302
+ serving the last successful build but go stale), check
303
+ `gh run list --repo sadhaka/loom-engine --workflow=docs.yml`.
304
+
305
+ ## License
306
+
307
+ [MIT](./LICENSE). Copyright (c) 2026 Misha Mitiev.
308
+
309
+ You can use the engine in commercial and non-commercial work without
310
+ royalties. Attribution is appreciated but not required by the license.
311
+ The patent-defensible novelty claims (see [Patent strategy](#patent-strategy))
312
+ are about specific architectural patterns documented in PRIOR-ART.md;
313
+ they are independent of the source-code license and do not constrain
314
+ typical engine reuse.
315
+
316
+ ## Publishing
317
+
318
+ Tagged releases publish to npm via
319
+ [`.github/workflows/npm-publish.yml`](./.github/workflows/npm-publish.yml).
320
+ The workflow runs `npm test` and `npm run build`, then
321
+ `npm publish --access public`, when a tag matching `v*` is pushed to
322
+ `main`. It needs the `NPM_TOKEN` repo secret to authenticate.
323
+
324
+ Manual publish from a local checkout:
325
+
326
+ ```sh
327
+ npm login # one-time, npm account named sadhaka
328
+ npm test # 208/208 must pass
329
+ npm run build # tsc -> dist/
330
+ npm publish --dry-run # inspect tarball contents first
331
+ npm publish --access public # scoped packages default to private; flag is required
332
+ ```
333
+
334
+ `prepublishOnly` in `package.json` re-runs `npm test && npm run build`
335
+ before any publish, so the dry-run and the final publish always rebuild
336
+ from a clean source tree.
337
+
338
+ ## Contributing
339
+
340
+ This is a single-author project (Misha Mitiev) for TheWorldTable.ai.
341
+ The MIT license permits forking and modification; pull requests are
342
+ welcome but not actively triaged - the canonical roadmap is the spec
343
+ file (`LOOM-ENGINE-SPEC.md` in the parent repo) and capacity is
344
+ limited. For bug reports, file an issue with a minimal repro.
@@ -0,0 +1,12 @@
1
+ export interface AnimationClip {
2
+ name: string;
3
+ frames: ReadonlyArray<number>;
4
+ durations_ms?: ReadonlyArray<number>;
5
+ loop: boolean;
6
+ fps?: number;
7
+ }
8
+ export declare function synthesizeDefaultClip(frameCount: number): AnimationClip;
9
+ export declare function clipDurationMs(clip: AnimationClip, manifestFps: number): number;
10
+ export declare function frameInClipAt(clip: AnimationClip, elapsedMs: number, manifestFps: number): number;
11
+ export declare function manifestFrameIndex(clip: AnimationClip, frameInClip: number): number;
12
+ //# sourceMappingURL=animation-clip.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"animation-clip.d.ts","sourceRoot":"","sources":["../../src/animation/animation-clip.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAG5B,IAAI,EAAE,MAAM,CAAC;IAKb,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAK9B,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAOrC,IAAI,EAAE,OAAO,CAAC;IAId,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAQvE;AAKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAW/E;AAMD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,CA+BR;AAKD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEnF"}
@@ -0,0 +1,85 @@
1
+ // AnimationClip - a named slice of a sprite sheet's frames[].
2
+ //
3
+ // One clip = one named animation (idle, walk, attack, etc.) on one
4
+ // sheet. The sheet manifest carries an optional clips[] field; if
5
+ // absent, the loader synthesizes a single 'default' clip covering
6
+ // all frames in order with the manifest's fps.
7
+ //
8
+ // Per-frame duration_ms takes precedence over the clip's fps which
9
+ // takes precedence over the manifest's fps. This mirrors Aseprite's
10
+ // tag + per-frame-duration pattern (see PRIOR-ART.md).
11
+ // Synthesizes a 'default' clip covering all frames of a manifest.
12
+ // Used when a manifest doesn't declare its own clips[] - keeps
13
+ // backward compat with the asset-pipeline session's original schema.
14
+ export function synthesizeDefaultClip(frameCount) {
15
+ const frames = [];
16
+ for (let i = 0; i < frameCount; i++)
17
+ frames.push(i);
18
+ return {
19
+ name: 'default',
20
+ frames,
21
+ loop: true,
22
+ };
23
+ }
24
+ // Total cycle duration of a clip in milliseconds. Honors precedence:
25
+ // per-frame durations_ms[] > clip.fps > manifestFps
26
+ // All clips with at least one frame have a positive duration.
27
+ export function clipDurationMs(clip, manifestFps) {
28
+ if (clip.durations_ms && clip.durations_ms.length === clip.frames.length) {
29
+ let total = 0;
30
+ for (let i = 0; i < clip.durations_ms.length; i++) {
31
+ total += clip.durations_ms[i] ?? 0;
32
+ }
33
+ return total;
34
+ }
35
+ const fps = clip.fps ?? manifestFps;
36
+ if (fps <= 0 || clip.frames.length === 0)
37
+ return 0;
38
+ return (clip.frames.length * 1000) / fps;
39
+ }
40
+ // Resolve which frame within a clip should display at a given
41
+ // elapsed time. Returns the index INTO clip.frames (not into the
42
+ // parent manifest). A non-looping clip held past its duration
43
+ // returns the last frame.
44
+ export function frameInClipAt(clip, elapsedMs, manifestFps) {
45
+ const n = clip.frames.length;
46
+ if (n === 0)
47
+ return 0;
48
+ if (n === 1)
49
+ return 0;
50
+ const total = clipDurationMs(clip, manifestFps);
51
+ if (total <= 0)
52
+ return 0;
53
+ let t = elapsedMs;
54
+ if (clip.loop) {
55
+ t = ((t % total) + total) % total;
56
+ }
57
+ else if (t >= total) {
58
+ return n - 1;
59
+ }
60
+ else if (t < 0) {
61
+ return 0;
62
+ }
63
+ // Per-frame durations: walk the array.
64
+ if (clip.durations_ms && clip.durations_ms.length === n) {
65
+ let acc = 0;
66
+ for (let i = 0; i < n; i++) {
67
+ acc += clip.durations_ms[i] ?? 0;
68
+ if (t < acc)
69
+ return i;
70
+ }
71
+ return n - 1;
72
+ }
73
+ // Uniform per-frame duration.
74
+ const fps = clip.fps ?? manifestFps;
75
+ const frameMs = 1000 / fps;
76
+ const idx = Math.floor(t / frameMs);
77
+ return idx >= n ? n - 1 : idx;
78
+ }
79
+ // Resolve clip.frames[i] to its parent manifest frame index. Bounds-
80
+ // safe: out-of-range returns 0 (rendering a black frame is preferable
81
+ // to throwing in the render loop).
82
+ export function manifestFrameIndex(clip, frameInClip) {
83
+ return clip.frames[frameInClip] ?? 0;
84
+ }
85
+ //# sourceMappingURL=animation-clip.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"animation-clip.js","sourceRoot":"","sources":["../../src/animation/animation-clip.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,25 @@
1
+ import { type EntityId } from '../entity.js';
2
+ import type { SpriteSheetManifest } from '../asset/sprite-sheet-loader.js';
3
+ export declare const ANIMATION_FLAG_ACTIVE: number;
4
+ export declare const ANIMATION_FLAG_FINISHED: number;
5
+ export declare class AnimationStatePool {
6
+ elapsedMs: Float32Array;
7
+ manifest: Array<SpriteSheetManifest | null>;
8
+ clipName: string[];
9
+ flags: Uint8Array;
10
+ private highWaterMark;
11
+ private capacity;
12
+ constructor(initialCapacity?: number);
13
+ ensureCapacity(neededIndex: number): void;
14
+ play(e: EntityId, manifest: SpriteSheetManifest, clipName: string, options?: {
15
+ startMs?: number;
16
+ }): void;
17
+ stop(e: EntityId): void;
18
+ isActive(e: EntityId): boolean;
19
+ isFinished(e: EntityId): boolean;
20
+ getClipName(e: EntityId): string;
21
+ getManifest(e: EntityId): SpriteSheetManifest | null;
22
+ getHighWaterMark(): number;
23
+ getCapacity(): number;
24
+ }
25
+ //# sourceMappingURL=animation-state-pool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"animation-state-pool.d.ts","sourceRoot":"","sources":["../../src/animation/animation-state-pool.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,KAAK,QAAQ,EAAe,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,qBAAa,kBAAkB;IAE7B,SAAS,EAAE,YAAY,CAAC;IAGxB,QAAQ,EAAE,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IAGnB,KAAK,EAAE,UAAU,CAAC;IAElB,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;gBAEjB,eAAe,GAAE,MAAW;IAQxC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAiBzC,IAAI,CACF,CAAC,EAAE,QAAQ,EACX,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GACjC,IAAI;IAaP,IAAI,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI;IASvB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IAS9B,UAAU,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IAOhC,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM;IAOhC,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,IAAI;IAMpD,gBAAgB,IAAI,MAAM;IAI1B,WAAW,IAAI,MAAM;CAGtB"}
@@ -0,0 +1,113 @@
1
+ // AnimationStatePool - per-entity animation state.
2
+ //
3
+ // Companion to TransformPool + SpritePool. An entity that has
4
+ // AnimationState gets its sprite frame advanced by AnimationSystem
5
+ // each tick.
6
+ //
7
+ // State per entity:
8
+ // - manifest: which sheet's clips[] to look in
9
+ // - clipName: which named clip is currently playing
10
+ // - elapsedMs: time since the clip started, monotonically advanced
11
+ // by AnimationSystem
12
+ // - flags: ACTIVE, FINISHED (non-looping clip past its duration)
13
+ //
14
+ // elapsedMs is hot data - a Float32Array indexed by entity index.
15
+ // manifest + clipName are cold (per-entity object refs / strings),
16
+ // in plain arrays.
17
+ import { entityIndex } from '../entity.js';
18
+ import { growF32, growU8, nextPow2 } from '../util/typed-arrays.js';
19
+ export const ANIMATION_FLAG_ACTIVE = 1 << 0;
20
+ export const ANIMATION_FLAG_FINISHED = 1 << 1;
21
+ export class AnimationStatePool {
22
+ // Hot data
23
+ elapsedMs;
24
+ // Cold data - per-entity object/string refs
25
+ manifest;
26
+ clipName;
27
+ // Bitflags
28
+ flags;
29
+ highWaterMark = 0;
30
+ capacity = 0;
31
+ constructor(initialCapacity = 64) {
32
+ this.capacity = nextPow2(initialCapacity);
33
+ this.elapsedMs = new Float32Array(this.capacity);
34
+ this.manifest = new Array(this.capacity).fill(null);
35
+ this.clipName = new Array(this.capacity).fill('');
36
+ this.flags = new Uint8Array(this.capacity);
37
+ }
38
+ ensureCapacity(neededIndex) {
39
+ if (neededIndex < this.capacity)
40
+ return;
41
+ const next = nextPow2(neededIndex + 1);
42
+ this.elapsedMs = growF32(this.elapsedMs, next);
43
+ // Plain JS arrays don't have a "grow" helper; just resize.
44
+ this.manifest.length = next;
45
+ this.clipName.length = next;
46
+ for (let i = this.capacity; i < next; i++) {
47
+ this.manifest[i] = null;
48
+ this.clipName[i] = '';
49
+ }
50
+ this.flags = growU8(this.flags, next);
51
+ this.capacity = next;
52
+ }
53
+ // Start a clip on an entity. Resets elapsedMs to 0 so the clip
54
+ // plays from frame 0 (or the user-supplied startMs offset).
55
+ play(e, manifest, clipName, options = {}) {
56
+ const i = entityIndex(e);
57
+ this.ensureCapacity(i);
58
+ this.manifest[i] = manifest;
59
+ this.clipName[i] = clipName;
60
+ this.elapsedMs[i] = options.startMs ?? 0;
61
+ this.flags[i] = ANIMATION_FLAG_ACTIVE;
62
+ if (i >= this.highWaterMark)
63
+ this.highWaterMark = i + 1;
64
+ }
65
+ // Stop animation on an entity. Frame stays where it was; the
66
+ // sprite-render system continues drawing whatever frame the
67
+ // SpritePool currently holds.
68
+ stop(e) {
69
+ const i = entityIndex(e);
70
+ if (i >= this.capacity)
71
+ return;
72
+ this.flags[i] = 0;
73
+ this.manifest[i] = null;
74
+ this.clipName[i] = '';
75
+ }
76
+ // True if the entity has an ACTIVE animation right now.
77
+ isActive(e) {
78
+ const i = entityIndex(e);
79
+ if (i >= this.capacity)
80
+ return false;
81
+ return ((this.flags[i] ?? 0) & ANIMATION_FLAG_ACTIVE) !== 0;
82
+ }
83
+ // True if the entity's last clip was non-looping and ran out.
84
+ // Cleared by play(); systems can poll this to chain transitions
85
+ // (e.g. attack -> idle).
86
+ isFinished(e) {
87
+ const i = entityIndex(e);
88
+ if (i >= this.capacity)
89
+ return false;
90
+ return ((this.flags[i] ?? 0) & ANIMATION_FLAG_FINISHED) !== 0;
91
+ }
92
+ // The active clip name. Empty string when no clip is playing.
93
+ getClipName(e) {
94
+ const i = entityIndex(e);
95
+ if (i >= this.capacity)
96
+ return '';
97
+ return this.clipName[i] ?? '';
98
+ }
99
+ // The active manifest. Null when no clip is playing.
100
+ getManifest(e) {
101
+ const i = entityIndex(e);
102
+ if (i >= this.capacity)
103
+ return null;
104
+ return this.manifest[i] ?? null;
105
+ }
106
+ getHighWaterMark() {
107
+ return this.highWaterMark;
108
+ }
109
+ getCapacity() {
110
+ return this.capacity;
111
+ }
112
+ }
113
+ //# sourceMappingURL=animation-state-pool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"animation-state-pool.js","sourceRoot":"","sources":["../../src/animation/animation-state-pool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,41 @@
1
+ import type { AtlasDescriptor } from '../renderer/graphics-device.js';
2
+ import type { AnimationClip } from '../animation/animation-clip.js';
3
+ export interface SpriteFrame {
4
+ x: number;
5
+ y: number;
6
+ w: number;
7
+ h: number;
8
+ name?: string;
9
+ duration_ms?: number;
10
+ }
11
+ export interface SpriteAnchor {
12
+ x: number;
13
+ y: number;
14
+ }
15
+ export interface SpriteSheetManifest {
16
+ name: string;
17
+ image: string;
18
+ frames: ReadonlyArray<SpriteFrame>;
19
+ anchor: SpriteAnchor;
20
+ fps: number;
21
+ clips: ReadonlyArray<AnimationClip>;
22
+ }
23
+ export interface LoadedSpriteSheet {
24
+ manifest: SpriteSheetManifest;
25
+ image: HTMLImageElement;
26
+ atlas: AtlasDescriptor;
27
+ }
28
+ export declare class SpriteSheetLoadError extends Error {
29
+ readonly kind: 'fetch-manifest' | 'parse-manifest' | 'invalid-manifest' | 'fetch-image' | 'decode-image';
30
+ readonly url: string;
31
+ constructor(kind: SpriteSheetLoadError['kind'], url: string, message: string, options?: {
32
+ cause?: unknown;
33
+ });
34
+ }
35
+ export interface LoaderOptions {
36
+ fetchImpl?: typeof fetch;
37
+ decodeImage?: (bytes: ArrayBuffer, url: string) => Promise<HTMLImageElement>;
38
+ }
39
+ export declare function loadSpriteSheet(manifestUrl: string, options?: LoaderOptions): Promise<LoadedSpriteSheet>;
40
+ export declare function computeFrameIndex(manifest: SpriteSheetManifest, now: number, start: number): number;
41
+ //# sourceMappingURL=sprite-sheet-loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sprite-sheet-loader.d.ts","sourceRoot":"","sources":["../../src/asset/sprite-sheet-loader.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,eAAe,EAChB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAKpE,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAGD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IAIZ,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CACrC;AAMD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,gBAAgB,CAAC;IAIxB,KAAK,EAAE,eAAe,CAAC;CACxB;AAID,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EACT,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,cAAc,CAAC;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAEnB,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOhC;AAID,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAIzB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9E;AA0OD,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAmE5B;AASD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,MAAM,CAiCR"}