@needle-tools/engine 5.1.0-alpha → 5.1.0-alpha.2

package/src/engine-components/GroundProjection.ts

@@ -1,4 +1,4 @@
-import { ShaderMaterial, Texture } from "three";
+import { CubeUVReflectionMapping, ShaderMaterial, Texture } from "three";
 import { GroundedSkybox as GroundProjection } from 'three/examples/jsm/objects/GroundedSkybox.js';
 
 import { Gizmos } from "../engine/engine_gizmos.js";
@@ -12,6 +12,174 @@ import type { ContactShadows } from "./ContactShadows.js";
 
 const debug = getParam("debuggroundprojection");
 
+type GroundProjectionMaterial = GroundProjection["material"] & {
+    defines?: Record<string, string | number>;
+};
+
+type GroundProjectionShaderUniforms = {
+    needleGroundProjectionBlurriness: { value: number };
+    needleGroundProjectionBlending: { value: number };
+    needleGroundProjectionAlphaFactor: { value: number };
+    needleGroundProjectionBackgroundIntensity: { value: number };
+};
+
+const needleCubeUvMapVarying = /* glsl */`
+#ifdef NEEDLE_USE_CUBE_UV_MAP
+varying vec3 vNeedleGroundProjectionWorldDirection;
+#endif
+`;
+
+const needleGroundProjectionFragmentPars = /* glsl */`
+${needleCubeUvMapVarying}
+uniform float needleGroundProjectionBlurriness;
+uniform float needleGroundProjectionBlending;
+uniform float needleGroundProjectionAlphaFactor;
+uniform float needleGroundProjectionBackgroundIntensity;
+
+float needleGroundProjectionSmoothstep(float edge0, float edge1, float x) {
+    float t = clamp((x - edge0) / max(edge1 - edge0, 0.000001), 0.0, 1.0);
+    return t * t * (3.0 - 2.0 * t);
+}
+
+float needleGroundProjectionDistance() {
+    return length(vec2(0.0, vMapUv.y));
+}
+
+float needleGroundProjectionBlurFactor(float needleGroundProjectionDistanceValue) {
+    return clamp(needleGroundProjectionSmoothstep(0.5, 1.0, needleGroundProjectionDistanceValue * 2.0), 0.0, 1.0);
+}
+`;
+
+const needleCubeUvMapFragment = /* glsl */`
+#ifdef USE_MAP
+
+    float needleGroundProjectionDistanceValue = needleGroundProjectionDistance();
+    float needleGroundProjectionBlurFactorValue = needleGroundProjectionBlurFactor(needleGroundProjectionDistanceValue);
+    vec4 sampledDiffuseColor;
+
+    #ifdef NEEDLE_USE_CUBE_UV_MAP
+        sampledDiffuseColor = textureCubeUV(
+            map,
+            normalize( vNeedleGroundProjectionWorldDirection ),
+            needleGroundProjectionBlurriness * needleGroundProjectionBlurFactorValue
+        );
+    #else
+        #ifdef USE_MIPMAP_BIAS
+            sampledDiffuseColor = texture2D( map, vMapUv, mipmapBias );
+        #else
+            sampledDiffuseColor = texture2D( map, vMapUv );
+        #endif
+    #endif
+
+    #ifdef DECODE_VIDEO_TEXTURE
+
+        // use inline sRGB decode until browsers properly support SRGB8_ALPHA8 with video textures (#26516)
+
+        sampledDiffuseColor = vec4( mix( pow( sampledDiffuseColor.rgb * 0.9478672986 + vec3( 0.0521327014 ), vec3( 2.4 ) ), sampledDiffuseColor.rgb * 0.0773993808, vec3( lessThanEqual( sampledDiffuseColor.rgb, vec3( 0.04045 ) ) ) ), sampledDiffuseColor.w );
+
+    #endif
+
+    sampledDiffuseColor.rgb *= mix(1.0, needleGroundProjectionBackgroundIntensity, needleGroundProjectionBlurFactorValue);
+    diffuseColor *= sampledDiffuseColor;
+
+#endif
+`;
+
+const needleGroundProjectionAlphaFragment = /* glsl */`
+#ifdef USE_MAP
+    if (needleGroundProjectionBlending > 0.000001) {
+        float needleGroundProjectionBrightness = dot(diffuseColor.rgb, vec3(0.299, 0.587, 0.114));
+        float needleGroundProjectionStepFactor = needleGroundProjectionBlending - needleGroundProjectionBrightness * 0.1;
+        diffuseColor.a *= pow(
+            1.0 - needleGroundProjectionBlending * needleGroundProjectionSmoothstep(
+                0.35 * needleGroundProjectionStepFactor,
+                0.45 * needleGroundProjectionStepFactor,
+                needleGroundProjectionDistanceValue
+            ),
+            5.0
+        );
+    }
+#endif
+diffuseColor.a *= needleGroundProjectionAlphaFactor;
+`;
+
+function getCubeUvSize(texture: Texture) {
+    const imageHeight = texture.image?.height;
+    if (!imageHeight) return null;
+
+    const maxMip = Math.log2(imageHeight) - 2;
+    const texelHeight = 1 / imageHeight;
+    const texelWidth = 1 / (3 * Math.max(Math.pow(2, maxMip), 7 * 16));
+    return { texelWidth, texelHeight, maxMip };
+}
+
+function getGroundProjectionShaderUniforms(material: GroundProjectionMaterial): GroundProjectionShaderUniforms {
+    const userData = material.userData as GroundProjectionMaterial["userData"] & {
+        needleGroundProjectionUniforms?: GroundProjectionShaderUniforms;
+    };
+
+    return userData.needleGroundProjectionUniforms ??= {
+        needleGroundProjectionBlurriness: { value: 0 },
+        needleGroundProjectionBlending: { value: 0 },
+        needleGroundProjectionAlphaFactor: { value: 1 },
+        needleGroundProjectionBackgroundIntensity: { value: 1 }
+    };
+}
+
+function configureGroundProjectionMaterial(material: GroundProjectionMaterial, texture: Texture) {
+    const projectionUniforms = getGroundProjectionShaderUniforms(material);
+    material.onBeforeCompile = shader => {
+        shader.uniforms.needleGroundProjectionBlurriness = projectionUniforms.needleGroundProjectionBlurriness;
+        shader.uniforms.needleGroundProjectionBlending = projectionUniforms.needleGroundProjectionBlending;
+        shader.uniforms.needleGroundProjectionAlphaFactor = projectionUniforms.needleGroundProjectionAlphaFactor;
+        shader.uniforms.needleGroundProjectionBackgroundIntensity = projectionUniforms.needleGroundProjectionBackgroundIntensity;
+
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <uv_pars_vertex>", `#include <uv_pars_vertex>\n${needleCubeUvMapVarying}`)
+            .replace(
+                "#include <worldpos_vertex>",
+                `#include <worldpos_vertex>
+#ifdef NEEDLE_USE_CUBE_UV_MAP
+	// GroundedSkybox mirrors geometry on Z, so undo that before deriving the sampling direction.
+	vNeedleGroundProjectionWorldDirection = transformDirection( vec3( position.x, position.y, -position.z ), modelMatrix );
+#endif`
+            );
+
+        shader.fragmentShader = shader.fragmentShader
+            .replace(
+                "#include <map_pars_fragment>",
+                `#include <map_pars_fragment>
+${needleGroundProjectionFragmentPars}
+#include <cube_uv_reflection_fragment>`
+            )
+            .replace("#include <map_fragment>", needleCubeUvMapFragment)
+            .replace("#include <opaque_fragment>", `${needleGroundProjectionAlphaFragment}\n#include <opaque_fragment>`);
+    };
+
+    const defines = material.defines ??= {};
+    const prevDefineState = JSON.stringify(defines);
+    const cubeUvSize = texture.mapping === CubeUVReflectionMapping ? getCubeUvSize(texture) : null;
+
+    if (cubeUvSize) {
+        defines.NEEDLE_USE_CUBE_UV_MAP = 1;
+        defines.ENVMAP_TYPE_CUBE_UV = 1;
+        defines.CUBEUV_TEXEL_WIDTH = cubeUvSize.texelWidth;
+        defines.CUBEUV_TEXEL_HEIGHT = cubeUvSize.texelHeight;
+        defines.CUBEUV_MAX_MIP = `${cubeUvSize.maxMip}.0`;
+    }
+    else {
+        delete defines.NEEDLE_USE_CUBE_UV_MAP;
+        delete defines.ENVMAP_TYPE_CUBE_UV;
+        delete defines.CUBEUV_TEXEL_WIDTH;
+        delete defines.CUBEUV_TEXEL_HEIGHT;
+        delete defines.CUBEUV_MAX_MIP;
+    }
+
+    if (prevDefineState !== JSON.stringify(defines)) {
+        material.needsUpdate = true;
+    }
+}
+
 /**
  * The [GroundProjectedEnv](https://engine.needle.tools/docs/api/GroundProjectedEnv) projects the environment map onto a virtual ground plane.
  * Creates a realistic floor from 360° panoramas/HDRIs by deforming the skybox
@@ -147,12 +315,10 @@ export class GroundProjectedEnv extends Behaviour {
             this._projection.rotation.copy(this.scene.backgroundRotation);
         }
 
-        const blurrinessChanged = this.context.scene.backgroundBlurriness !== undefined && this._lastBlurriness != this.context.scene.backgroundBlurriness && this.context.scene.backgroundBlurriness > 0.001;
-        if (blurrinessChanged) {
-            this.updateProjection();
-        }
-        else if (this._needsTextureUpdate && this.context.scene.background instanceof Texture) {
-            this.updateBlurriness(this.context.scene.background, this.context.scene.backgroundBlurriness);
+        if (this._projection && this.context.scene.background instanceof Texture) {
+            const blurriness = this.context.scene.backgroundBlurriness ?? 0;
+            const blurrinessChanged = this._lastBlurriness !== blurriness;
+            this.updateProjectionMaterial(this.context.scene.background, blurrinessChanged || this._needsTextureUpdate);
         }
     }
 
@@ -202,6 +368,7 @@ export class GroundProjectedEnv extends Behaviour {
 
             try {
                 this._projection = new GroundProjection(backgroundTexture, this._height, this._radius, 64);
+                configureGroundProjectionMaterial(this._projection.material, backgroundTexture);
             }
             catch (e) {
                 console.error("Error creating three GroundProjection", e);
@@ -242,9 +409,7 @@ export class GroundProjectedEnv extends Behaviour {
         this.env.height = this._height;
         */
 
-        if (this.context.scene.backgroundBlurriness > 0.001 && this._needsTextureUpdate) {
-            this.updateBlurriness(backgroundTexture, this.context.scene.backgroundBlurriness);
-        }
+        this.updateProjectionMaterial(backgroundTexture, true);
 
         this._lastBackground = backgroundTexture;
         this._lastHeight = this._height;
@@ -254,24 +419,60 @@ export class GroundProjectedEnv extends Behaviour {
 
     private _blurrynessShader: ShaderMaterial | null = null;
     private _lastBlurriness: number = -1;
-
-    private updateBlurriness(texture: Texture, blurriness: number) {
+    
+    private updateProjectionMaterial(texture: Texture, forceTextureUpdate = false) {
         if (!this._projection) {
             return;
         }
-        else if (!texture) {
-            return;
+
+        const blurriness = this.context.scene.backgroundBlurriness ?? 0;
+        const useCubeUvBlur = texture.mapping === CubeUVReflectionMapping;
+
+        let targetTexture = texture;
+        if (!useCubeUvBlur && blurriness > 0.001) {
+            const hasBlurredTextureAssigned = !!this._projection.material.map && this._projection.material.map !== texture;
+            if (forceTextureUpdate || !hasBlurredTextureAssigned) {
+                targetTexture = this.updateBlurriness(texture, blurriness);
+            }
+            else if (this._projection.material.map) {
+                targetTexture = this._projection.material.map;
+            }
+        }
+
+        if (this._projection.material.map !== targetTexture) {
+            this._projection.material.map = targetTexture;
+        }
+
+        const appliedTexture = this._projection.material.map ?? texture;
+        appliedTexture.mapping = texture.mapping;
+        configureGroundProjectionMaterial(this._projection.material, appliedTexture);
+
+        const shaderUniforms = getGroundProjectionShaderUniforms(this._projection.material);
+        shaderUniforms.needleGroundProjectionBlurriness.value = useCubeUvBlur ? blurriness : 0;
+        shaderUniforms.needleGroundProjectionBackgroundIntensity.value = this.context.scene.backgroundIntensity ?? 1;
+
+        const wasTransparent = this._projection.material.transparent;
+        this._projection.material.transparent = (this.context.xr?.isAR === true && this.arBlending > 0.000001) ?? false;
+        shaderUniforms.needleGroundProjectionBlending.value = this._projection.material.transparent ? this.arBlending : 0;
+        shaderUniforms.needleGroundProjectionAlphaFactor.value = this.context.isInPassThrough ? 0.95 : 1;
+
+        if (wasTransparent !== this._projection.material.transparent) {
+            this._projection.material.needsUpdate = true;
         }
 
+        this._projection.material.depthTest = true;
+        this._projection.material.depthWrite = false;
+        this._lastBlurriness = blurriness;
         this._needsTextureUpdate = false;
+    }
+
+    private updateBlurriness(texture: Texture, blurriness: number): Texture {
         if (debug) console.log("Update Blurriness", blurriness);
         this._blurrynessShader ??= new ShaderMaterial({
             name: "GroundProjectionBlurriness",
             uniforms: {
                 map: { value: texture },
-                blurriness: { value: blurriness },
-                blending: { value: 0 },
-                alphaFactor: { value: 1 }
+                blurriness: { value: blurriness }
             },
             vertexShader: blurVertexShader,
             fragmentShader: blurFragmentShader
@@ -279,33 +480,10 @@ export class GroundProjectedEnv extends Behaviour {
         this._blurrynessShader.depthWrite = false;
         this._blurrynessShader.uniforms.map.value = texture;
         this._blurrynessShader.uniforms.blurriness.value = blurriness;
-        this._lastBlurriness = blurriness;
         texture.needsUpdate = true;
-
-        const wasTransparent = this._projection.material.transparent;
-        this._projection.material.transparent = (this.context.xr?.isAR === true && this.arBlending > 0.000001) ?? false;
-        if (this._projection.material.transparent) {
-            this._blurrynessShader.uniforms.blending.value = this.arBlending;
-        }
-        else { this._blurrynessShader.uniforms.blending.value = 0; }
-
-        if (this.context.isInPassThrough) {
-            // Make the ground slightly transparent in passthrough mode
-            this._blurrynessShader.uniforms.alphaFactor.value = 0.95;
-        }
-        else {
-            this._blurrynessShader.uniforms.alphaFactor.value = 1;
-        }
-
-        // Make sure the material is updated if the transparency changed
-        if (wasTransparent !== this._projection.material.transparent) {
-            this._projection.material.needsUpdate = true;
-        }
-
-        // Update the texture
-        this._projection.material.map = Graphics.copyTexture(texture, this._blurrynessShader);
-        this._projection.material.depthTest = true;
-        this._projection.material.depthWrite = false;
+        const blurredTexture = Graphics.copyTexture(texture, this._blurrynessShader);
+        blurredTexture.mapping = texture.mapping;
+        return blurredTexture;
     }
 
 }
@@ -324,8 +502,6 @@ const blurVertexShader = `
 const blurFragmentShader = `
   uniform sampler2D map;
   uniform float blurriness;
-  uniform float alphaFactor;
-  uniform float blending;
   varying vec2 vUv;
 
   const float PI = 3.14159265359;
@@ -356,6 +532,10 @@ const blurFragmentShader = `
     vec4 color = vec4(0.0);
     float totalWeight = 0.0;
     int blurSize = int(60.0 * min(1.0, blurriness) * blurAmount); // Adjust blur size based on distance and blurriness
+    if (blurSize <= 0) {
+      gl_FragColor = texture2D(map, vUv);
+      return;
+    }
     float lodLevel = log2(float(blurSize)) * 0.5; // Compute LOD level
 
     for (int x = -blurSize; x <= blurSize; x++) {
@@ -371,16 +551,10 @@ const blurFragmentShader = `
 
     gl_FragColor = color;
 
-    float brightness = dot(gl_FragColor.rgb, vec3(0.299, 0.587, 0.114));
-    float stepFactor = blending - brightness * .1;
-    gl_FragColor.a = pow(1.0 - blending * customSmoothstep(0.35 * stepFactor, 0.45 * stepFactor, distance), 5.);
-    gl_FragColor.a *= alphaFactor;
-    // gl_FragColor.rgb = vec3(1.0);
-
     // #include <tonemapping_fragment>
     // #include <colorspace_fragment>
     
     // Uncomment to visualize blur amount
     // gl_FragColor = vec4(blurAmount, 0.0, 0.0, 1.0);
   }
-`;
+`;

package/src/engine-components/Light.ts

@@ -106,11 +106,40 @@ enum LightShadows {
 export class Light extends Behaviour implements ILight {
 
     /**
-     * The type of light (spot, directional, point, etc.)  
-     * Can not be changed at runtime.  
+     * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
+     * Implements {@link ILight.type}. Can not be changed at runtime.
      */
+    get type(): ILight["type"] {
+        return this._type;
+    }
+
+    /** Numeric LightType serialized from Unity/Blender — converts to string on write */
     @serializable()
-    private type: LightType = 0;
+    set type(value: LightType | ILight["type"]) {
+        if (this.light && this.__didAwake) {
+            throw new Error("Changing the light type at runtime is not supported");
+        }
+        switch (value) {
+            case LightType.Directional:
+                this._type = "directional";
+                break;
+            case LightType.Point:
+                this._type = "point";
+                break;
+            case LightType.Spot:
+                this._type = "spot";
+                break;
+            case "directional":
+            case "point":
+            case "spot":
+                this._type = value;
+                break;
+            default:
+                throw new Error("Invalid light type: " + value);
+        }
+    }
+    private _type: ILight["type"] = "point";
+
 
     /**
      * The maximum distance the light affects.  
@@ -345,7 +374,7 @@ export class Light extends Behaviour implements ILight {
      */
     public getWorldPosition(vec: Vector3): Vector3 {
         if (this.light) {
-            if (this.type === LightType.Directional) {
+            if (this.type === "directional") {
                 return this.light.getWorldPosition(vec).multiplyScalar(1);
             }
             return this.light.getWorldPosition(vec);
@@ -372,12 +401,13 @@ export class Light extends Behaviour implements ILight {
             else if (this.light.parent !== this.gameObject)
                 this.gameObject.add(this.light);
         }
-        if (this.type === LightType.Directional)
-            this.startCoroutine(this.updateMainLightRoutine(), FrameEvent.LateUpdate);
+        this.context.lights.push(this);
     }
 
     onDisable() {
         if (debug) console.log("DISABLE LIGHT", this.name);
+        const index = this.context.lights.indexOf(this);
+        if (index !== -1) this.context.lights.splice(index, 1);
         if (this.light) {
             if (this.selfIsLight)
                 this.light.intensity = 0;
@@ -399,14 +429,14 @@ export class Light extends Behaviour implements ILight {
             this._intensity = this.light.intensity;
 
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     this.setDirectionalLight(this.light as DirectionalLight);
                     break;
             }
         }
         else if (!this.light) {
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     // console.log(this);
                     const dirLight = new DirectionalLight(this.color, this.intensity * Math.PI);
                     // directional light target is at 0 0 0 by default
@@ -425,7 +455,7 @@ export class Light extends Behaviour implements ILight {
                     }
                     break;
 
-                case LightType.Spot:
+                case "spot":
                     const spotLight = new SpotLight(this.color, this.intensity * Math.PI, this.range, toRadians(this.spotAngle / 2), 1 - toRadians(this.innerSpotAngle / 2) / toRadians(this.spotAngle / 2), 2);
                     spotLight.position.set(0, 0, 0);
                     spotLight.rotation.set(0, 0, 0);
@@ -437,7 +467,7 @@ export class Light extends Behaviour implements ILight {
                     spotLightTarget.rotation.set(0, 0, 0);
                     break;
 
-                case LightType.Point:
+                case "point":
                     const pointLight = new PointLight(this.color, this.intensity * Math.PI, this.range);
                     this.light = pointLight;
 
@@ -526,22 +556,6 @@ export class Light extends Behaviour implements ILight {
 
     }
 
-    /**
-     * Coroutine that updates the main light reference in the context
-     * if this directional light should be the main light
-     */
-    *updateMainLightRoutine() {
-        while (true) {
-            if (this.type === LightType.Directional) {
-                if (!this.context.mainLight || this.intensity > this.context.mainLight.intensity) {
-                    this.context.mainLight = this;
-                }
-                yield;
-            }
-            break;
-        }
-    }
-
     /**
      * Controls whether the renderer's shadow map type can be changed when soft shadows are used
      */

package/src/engine-components/RigidBody.ts

@@ -382,12 +382,12 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this._watch.start(true, true);
         this.startCoroutine(this.beforePhysics(), FrameEvent.LateUpdate);
         if (isDevEnvironment()) {
-            if (!globalThis["NEEDLE_USE_RAPIER"])
-                console.warn(`Rigidbody could not be created: Rapier physics are explicitly disabled.`);
+            if (globalThis["NEEDLE_USE_RAPIER"] === false)
+                console.warn(`RAPIER physics are disabled in your build. Enable them by setting NEEDLE_USE_RAPIER to true in your build config: Rigidbody could not be created.`);
             else {
                 MODULES.RAPIER_PHYSICS.ready().then(async () => {
                     await delayForFrames(3);
-                    if (!this.context.physics.engine?.getBody(this))
+                    if (this.activeAndEnabled && !this.context.physics.engine?.getBody(this))
                         console.warn(`Rigidbody could not be created. Ensure \"${this.name}\" has a Collider component.`);
                 })
             }

package/src/engine-components/SceneSwitcher.ts

@@ -723,6 +723,7 @@ export class SceneSwitcher extends Behaviour {
                     // unless the user defines that he wants to use the scene name
                     if (this.useSceneName) {
                         if (scene instanceof Object3D) queryParameterValue = scene.name;
+                        else if (scene instanceof AssetReference && scene.asset?.name) queryParameterValue = scene.asset.name;
                         else if (scene.url) queryParameterValue = sceneUriToName(scene.url);
                     }
                     // save the loaded scene as an url parameter

package/src/engine-components/api.ts

@@ -35,6 +35,7 @@
  */
 
 export * from "./codegen/components.js";
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 

package/src/engine-components/codegen/components.ts

@@ -6,6 +6,7 @@ export { Animation } from "../Animation.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
+export { AnimatorControllerBuilder } from "../AnimatorController.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -1,4 +1,4 @@
-import { BloomEffect as _BloomEffect, EffectAttribute } from "postprocessing";
+import type { BloomEffect as _BloomEffect } from "postprocessing";
 import { MathUtils } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -1,4 +1,3 @@
-import { EffectAttribute } from "postprocessing";
 import { Uniform } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";
@@ -138,7 +137,7 @@ function createSharpeningEffectType() {
                     ["radius", new Uniform(1)],
                     // ["threshold", new Uniform(0)],
                 ]),
-                attributes: EffectAttribute.CONVOLUTION
+                attributes: MODULES.POSTPROCESSING.MODULE.EffectAttribute.CONVOLUTION
             });
         }
     }

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -14,10 +14,6 @@ import { threeToneMappingToEffectMode } from "./Effects/Tonemapping.utils.js";
 import { PostProcessingEffect, PostProcessingEffectContext } from "./PostProcessingEffect.js";
 import { orderEffects, PostprocessingEffectData, PostProcessingEffectOrder } from "./utils.js";
 
-declare const NEEDLE_USE_POSTPROCESSING: boolean;
-globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
-
-
 const debug = getParam("debugpost");
 
 const activeKey = Symbol("needle:postprocessing-handler");
@@ -58,13 +54,13 @@ export class PostProcessingHandler implements IPostProcessingHandler {
 
     apply(components: PostProcessingEffect[]): Promise<void> {
         if ("env" in import.meta && (import.meta as any /* webpack support */ ).env.VITE_NEEDLE_USE_POSTPROCESSING === "false") {
-            if (debug) console.warn("Postprocessing is disabled via vite env setting");
-            else console.debug("Postprocessing is disabled via vite env setting");
+            if (debug) console.warn("POSTPROCESSING is disabled via vite env setting");
+            else console.debug("POSTPROCESSING is disabled via vite env setting");
             return Promise.resolve();
         }
         if (!NEEDLE_USE_POSTPROCESSING) {
-            if (debug) console.warn("Postprocessing is disabled via global vite define setting");
-            else console.debug("Postprocessing is disabled via vite define");
+            if (debug || isDevEnvironment()) console.warn("POSTPROCESSING is disabled via global vite define setting");
+            else console.debug("POSTPROCESSING is disabled via vite define");
             return Promise.resolve();
         }
 

package/src/engine-components/web/ScrollFollow.ts

@@ -1,5 +1,5 @@
-// For firefox ViewTimeline support
-import "scroll-timeline-polyfill/dist/scroll-timeline.js";
+// For firefox ViewTimeline support — dynamic import to avoid SSR crashes (polyfill accesses window at module level)
+if (typeof window !== "undefined") import("scroll-timeline-polyfill/dist/scroll-timeline.js");
 
 import { Box3, Object3D } from "three";
 

package/src/needle-engine.ts

@@ -1,3 +1,6 @@
+/// <reference path="../plugins/types/needle-bindings.d.ts" />
+/// <reference path="./engine/webcomponents/jsx.d.ts" />
+
 import { initEngine } from "./engine/engine_init.js";
 initEngine();
 import "./engine/webcomponents/needle-engine.js";

package/src/vite-env.d.ts

@@ -0,0 +1,16 @@
+// Vite global defines — see plugins/vite/defines.js
+// declare const entries here are picked up globally (ambient, no import/export).
+// Vite sets these as globals in dev and statically replaces them at build time.
+// Webpack DefinePlugin replaces them at build time too.
+// The globalThis fallbacks for vanilla JS are in engine_constants.ts.
+
+declare const NEEDLE_ENGINE_VERSION: string;
+declare const NEEDLE_ENGINE_GENERATOR: string;
+declare const NEEDLE_PROJECT_BUILD_TIME: string;
+declare const NEEDLE_PUBLIC_KEY: string;
+
+// #region treeshake flags
+// declare var (not const) so globalThis["NEEDLE_USE_*"] access is also type-safe
+declare var NEEDLE_USE_RAPIER: boolean;
+declare var NEEDLE_USE_POSTPROCESSING: boolean;
+// #endregion treeshake flags