@navaramap/three 0.0.0

package/src/material/enhancer/polygon/polygonWaterEnhancer/material.test.ts

@@ -0,0 +1,48 @@
+import { MeshLambertMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { applyWaterMaterialConfig } from "./material";
+import { DEFAULT_WATER_STATE } from "./state";
+import type { PolygonWaterState } from "./types";
+
+describe("polygonWaterEnhancer/material", () => {
+  describe("applyWaterMaterialConfig", () => {
+    it("should trigger material.needsUpdate when water flag changes", () => {
+      const material = new MeshLambertMaterial();
+      const state: PolygonWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+      };
+
+      let needsUpdateCalled = false;
+      Object.defineProperty(material, "needsUpdate", {
+        set: (value: boolean) => {
+          if (value) needsUpdateCalled = true;
+        },
+        configurable: true,
+      });
+
+      applyWaterMaterialConfig(material, state, false, false);
+      expect(needsUpdateCalled).toBe(true);
+    });
+
+    it("should not trigger material.needsUpdate when water flag stays the same", () => {
+      const material = new MeshLambertMaterial();
+      const state: PolygonWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+      };
+
+      let needsUpdateCalled = false;
+      Object.defineProperty(material, "needsUpdate", {
+        set: (value: boolean) => {
+          if (value) needsUpdateCalled = true;
+        },
+        configurable: true,
+      });
+
+      applyWaterMaterialConfig(material, state, false, true);
+      expect(needsUpdateCalled).toBe(false);
+    });
+  });
+});

package/src/material/enhancer/polygon/polygonWaterEnhancer/material.ts

@@ -0,0 +1,35 @@
+import { AddOperation } from "three";
+
+import type { MaterialsFromShaders, ShaderName } from "../../MaterialEnhancer";
+
+import type { PolygonWaterState } from "./types";
+
+// Shaders this enhancer supports
+export const AVAILABLE_SHADERS = ["lambert"] satisfies ShaderName[];
+export type SupportedMaterial = MaterialsFromShaders<typeof AVAILABLE_SHADERS>;
+
+/**
+ * Apply water-related material configuration.
+ * Side effect function - mutates material directly.
+ */
+export const applyWaterMaterialConfig = (
+  material: SupportedMaterial,
+  state: PolygonWaterState,
+  isTexturized: boolean,
+  prevUseWater: boolean,
+): void => {
+  // Trigger shader recompilation if water flag changed
+  if (state.useWater !== prevUseWater) {
+    material.needsUpdate = true;
+  }
+
+  // Update envMap based on water state
+  if (!isTexturized && state.useWater) {
+    material.envMap = state.skyEnvMap;
+    if ("combine" in material) {
+      material.combine = AddOperation;
+    }
+  } else {
+    material.envMap = null;
+  }
+};

package/src/material/enhancer/polygon/polygonWaterEnhancer/mutates.ts

@@ -0,0 +1,61 @@
+import type { UniformValue } from "../../../types";
+
+import type { PolygonWaterRefs, WaterMutates } from "./types";
+
+/**
+ * Default refs with initial values.
+ * These are cloned in createWaterMutates and synced from state via update().
+ * Note: timeUniform is an external ref assigned via setter (identity doesn't change).
+ */
+const DEFAULT_WATER_REFS: Omit<PolygonWaterRefs, "timeUniform"> = {
+  uWaterNormalMap: { value: null },
+  uWaterScaleNormal: { value: 0 },
+  uWaterSpeed: { value: 0 },
+  uShininess: { value: 0 },
+  uSpecularStrength: { value: 0 },
+  uApplyWaterNormal: { value: 0 },
+  uSpecular: { value: false },
+  uIor: { value: 1.33333 },
+};
+
+/**
+ * Create mutation functions for the water enhancer.
+ * Refs are created internally and captured via closure.
+ */
+export const createWaterMutates = (): WaterMutates => {
+  // Clone defaults so each enhancer instance gets independent ref objects
+  // timeUniform is an external ref assigned via setter (identity doesn't change)
+  const refs: PolygonWaterRefs = structuredClone(DEFAULT_WATER_REFS);
+
+  return {
+    update: (state) => {
+      // Sync refs from state
+      refs.uWaterNormalMap.value = state.waterNormalMap;
+      refs.uWaterScaleNormal.value = state.waterScaleNormal;
+      refs.uWaterSpeed.value = state.waterSpeed;
+      refs.uShininess.value = state.shininess;
+      refs.uSpecularStrength.value = state.specularStrength;
+      refs.uApplyWaterNormal.value = state.applyWaterNormal ? 1 : 0;
+      refs.uSpecular.value = state.specular;
+      refs.uIor.value = state.ior;
+    },
+    updateUniforms: (uniforms) => {
+      // Assign water uniform refs to shader.uniforms
+      uniforms.uWaterNormalMap = refs.uWaterNormalMap;
+      uniforms.uWaterScaleNormal = refs.uWaterScaleNormal;
+      uniforms.uWaterSpeed = refs.uWaterSpeed;
+      uniforms.uShininess = refs.uShininess;
+      uniforms.uSpecularStrength = refs.uSpecularStrength;
+      uniforms.uApplyWaterNormal = refs.uApplyWaterNormal;
+      uniforms.uSpecular = refs.uSpecular;
+      uniforms.uIor = refs.uIor;
+      if (refs.uTime) {
+        uniforms.uTime = refs.uTime;
+      }
+    },
+    setTimeUniform: (timeUniform: UniformValue<number>): void => {
+      // Assign external ref object (identity doesn't change after mount)
+      refs.uTime = timeUniform;
+    },
+  };
+};

package/src/material/enhancer/polygon/polygonWaterEnhancer/shader.test.ts

@@ -0,0 +1,34 @@
+import { testShaderCompatibility } from "../../test-utils/shaderCompatibility";
+import {
+  POLYGON_BASE_SHADER_MARKERS,
+  createPolygonBaseEnhancer,
+} from "../polygonBaseEnhancer";
+
+import { createPolygonWaterEnhancer, type SupportedMaterial } from ".";
+
+testShaderCompatibility(
+  "polygonWaterEnhancer",
+  (material) =>
+    createPolygonWaterEnhancer(
+      createPolygonBaseEnhancer(material as SupportedMaterial),
+    ),
+  [
+    {
+      name: "With water",
+      props: {
+        water: {
+          water: true,
+        },
+      },
+    },
+    {
+      name: "Without water",
+      props: {
+        water: {
+          water: false,
+        },
+      },
+    },
+  ],
+  POLYGON_BASE_SHADER_MARKERS,
+);

package/src/material/enhancer/polygon/polygonWaterEnhancer/shader.ts

@@ -0,0 +1,96 @@
+import WaterParsFragment from "@shaders/glsl/chunks/water_pars_fragment.glsl?raw";
+import type { WebGLProgramParametersWithUniforms } from "three";
+
+import {
+  POLYGON_BASE_SHADER_MARKERS,
+  createPolygonBaseShaderReplacer,
+} from "../polygonBaseEnhancer/markers";
+
+import type { PolygonWaterState, WaterMutates } from "./types";
+
+/**
+ * Transform shader with water-specific modifications.
+ * Uniform assignment is handled by mutates.updateUniforms().
+ */
+export const transformWaterShader = (
+  shader: WebGLProgramParametersWithUniforms,
+  state: PolygonWaterState,
+  mutates: WaterMutates,
+): void => {
+  const { useWater } = state;
+
+  // Derive shader defines from semantic state flags
+  shader.defines ??= {};
+  if (useWater) {
+    shader.defines.WATER = 1;
+    shader.defines.USE_UV = 1;
+  } else {
+    delete shader.defines.WATER;
+  }
+
+  // Assign water uniform refs to shader.uniforms via mutates
+  mutates.updateUniforms(shader.uniforms, state);
+
+  // Insert WaterParsFragment before the computeSpecular function (non-marker-based)
+  const computeSpecularMarker = "vec3 computeSpecular(";
+  const specularIdx = shader.fragmentShader.indexOf(computeSpecularMarker);
+  if (specularIdx !== -1) {
+    const beforeSpecular = shader.fragmentShader.substring(0, specularIdx);
+    const afterSpecular = shader.fragmentShader.substring(specularIdx);
+    shader.fragmentShader =
+      beforeSpecular + WaterParsFragment + "\n\n" + afterSpecular;
+  }
+
+  shader.fragmentShader = createPolygonBaseShaderReplacer(shader.fragmentShader)
+    // Add water uniform declarations after base's UNIFORM_END
+    .insertAfter(
+      POLYGON_BASE_SHADER_MARKERS.fragment.UNIFORM_END,
+      `uniform sampler2D uWaterNormalMap;
+uniform float uWaterScaleNormal;
+uniform float uWaterSpeed;
+uniform float uShininess;
+uniform float uSpecularStrength;
+uniform float uApplyWaterNormal;
+uniform bool uSpecular;
+uniform float uIor;
+uniform float uTime;`,
+    )
+    // Insert specular computation after base's NORMAL_END
+    .insertAfter(
+      POLYGON_BASE_SHADER_MARKERS.fragment.NORMAL_END,
+      useWater
+        ? `
+if(!uIsTexturized) {
+  specular = computeWaterSpecular(
+    uWaterNormalMap,
+    (vPosition.xy + vPosition.zy + vPosition.xz) / 3.0 * uWaterScaleNormal,
+    uTime * uWaterSpeed,
+    vViewPosition,
+    normalMatrix,
+    origNormal,
+    uShininess,
+    uSpecularStrength,
+    diffuseColor.rgb,
+    normal
+  );
+}`
+        : `
+if(uSpecular && !uIsTexturized) {
+  specular = computeSpecular(
+    vViewPosition,
+    origNormal,
+    uShininess,
+    uSpecularStrength,
+    uIor
+  );
+}`,
+    )
+    // Replace final normal block with water version
+    .replaceBlock(
+      {
+        start: POLYGON_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_START,
+        end: POLYGON_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_END,
+      },
+      `vec3 finalNormal = mix(origNormal, normalize(origNormal * 0.7 + normal), uApplyWaterNormal);`,
+    ).source;
+};

package/src/material/enhancer/polygon/polygonWaterEnhancer/state.test.ts

@@ -0,0 +1,98 @@
+import { Texture } from "three";
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_WATER_STATE, updateWaterState } from "./state";
+import type { PolygonWaterState } from "./types";
+
+/**
+ * Helper to create expected water state by merging with defaults.
+ */
+const createExpectedState = (
+  overrides: Partial<PolygonWaterState> = {},
+): PolygonWaterState => ({
+  ...DEFAULT_WATER_STATE,
+  ...overrides,
+});
+
+describe("polygonWaterEnhancer/state", () => {
+  describe("updateWaterState", () => {
+    it("returns default state when given empty props", () => {
+      const result = updateWaterState({}, DEFAULT_WATER_STATE);
+      expect(result).toEqual(createExpectedState());
+    });
+
+    it("applies all props", () => {
+      const mockTexture = new Texture();
+      const mockSkyEnvMap = new Texture();
+
+      const result = updateWaterState(
+        {
+          water: true,
+          waterNormalMap: mockTexture,
+          waterScaleNormal: 0.5,
+          waterSpeed: 1.0,
+          shininess: 30,
+          specularStrength: 0.8,
+          applyWaterNormal: true,
+          specular: true,
+          ior: 1.5,
+          skyEnvMap: mockSkyEnvMap,
+        },
+        DEFAULT_WATER_STATE,
+      );
+
+      expect(result).toEqual(
+        createExpectedState({
+          useWater: true,
+          waterNormalMap: mockTexture,
+          waterScaleNormal: 0.5,
+          waterSpeed: 1.0,
+          shininess: 30,
+          specularStrength: 0.8,
+          applyWaterNormal: true,
+          specular: true,
+          ior: 1.5,
+          skyEnvMap: mockSkyEnvMap,
+        }),
+      );
+    });
+
+    it("falls back to currentState for missing props", () => {
+      const currentState: PolygonWaterState = {
+        ...DEFAULT_WATER_STATE,
+        useWater: true,
+        waterScaleNormal: 0.3,
+        shininess: 25,
+      };
+
+      const result = updateWaterState({ waterSpeed: 5.0 }, currentState);
+
+      expect(result.useWater).toBe(true);
+      expect(result.waterScaleNormal).toBe(0.3);
+      expect(result.shininess).toBe(25);
+      expect(result.waterSpeed).toBe(5.0);
+    });
+
+    it("preserves waterNormalMap when not provided in props", () => {
+      const mockTexture = new Texture();
+      const currentState: PolygonWaterState = {
+        ...DEFAULT_WATER_STATE,
+        waterNormalMap: mockTexture,
+      };
+
+      const result = updateWaterState({ waterSpeed: 2.0 }, currentState);
+      expect(result.waterNormalMap).toBe(mockTexture);
+    });
+
+    it("sets waterNormalMap to null when explicitly set to null", () => {
+      const mockTexture = new Texture();
+      const currentState: PolygonWaterState = {
+        ...DEFAULT_WATER_STATE,
+        waterNormalMap: mockTexture,
+      };
+
+      const result = updateWaterState({ waterNormalMap: null }, currentState);
+      expect(result.waterNormalMap).toBeNull();
+    });
+  });
+});

package/src/material/enhancer/polygon/polygonWaterEnhancer/state.ts

@@ -0,0 +1,57 @@
+import type { PolygonWaterState, WaterOnlyProps } from "./types";
+
+export const DEFAULT_WATER_PROPS: Required<WaterOnlyProps> = {
+  water: false,
+  waterScaleNormal: 0,
+  waterSpeed: 0,
+  shininess: 0,
+  specularStrength: 0,
+  applyWaterNormal: false,
+  specular: false,
+  ior: 1.33333,
+  skyEnvMap: null,
+  waterNormalMap: null,
+  timeUniform: { value: 0 },
+};
+
+/** Default state derived from DEFAULT_WATER_PROPS */
+export const DEFAULT_WATER_STATE: PolygonWaterState = {
+  useWater: DEFAULT_WATER_PROPS.water,
+  skyEnvMap: DEFAULT_WATER_PROPS.skyEnvMap,
+  waterNormalMap: DEFAULT_WATER_PROPS.waterNormalMap,
+  waterScaleNormal: DEFAULT_WATER_PROPS.waterScaleNormal,
+  waterSpeed: DEFAULT_WATER_PROPS.waterSpeed,
+  shininess: DEFAULT_WATER_PROPS.shininess,
+  specularStrength: DEFAULT_WATER_PROPS.specularStrength,
+  applyWaterNormal: DEFAULT_WATER_PROPS.applyWaterNormal,
+  specular: DEFAULT_WATER_PROPS.specular,
+  ior: DEFAULT_WATER_PROPS.ior,
+};
+
+/**
+ * Update immutable state from props.
+ * Props override currentState values; missing props fall back to currentState.
+ * Pass DEFAULT_WATER_STATE as currentState for initial mount.
+ *
+ * @param props - The props to apply
+ * @param currentState - The current state to use as fallback (use DEFAULT_WATER_STATE for mount)
+ */
+export const updateWaterState = (
+  props: WaterOnlyProps,
+  currentState: PolygonWaterState,
+): PolygonWaterState => ({
+  useWater: props.water ?? currentState.useWater,
+  skyEnvMap: props.skyEnvMap ?? currentState.skyEnvMap,
+  // Only update waterNormalMap when explicitly provided (not undefined)
+  waterNormalMap:
+    props.waterNormalMap !== undefined
+      ? props.waterNormalMap
+      : currentState.waterNormalMap,
+  waterScaleNormal: props.waterScaleNormal ?? currentState.waterScaleNormal,
+  waterSpeed: props.waterSpeed ?? currentState.waterSpeed,
+  shininess: props.shininess ?? currentState.shininess,
+  specularStrength: props.specularStrength ?? currentState.specularStrength,
+  applyWaterNormal: props.applyWaterNormal ?? currentState.applyWaterNormal,
+  specular: props.specular ?? currentState.specular,
+  ior: props.ior ?? currentState.ior,
+});

package/src/material/enhancer/polygon/polygonWaterEnhancer/types.ts

@@ -0,0 +1,115 @@
+import type { Texture } from "three";
+
+import type { UniformValue } from "../../../types";
+import type { Mutates } from "../../MaterialEnhancer";
+import type {
+  PolygonBaseMutates,
+  PolygonBaseProps,
+  PolygonBaseState,
+} from "../polygonBaseEnhancer";
+
+/**
+ * Water-only props (excluding base props).
+ */
+export type WaterOnlyProps = {
+  water?: boolean;
+  waterScaleNormal?: number;
+  waterSpeed?: number;
+  shininess?: number;
+  specularStrength?: number;
+  applyWaterNormal?: boolean;
+  specular?: boolean;
+  ior?: number;
+  skyEnvMap?: Texture | null;
+
+  // Water normal map texture (value-based, not ref-based)
+  // This is set dynamically and may change identity, so we mutate the internal ref's value
+  waterNormalMap?: Texture | null;
+
+  // External uniform ref (ref-based, shared with CommonUniforms)
+  // This ref identity doesn't change, so we assign the ref object itself
+  timeUniform?: UniformValue<number>;
+};
+
+/**
+ * Combined props for the polygon water enhancer.
+ * Props are explicitly separated into base and water sections for clarity.
+ */
+export type PolygonWaterProps = {
+  base?: PolygonBaseProps;
+  water?: WaterOnlyProps;
+};
+
+/**
+ * Immutable state for the water enhancer.
+ * This state is always replaced as a whole (never mutated).
+ * Returned directly via states() - refresh after updates.
+ */
+export type PolygonWaterState = Readonly<{
+  useWater: boolean;
+  skyEnvMap: Texture | null;
+  waterNormalMap: Texture | null;
+  waterScaleNormal: number;
+  waterSpeed: number;
+  shininess: number;
+  specularStrength: number;
+  applyWaterNormal: boolean;
+  specular: boolean;
+  ior: number;
+}>;
+
+/**
+ * Combined state for the polygon water enhancer.
+ * Includes both base state and water-specific state.
+ */
+export type PolygonWaterCombinedStates = {
+  readonly base: PolygonBaseState;
+  readonly water: PolygonWaterState;
+};
+
+/**
+ * Combined mutation functions for the polygon water enhancer.
+ */
+export type PolygonWaterCombinedMutates = {
+  readonly base: PolygonBaseMutates;
+  readonly water: WaterMutates;
+};
+
+/**
+ * Mutable references (uniforms) for the water enhancer.
+ *
+ * These are shared references with shader.uniforms and can be mutated directly
+ * for efficient GPU uniform updates without shader recompilation.
+ * Internal type - not exposed externally.
+ */
+export type PolygonWaterRefs = {
+  // Internal refs (value-based updates)
+  uWaterNormalMap: UniformValue<Texture | null>;
+  uWaterScaleNormal: UniformValue<number>;
+  uWaterSpeed: UniformValue<number>;
+  uShininess: UniformValue<number>;
+  uSpecularStrength: UniformValue<number>;
+  uApplyWaterNormal: UniformValue<number>;
+  uSpecular: UniformValue<boolean>;
+  uIor: UniformValue<number>;
+
+  // External uniform ref (assigned as ref object, identity doesn't change)
+  uTime?: UniformValue<number>;
+};
+
+export type PolygonWaterUniforms = Partial<PolygonWaterRefs>;
+
+/**
+ * Mutation functions for the water enhancer (internal only).
+ */
+export type WaterMutates = Mutates<
+  PolygonWaterState,
+  PolygonWaterUniforms,
+  {
+    /**
+     * Set the time uniform ref.
+     * Assigns the external ref object (identity doesn't change after mount).
+     */
+    setTimeUniform: (timeUniform: UniformValue<number>) => void;
+  }
+>;

package/src/material/enhancer/polyline/index.ts

@@ -0,0 +1,7 @@
+export { createPolylineMaterialEnhancer } from "./polylineMaterialEnhancer";
+export type { PolylineMaterialProps } from "./polylineMaterialEnhancer";
+export type {
+  PolylineBaseMutates,
+  PolylineBaseProps,
+  PolylineBaseState,
+} from "./polylineMaterialEnhancer";