@needle-tools/engine 5.1.0-canary.525aa82 → 5.1.0-canary.5e8eec4

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 (71) hide show
  1. package/CHANGELOG.md +9 -1
  2. package/components.needle.json +1 -1
  3. package/dist/{needle-engine.bundle-DPag02s9.min.js → needle-engine.bundle-B_tkRZ6n.min.js} +146 -146
  4. package/dist/{needle-engine.bundle-qa_NEunk.js → needle-engine.bundle-BuTzVOvj.js} +8613 -8552
  5. package/dist/{needle-engine.bundle-IPMzQpe1.umd.cjs → needle-engine.bundle-xboPkDEI.umd.cjs} +147 -147
  6. package/dist/needle-engine.d.ts +98 -24
  7. package/dist/needle-engine.js +188 -185
  8. package/dist/needle-engine.min.js +1 -1
  9. package/dist/needle-engine.umd.cjs +1 -1
  10. package/dist/{postprocessing-B_9sKVU7.min.js → postprocessing-B571qGWR.min.js} +34 -34
  11. package/dist/{postprocessing-WDc9WwI3.js → postprocessing-CfrLAbLX.js} +0 -1
  12. package/dist/{postprocessing-B2wb6pzI.umd.cjs → postprocessing-CiGkAeM9.umd.cjs} +17 -17
  13. package/lib/engine/api.d.ts +12 -0
  14. package/lib/engine/api.js +2 -0
  15. package/lib/engine/api.js.map +1 -1
  16. package/lib/engine/engine_constants.js +6 -0
  17. package/lib/engine/engine_constants.js.map +1 -1
  18. package/lib/engine/engine_context.d.ts +25 -0
  19. package/lib/engine/engine_context.js +27 -0
  20. package/lib/engine/engine_context.js.map +1 -1
  21. package/lib/engine/engine_physics_rapier.js +0 -1
  22. package/lib/engine/engine_physics_rapier.js.map +1 -1
  23. package/lib/engine/engine_scenedata.d.ts +18 -0
  24. package/lib/engine/engine_scenedata.js +67 -0
  25. package/lib/engine/engine_scenedata.js.map +1 -0
  26. package/lib/engine/engine_utils.js +2 -2
  27. package/lib/engine/engine_utils.js.map +1 -1
  28. package/lib/engine/xr/NeedleXRSession.d.ts +1 -0
  29. package/lib/engine/xr/NeedleXRSession.js +4 -4
  30. package/lib/engine/xr/NeedleXRSession.js.map +1 -1
  31. package/lib/engine/xr/events.d.ts +30 -3
  32. package/lib/engine/xr/events.js +38 -0
  33. package/lib/engine/xr/events.js.map +1 -1
  34. package/lib/engine/xr/init.js +1 -7
  35. package/lib/engine/xr/init.js.map +1 -1
  36. package/lib/engine-components/RigidBody.js +3 -3
  37. package/lib/engine-components/RigidBody.js.map +1 -1
  38. package/lib/engine-components/SceneSwitcher.js +2 -0
  39. package/lib/engine-components/SceneSwitcher.js.map +1 -1
  40. package/lib/engine-components/postprocessing/Effects/BloomEffect.d.ts +1 -1
  41. package/lib/engine-components/postprocessing/Effects/Sharpening.js +1 -2
  42. package/lib/engine-components/postprocessing/Effects/Sharpening.js.map +1 -1
  43. package/lib/engine-components/postprocessing/PostProcessingHandler.js +5 -6
  44. package/lib/engine-components/postprocessing/PostProcessingHandler.js.map +1 -1
  45. package/package.json +1 -1
  46. package/plugins/common/logger.js +42 -19
  47. package/plugins/dts-generator/index.js +859 -0
  48. package/plugins/types/index.d.ts +2 -1
  49. package/plugins/types/needle-bindings.d.ts +19 -0
  50. package/plugins/types/userconfig.d.ts +9 -2
  51. package/plugins/vite/dts-generator.d.ts +7 -0
  52. package/plugins/vite/dts-generator.js +157 -0
  53. package/plugins/vite/index.d.ts +1 -0
  54. package/plugins/vite/index.js +4 -0
  55. package/plugins/vite/logger.client.js +4 -3
  56. package/plugins/vite/reload.js +2 -1
  57. package/src/engine/api.ts +15 -1
  58. package/src/engine/engine_constants.ts +11 -6
  59. package/src/engine/engine_context.ts +29 -0
  60. package/src/engine/engine_physics_rapier.ts +0 -3
  61. package/src/engine/engine_scenedata.ts +67 -0
  62. package/src/engine/engine_utils.ts +2 -2
  63. package/src/engine/xr/NeedleXRSession.ts +5 -5
  64. package/src/engine/xr/events.ts +44 -1
  65. package/src/engine/xr/init.ts +0 -7
  66. package/src/engine-components/RigidBody.ts +3 -3
  67. package/src/engine-components/SceneSwitcher.ts +1 -0
  68. package/src/engine-components/postprocessing/Effects/BloomEffect.ts +1 -1
  69. package/src/engine-components/postprocessing/Effects/Sharpening.ts +1 -2
  70. package/src/engine-components/postprocessing/PostProcessingHandler.ts +4 -8
  71. package/src/vite-env.d.ts +16 -0
@@ -84,6 +84,7 @@ import { RawShaderMaterial } from 'three';
84
84
  import { Ray } from 'three';
85
85
  import { Raycaster } from 'three';
86
86
  import { Scene } from 'three';
87
+ import { SceneData } from '../../plugins/types/needle-bindings.d.ts';
87
88
  import { ShaderMaterial } from 'three';
88
89
  import { ShapeJSON } from 'three.quarks';
89
90
  import { SkinnedMesh } from 'three';
@@ -4458,6 +4459,30 @@ export declare class Context implements IContext {
4458
4459
  * The main camera of the scene - this camera is used for rendering
4459
4460
  * Use `setCurrentCamera` for updating the main camera.
4460
4461
  */
4462
+ /**
4463
+ * Typed proxy providing direct access to scene components by node and component name.
4464
+ * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
4465
+ * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
4466
+ *
4467
+ * Each property access traverses the live scene graph on demand — no caching, always fresh.
4468
+ * This is a convenience shorthand for `getComponent` lookups; the same result can be
4469
+ * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
4470
+ *
4471
+ * @example
4472
+ * // Toggle auto-rotate on the orbit camera
4473
+ * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
4474
+ *
4475
+ * @example
4476
+ * // Change the background color
4477
+ * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
4478
+ *
4479
+ * @example
4480
+ * // Equivalent manual approach (without sceneData)
4481
+ * const node = ctx.scene.getObjectByName("Camera");
4482
+ * const orbit = getComponent(node, OrbitControls);
4483
+ * if (orbit) orbit.autoRotate = true;
4484
+ */
4485
+ get sceneData(): SceneData;
4461
4486
  get mainCamera(): Camera_2;
4462
4487
  /** Set the main camera of the scene. If set to null the camera of the {@link mainCameraComponent} will be used - this camera is used for rendering */
4463
4488
  set mainCamera(cam: Camera_2 | null);
@@ -7130,6 +7155,23 @@ export declare function getPeerOptions(): PeerJSOption | undefined;
7130
7155
 
7131
7156
  export declare function getResourceUserCount(object: object): number | undefined;
7132
7157
 
7158
+ /**
7159
+ * Returns a lazily-resolved proxy typed as {@link SceneData}.
7160
+ * The proxy is cached per context — each context gets exactly one instance.
7161
+ *
7162
+ * Accessing a property traverses the scene graph on demand:
7163
+ * - First level → find Object3D by node name
7164
+ * - Second level → getComponent by component name (via TypeStore)
7165
+ * - Third level → read/write a field on the real component instance
7166
+ *
7167
+ * If a node or component is not found, property accesses log a warning
7168
+ * instead of throwing, so chained access never crashes.
7169
+ *
7170
+ * @example
7171
+ * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
7172
+ */
7173
+ export declare function getSceneData(ctx: IContext): SceneData;
7174
+
7133
7175
  export declare function getTempColor(color?: Color): Color;
7134
7176
 
7135
7177
  /**
@@ -13008,6 +13050,12 @@ export declare class ObjectUtils {
13008
13050
  private static applyDefaultObjectOptions;
13009
13051
  }
13010
13052
 
13053
+ /**
13054
+ * Remove a listener for before an XR session is requested
13055
+ * @param fn The function to remove from the listeners
13056
+ */
13057
+ export declare function offBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): void;
13058
+
13011
13059
  /* Excluded from this release type: OffscreenCanvasExt */
13012
13060
 
13013
13061
  /**
@@ -13112,6 +13160,21 @@ export declare function onAfterRender(cb: LifecycleMethod, opts?: LifecycleMetho
13112
13160
  * */
13113
13161
  export declare function onBeforeRender(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
13114
13162
 
13163
+ /**
13164
+ * Add a listener that fires before an XR session is requested.
13165
+ * Use this to modify the session init options, e.g. to add optional features like `camera-access`.
13166
+ * @param fn The function to call before the XR session is requested
13167
+ * @example
13168
+ * ```js
13169
+ * onBeforeXRSession((args) => {
13170
+ * args.init.optionalFeatures ??= [];
13171
+ * args.init.optionalFeatures.push("camera-access");
13172
+ * });
13173
+ * ```
13174
+ * @return A function to remove the listener
13175
+ */
13176
+ export declare function onBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): () => void;
13177
+
13115
13178
  /**
13116
13179
  * Register a callback before the engine context is cleared.
13117
13180
  * This happens if e.g. `<needle-engine src>` changes
@@ -13333,8 +13396,9 @@ export declare function onUpdate(cb: LifecycleMethod, opts?: LifecycleMethodOpti
13333
13396
  * console.log("XR session ended", evt);
13334
13397
  * });
13335
13398
  * ```
13399
+ * @returns A function to remove the listener
13336
13400
  */
13337
- export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): void;
13401
+ export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): () => void;
13338
13402
 
13339
13403
  /**
13340
13404
  * Add a listener for when an XR session starts
@@ -13346,8 +13410,9 @@ export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): v
13346
13410
  * console.log("XR session started", evt);
13347
13411
  * });
13348
13412
  * ```
13413
+ * @returns A function to remove the listener
13349
13414
  */
13350
- export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
13415
+ export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): () => void;
13351
13416
 
13352
13417
  /**
13353
13418
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
@@ -16938,6 +17003,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16938
17003
  */
16939
17004
  declare type ScaleClipType = "linear" | "spring";
16940
17005
 
17006
+ export { SceneData }
17007
+
16941
17008
  export declare class SceneLightSettings extends Component {
16942
17009
  ambientMode: AmbientMode;
16943
17010
  ambientLight?: Color;
@@ -18085,6 +18152,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
18085
18152
  export declare type SessionRequestedEvent = (args: {
18086
18153
  readonly mode: XRSessionMode;
18087
18154
  readonly init: XRSessionInit;
18155
+ readonly context: Context;
18088
18156
  }) => void;
18089
18157
 
18090
18158
  export declare function setActive(go: Object3D, active: boolean | number): boolean;
@@ -23373,6 +23441,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
23373
23441
  session: NeedleXRSession;
23374
23442
  };
23375
23443
 
23444
+ export declare type XRSessionRequestEventArgs = {
23445
+ readonly mode: XRSessionMode;
23446
+ readonly init: XRSessionInit;
23447
+ readonly context: Context;
23448
+ };
23449
+
23376
23450
  export declare class XRState {
23377
23451
  static Global: XRState;
23378
23452
  Mask: XRStateFlag;
@@ -23398,6 +23472,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
23398
23472
  export { }
23399
23473
 
23400
23474
 
23475
+ declare module 'three' {
23476
+ interface SkinnedMesh {
23477
+ staticGenerator?: StaticGeometryGenerator;
23478
+ staticGeometry?: BufferGeometry;
23479
+ staticGeometryLastUpdate?: number;
23480
+ }
23481
+ interface Mesh {
23482
+ acceleratedRaycast?: any;
23483
+ }
23484
+ interface SkinnedMesh {
23485
+ /** @deprecated use autoUpdateMeshBvhInterval */
23486
+ autoUpdateMeshBVH?: boolean;
23487
+ /**
23488
+ * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
23489
+ * @default undefined (disabled)
23490
+ */
23491
+ autoUpdateMeshBvhInterval?: number;
23492
+ bvhNeedsUpdate?: boolean;
23493
+ }
23494
+ }
23495
+
23496
+
23401
23497
  declare module 'three' {
23402
23498
  interface Object3D {
23403
23499
  get guid(): string | undefined;
@@ -23543,25 +23639,3 @@ declare module 'three' {
23543
23639
  slerp(end: Vector3, t: number): Vector3;
23544
23640
  }
23545
23641
  }
23546
-
23547
-
23548
- declare module 'three' {
23549
- interface SkinnedMesh {
23550
- staticGenerator?: StaticGeometryGenerator;
23551
- staticGeometry?: BufferGeometry;
23552
- staticGeometryLastUpdate?: number;
23553
- }
23554
- interface Mesh {
23555
- acceleratedRaycast?: any;
23556
- }
23557
- interface SkinnedMesh {
23558
- /** @deprecated use autoUpdateMeshBvhInterval */
23559
- autoUpdateMeshBVH?: boolean;
23560
- /**
23561
- * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
23562
- * @default undefined (disabled)
23563
- */
23564
- autoUpdateMeshBvhInterval?: number;
23565
- bvhNeedsUpdate?: boolean;
23566
- }
23567
- }