@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
@@ -5,11 +5,13 @@
5
5
  // An interrupted fade keeps the weights it had reached, so poses never pop.
6
6
  import { AnimationMixer3D } from './Animation3D.js';
7
7
  import { World3DError, requireFinite3D } from './core3D.js';
8
+ /** The most states and transitions a state machine has, and how many transitions it takes in one update. */
8
9
  export const STATE_MACHINE3D_LIMITS = Object.freeze({
9
10
  maxStates: 256,
10
11
  maxTransitions: 2048,
11
12
  maxTransitionsPerUpdate: 8
12
13
  });
14
+ /** Plays clips by state, moving between states when their conditions are met. */
13
15
  export class AnimationStateMachine3D {
14
16
  mixer;
15
17
  /** Called after every state change, including forced ones. */
@@ -271,6 +273,7 @@ export class AnimationStateMachine3D {
271
273
  this.#triggers.clear();
272
274
  }
273
275
  }
276
+ /** Makes an animation state machine that drives a mixer. */
274
277
  export function createAnimationStateMachine3D(mixer) {
275
278
  return new AnimationStateMachine3D(mixer);
276
279
  }
@@ -0,0 +1,26 @@
1
+ import type { Material3D, StandardMaterialOptions3D } from './Material3D.js';
2
+ /** The surfaces the shader can draw. */
3
+ export type SurfaceKind3D = 'wood' | 'stone' | 'brick' | 'plaster' | 'metal' | 'cloth' | 'bark';
4
+ /** A material with a surface: the standard material's options and how the surface looks. */
5
+ export interface SurfaceMaterialOptions3D extends StandardMaterialOptions3D {
6
+ readonly surface: SurfaceKind3D;
7
+ /** How many of the pattern's units fit in one world unit; each surface has its own unless given. */
8
+ readonly scale?: number;
9
+ /** How much the pattern darkens and lightens the colour, 0 to 1; 0.5 unless given. */
10
+ readonly strength?: number;
11
+ /** How deep the relief looks under light, 0 to 1; 0.5 unless given. */
12
+ readonly bump?: number;
13
+ }
14
+ /** The shader sources of a surface: its height, the colour it gives and the relief it gives, in GLSL and WGSL. */
15
+ export declare function surfaceShaderSources3D(kind: SurfaceKind3D): {
16
+ glsl: string;
17
+ wgsl: string;
18
+ glslNormal: string;
19
+ wgslNormal: string;
20
+ };
21
+ /**
22
+ * A standard material with a surface drawn by the shader, over its colour or its vertex colours (on unless
23
+ * `vertexColors: false`): `createSurfaceMaterial3D({ surface: 'wood' })` for a crate made in code.
24
+ */
25
+ export declare function createSurfaceMaterial3D(options: SurfaceMaterialOptions3D): Material3D;
26
+ //# sourceMappingURL=SurfaceMaterial3D.d.ts.map
@@ -0,0 +1,138 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Materials with a surface drawn by the shader: wood grain, stone, brick courses, plaster, brushed metal, woven cloth
3
+ // and bark, as fine as the pixels and not as the mesh. A model made in code carries its colours in its vertices, which
4
+ // cannot hold a line finer than its triangles; these add the detail between them, in colour and in relief, with no
5
+ // texture to load and no texture coordinates to lay out. The pattern is laid in world space and projected from the
6
+ // three axes, so it suits models that stay where they are put (buildings, props, scenery): on one that moves, the
7
+ // pattern stays in the world while the model moves through it.
8
+ import { World3DError } from './core3D.js';
9
+ import { createCustomShader3D, createStandardMaterial3D } from './Material3D.js';
10
+ const KINDS = {
11
+ wood: { scale: 4, roughness: 0.7, metallic: 0 },
12
+ stone: { scale: 2, roughness: 0.9, metallic: 0 },
13
+ brick: { scale: 3, roughness: 0.85, metallic: 0 },
14
+ plaster: { scale: 2, roughness: 0.95, metallic: 0 },
15
+ metal: { scale: 3, roughness: 0.35, metallic: 0.8 },
16
+ cloth: { scale: 20, roughness: 0.9, metallic: 0 },
17
+ bark: { scale: 4, roughness: 0.95, metallic: 0 }
18
+ };
19
+ // The height of each surface at a point p already scaled, with the world normal n for surfaces laid in a plane. The
20
+ // same function, in each shading language, gives the colour (low is darker) and the relief (its slope bends the
21
+ // normal). Heights are about 0 to 1.
22
+ const HEIGHT_GLSL = {
23
+ wood: 'float r = (p.x + p.z) * 3.0 + egsFbm(p * vec3(1.5, 0.12, 1.5)) * 6.0; return 0.5 + 0.5 * sin(r);',
24
+ stone: 'float cracks = smoothstep(0.015, 0.06, abs(egsNoise(p * 1.3) - 0.5)); return mix(0.15, 0.55 + 0.45 * egsFbm(p * 2.0), cracks);',
25
+ brick: 'vec2 q = egsPlane(p, n) * vec2(1.0, 2.0); q.x += 0.5 * mod(floor(q.y), 2.0); vec2 f = abs(fract(q) - 0.5) * vec2(1.0, 0.5);' +
26
+ ' float joint = min(0.5 - f.x, 0.25 - f.y); return smoothstep(0.0, 0.035, joint) * (0.8 + 0.2 * egsNoise(p * 6.0));',
27
+ plaster: 'return 0.45 + 0.55 * egsFbm(p * 1.5 + egsFbm(p * 4.0));',
28
+ metal: 'return 0.55 + 0.45 * egsNoise(p * vec3(1.0, 60.0, 1.0)) * egsNoise(p * 2.0 + 3.0);',
29
+ cloth: 'vec2 q = egsPlane(p, n); return 0.5 + 0.25 * (sin(q.x * 6.2832) * sin(q.y * 3.1416) + sin(q.y * 6.2832) * sin(q.x * 3.1416));',
30
+ bark: 'float ridges = egsNoise(p * vec3(3.0, 0.35, 3.0)); return smoothstep(0.25, 0.75, ridges) * (0.7 + 0.3 * egsNoise(p * 8.0));'
31
+ };
32
+ const HEIGHT_WGSL = {
33
+ wood: 'let r = (p.x + p.z) * 3.0 + egsFbm(p * vec3f(1.5, 0.12, 1.5)) * 6.0; return 0.5 + 0.5 * sin(r);',
34
+ stone: 'let cracks = smoothstep(0.015, 0.06, abs(egsNoise(p * 1.3) - 0.5)); return mix(0.15, 0.55 + 0.45 * egsFbm(p * 2.0), cracks);',
35
+ brick: 'var q = egsPlane(p, n) * vec2f(1.0, 2.0); q.x = q.x + 0.5 * (floor(q.y) - 2.0 * floor(floor(q.y) / 2.0)); let f = abs(fract(q) - vec2f(0.5)) * vec2f(1.0, 0.5);' +
36
+ ' let joint = min(0.5 - f.x, 0.25 - f.y); return smoothstep(0.0, 0.035, joint) * (0.8 + 0.2 * egsNoise(p * 6.0));',
37
+ plaster: 'return 0.45 + 0.55 * egsFbm(p * 1.5 + vec3f(egsFbm(p * 4.0)));',
38
+ metal: 'return 0.55 + 0.45 * egsNoise(p * vec3f(1.0, 60.0, 1.0)) * egsNoise(p * 2.0 + vec3f(3.0));',
39
+ cloth: 'let q = egsPlane(p, n); return 0.5 + 0.25 * (sin(q.x * 6.2832) * sin(q.y * 3.1416) + sin(q.y * 6.2832) * sin(q.x * 3.1416));',
40
+ bark: 'let ridges = egsNoise(p * vec3f(3.0, 0.35, 3.0)); return smoothstep(0.25, 0.75, ridges) * (0.7 + 0.3 * egsNoise(p * 8.0));'
41
+ };
42
+ const NOISE_GLSL = `
43
+ float egsHash(vec3 p) { p = fract(p * 0.3183099 + 0.1); p *= 17.0; return fract(p.x * p.y * p.z * (p.x + p.y + p.z)); }
44
+ float egsNoise(vec3 x) {
45
+ vec3 i = floor(x); vec3 f = fract(x); f = f * f * (3.0 - 2.0 * f);
46
+ return mix(mix(mix(egsHash(i), egsHash(i + vec3(1.0, 0.0, 0.0)), f.x), mix(egsHash(i + vec3(0.0, 1.0, 0.0)), egsHash(i + vec3(1.0, 1.0, 0.0)), f.x), f.y),
47
+ mix(mix(egsHash(i + vec3(0.0, 0.0, 1.0)), egsHash(i + vec3(1.0, 0.0, 1.0)), f.x), mix(egsHash(i + vec3(0.0, 1.0, 1.0)), egsHash(i + vec3(1.0, 1.0, 1.0)), f.x), f.y), f.z);
48
+ }
49
+ float egsFbm(vec3 p) { float s = 0.0; float a = 0.5; for (int i = 0; i < 4; i++) { s += a * egsNoise(p); p = p * 2.03 + vec3(1.7, 9.2, 3.1); a *= 0.5; } return s / 0.9375; }
50
+ vec2 egsPlane(vec3 p, vec3 n) { vec3 a = abs(n); return a.x > a.y && a.x > a.z ? p.zy : (a.z > a.y ? p.xy : p.xz); }
51
+ `;
52
+ const NOISE_WGSL = `
53
+ fn egsHash(p0: vec3f) -> f32 { var p = fract(p0 * 0.3183099 + vec3f(0.1)); p = p * 17.0; return fract(p.x * p.y * p.z * (p.x + p.y + p.z)); }
54
+ fn egsNoise(x: vec3f) -> f32 {
55
+ let i = floor(x); var f = fract(x); f = f * f * (vec3f(3.0) - 2.0 * f);
56
+ return mix(mix(mix(egsHash(i), egsHash(i + vec3f(1.0, 0.0, 0.0)), f.x), mix(egsHash(i + vec3f(0.0, 1.0, 0.0)), egsHash(i + vec3f(1.0, 1.0, 0.0)), f.x), f.y),
57
+ mix(mix(egsHash(i + vec3f(0.0, 0.0, 1.0)), egsHash(i + vec3f(1.0, 0.0, 1.0)), f.x), mix(egsHash(i + vec3f(0.0, 1.0, 1.0)), egsHash(i + vec3f(1.0, 1.0, 1.0)), f.x), f.y), f.z);
58
+ }
59
+ fn egsFbm(p0: vec3f) -> f32 { var s = 0.0; var a = 0.5; var p = p0; for (var i = 0; i < 4; i = i + 1) { s = s + a * egsNoise(p); p = p * 2.03 + vec3f(1.7, 9.2, 3.1); a = a * 0.5; } return s / 0.9375; }
60
+ fn egsPlane(p: vec3f, n: vec3f) -> vec2f { let a = abs(n); if (a.x > a.y && a.x > a.z) { return p.zy; } if (a.z > a.y) { return p.xy; } return p.xz; }
61
+ `;
62
+ /** The shader sources of a surface: its height, the colour it gives and the relief it gives, in GLSL and WGSL. */
63
+ export function surfaceShaderSources3D(kind) {
64
+ if (!Object.prototype.hasOwnProperty.call(KINDS, kind))
65
+ throw new World3DError('WORLD3D_INPUT_INVALID', 'surface');
66
+ // custom[0]: scale, strength, bump. The slope of the height is taken across about a fiftieth of a pattern unit.
67
+ const glslHeight = `${NOISE_GLSL}float egsHeight(vec3 p, vec3 n) { ${HEIGHT_GLSL[kind]} }\n`;
68
+ const wgslHeight = `${NOISE_WGSL}fn egsHeight(p: vec3f, n: vec3f) -> f32 { ${HEIGHT_WGSL[kind]} }\n`;
69
+ return {
70
+ glsl: glslHeight +
71
+ `vec4 customFragment(vec4 color, vec3 worldPosition, vec3 normal, vec2 uv) {
72
+ float h = egsHeight(worldPosition * uCustom[0].x, normal);
73
+ return vec4(color.rgb * mix(1.0 - 0.6 * uCustom[0].y, 1.0 + 0.15 * uCustom[0].y, h), color.a);
74
+ }`,
75
+ wgsl: wgslHeight +
76
+ `fn customFragment(color: vec4f, worldPosition: vec3f, normal: vec3f, uv: vec2f) -> vec4f {
77
+ let h = egsHeight(worldPosition * material.custom[0].x, normal);
78
+ return vec4f(color.rgb * mix(1.0 - 0.6 * material.custom[0].y, 1.0 + 0.15 * material.custom[0].y, h), color.a);
79
+ }`,
80
+ // The engine places the fragment hook before the normal hook in both languages, so the normal hook uses the
81
+ // height and noise the fragment hook defines rather than defining them twice.
82
+ glslNormal: `vec3 customNormal(vec3 normal, vec3 worldPosition, vec2 uv) {
83
+ float s = uCustom[0].x; float e = 0.02;
84
+ vec3 p = worldPosition * s;
85
+ vec3 g = vec3(egsHeight(p + vec3(e, 0.0, 0.0), normal) - egsHeight(p - vec3(e, 0.0, 0.0), normal),
86
+ egsHeight(p + vec3(0.0, e, 0.0), normal) - egsHeight(p - vec3(0.0, e, 0.0), normal),
87
+ egsHeight(p + vec3(0.0, 0.0, e), normal) - egsHeight(p - vec3(0.0, 0.0, e), normal)) / (2.0 * e);
88
+ g -= normal * dot(g, normal);
89
+ return normal - g * (0.06 * uCustom[0].z);
90
+ }`,
91
+ wgslNormal: `fn customNormal(normal: vec3f, worldPosition: vec3f, uv: vec2f) -> vec3f {
92
+ let s = material.custom[0].x; let e = 0.02;
93
+ let p = worldPosition * s;
94
+ var g = vec3f(egsHeight(p + vec3f(e, 0.0, 0.0), normal) - egsHeight(p - vec3f(e, 0.0, 0.0), normal),
95
+ egsHeight(p + vec3f(0.0, e, 0.0), normal) - egsHeight(p - vec3f(0.0, e, 0.0), normal),
96
+ egsHeight(p + vec3f(0.0, 0.0, e), normal) - egsHeight(p - vec3f(0.0, 0.0, e), normal)) / (2.0 * e);
97
+ g = g - normal * dot(g, normal);
98
+ return normal - g * (0.06 * material.custom[0].z);
99
+ }`
100
+ };
101
+ }
102
+ /**
103
+ * A standard material with a surface drawn by the shader, over its colour or its vertex colours (on unless
104
+ * `vertexColors: false`): `createSurfaceMaterial3D({ surface: 'wood' })` for a crate made in code.
105
+ */
106
+ export function createSurfaceMaterial3D(options) {
107
+ if (options === null || typeof options !== 'object')
108
+ throw new World3DError('WORLD3D_INPUT_INVALID', 'surface options');
109
+ const kind = options.surface;
110
+ if (!Object.prototype.hasOwnProperty.call(KINDS, kind))
111
+ throw new World3DError('WORLD3D_INPUT_INVALID', 'surface');
112
+ const defaults = KINDS[kind];
113
+ const amount = (value, fallback, what, max = 1) => {
114
+ if (value === undefined)
115
+ return fallback;
116
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > max)
117
+ throw new World3DError('WORLD3D_INPUT_INVALID', what);
118
+ return value;
119
+ };
120
+ const scale = amount(options.scale, defaults.scale, 'surface scale', 1000);
121
+ if (scale === 0)
122
+ throw new World3DError('WORLD3D_INPUT_INVALID', 'surface scale');
123
+ const strength = amount(options.strength, 0.5, 'surface strength'), bump = amount(options.bump, 0.5, 'surface bump');
124
+ const { surface: _surface, scale: _scale, strength: _strength, bump: _bump, ...rest } = options;
125
+ const material = createStandardMaterial3D({
126
+ roughness: defaults.roughness,
127
+ metallic: defaults.metallic,
128
+ vertexColors: true,
129
+ ...rest
130
+ });
131
+ material.shader = createCustomShader3D({
132
+ key: 'surface-' + kind,
133
+ ...surfaceShaderSources3D(kind),
134
+ uniforms: [scale, strength, bump, 0]
135
+ });
136
+ return material;
137
+ }
138
+ //# sourceMappingURL=SurfaceMaterial3D.js.map
@@ -5,6 +5,7 @@ import { Mesh3D } from './Mesh3D.js';
5
5
  import { Object3D } from './Object3D.js';
6
6
  import { TriangleMeshShape3D } from './PhysicsMesh3D.js';
7
7
  import type { Camera3D } from './Camera3D.js';
8
+ /** The largest height field, chunk and number of levels and chunks terrain has, and the most streamed tiles. */
8
9
  export declare const TERRAIN3D_LIMITS: Readonly<{
9
10
  readonly maxSamplesPerSide: 4097;
10
11
  readonly maxChunkCells: 254;
@@ -14,6 +15,7 @@ export declare const TERRAIN3D_LIMITS: Readonly<{
14
15
  readonly maxStreamTiles: 256;
15
16
  readonly maxStreamPending: 32;
16
17
  }>;
18
+ /** A height field to make: its columns and rows, its size, and its heights or a function that gives them. */
17
19
  export interface HeightFieldOptions3D {
18
20
  /** Samples along X and along Z; a field of n samples has n - 1 cells. */
19
21
  readonly columns: number;
@@ -75,7 +77,9 @@ export declare class HeightField3D {
75
77
  readonly mesh: TriangleMeshShape3D;
76
78
  };
77
79
  }
80
+ /** Makes a grid of heights for terrain and physics. */
78
81
  export declare function createHeightField3D(options: HeightFieldOptions3D): HeightField3D;
82
+ /** How an image becomes heights: the field's size, its lowest and highest height, and how heights are encoded. */
79
83
  export interface HeightImageOptions3D {
80
84
  readonly width: number;
81
85
  readonly depth: number;
@@ -91,6 +95,7 @@ export declare function createHeightFieldFromPixels3D(pixels: {
91
95
  readonly height: number;
92
96
  readonly data: ArrayLike<number>;
93
97
  }, options: HeightImageOptions3D): HeightField3D;
98
+ /** Terrain to make: its chunks, levels of detail and their distance, its skirts, texture scale and colors. */
94
99
  export interface TerrainOptions3D {
95
100
  /** Cells along each side of a chunk. Default 32. */
96
101
  readonly chunkCells?: number;
@@ -155,7 +160,9 @@ export declare class Terrain3D extends Object3D {
155
160
  private use;
156
161
  private build;
157
162
  }
163
+ /** Makes terrain from a height field, drawn in chunks at levels of detail. */
158
164
  export declare function createTerrain3D(field: HeightField3D, material: Material3D, options?: TerrainOptions3D): Terrain3D;
165
+ /** A terrain material's layers, their weights, and how often they repeat. */
159
166
  export interface TerrainMaterialOptions3D extends StandardMaterialOptions3D {
160
167
  /** One to four tiling ground textures. */
161
168
  readonly layers: readonly Texture3D[];
@@ -170,12 +177,19 @@ export interface TerrainMaterialOptions3D extends StandardMaterialOptions3D {
170
177
  * with `uvScale` 1 so the weight map covers the terrain once.
171
178
  */
172
179
  export declare function createTerrainMaterial3D(options: TerrainMaterialOptions3D): Material3D;
180
+ /** One tile of streamed terrain: where it is, its height field and terrain. */
173
181
  export interface TerrainTile3D {
174
182
  readonly x: number;
175
183
  readonly z: number;
176
184
  readonly field: HeightField3D;
177
185
  readonly terrain: Terrain3D;
186
+ /**
187
+ * The world `[x, z]` of the tile's centre, which is the origin of its `field`: read a height at a world point as
188
+ * `field.heightAt(x - center[0], z - center[1])`.
189
+ */
190
+ readonly center: readonly [number, number];
178
191
  }
192
+ /** Streamed terrain to make: its tile size and view distance, how a tile is loaded, and what is called as tiles come and go. */
179
193
  export interface TerrainStreamOptions3D {
180
194
  /** World size of one square tile. Tile (x, z) covers x * size to (x + 1) * size on each axis. */
181
195
  readonly tileSize: number;
@@ -201,11 +215,17 @@ type TerrainStreamFailure3D = Readonly<{
201
215
  phase: 'load' | 'prepare' | 'onLoad' | 'dispose' | 'onUnload';
202
216
  cause: unknown;
203
217
  }>;
218
+ /** Terrain loaded in tiles around the camera: read heights, and update it as the camera moves. */
204
219
  export declare class TerrainStream3D extends Object3D {
205
220
  #private;
206
221
  readonly tileSize: number;
207
222
  viewDistance: number;
208
223
  constructor(options: TerrainStreamOptions3D);
224
+ /**
225
+ * How far the viewer of the last `update` is from the nearest point of a tile, in world units: for showing the
226
+ * things a game scattered on it in more or less detail. 0 inside it; Infinity before the first update.
227
+ */
228
+ distanceOf(tile: TerrainTile3D): number;
209
229
  get tiles(): readonly TerrainTile3D[];
210
230
  /** Outstanding loader calls, including retired requests that have yet to settle. */
211
231
  get pendingCount(): number;
@@ -222,6 +242,7 @@ export declare class TerrainStream3D extends Object3D {
222
242
  private release;
223
243
  private recordFailure;
224
244
  }
245
+ /** Makes terrain that loads and unloads tiles around a point. */
225
246
  export declare function createTerrainStream3D(options: TerrainStreamOptions3D): TerrainStream3D;
226
247
  export {};
227
248
  //# sourceMappingURL=Terrain3D.d.ts.map
@@ -11,6 +11,7 @@ import { mat4Invert, vec3TransformMat4 } from './math3D.js';
11
11
  import { Mesh3D } from './Mesh3D.js';
12
12
  import { Object3D } from './Object3D.js';
13
13
  import { TriangleMeshShape3D } from './PhysicsMesh3D.js';
14
+ /** The largest height field, chunk and number of levels and chunks terrain has, and the most streamed tiles. */
14
15
  export const TERRAIN3D_LIMITS = Object.freeze({
15
16
  maxSamplesPerSide: 4097,
16
17
  maxChunkCells: 254,
@@ -204,6 +205,7 @@ export class HeightField3D {
204
205
  return { type: 'mesh', mesh: new TriangleMeshShape3D(positions, indices) };
205
206
  }
206
207
  }
208
+ /** Makes a grid of heights for terrain and physics. */
207
209
  export function createHeightField3D(options) {
208
210
  return new HeightField3D(options);
209
211
  }
@@ -580,6 +582,7 @@ export class Terrain3D extends Object3D {
580
582
  return geometry;
581
583
  }
582
584
  }
585
+ /** Makes terrain from a height field, drawn in chunks at levels of detail. */
583
586
  export function createTerrain3D(field, material, options = {}) {
584
587
  return new Terrain3D(field, material, options);
585
588
  }
@@ -604,6 +607,7 @@ export function createTerrainMaterial3D(options) {
604
607
  });
605
608
  return material;
606
609
  }
610
+ /** Terrain loaded in tiles around the camera: read heights, and update it as the camera moves. */
607
611
  export class TerrainStream3D extends Object3D {
608
612
  tileSize;
609
613
  viewDistance;
@@ -629,6 +633,18 @@ export class TerrainStream3D extends Object3D {
629
633
  throw new World3DError('WORLD3D_INPUT_INVALID', 'loadsPerUpdate');
630
634
  this.#options = options;
631
635
  }
636
+ #viewer;
637
+ /**
638
+ * How far the viewer of the last `update` is from the nearest point of a tile, in world units: for showing the
639
+ * things a game scattered on it in more or less detail. 0 inside it; Infinity before the first update.
640
+ */
641
+ distanceOf(tile) {
642
+ const viewer = this.#viewer;
643
+ if (viewer === undefined)
644
+ return Infinity;
645
+ const size = this.tileSize, [x, z] = viewer;
646
+ return Math.hypot(Math.max(tile.x * size - x, 0, x - (tile.x + 1) * size), Math.max(tile.z * size - z, 0, z - (tile.z + 1) * size));
647
+ }
632
648
  get tiles() {
633
649
  return [...this.#tiles.values()];
634
650
  }
@@ -668,6 +684,7 @@ export class TerrainStream3D extends Object3D {
668
684
  throw new World3DError('WORLD3D_BUDGET', 'terrain stream tile range');
669
685
  }
670
686
  const near = (tx, tz) => Math.hypot(Math.max(tx * size - x, 0, x - (tx + 1) * size), Math.max(tz * size - z, 0, z - (tz + 1) * size));
687
+ this.#viewer = [x, z];
671
688
  this.#updating = true;
672
689
  try {
673
690
  for (const [key, tile] of this.#tiles)
@@ -737,7 +754,13 @@ export class TerrainStream3D extends Object3D {
737
754
  return;
738
755
  terrain.setPosition((x + 0.5) * this.tileSize, 0, (z + 0.5) * this.tileSize);
739
756
  this.addChild(terrain);
740
- const tile = Object.freeze({ x, z, field, terrain });
757
+ const tile = Object.freeze({
758
+ x,
759
+ z,
760
+ field,
761
+ terrain,
762
+ center: Object.freeze([(x + 0.5) * this.tileSize, (z + 0.5) * this.tileSize])
763
+ });
741
764
  this.#tiles.set(key, tile);
742
765
  this.#requests.delete(key);
743
766
  staged = undefined;
@@ -797,6 +820,7 @@ export class TerrainStream3D extends Object3D {
797
820
  this.#lastFailure = Object.freeze({ x: location.x, z: location.z, phase, cause });
798
821
  }
799
822
  }
823
+ /** Makes terrain that loads and unloads tiles around a point. */
800
824
  export function createTerrainStream3D(options) {
801
825
  return new TerrainStream3D(options);
802
826
  }
@@ -1,5 +1,6 @@
1
1
  import { Shape3D } from './Curves3D.js';
2
2
  import type { Geometry3D } from './Geometry3D.js';
3
+ /** The most characters, font bytes and glyph points 3D text has. */
3
4
  export declare const TEXT3D_LIMITS: Readonly<{
4
5
  readonly maxCharacters: 4096;
5
6
  readonly maxFontBytes: 67108864;
@@ -15,6 +16,7 @@ export interface GlyphOutline3D {
15
16
  readonly advance: number;
16
17
  readonly commands: readonly number[];
17
18
  }
19
+ /** A font for 3D text: its metrics, family, and its glyphs' outlines. */
18
20
  export interface FontSource3D {
19
21
  readonly unitsPerEm: number;
20
22
  readonly ascender: number;
@@ -25,6 +27,7 @@ export interface FontSource3D {
25
27
  /** Outline for a Unicode code point, or undefined when the font lacks it. */
26
28
  readonly glyph: (codePoint: number) => GlyphOutline3D | undefined;
27
29
  }
30
+ /** How 3D text is laid out: its size, curve detail, spacing, line height and alignment. */
28
31
  export interface TextLayoutOptions3D {
29
32
  /** Height of the em square in world units. Defaults to 1. */
30
33
  readonly size?: number;
@@ -37,12 +40,14 @@ export interface TextLayoutOptions3D {
37
40
  /** How lines are placed against x = 0. Defaults to 'left'. */
38
41
  readonly align?: 'left' | 'center' | 'right';
39
42
  }
43
+ /** 3D text to make: how deep it is extruded, and in how many steps. */
40
44
  export interface TextGeometryOptions3D extends TextLayoutOptions3D {
41
45
  /** Thickness along +Z. Zero gives flat text. Defaults to a fifth of the size. */
42
46
  readonly depth?: number;
43
47
  /** Subdivisions along the depth. */
44
48
  readonly steps?: number;
45
49
  }
50
+ /** A font that gives the outlines of text for 3D text geometry. */
46
51
  export declare class Font3D {
47
52
  #private;
48
53
  readonly unitsPerEm: number;
@@ -8,6 +8,7 @@
8
8
  import { World3DError, requireFinite3D, requirePositive3D } from './core3D.js';
9
9
  import { Path2D3D, Shape3D, signedArea2D } from './Curves3D.js';
10
10
  import { createExtrudeGeometry3D, createShapeGeometry3D } from './geometries3D.js';
11
+ /** The most characters, font bytes and glyph points 3D text has. */
11
12
  export const TEXT3D_LIMITS = Object.freeze({
12
13
  maxCharacters: 4096,
13
14
  maxFontBytes: 67108864,
@@ -23,6 +24,7 @@ function inside(point, polygon) {
23
24
  }
24
25
  return hit;
25
26
  }
27
+ /** A font that gives the outlines of text for 3D text geometry. */
26
28
  export class Font3D {
27
29
  unitsPerEm;
28
30
  ascender;
@@ -1,7 +1,11 @@
1
1
  import { Resource3D } from './core3D.js';
2
+ /** What a texture does past its edges: repeats, clamps or mirrors. */
2
3
  export type TextureWrap3D = 'repeat' | 'clamp' | 'mirror';
4
+ /** How a texture is sampled: the nearest texel, or blended. */
3
5
  export type TextureFilter3D = 'nearest' | 'linear';
6
+ /** Whether a texture's values are sRGB colors or linear data. */
4
7
  export type TextureColorSpace3D = 'srgb' | 'linear';
8
+ /** The largest texture edge and size. */
5
9
  export declare const TEXTURE3D_LIMITS: Readonly<{
6
10
  readonly maxEdge: 8192;
7
11
  readonly maxBytes: 268435456;
@@ -28,8 +32,11 @@ export interface CompressedPixels3D {
28
32
  readonly format: CompressedFormat3D;
29
33
  readonly levels: readonly Uint8Array[];
30
34
  }
35
+ /** What a texture is made from: pixels, compressed pixels, or an image the browser decoded. */
31
36
  export type TextureSource3D = TexturePixels3D | CompressedPixels3D | object;
37
+ /** Whether a value holds compressed pixels. */
32
38
  export declare function isCompressedPixels3D(source: unknown): source is CompressedPixels3D;
39
+ /** A texture to make: its name, wrapping and filters, its mipmaps and color space, whether it is flipped, and its anisotropy. */
33
40
  export interface TextureOptions3D {
34
41
  readonly name?: string;
35
42
  readonly wrapS?: TextureWrap3D;
@@ -43,6 +50,7 @@ export interface TextureOptions3D {
43
50
  /** Texture coordinate set to sample with: 0 for `uv`, 1 for `uv1`. */
44
51
  readonly channel?: 0 | 1;
45
52
  }
53
+ /** Whether a value holds plain pixels. */
46
54
  export declare function isTexturePixels3D(source: unknown): source is TexturePixels3D;
47
55
  declare abstract class TextureBase3D extends Resource3D {
48
56
  wrapS: TextureWrap3D;
@@ -68,6 +76,7 @@ declare abstract class TextureBase3D extends Resource3D {
68
76
  channel: 0 | 1;
69
77
  protected constructor(options: TextureOptions3D);
70
78
  }
79
+ /** A texture for 3D materials; set its source to change its picture. */
71
80
  export declare class Texture3D extends TextureBase3D {
72
81
  #private;
73
82
  /** UV transform applied as: uv' = rotate(uv * repeat) + offset. */
@@ -90,6 +99,7 @@ export declare class CubeTexture3D extends TextureBase3D {
90
99
  export declare function createSolidTexture3D(r: number, g: number, b: number, a?: number, options?: TextureOptions3D): Texture3D;
91
100
  /** Color storage of a render target: 8-bit sRGB, or half-float linear for values above 1. */
92
101
  export type RenderTargetFormat3D = 'rgba8' | 'rgba16f';
102
+ /** A render target to make: its format, its depth, and its filters and wrapping. */
93
103
  export interface RenderTargetOptions3D {
94
104
  readonly name?: string;
95
105
  /**
@@ -126,7 +136,12 @@ export declare class RenderTarget3D extends Resource3D {
126
136
  }
127
137
  /**
128
138
  * Procedural sky cube: a vertical gradient from `ground` through `horizon` to
129
- * `zenith`, in sRGB bytes. Useful as a background and a soft light probe.
139
+ * `zenith`, in sRGB. Useful as a background and a soft light probe.
140
+ *
141
+ * Colours are bytes, 0 to 255. Colours whose nine numbers are all from 0 to 1,
142
+ * as the other colours of the 3D world are written, are read as fractions of
143
+ * 255: `[0.4, 0.6, 1]` is the same sky as `[102, 153, 255]`. (Given as
144
+ * fractions before this, a sky was nearly black.)
130
145
  */
131
146
  export declare function createGradientCubeTexture3D(zenith: readonly [number, number, number], horizon: readonly [number, number, number], ground: readonly [number, number, number], size?: number): CubeTexture3D;
132
147
  export {};
@@ -3,6 +3,7 @@
3
3
  // or an opaque host image (ImageBitmap, canvas, video) that only a backend
4
4
  // interprets, which keeps this module DOM-free.
5
5
  import { Resource3D, World3DError, requireCount3D } from './core3D.js';
6
+ /** The largest texture edge and size. */
6
7
  export const TEXTURE3D_LIMITS = Object.freeze({ maxEdge: 8192, maxBytes: 268435456 });
7
8
  /** Bytes per 4x4 block of each compressed format. */
8
9
  export const COMPRESSED_BLOCK_BYTES_3D = Object.freeze({
@@ -13,12 +14,14 @@ export const COMPRESSED_BLOCK_BYTES_3D = Object.freeze({
13
14
  'etc2-rgba8': 16,
14
15
  'astc-4x4': 16
15
16
  });
17
+ /** Whether a value holds compressed pixels. */
16
18
  export function isCompressedPixels3D(source) {
17
19
  return (typeof source === 'object' &&
18
20
  source !== null &&
19
21
  Array.isArray(source.levels) &&
20
22
  typeof source.format === 'string');
21
23
  }
24
+ /** Whether a value holds plain pixels. */
22
25
  export function isTexturePixels3D(source) {
23
26
  return typeof source === 'object' && source !== null && source.data instanceof Uint8Array;
24
27
  }
@@ -85,6 +88,7 @@ class TextureBase3D extends Resource3D {
85
88
  this.anisotropy = options.anisotropy ?? 1;
86
89
  }
87
90
  }
91
+ /** A texture for 3D materials; set its source to change its picture. */
88
92
  export class Texture3D extends TextureBase3D {
89
93
  #source;
90
94
  /** UV transform applied as: uv' = rotate(uv * repeat) + offset. */
@@ -193,12 +197,26 @@ export class RenderTarget3D extends Resource3D {
193
197
  }
194
198
  /**
195
199
  * Procedural sky cube: a vertical gradient from `ground` through `horizon` to
196
- * `zenith`, in sRGB bytes. Useful as a background and a soft light probe.
200
+ * `zenith`, in sRGB. Useful as a background and a soft light probe.
201
+ *
202
+ * Colours are bytes, 0 to 255. Colours whose nine numbers are all from 0 to 1,
203
+ * as the other colours of the 3D world are written, are read as fractions of
204
+ * 255: `[0.4, 0.6, 1]` is the same sky as `[102, 153, 255]`. (Given as
205
+ * fractions before this, a sky was nearly black.)
197
206
  */
198
207
  export function createGradientCubeTexture3D(zenith, horizon, ground, size = 32) {
199
208
  const edge = requireCount3D(size, 'cube size', 1024);
200
209
  if (edge < 2)
201
210
  throw new World3DError('WORLD3D_INPUT_INVALID', 'cube size');
211
+ const all = [...zenith, ...horizon, ...ground];
212
+ if (all.length !== 9 || !all.every(v => typeof v === 'number' && v >= 0 && v <= 255))
213
+ throw new World3DError('WORLD3D_INPUT_INVALID', 'sky colour');
214
+ if (all.every(v => v <= 1)) {
215
+ const bytes = (c) => c.map(v => v * 255);
216
+ zenith = bytes(zenith);
217
+ horizon = bytes(horizon);
218
+ ground = bytes(ground);
219
+ }
202
220
  const faces = [];
203
221
  for (let face = 0; face < 6; face++) {
204
222
  const data = new Uint8Array(edge * edge * 4);
@@ -2,9 +2,11 @@ import { type Blending3D, type ColorInput3D } from './Material3D.js';
2
2
  import { Mesh3D } from './Mesh3D.js';
3
3
  import type { Object3D } from './Object3D.js';
4
4
  import type { Texture3D } from './Texture3D.js';
5
+ /** The most points a trail has. */
5
6
  export declare const TRAIL3D_LIMITS: Readonly<{
6
7
  readonly maxPoints: 4096;
7
8
  }>;
9
+ /** A trail to make: what it follows, how long it lasts, how far apart its points are, and how its width, color and opacity change. */
8
10
  export interface TrailOptions3D {
9
11
  /** The object whose world position the trail follows. Without one, feed points with `push`. */
10
12
  readonly target?: Object3D;
@@ -55,5 +57,6 @@ export declare class Trail3D extends Mesh3D {
55
57
  dispose(): void;
56
58
  private build;
57
59
  }
60
+ /** Makes a ribbon that follows a moving object and fades behind it. */
58
61
  export declare function createTrail3D(options?: TrailOptions3D): Trail3D;
59
62
  //# sourceMappingURL=Trail3D.d.ts.map
@@ -7,6 +7,7 @@ import { World3DError, requireCount3D, requireFinite3D, requirePositive3D } from
7
7
  import { Attribute3D, Geometry3D } from './Geometry3D.js';
8
8
  import { createUnlitMaterial3D, setColor3D } from './Material3D.js';
9
9
  import { Mesh3D } from './Mesh3D.js';
10
+ /** The most points a trail has. */
10
11
  export const TRAIL3D_LIMITS = Object.freeze({ maxPoints: 4096 });
11
12
  /**
12
13
  * Add the trail to the scene itself, not under the object it follows: its
@@ -187,6 +188,7 @@ export class Trail3D extends Mesh3D {
187
188
  this.geometry.invalidateBounds();
188
189
  }
189
190
  }
191
+ /** Makes a ribbon that follows a moving object and fades behind it. */
190
192
  export function createTrail3D(options = {}) {
191
193
  return new Trail3D(options);
192
194
  }
@@ -1,8 +1,10 @@
1
1
  import type { Object3D } from './Object3D.js';
2
2
  import { type PhysicsWorld3D, type RigidBody3D } from './Physics3D.js';
3
+ /** The most wheels a vehicle has. */
3
4
  export declare const VEHICLE3D_LIMITS: Readonly<{
4
5
  readonly maxWheels: 16;
5
6
  }>;
7
+ /** A wheel to add: where, its radius and suspension, whether it steers or drives, its grip and the node it turns. */
6
8
  export interface WheelOptions3D {
7
9
  /** Where the suspension is attached, in the chassis's local frame. */
8
10
  readonly position: readonly [number, number, number];
@@ -24,6 +26,7 @@ export interface WheelOptions3D {
24
26
  /** Node placed at the wheel's center and turned with it; give it to a mesh whose axle is its local X axis. */
25
27
  readonly node?: Object3D;
26
28
  }
29
+ /** A vehicle to make: its wheels, its engine and brakes, its steering, its top speed and how it rolls. */
27
30
  export interface VehicleOptions3D {
28
31
  readonly wheels: readonly WheelOptions3D[];
29
32
  /** Force the engine shares between the driven wheels at full throttle. */
@@ -43,6 +46,7 @@ export interface VehicleOptions3D {
43
46
  /** Bodies the wheels' rays may land on. Defaults to everything. */
44
47
  readonly mask?: number;
45
48
  }
49
+ /** A wheel of a vehicle: its suspension and grip, and whether it touches the ground. */
46
50
  export interface Wheel3D {
47
51
  readonly position: Float64Array;
48
52
  radius: number;
@@ -93,5 +97,6 @@ export declare class Vehicle3D {
93
97
  /** Apply suspension, engine, brakes and tyre grip for the coming step of `deltaSeconds`. */
94
98
  update(deltaSeconds: number): void;
95
99
  }
100
+ /** Makes a vehicle of wheels on raycast suspension under a chassis body. */
96
101
  export declare function createVehicle3D(world: PhysicsWorld3D, chassis: RigidBody3D, options: VehicleOptions3D): Vehicle3D;
97
102
  //# sourceMappingURL=Vehicle3D.d.ts.map
@@ -5,6 +5,7 @@
5
5
  // to drive, brake and resist sliding sideways. DOM-free and backend-independent.
6
6
  import { World3DError, requireFinite3D, requirePositive3D } from './core3D.js';
7
7
  import { raycastExcludingBody3D } from './Physics3D.js';
8
+ /** The most wheels a vehicle has. */
8
9
  export const VEHICLE3D_LIMITS = Object.freeze({ maxWheels: 16 });
9
10
  const down = new Float64Array(3), forward = new Float64Array(3), side = new Float64Array(3), from = new Float64Array(3), v = new Float64Array(3), w = new Float64Array(3), grip = new Float64Array(3);
10
11
  /**
@@ -220,6 +221,7 @@ export class Vehicle3D {
220
221
  }
221
222
  }
222
223
  }
224
+ /** Makes a vehicle of wheels on raycast suspension under a chassis body. */
223
225
  export function createVehicle3D(world, chassis, options) {
224
226
  return new Vehicle3D(world, chassis, options);
225
227
  }
@@ -1,5 +1,6 @@
1
1
  import { type ColorInput3D } from './Material3D.js';
2
2
  import { Mesh3D } from './Mesh3D.js';
3
+ /** Volumetric fog to make: its color and density, its height and falloff, its distance, and how much the sun and lights shine through it. */
3
4
  export interface VolumetricFogOptions3D {
4
5
  readonly color?: ColorInput3D;
5
6
  /** Fog thickness per world unit at `height`. Default 0.02. */
@@ -51,5 +52,6 @@ export declare class VolumetricFog3D extends Mesh3D {
51
52
  private face;
52
53
  private amount;
53
54
  }
55
+ /** Makes fog that light shines through. */
54
56
  export declare function createVolumetricFog3D(options?: VolumetricFogOptions3D): VolumetricFog3D;
55
57
  //# sourceMappingURL=VolumetricFog3D.d.ts.map
@@ -223,6 +223,7 @@ export class VolumetricFog3D extends Mesh3D {
223
223
  return value;
224
224
  }
225
225
  }
226
+ /** Makes fog that light shines through. */
226
227
  export function createVolumetricFog3D(options = {}) {
227
228
  return new VolumetricFog3D(options);
228
229
  }
@@ -72,6 +72,7 @@ export declare class PlanarReflection3D {
72
72
  private renderLegacy;
73
73
  dispose(): void;
74
74
  }
75
+ /** Water to make: its size and detail, its waves and ripples, its colors and clarity, its reflections, foam and caustics. */
75
76
  export interface WaterOptions3D {
76
77
  /** Size of the surface along X and Z. Defaults: 100 each. */
77
78
  readonly width?: number;
@@ -153,6 +154,7 @@ export declare class Water3D extends Mesh3D {
153
154
  /** Release the geometry, the material and the mirror image. */
154
155
  dispose(): void;
155
156
  }
157
+ /** Makes a water surface with waves, reflections and foam. */
156
158
  export declare function createWater3D(options?: WaterOptions3D): Water3D;
157
159
  /**
158
160
  * The material Water3D uses, for a water surface on your own geometry: a