@egret/engine 7.0.1-rc.3 → 7.0.2

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 (304) hide show
  1. package/dist/Engine.js +7 -2
  2. package/dist/animation/sequenceResetTypes.d.ts +6 -0
  3. package/dist/animation/types.d.ts +6 -0
  4. package/dist/assetBundle.d.ts +2 -0
  5. package/dist/assetGroupTypes.d.ts +2 -0
  6. package/dist/audioCues.d.ts +4 -0
  7. package/dist/audioTypes.d.ts +13 -0
  8. package/dist/bitmapButtonTypes.d.ts +2 -0
  9. package/dist/bitmapFontTypes.d.ts +3 -0
  10. package/dist/bitmapResourceSlot.d.ts +1 -0
  11. package/dist/camera2d.js +10 -2
  12. package/dist/cameraTypes.d.ts +12 -0
  13. package/dist/contentTypes.d.ts +2 -0
  14. package/dist/createEngineForProfile.js +8 -5
  15. package/dist/fontContentTypes.d.ts +5 -0
  16. package/dist/gameClockTypes.d.ts +6 -0
  17. package/dist/gameRun.d.ts +3 -0
  18. package/dist/gamepadTypes.d.ts +8 -0
  19. package/dist/hoverInputTypes.d.ts +10 -0
  20. package/dist/index.d.ts +5 -2
  21. package/dist/index.js +2 -1
  22. package/dist/inputActions.d.ts +5 -0
  23. package/dist/internal/uiFactoryState.d.ts +4 -0
  24. package/dist/internal/uiFactoryState.js +18 -2
  25. package/dist/keyboardInput.d.ts +1 -0
  26. package/dist/keyboardInput.js +1 -0
  27. package/dist/keyboardInputTypes.d.ts +12 -0
  28. package/dist/kit.d.ts +3 -1
  29. package/dist/kit.js +2 -1
  30. package/dist/manifestResourceState.d.ts +1 -0
  31. package/dist/manifestResourceState.js +1 -0
  32. package/dist/manifestResourceTypes.d.ts +1 -0
  33. package/dist/motion.d.ts +2 -0
  34. package/dist/mouseInputTypes.d.ts +4 -0
  35. package/dist/particleEmitter.js +8 -0
  36. package/dist/particleTypes.d.ts +8 -0
  37. package/dist/physics2d.d.ts +2 -2
  38. package/dist/physics2d.js +1 -1
  39. package/dist/physics2dTypes.d.ts +55 -1
  40. package/dist/physics2dWorld.js +209 -9
  41. package/dist/pointerInput.d.ts +1 -0
  42. package/dist/pointerInput.js +1 -0
  43. package/dist/pointerInputTypes.d.ts +3 -0
  44. package/dist/random.d.ts +1 -0
  45. package/dist/rendering/packSharedDraws2D.js +53 -5
  46. package/dist/rendering/prepareSharedDraws2D.d.ts +2 -0
  47. package/dist/rendering/prepareSharedDraws2D.js +17 -6
  48. package/dist/rendering/sharedColor2D.d.ts +35 -1
  49. package/dist/rendering/sharedColor2D.js +131 -8
  50. package/dist/rendering/sharedEffects2D.js +16 -8
  51. package/dist/rendering/world3d/Animation3D.d.ts +9 -0
  52. package/dist/rendering/world3d/Animation3D.js +4 -0
  53. package/dist/rendering/world3d/AnimationTexture3D.d.ts +6 -0
  54. package/dist/rendering/world3d/AnimationTexture3D.js +2 -0
  55. package/dist/rendering/world3d/Batch3D.d.ts +4 -0
  56. package/dist/rendering/world3d/Batch3D.js +3 -0
  57. package/dist/rendering/world3d/Camera3D.d.ts +5 -0
  58. package/dist/rendering/world3d/Camera3D.js +3 -0
  59. package/dist/rendering/world3d/Character3D.d.ts +4 -0
  60. package/dist/rendering/world3d/Character3D.js +2 -0
  61. package/dist/rendering/world3d/Cloth3D.d.ts +18 -3
  62. package/dist/rendering/world3d/Cloth3D.js +6 -1
  63. package/dist/rendering/world3d/Compression3D.d.ts +1 -0
  64. package/dist/rendering/world3d/Compression3D.js +1 -0
  65. package/dist/rendering/world3d/Curves3D.d.ts +8 -0
  66. package/dist/rendering/world3d/Curves3D.js +5 -0
  67. package/dist/rendering/world3d/Decal3D.d.ts +2 -0
  68. package/dist/rendering/world3d/Decal3D.js +1 -0
  69. package/dist/rendering/world3d/Export3D.d.ts +13 -0
  70. package/dist/rendering/world3d/Export3D.js +263 -0
  71. package/dist/rendering/world3d/Geometry3D.d.ts +11 -1
  72. package/dist/rendering/world3d/Geometry3D.js +10 -1
  73. package/dist/rendering/world3d/GeometryBuilder3D.d.ts +2 -0
  74. package/dist/rendering/world3d/Gizmo3D.d.ts +5 -0
  75. package/dist/rendering/world3d/Gizmo3D.js +2 -0
  76. package/dist/rendering/world3d/Gltf3D.d.ts +6 -0
  77. package/dist/rendering/world3d/Gltf3D.js +25 -5
  78. package/dist/rendering/world3d/GpuParticles3D.d.ts +2 -0
  79. package/dist/rendering/world3d/GpuParticles3D.js +1 -0
  80. package/dist/rendering/world3d/Hdr3D.d.ts +2 -0
  81. package/dist/rendering/world3d/Hdr3D.js +1 -0
  82. package/dist/rendering/world3d/Jelly3D.d.ts +2 -0
  83. package/dist/rendering/world3d/Jelly3D.js +1 -0
  84. package/dist/rendering/world3d/Ktx23D.d.ts +3 -0
  85. package/dist/rendering/world3d/Light3D.d.ts +9 -0
  86. package/dist/rendering/world3d/Light3D.js +4 -0
  87. package/dist/rendering/world3d/Material3D.d.ts +10 -0
  88. package/dist/rendering/world3d/Material3D.js +2 -0
  89. package/dist/rendering/world3d/Mesh3D.d.ts +4 -0
  90. package/dist/rendering/world3d/Mesh3D.js +16 -2
  91. package/dist/rendering/world3d/Meshopt3D.d.ts +3 -0
  92. package/dist/rendering/world3d/Meshopt3D.js +1 -0
  93. package/dist/rendering/world3d/Navigation3D.d.ts +41 -1
  94. package/dist/rendering/world3d/Navigation3D.js +74 -2
  95. package/dist/rendering/world3d/Object3D.d.ts +11 -0
  96. package/dist/rendering/world3d/Object3D.js +10 -0
  97. package/dist/rendering/world3d/Particles3D.d.ts +5 -0
  98. package/dist/rendering/world3d/Particles3D.js +3 -0
  99. package/dist/rendering/world3d/Physics3D.d.ts +14 -0
  100. package/dist/rendering/world3d/Physics3D.js +5 -0
  101. package/dist/rendering/world3d/PhysicsHull3D.d.ts +2 -0
  102. package/dist/rendering/world3d/PhysicsHull3D.js +2 -0
  103. package/dist/rendering/world3d/PhysicsMesh3D.d.ts +2 -0
  104. package/dist/rendering/world3d/PhysicsMesh3D.js +2 -0
  105. package/dist/rendering/world3d/PhysicsRemote3D.d.ts +5 -0
  106. package/dist/rendering/world3d/PhysicsRemote3D.js +2 -0
  107. package/dist/rendering/world3d/Ragdoll3D.d.ts +5 -0
  108. package/dist/rendering/world3d/Ragdoll3D.js +2 -0
  109. package/dist/rendering/world3d/Raycast3D.d.ts +3 -0
  110. package/dist/rendering/world3d/Raycast3D.js +1 -0
  111. package/dist/rendering/world3d/RenderList3D.d.ts +3 -0
  112. package/dist/rendering/world3d/RenderList3D.js +12 -0
  113. package/dist/rendering/world3d/Retarget3D.d.ts +1 -0
  114. package/dist/rendering/world3d/Rig3D.d.ts +57 -0
  115. package/dist/rendering/world3d/Rig3D.js +219 -0
  116. package/dist/rendering/world3d/Sdf3D.d.ts +181 -0
  117. package/dist/rendering/world3d/Sdf3D.js +1136 -0
  118. package/dist/rendering/world3d/SdfLod3D.d.ts +17 -0
  119. package/dist/rendering/world3d/SdfLod3D.js +56 -0
  120. package/dist/rendering/world3d/Serialize3D.d.ts +17 -0
  121. package/dist/rendering/world3d/Serialize3D.js +22 -0
  122. package/dist/rendering/world3d/Simplify3D.d.ts +29 -0
  123. package/dist/rendering/world3d/Simplify3D.js +426 -0
  124. package/dist/rendering/world3d/StateMachine3D.d.ts +9 -0
  125. package/dist/rendering/world3d/StateMachine3D.js +3 -0
  126. package/dist/rendering/world3d/SurfaceMaterial3D.d.ts +26 -0
  127. package/dist/rendering/world3d/SurfaceMaterial3D.js +138 -0
  128. package/dist/rendering/world3d/Terrain3D.d.ts +21 -0
  129. package/dist/rendering/world3d/Terrain3D.js +25 -1
  130. package/dist/rendering/world3d/Text3D.d.ts +5 -0
  131. package/dist/rendering/world3d/Text3D.js +2 -0
  132. package/dist/rendering/world3d/Texture3D.d.ts +16 -1
  133. package/dist/rendering/world3d/Texture3D.js +19 -1
  134. package/dist/rendering/world3d/Trail3D.d.ts +3 -0
  135. package/dist/rendering/world3d/Trail3D.js +2 -0
  136. package/dist/rendering/world3d/Vehicle3D.d.ts +5 -0
  137. package/dist/rendering/world3d/Vehicle3D.js +2 -0
  138. package/dist/rendering/world3d/VolumetricFog3D.d.ts +2 -0
  139. package/dist/rendering/world3d/VolumetricFog3D.js +1 -0
  140. package/dist/rendering/world3d/Water3D.d.ts +2 -0
  141. package/dist/rendering/world3d/Water3D.js +1 -0
  142. package/dist/rendering/world3d/core3D.d.ts +2 -0
  143. package/dist/rendering/world3d/debug3D.d.ts +5 -0
  144. package/dist/rendering/world3d/debug3D.js +5 -0
  145. package/dist/rendering/world3d/geometries3D.d.ts +12 -0
  146. package/dist/rendering/world3d/geometries3D.js +5 -0
  147. package/dist/rendering/world3d/helpers3D.d.ts +2 -0
  148. package/dist/rendering/world3d/helpers3D.js +1 -0
  149. package/dist/rendering/world3d/index.d.ts +12 -0
  150. package/dist/rendering/world3d/index.js +6 -0
  151. package/dist/rendering/world3d/math3D.d.ts +36 -0
  152. package/dist/rendering/world3d/math3D.js +35 -0
  153. package/dist/rendering/world3d/primitives3D.d.ts +7 -0
  154. package/dist/rendering/world3d/primitives3D.js +1 -0
  155. package/dist/saveStore.d.ts +18 -3
  156. package/dist/saveStore.js +23 -4
  157. package/dist/semanticList.d.ts +4 -0
  158. package/dist/semanticList.js +1 -0
  159. package/dist/semanticTree.js +11 -4
  160. package/dist/semanticTypes.d.ts +8 -0
  161. package/dist/sequencePlaybackTypes.d.ts +3 -0
  162. package/dist/text.d.ts +1 -0
  163. package/dist/textTable.d.ts +41 -0
  164. package/dist/textTable.js +114 -0
  165. package/dist/tilemapTypes.d.ts +13 -0
  166. package/dist/timer.d.ts +34 -0
  167. package/dist/timer.js +119 -0
  168. package/dist/tweenTypes.d.ts +4 -0
  169. package/dist/ui/controlKeys.d.ts +4 -0
  170. package/dist/ui/controlKeys.js +1 -0
  171. package/dist/ui/controls.d.ts +6 -0
  172. package/dist/ui/controls.js +2 -0
  173. package/dist/ui/layerTypes.d.ts +7 -0
  174. package/dist/ui/rangeControl.d.ts +3 -0
  175. package/dist/ui/rangeControl.js +1 -0
  176. package/dist/ui/scrollControl.d.ts +12 -0
  177. package/dist/ui/scrollControl.js +5 -1
  178. package/dist/ui/stateControls.d.ts +8 -0
  179. package/dist/ui/stateControls.js +3 -0
  180. package/dist/ui/textEditor.d.ts +1 -0
  181. package/dist/ui/textEditor.js +1 -0
  182. package/dist/ui/textEditorTypes.d.ts +7 -0
  183. package/dist/ui/textFieldControl.d.ts +4 -0
  184. package/dist/ui/textFieldControl.js +1 -0
  185. package/dist/ui/theme.d.ts +5 -0
  186. package/dist/ui/theme.js +1 -0
  187. package/dist/ui/types.d.ts +20 -0
  188. package/dist/ui/uiRoot.js +38 -9
  189. package/dist/ui/uiRootModel.d.ts +3 -1
  190. package/dist/ui/uiRootModel.js +8 -2
  191. package/dist/videoTypes.d.ts +3 -0
  192. package/dist/web/BrowserAssetBundle.d.ts +2 -0
  193. package/dist/web/BrowserAudio.d.ts +34 -1
  194. package/dist/web/BrowserAudio.js +69 -39
  195. package/dist/web/BrowserFrameLoop.d.ts +4 -0
  196. package/dist/web/BrowserGame.d.ts +64 -2
  197. package/dist/web/BrowserGame.js +129 -8
  198. package/dist/web/BrowserGamepadInput.d.ts +3 -0
  199. package/dist/web/BrowserHoverInput.d.ts +1 -0
  200. package/dist/web/BrowserImageTextures.d.ts +6 -0
  201. package/dist/web/BrowserInputActions.d.ts +10 -0
  202. package/dist/web/BrowserInputActions.js +4 -1
  203. package/dist/web/BrowserPlay.d.ts +130 -2
  204. package/dist/web/BrowserPlay.js +366 -19
  205. package/dist/web/BrowserPreferences.d.ts +10 -0
  206. package/dist/web/BrowserPreferences.js +39 -0
  207. package/dist/web/BrowserSemantics.d.ts +2 -0
  208. package/dist/web/BrowserStatsPanel.d.ts +10 -0
  209. package/dist/web/BrowserStatsPanel.js +9 -3
  210. package/dist/web/BrowserStorage.d.ts +2 -0
  211. package/dist/web/BrowserTextEditor.d.ts +3 -0
  212. package/dist/web/BrowserTextInput.d.ts +6 -0
  213. package/dist/web/BrowserTextureProvider.d.ts +6 -0
  214. package/dist/web/BrowserVideo.d.ts +13 -1
  215. package/dist/web/BrowserVideo.js +28 -2
  216. package/dist/web/CanvasKitFontSetProvider.d.ts +3 -0
  217. package/dist/web/CanvasKitParagraphProvider.d.ts +4 -0
  218. package/dist/web/CanvasKitParagraphProvider.js +1 -0
  219. package/dist/web/ManifestByteSource.d.ts +4 -0
  220. package/dist/web/ManifestByteSource.js +1 -0
  221. package/dist/web/ManifestFontContentLoader.d.ts +1 -0
  222. package/dist/web/WebGL2Host.js +64 -25
  223. package/dist/web/WebGPUHost.d.ts +13 -0
  224. package/dist/web/WebGPUHost.js +117 -36
  225. package/dist/web/audio.d.ts +2 -2
  226. package/dist/web/audio.js +1 -1
  227. package/dist/web/editorFonts.d.ts +4 -0
  228. package/dist/web/game.d.ts +1 -1
  229. package/dist/web/imageProjections2D.d.ts +2 -0
  230. package/dist/web/kit.d.ts +1 -0
  231. package/dist/web/kit.js +1 -0
  232. package/dist/web/play.d.ts +6 -1
  233. package/dist/web/play.js +4 -1
  234. package/dist/web/playMusic.d.ts +33 -0
  235. package/dist/web/playMusic.js +194 -0
  236. package/dist/web/playTouch.d.ts +45 -0
  237. package/dist/web/playTouch.js +141 -0
  238. package/dist/web/playWidgets.d.ts +71 -0
  239. package/dist/web/playWidgets.js +431 -0
  240. package/dist/web/prepareSharedSubmission2D.js +9 -3
  241. package/dist/web/resources.d.ts +2 -0
  242. package/dist/web/sharedEffectShaders.d.ts +6 -2
  243. package/dist/web/sharedEffectShaders.js +23 -7
  244. package/dist/web/sharedSubmissionStorage2D.js +1 -1
  245. package/dist/web/sharedWebGL2Options.d.ts +3 -0
  246. package/dist/web/sharedWebGL2Options.js +8 -2
  247. package/dist/web/sharedWebGL2Shaders.d.ts +15 -2
  248. package/dist/web/sharedWebGL2Shaders.js +108 -14
  249. package/dist/web/sharedWebGPUOptions.d.ts +5 -1
  250. package/dist/web/sharedWebGPUOptions.js +6 -2
  251. package/dist/web/video.d.ts +1 -1
  252. package/dist/web/webgl2Native.d.ts +3 -1
  253. package/dist/web/webgl2Native.js +9 -5
  254. package/dist/web/webgl2Types.d.ts +18 -0
  255. package/dist/web/webgpuImageResidency.d.ts +5 -2
  256. package/dist/web/webgpuImageResidency.js +7 -3
  257. package/dist/web/webgpuRetentionPool.d.ts +2 -2
  258. package/dist/web/webgpuRetentionPool.js +2 -1
  259. package/dist/web/webgpuSharedPass.d.ts +1 -1
  260. package/dist/web/webgpuSharedPass.js +87 -5
  261. package/dist/web/webgpuSharedResolvePass.d.ts +1 -1
  262. package/dist/web/webgpuSharedResolvePass.js +9 -4
  263. package/dist/web/world3d/Audio3D.d.ts +18 -1
  264. package/dist/web/world3d/Audio3D.js +62 -3
  265. package/dist/web/world3d/BrowserPlay3D.d.ts +115 -2
  266. package/dist/web/world3d/BrowserPlay3D.js +448 -43
  267. package/dist/web/world3d/FlyControls3D.d.ts +4 -0
  268. package/dist/web/world3d/FlyControls3D.js +2 -0
  269. package/dist/web/world3d/FollowControls3D.d.ts +3 -0
  270. package/dist/web/world3d/FollowControls3D.js +2 -0
  271. package/dist/web/world3d/OrbitControls3D.d.ts +3 -0
  272. package/dist/web/world3d/OrbitControls3D.js +2 -0
  273. package/dist/web/world3d/TransformControls3D.d.ts +5 -2
  274. package/dist/web/world3d/TransformControls3D.js +7 -4
  275. package/dist/web/world3d/WebGL2Renderer3D.d.ts +3 -0
  276. package/dist/web/world3d/WebGL2Renderer3D.js +2 -0
  277. package/dist/web/world3d/WebGPURenderer3D.d.ts +2 -0
  278. package/dist/web/world3d/WebGPURenderer3D.js +1 -0
  279. package/dist/web/world3d/World3DView.d.ts +3 -0
  280. package/dist/web/world3d/World3DView.js +2 -0
  281. package/dist/web/world3d/app3D.d.ts +7 -0
  282. package/dist/web/world3d/app3D.js +1 -0
  283. package/dist/web/world3d/assets3D.d.ts +1 -0
  284. package/dist/web/world3d/atmosphere3D.d.ts +9 -0
  285. package/dist/web/world3d/atmosphere3D.js +19 -4
  286. package/dist/web/world3d/canvasFont3D.d.ts +21 -0
  287. package/dist/web/world3d/canvasFont3D.js +165 -0
  288. package/dist/web/world3d/frame3D.d.ts +2 -0
  289. package/dist/web/world3d/host3D.d.ts +1 -0
  290. package/dist/web/world3d/index.d.ts +4 -2
  291. package/dist/web/world3d/index.js +2 -1
  292. package/dist/web/world3d/loaders3D.d.ts +1 -0
  293. package/dist/web/world3d/markers3D.d.ts +4 -0
  294. package/dist/web/world3d/overlay3D.d.ts +19 -0
  295. package/dist/web/world3d/overlay3D.js +21 -4
  296. package/dist/web/world3d/post3D.d.ts +4 -0
  297. package/dist/web/world3d/post3D.js +3 -0
  298. package/dist/web/world3d/probe3D.d.ts +1 -0
  299. package/dist/web/world3d/stats3D.d.ts +3 -0
  300. package/dist/web/world3d/stats3D.js +1 -0
  301. package/dist/web/world3d/webGL2FrameMetrics3D.d.ts +5 -0
  302. package/dist/web/world3d/webgpu.d.ts +2 -0
  303. package/dist/web/world3d/webgpu.js +1 -0
  304. package/package.json +3 -3
@@ -4,6 +4,7 @@ export interface SaveStorage {
4
4
  setItem(key: string, value: string): void;
5
5
  removeItem(key: string): void;
6
6
  }
7
+ /** A save to keep: its key and version, its defaults and migrations, its check and its storage. */
7
8
  export interface SaveStoreOptions<T> {
8
9
  /** The key the save is kept under. */
9
10
  readonly key: string;
@@ -23,20 +24,35 @@ export interface SaveStoreOptions<T> {
23
24
  /** Told of every load or write that did not go as planned. */
24
25
  readonly onProblem?: (problem: SaveProblem) => void;
25
26
  }
27
+ /** What went wrong with a save: unreadable, invalid, too new or too old, or a migration or write that failed. */
26
28
  export type SaveProblemKind = 'unreadable' | 'invalid' | 'too-new' | 'too-old' | 'migration-failed' | 'write-failed';
29
+ /** A problem with a save: what kind, which key, and its cause. */
27
30
  export interface SaveProblem {
28
31
  readonly kind: SaveProblemKind;
29
32
  readonly key: string;
30
33
  readonly cause?: unknown;
31
34
  }
35
+ /** A saved value: read it, change it and save it, reset or remove it, export or import it. */
32
36
  export interface SaveStore<T> {
33
37
  /** The data now: loaded, migrated, or the defaults. */
34
38
  readonly data: T;
35
39
  /** The version the loaded save had before migration, or undefined for a new game. */
36
40
  readonly loadedVersion: number | undefined;
37
- /** Replaces the data and writes it. Returns false when the storage refused, as when it is full. */
41
+ /**
42
+ * Replaces the data and writes it. Returns false when the storage refused, as when it is full, or when the new
43
+ * data fails `validate`: then it is reported as `invalid` and the data stays as it was.
44
+ */
38
45
  save(data?: T): boolean;
39
- /** Changes the data with `change`, which may edit it in place or return new data, then writes it. */
46
+ /**
47
+ * Changes the data with `change`, which may edit it in place or return new data, then writes it. What it returns,
48
+ * other than `undefined`, replaces the data only if it passes `validate`, so `data => (data.coins = 5)`, which
49
+ * returns 5, is reported as `invalid` and keeps the save; write such a change as a block, `data => { data.coins = 5; }`.
50
+ * Data edited in place that no longer passes `validate` is reported and not written.
51
+ *
52
+ * `change` is given a copy of the data, and the copy becomes the data only once it passes: a refused change, or one
53
+ * that throws, leaves `data` exactly as it was. So `save.data` is a new object after an update; read it again rather
54
+ * than keeping the old one.
55
+ */
40
56
  update(change: (data: T) => T | void): boolean;
41
57
  /** Back to the defaults, written. */
42
58
  reset(): boolean;
@@ -47,7 +63,6 @@ export interface SaveStore<T> {
47
63
  /** Loads an exported string, migrating it like a stored save. Returns false and changes nothing when it cannot. */
48
64
  import(text: string): boolean;
49
65
  }
50
- /** Opens the save under `options.key`, migrating an older one. */
51
66
  export declare function createSaveStore<T>(options: SaveStoreOptions<T>): SaveStore<T>;
52
67
  /** Storage kept in memory: for tests, for a page without browser storage, or for a game played once. */
53
68
  export declare function createMemorySaveStorage(initial?: Readonly<Record<string, string>>): SaveStorage & {
package/dist/saveStore.js CHANGED
@@ -8,6 +8,11 @@
8
8
  import { EgretError } from '@egret/runtime';
9
9
  const isObject = (value) => typeof value === 'object' && value !== null;
10
10
  /** Opens the save under `options.key`, migrating an older one. */
11
+ /** A deep copy: by `structuredClone` where the platform has it, else through JSON, as the save is stored. */
12
+ function copyOf(value) {
13
+ const clone = globalThis.structuredClone;
14
+ return typeof clone === 'function' ? clone(value) : JSON.parse(JSON.stringify(value));
15
+ }
11
16
  export function createSaveStore(options) {
12
17
  if (!isObject(options))
13
18
  throw new EgretError('SAVE_STORE_OPTIONS_INVALID');
@@ -87,6 +92,13 @@ export function createSaveStore(options) {
87
92
  keepAside(text);
88
93
  }
89
94
  }
95
+ // New data that fails the check is not kept or written: the save on disk stays the last good one.
96
+ const refuse = (value) => {
97
+ report('invalid', new TypeError('The new save data fails validate' +
98
+ (isObject(value) ? '' : ': it is ' + (value === null ? 'null' : typeof value) + ', not an object') +
99
+ '. A change that edits in place returns nothing; write it as a block.'));
100
+ return false;
101
+ };
90
102
  const write = () => {
91
103
  try {
92
104
  const envelope = { version, savedAt: new Date().toISOString(), data };
@@ -109,16 +121,23 @@ export function createSaveStore(options) {
109
121
  return loadedVersion;
110
122
  },
111
123
  save(next) {
112
- if (next !== undefined)
124
+ if (next !== undefined) {
125
+ if (!validate(next))
126
+ return refuse(next);
113
127
  data = next;
128
+ }
114
129
  return write();
115
130
  },
116
131
  update(change) {
117
132
  if (typeof change !== 'function')
118
133
  throw new EgretError('SAVE_STORE_OPTIONS_INVALID');
119
- const result = change(data);
120
- if (result !== undefined)
121
- data = result;
134
+ // A copy, so that a change refused, or one that throws halfway, does not reach the data.
135
+ const draft = copyOf(data);
136
+ const result = change(draft);
137
+ const next = result === undefined ? draft : result;
138
+ if (!validate(next))
139
+ return refuse(next);
140
+ data = next;
122
141
  return write();
123
142
  },
124
143
  reset() {
@@ -44,6 +44,7 @@ export interface SemanticListSource {
44
44
  }): void;
45
45
  };
46
46
  }
47
+ /** What one row of a list says: its name, whether it is selected or disabled, its level and its place. */
47
48
  export interface SemanticListRow {
48
49
  /** What the row is called. An option and a menu item need a name; a list item may leave it to the nodes inside it. */
49
50
  readonly name?: string;
@@ -61,6 +62,7 @@ export interface SemanticListRow {
61
62
  readonly size: number;
62
63
  };
63
64
  }
65
+ /** Semantics for a list control: its tree and list, its role and name, and how its rows are described. */
64
66
  export interface UiListSemanticsOptions {
65
67
  readonly semantics: UiSemantics;
66
68
  readonly root: SemanticListSource;
@@ -97,6 +99,7 @@ export interface UiListSemanticsOptions {
97
99
  /** Called after the node of a row was added, so that nodes inside it can be added under `id`. They go with the row. */
98
100
  readonly onRowAdded?: (key: string, id: string) => void;
99
101
  }
102
+ /** The semantic nodes of a list control and its rows; sync it when the rows change. */
100
103
  export interface UiListSemantics {
101
104
  readonly id: string;
102
105
  /** The id of the node of a row, whether or not the row shows now. */
@@ -118,5 +121,6 @@ export interface UiListSemantics {
118
121
  * call it from `describe`. A box the root has not laid out has no size, at the origin of the root.
119
122
  */
120
123
  export declare function semanticBoxOf(root: Pick<SemanticListSource, 'snapshot'>, id: string): SemanticBounds;
124
+ /** Semantic nodes for a list control and its rows, kept in step with the control. */
121
125
  export declare function createUiListSemantics(options: UiListSemanticsOptions): UiListSemantics;
122
126
  //# sourceMappingURL=semanticList.d.ts.map
@@ -15,6 +15,7 @@ export function semanticBoxOf(root, id) {
15
15
  }
16
16
  const text = (value) => typeof value === 'string' && value.length >= 1 && value.length <= 128 && !value.includes('\0');
17
17
  const optional = (value, type) => value === undefined || typeof value === type;
18
+ /** Semantic nodes for a list control and its rows, kept in step with the control. */
18
19
  export function createUiListSemantics(options) {
19
20
  if (options === null || typeof options !== 'object')
20
21
  throw new EgretError('UI_SEMANTICS_OPTIONS');
@@ -397,13 +397,20 @@ export function createUiSemantics(options = {}) {
397
397
  const inert = modal !== undefined && !live.has(draft.entry) && !within(draft.entry);
398
398
  if (draft.node.controls !== undefined && !present.has(draft.node.controls))
399
399
  throw new EgretError('UI_SEMANTICS_RELATION', { cause: new TypeError(draft.entry.id + ': controls') });
400
- if (draft.node.focused) {
401
- // One node holds the focus, and never one a modal dialog has made inert.
402
- if (focused !== undefined || inert)
400
+ // A node a modal dialog has just made inert may still hold the keyboard focus, for the frame between the dialog
401
+ // opening and the application moving the focus into it: it is published without the focus, not refused.
402
+ const holds = draft.node.focused === true && !inert;
403
+ if (holds) {
404
+ // One node holds the focus.
405
+ if (focused !== undefined)
403
406
  throw new EgretError('UI_SEMANTICS_FOCUS', { cause: new TypeError(draft.entry.id + ': focused') });
404
407
  focused = draft.entry.id;
405
408
  }
406
- const fresh = { ...draft.node, inert }, before = snapshot.nodes[index];
409
+ const fresh = {
410
+ ...draft.node,
411
+ inert,
412
+ ...(draft.node.focused && inert ? { focused: false } : {})
413
+ }, before = snapshot.nodes[index];
407
414
  const node = before !== undefined && sameNode(before, fresh) ? before : Object.freeze(fresh);
408
415
  if (node !== before)
409
416
  changed = true;
@@ -5,10 +5,13 @@
5
5
  export type SemanticRole = 'group' | 'image' | 'text' | 'button' | 'checkbox' | 'switch' | 'radiogroup' | 'radio' | 'listbox' | 'option' | 'list' | 'listitem' | 'scrollbar' | 'slider' | 'spinbutton' | 'progressbar' | 'tablist' | 'tab' | 'tabpanel' | 'menu' | 'menuitem' | 'dialog' | 'textbox' | 'status' | 'alert' | 'grid' | 'row' | 'gridcell' | 'columnheader' | 'tree' | 'treeitem' | 'heading';
6
6
  /** What assistive technology may ask of a node: its activation, or the keyboard focus. */
7
7
  export type SemanticAction = 'activate' | 'focus';
8
+ /** Whether a node is checked, not checked, or partly checked. */
8
9
  export type SemanticChecked = boolean | 'mixed';
10
+ /** Whether a node runs across or down. */
9
11
  export type SemanticOrientation = 'horizontal' | 'vertical';
10
12
  /** How the rows of a grid are ordered by one of its columns. */
11
13
  export type SemanticSort = 'ascending' | 'descending' | 'none';
14
+ /** Whether a semantic tree is active or closed. */
12
15
  export type SemanticsState = 'active' | 'closed';
13
16
  /** A rectangle in the logical coordinates of the stage, the ones picking uses. */
14
17
  export interface SemanticBounds {
@@ -17,6 +20,7 @@ export interface SemanticBounds {
17
20
  readonly width: number;
18
21
  readonly height: number;
19
22
  }
23
+ /** The value of a range node and its least and greatest value. */
20
24
  export interface SemanticRange {
21
25
  readonly now: number;
22
26
  readonly min: number;
@@ -76,6 +80,7 @@ export interface SemanticDescription {
76
80
  /** Reading order among the nodes of one parent, lowest first. Equal values keep the order of addition. */
77
81
  readonly order?: number;
78
82
  }
83
+ /** A node to add: its id, role and parent, how it is described, and what it does when activated or focused. */
79
84
  export interface SemanticNodeOptions {
80
85
  /** One to 128 characters, distinct among the nodes of the tree. */
81
86
  readonly id: string;
@@ -88,6 +93,7 @@ export interface SemanticNodeOptions {
88
93
  /** Moves the keyboard focus of the application to the control. Without it the node cannot be focused. */
89
94
  readonly onFocus?: () => void;
90
95
  }
96
+ /** A node of the semantic tree; remove it to take it out. */
91
97
  export interface SemanticNode {
92
98
  readonly id: string;
93
99
  readonly role: SemanticRole;
@@ -124,6 +130,7 @@ export interface SemanticSnapshotNode {
124
130
  readonly controls: string | undefined;
125
131
  readonly position: SemanticPosition | undefined;
126
132
  }
133
+ /** The semantic tree as published: its revisions, its nodes and the focused one. */
127
134
  export interface SemanticSnapshot {
128
135
  /** Grows by one with every publication that differs from the one before. */
129
136
  readonly revision: number;
@@ -133,6 +140,7 @@ export interface SemanticSnapshot {
133
140
  readonly nodes: readonly SemanticSnapshotNode[];
134
141
  readonly focused: string | undefined;
135
142
  }
143
+ /** A semantic tree to make: how many nodes it holds. */
136
144
  export interface UiSemanticsOptions {
137
145
  /** Most nodes the tree holds at once. Defaults to 256, and is at most 4,096. */
138
146
  readonly maxNodes?: number;
@@ -1,10 +1,13 @@
1
1
  import type { Disposable } from '@egret/contracts';
2
2
  import type { SequencePlaybackMode, SequenceSample } from '@egret/runtime';
3
+ /** Whether a sequence playback is idle, running, paused, completed, stopped or failed. */
3
4
  export type SequencePlaybackState = 'idle' | 'running' | 'paused' | 'completed' | 'stopped' | 'failed';
5
+ /** Whether a sequence plays once or loops. */
4
6
  export interface SequencePlaybackOptions {
5
7
  readonly mode?: SequencePlaybackMode;
6
8
  }
7
9
  declare const sequencePlaybackBrand: unique symbol;
10
+ /** A sequence playing on the game clock: start, pause, resume and stop it, and read its last sample. */
8
11
  export interface SequencePlayback extends Disposable {
9
12
  readonly [sequencePlaybackBrand]: true;
10
13
  readonly state: SequencePlaybackState;
package/dist/text.d.ts CHANGED
@@ -5,6 +5,7 @@ import type { DisplayObject } from '@egret/runtime';
5
5
  import type { TextRasterMetrics, TextRasterRequestInput } from '@egret/runtime/text';
6
6
  export { createTextField } from './textField.js';
7
7
  declare const textFieldBrand: unique symbol;
8
+ /** Where a text field is: unprepared, ready or disposed, its revisions and its metrics. */
8
9
  export interface TextFieldStatus {
9
10
  readonly state: 'unprepared' | 'ready' | 'disposed';
10
11
  readonly desiredRevision: number;
@@ -0,0 +1,41 @@
1
+ /** The words of one language, by key. A value may name `{placeholders}`. */
2
+ export type TextTableWords = Readonly<Record<string, string>>;
3
+ /** A text table to make: the words of each language, the language to start in and the one to fall back to. */
4
+ export interface TextTableOptions<L extends string> {
5
+ /** One set of words per language, such as `{ zh: { start: '开始' }, en: { start: 'Start' } }`. */
6
+ readonly languages: Readonly<Record<L, TextTableWords>>;
7
+ /** The language to start in. The first that `languages` names unless given. */
8
+ readonly language?: L;
9
+ /** Where a word missing from the current language is taken from. The first language unless given. */
10
+ readonly fallback?: L;
11
+ /** Told of a key missing from the current language, once per key and language: for a check in development. */
12
+ readonly onMissing?: (key: string, language: L) => void;
13
+ }
14
+ /** A game's words in its languages: the current one, a word by key, and who is told when the language changes. */
15
+ export interface TextTable<L extends string> {
16
+ readonly languages: readonly L[];
17
+ /** The current language. */
18
+ readonly language: L;
19
+ /** Changes the language and tells every listener, which redraws the words it shows. */
20
+ setLanguage(language: L): void;
21
+ /**
22
+ * The word for `key` in the current language, else in the fallback, else the key itself, with each `{name}` replaced
23
+ * by `values[name]`.
24
+ */
25
+ text(key: string, values?: Readonly<Record<string, string | number>>): string;
26
+ /** Whether the current language has its own word for `key`. */
27
+ has(key: string): boolean;
28
+ /** Calls `listener` whenever the language changes. The function returned stops it. */
29
+ onChange(listener: (language: L) => void): () => void;
30
+ /** The keys some language has and another lacks, by language: for a test that every word is in every language. */
31
+ missing(): Readonly<Record<L, readonly string[]>>;
32
+ }
33
+ /** Makes a table of a game's words in its languages. */
34
+ export declare function createTextTable<L extends string>(options: TextTableOptions<L>): TextTable<L>;
35
+ /**
36
+ * The language of `languages` that best matches what the player's browser or system asks for (`navigator.languages`,
37
+ * given here as a list, such as `['zh-CN', 'en']`): an exact match first, then the same main language (`zh-TW` asks
38
+ * for `zh`). The first of `languages` when none matches.
39
+ */
40
+ export declare function pickLanguage<L extends string>(languages: readonly L[], wanted: readonly string[]): L;
41
+ //# sourceMappingURL=textTable.d.ts.map
@@ -0,0 +1,114 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // A game's words in each of its languages: one table, a current language that can change while the game runs, and
3
+ // a word asked for by its key with values put in. Every string a player reads goes through it, so no Chinese is left
4
+ // on an English screen.
5
+ import { EgretError } from '@egret/runtime';
6
+ const PLACEHOLDER = /\{([A-Za-z0-9_]+)\}/g;
7
+ /** Makes a table of a game's words in its languages. */
8
+ export function createTextTable(options) {
9
+ const invalid = () => new EgretError('TEXT_TABLE_INVALID');
10
+ if (options === null ||
11
+ typeof options !== 'object' ||
12
+ options.languages === null ||
13
+ typeof options.languages !== 'object')
14
+ throw invalid();
15
+ const languages = Object.keys(options.languages);
16
+ if (languages.length === 0)
17
+ throw invalid();
18
+ for (const language of languages) {
19
+ const words = options.languages[language];
20
+ if (words === null || typeof words !== 'object' || Object.values(words).some(word => typeof word !== 'string'))
21
+ throw invalid();
22
+ }
23
+ const fallback = options.fallback ?? languages[0];
24
+ let language = options.language ?? languages[0];
25
+ if (!languages.includes(fallback) || !languages.includes(language))
26
+ throw invalid();
27
+ const onMissing = options.onMissing;
28
+ if (onMissing !== undefined && typeof onMissing !== 'function')
29
+ throw invalid();
30
+ const told = new Set(), listeners = new Set();
31
+ const own = (words, key) => Object.prototype.hasOwnProperty.call(words, key) ? words[key] : undefined;
32
+ return {
33
+ languages: Object.freeze([...languages]),
34
+ get language() {
35
+ return language;
36
+ },
37
+ setLanguage(next) {
38
+ if (!languages.includes(next))
39
+ throw invalid();
40
+ if (next === language)
41
+ return;
42
+ language = next;
43
+ let first;
44
+ for (const listener of [...listeners])
45
+ try {
46
+ listener(next);
47
+ }
48
+ catch (cause) {
49
+ first ??= cause;
50
+ }
51
+ if (first !== undefined)
52
+ throw first;
53
+ },
54
+ text(key, values) {
55
+ if (typeof key !== 'string')
56
+ throw invalid();
57
+ let word = own(options.languages[language], key);
58
+ if (word === undefined) {
59
+ if (onMissing !== undefined && !told.has(language + '\u0000' + key)) {
60
+ told.add(language + '\u0000' + key);
61
+ onMissing(key, language);
62
+ }
63
+ word = own(options.languages[fallback], key) ?? key;
64
+ }
65
+ return values === undefined
66
+ ? word
67
+ : word.replace(PLACEHOLDER, (whole, name) => Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : whole);
68
+ },
69
+ has(key) {
70
+ return own(options.languages[language], key) !== undefined;
71
+ },
72
+ onChange(listener) {
73
+ if (typeof listener !== 'function')
74
+ throw invalid();
75
+ listeners.add(listener);
76
+ return () => {
77
+ listeners.delete(listener);
78
+ };
79
+ },
80
+ missing() {
81
+ const all = new Set();
82
+ for (const each of languages)
83
+ for (const key of Object.keys(options.languages[each]))
84
+ all.add(key);
85
+ const result = {};
86
+ for (const each of languages)
87
+ result[each] = Object.freeze([...all].filter(key => own(options.languages[each], key) === undefined).sort());
88
+ return Object.freeze(result);
89
+ }
90
+ };
91
+ }
92
+ /**
93
+ * The language of `languages` that best matches what the player's browser or system asks for (`navigator.languages`,
94
+ * given here as a list, such as `['zh-CN', 'en']`): an exact match first, then the same main language (`zh-TW` asks
95
+ * for `zh`). The first of `languages` when none matches.
96
+ */
97
+ export function pickLanguage(languages, wanted) {
98
+ if (!Array.isArray(languages) || languages.length === 0)
99
+ throw new EgretError('TEXT_TABLE_INVALID');
100
+ const lower = languages.map(language => language.toLowerCase());
101
+ for (const ask of Array.isArray(wanted) ? wanted : []) {
102
+ if (typeof ask !== 'string')
103
+ continue;
104
+ const exact = lower.indexOf(ask.toLowerCase());
105
+ if (exact >= 0)
106
+ return languages[exact];
107
+ const main = ask.toLowerCase().split('-')[0];
108
+ const same = lower.findIndex(language => language.split('-')[0] === main);
109
+ if (same >= 0)
110
+ return languages[same];
111
+ }
112
+ return languages[0];
113
+ }
114
+ //# sourceMappingURL=textTable.js.map
@@ -1,11 +1,15 @@
1
1
  import type { AssetLease, DisplayObjectContainer, Mesh2D, Texture } from '@egret/runtime';
2
2
  import type { TexturedGeometry2D } from '@egret/contracts';
3
+ /** The value of a tile map property. */
3
4
  export type TileMapPropertyValue = string | number | boolean;
5
+ /** The properties of a map, layer, tile or object, by name. */
4
6
  export type TileMapProperties = Readonly<Record<string, TileMapPropertyValue>>;
7
+ /** One frame of an animated tile: the tile it shows and for how long. */
5
8
  export interface TileAnimationFrame {
6
9
  readonly tileId: number;
7
10
  readonly duration: number;
8
11
  }
12
+ /** A tileset: its tiles' size and count, its image, and the properties and animations of its tiles. */
9
13
  export interface TileSetData {
10
14
  readonly name: string;
11
15
  /** The global id of the first tile of the set. */
@@ -28,6 +32,7 @@ export interface TileSetData {
28
32
  readonly type?: string;
29
33
  }>;
30
34
  }
35
+ /** A layer of tiles: its name, size, offset, opacity and parallax, and its tiles' global ids. */
31
36
  export interface TileLayerData {
32
37
  readonly type: 'tile';
33
38
  readonly name: string;
@@ -46,6 +51,7 @@ export interface TileLayerData {
46
51
  /** A global id with its flip flags in the top three bits, row by row. 0 is no tile. */
47
52
  readonly data: Uint32Array;
48
53
  }
54
+ /** An object of an object layer: its place and size, its shape or tile, its text and properties. */
49
55
  export interface TileMapObject {
50
56
  readonly id: number;
51
57
  readonly name: string;
@@ -66,6 +72,7 @@ export interface TileMapObject {
66
72
  readonly text?: string;
67
73
  readonly properties: TileMapProperties;
68
74
  }
75
+ /** A layer of objects: its name, offset, opacity and objects. */
69
76
  export interface ObjectLayerData {
70
77
  readonly type: 'object';
71
78
  readonly name: string;
@@ -76,6 +83,7 @@ export interface ObjectLayerData {
76
83
  readonly properties: TileMapProperties;
77
84
  readonly objects: readonly TileMapObject[];
78
85
  }
86
+ /** A layer of a map: tiles or objects. */
79
87
  export type TileMapLayerData = TileLayerData | ObjectLayerData;
80
88
  /** A map as plain, frozen data: what a tile map is made from. */
81
89
  export interface TileMapData {
@@ -92,10 +100,12 @@ export interface TileMapData {
92
100
  /** Back to front. Layers inside groups are given with the names of their groups before theirs, `group/layer`. */
93
101
  readonly layers: readonly TileMapLayerData[];
94
102
  }
103
+ /** Tilesets kept in files of their own, for importing a map from Tiled. */
95
104
  export interface TiledImportOptions {
96
105
  /** Tilesets kept in files of their own, by the `source` the map names, as the JSON Tiled writes for them. */
97
106
  readonly tilesets?: Readonly<Record<string, unknown>>;
98
107
  }
108
+ /** What a cell holds: its tile, tileset and flips, and the tile's properties. */
99
109
  export interface TileInfo {
100
110
  /** The global id, without flip flags. */
101
111
  readonly gid: number;
@@ -107,6 +117,7 @@ export interface TileInfo {
107
117
  readonly flippedDiagonally: boolean;
108
118
  readonly properties: TileMapProperties;
109
119
  }
120
+ /** A chunk of a layer drawn as one: its first cell, whether it shows, and its meshes. */
110
121
  export interface TileMapChunk {
111
122
  /** The first cell of the chunk. */
112
123
  readonly column: number;
@@ -120,12 +131,14 @@ export interface TileMapChunk {
120
131
  readonly tiles: number;
121
132
  }[];
122
133
  }
134
+ /** A layer as drawn: its name and data, its display object and its chunks. */
123
135
  export interface TileMapLayer {
124
136
  readonly name: string;
125
137
  readonly data: TileLayerData;
126
138
  readonly display: DisplayObjectContainer;
127
139
  readonly chunks: readonly TileMapChunk[];
128
140
  }
141
+ /** A tile map to make: its map, its tileset textures and the size of its chunks. */
129
142
  export interface TileMapOptions {
130
143
  readonly map: TileMapData;
131
144
  /** The image of each tileset that is drawn, by its name. A set without one cannot be drawn. */
@@ -0,0 +1,34 @@
1
+ import type { Scope } from '@egret/runtime';
2
+ import type { Engine } from './Engine.js';
3
+ /** Calls a function every `delay` seconds, `repeatCount` times or until it is stopped, as Egret's Timer. */
4
+ export interface Timer {
5
+ /** Seconds between calls. It can be changed while it runs; the next call comes that long after the last. */
6
+ delay: number;
7
+ /** How many calls in all before it completes; 0 for no end. */
8
+ repeatCount: number;
9
+ /** How many calls there have been since it was made or reset. */
10
+ readonly currentCount: number;
11
+ readonly running: boolean;
12
+ /** Called each time, with the count so far. Several can be added; they are called in the order they were. */
13
+ onTimer(callback: (count: number) => void): this;
14
+ /** Called once, after the last call of a timer with a `repeatCount`. */
15
+ onComplete(callback: () => void): this;
16
+ start(): this;
17
+ /** Stops it, keeping its count; `start` waits a whole delay again before the next call, as Egret's did. */
18
+ stop(): this;
19
+ /** Stops it and sets its count back to 0. */
20
+ reset(): this;
21
+ }
22
+ /** A call to come: `cancel` takes it back if it has not been made. */
23
+ export interface Delayed {
24
+ readonly done: boolean;
25
+ cancel(): void;
26
+ }
27
+ /**
28
+ * A timer: `createTimer(engine, scope, 1, 5).onTimer(n => …).onComplete(() => …).start()`. A frame longer than the
29
+ * delay makes as many calls as the delay fits into it, so a count of seconds stays right however the frames fall.
30
+ */
31
+ export declare function createTimer(engine: Engine, scope: Scope, delay: number, repeatCount?: number): Timer;
32
+ /** Calls a function once, `seconds` from now on the Engine's clock, as Egret's setTimeout. */
33
+ export declare function after(engine: Engine, scope: Scope, seconds: number, callback: () => void): Delayed;
34
+ //# sourceMappingURL=timer.d.ts.map
package/dist/timer.js ADDED
@@ -0,0 +1,119 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Timers on the Engine's clock, for code that used Egret's Timer and setTimeout. They count the clock's seconds, so
3
+ // they stop while the clock is paused and keep pace with a game run by hand. A timer ends with its scope.
4
+ import { EgretError } from '@egret/runtime';
5
+ const invalid = () => new EgretError('TIMER_OPTIONS_INVALID');
6
+ /** The shortest delay: shorter ones would call more times in a frame than a frame should hold. */
7
+ const SHORTEST = 0.001;
8
+ const seconds = (value) => {
9
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < SHORTEST)
10
+ throw invalid();
11
+ return value;
12
+ };
13
+ const count = (value) => {
14
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
15
+ throw invalid();
16
+ return value;
17
+ };
18
+ /**
19
+ * A timer: `createTimer(engine, scope, 1, 5).onTimer(n => …).onComplete(() => …).start()`. A frame longer than the
20
+ * delay makes as many calls as the delay fits into it, so a count of seconds stays right however the frames fall.
21
+ */
22
+ export function createTimer(engine, scope, delay, repeatCount = 0) {
23
+ let every = seconds(delay), limit = count(repeatCount), done = 0, owed = 0, subscription;
24
+ const ticks = [], ends = [];
25
+ const halt = () => {
26
+ subscription?.dispose();
27
+ subscription = undefined;
28
+ };
29
+ const timer = {
30
+ get delay() {
31
+ return every;
32
+ },
33
+ set delay(value) {
34
+ every = seconds(value);
35
+ },
36
+ get repeatCount() {
37
+ return limit;
38
+ },
39
+ set repeatCount(value) {
40
+ limit = count(value);
41
+ },
42
+ get currentCount() {
43
+ return done;
44
+ },
45
+ get running() {
46
+ return subscription !== undefined && !subscription.isDisposed;
47
+ },
48
+ onTimer(callback) {
49
+ if (typeof callback !== 'function')
50
+ throw invalid();
51
+ ticks.push(callback);
52
+ return timer;
53
+ },
54
+ onComplete(callback) {
55
+ if (typeof callback !== 'function')
56
+ throw invalid();
57
+ ends.push(callback);
58
+ return timer;
59
+ },
60
+ start() {
61
+ if (timer.running || (limit > 0 && done >= limit))
62
+ return timer;
63
+ subscription = engine.clock.onTick(scope, tick => {
64
+ owed += tick.deltaSeconds;
65
+ // A callback may stop, reset or restart the timer, or change its delay.
66
+ while (owed >= every && timer.running) {
67
+ owed -= every;
68
+ done++;
69
+ for (const callback of [...ticks])
70
+ callback(done);
71
+ if (limit > 0 && done >= limit && timer.running) {
72
+ halt();
73
+ owed = 0;
74
+ for (const callback of [...ends])
75
+ callback();
76
+ }
77
+ }
78
+ return undefined;
79
+ });
80
+ return timer;
81
+ },
82
+ stop() {
83
+ halt();
84
+ owed = 0;
85
+ return timer;
86
+ },
87
+ reset() {
88
+ halt();
89
+ done = 0;
90
+ owed = 0;
91
+ return timer;
92
+ }
93
+ };
94
+ return timer;
95
+ }
96
+ /** Calls a function once, `seconds` from now on the Engine's clock, as Egret's setTimeout. */
97
+ export function after(engine, scope, seconds, callback) {
98
+ if (typeof callback !== 'function')
99
+ throw invalid();
100
+ let done = false;
101
+ const timer = createTimer(engine, scope, seconds, 1)
102
+ .onComplete(() => {
103
+ done = true;
104
+ callback();
105
+ })
106
+ .start();
107
+ return {
108
+ get done() {
109
+ return done;
110
+ },
111
+ cancel() {
112
+ if (!done) {
113
+ done = true;
114
+ timer.stop();
115
+ }
116
+ }
117
+ };
118
+ }
119
+ //# sourceMappingURL=timer.js.map
@@ -1,6 +1,9 @@
1
1
  import type { Disposable } from '@egret/contracts';
2
+ /** The easing a tween uses. */
2
3
  export type TweenEasing = 'linear' | 'quadIn' | 'quadOut' | 'quadInOut';
4
+ /** Whether a tween is idle, running, paused, completed, stopped or failed. */
3
5
  export type TweenState = 'idle' | 'running' | 'paused' | 'completed' | 'stopped' | 'failed';
6
+ /** A tween to make: from and to which number, for how long, with which easing, and what it calls. */
4
7
  export interface TweenOptions {
5
8
  readonly from: number;
6
9
  readonly to: number;
@@ -10,6 +13,7 @@ export interface TweenOptions {
10
13
  readonly onComplete?: () => undefined;
11
14
  }
12
15
  declare const tweenBrand: unique symbol;
16
+ /** A number tweened on the game clock: start, pause, resume and stop it, and read its value. */
13
17
  export interface Tween extends Disposable {
14
18
  readonly [tweenBrand]: true;
15
19
  readonly state: TweenState;