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

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/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";