@forgeax/engine-render 0.1.25 → 0.1.26

package/dist/construct-renderer.mjs

@@ -1,12 +1,12 @@
 import { inspectVolumetricFog, inspectLodOcclusion, resolveSsrAdmissionGeneration, projectSsrDependencies, inspectReflectionFallback, admitReflectionProbe, DEFAULT_REFLECTION_PROBE_LIMITS, buildReflectionProbeTable, advanceProbeFilter, buildCubeCameraFaceViews, commitProbeFilterStep, resolveReflectionFallbackSource, deriveReflectionFallbackProjection, reflectionFallbackCoverage, reflectionFallbackSourceKey, reflectionFallbackProjectionSignature, createProbeFilterState, ReflectionProbeProjection, admitPointsLines, inspectPointShadow } from './chunk-KM2NOX2I.mjs';
-import { createExtendedLightingState, promoteExtendedLightingCandidate, OcclusionRenderRuntime, extractFrames, viewKey, primitiveKey, glyphTextLayoutSystem, projectExtendedLightingInspection, viewKeyId, primitiveKeyId, ProbeBlendSceneProjection, SKYLIGHT_RECOVERY_FALLBACK, InstanceBoundsCache, fingerprintNumericArray, createCookieProjectionMatrixData } from './chunk-N3RT2EUR.mjs';
+import { createExtendedLightingState, promoteExtendedLightingCandidate, OcclusionRenderRuntime, extractFrames, viewKey, primitiveKey, glyphTextLayoutSystem, projectExtendedLightingInspection, viewKeyId, primitiveKeyId, ProbeBlendSceneProjection, SKYLIGHT_RECOVERY_FALLBACK, InstanceBoundsCache, fingerprintNumericArray, createCookieProjectionMatrixData } from './chunk-YUQXSEHG.mjs';
 import './chunk-FJ6P52EE.mjs';
 import { MeshFilter, MeshRenderer, Instances, Layer, Visibility, Points, Lines, SortKey, Camera, MotionBlur, DirectionalLight, LightProbe, PointLight, PointLightShadow, SpotLight, Skylight, SkyboxBackground, PostProcessParams, ReflectionProbe, VolumetricFog, projectMeshMaterialBindingObservation, createVisibilityBudget, hasVolumetricFogCapability, CUBE_CAMERA_FACE_ORDER, CAMERA_PROJECTION_ORTHOGRAPHIC } from './chunk-ADHHVYLW.mjs';
 import { SpriteInstances, SpriteRegionOverride, TileLayer, decodeSortScope, Tilemap } from './chunk-JDWARUOI.mjs';
-import { assertStorageBufferCap, GpuBuffer, GpuTexture, deriveRenderDataTexture, deriveRenderDataMesh, deriveRenderDataCubemap, createIblPipelines, CUBEMAP_FACE_VERTICES, runIblPrecompute, InstanceProjectionStore, createClusterBinScratch, resetHdrpBuffers, retireTemporalGpuState, PostProcessError, entryHasDepthRead, DEPTH_MIN_PARAMS_BYTE_SIZE, postProcessShaderModuleLabel, resolveSsaoParameters, buildPerFrameBindGroups, postProcessShaderEntrySignature, PipelineSpecError, CAPTURE_VIEW_PROJS, PREFILTER_MIP_LEVELS, selectSwapChainFormat, setIblComposedShaders, POINTS_LINES_MATERIAL_SHADER_ID, createHdrpClusterMembershipBindGroupLayoutDescriptor, createSkylightFallback, buildSpecConstTable, buildLinearLdrMaterialSpecTable, getOrBuildPipeline, cacheKeyOf, REFLECTION_PROBE_VIEW_SLOT_BASE, VIEW_UNIFORM_SLOT_STRIDE, getOrCreateIblCache, postProcessShaderPipelineLabel, createPointsLinesLaneAdapter, computeViewMatrix, computeProjectionMatrix, prepareFrameLighting, warnMultiSkylight, warnMultiSkybox, selectLazyEquirectHandle, driveLazyEquirectProjection, warnZeroLightStandard, writeShadowParamsBuffer, writeSpotModifierTextures, writeHdrpClusterAndSsaoBuffers, resolveSkyboxActive, computeSplitLdrSprite, writeViewUbo, writePointsLinesViewUbo, writeShadowCasterUniforms, uploadMeshSsboBatch, passKindPolicyTable, colorFormatsForPassKind, configureSurface, VIEW_UNIFORM_BUFFER_SIZE, POINTS_LINES_VIEW_BUFFER_SIZE, SHADOW_CASTER_BUFFER_SIZE, FALLBACK_BYTES_PER_ROW, PREFILTER_SIZE, geometryRenderStateForTopology, assembleMaterialWithSkylightEntries, MESH_SSBO_BYTES, createPointsLinesLaneContract, foldDispatchBuckets, CUBE_CAPTURE_VIEW_SLOT_BASE, variantSetFromDefines, cleanPerEntityCache, ensureMeshSsboCapacity, buildFoldDispatchPlan, evaluateFoldBucketUniformCap, incrementFoldedDrawsMetric, resolveGeometryInstanceBuffer, buildFullscreenPostProcessPass, getTemporalGpuState, getTemporalParamsBuffer, getTemporalBindGroupResources, resolveSurfaceFormatPair, resolveSurfaceProfile, encodeMainPass, abortTemporalGpuSubmit, commitTemporalGpuSubmit, retireTemporalGpuStateAfterFence, hasPendingTemporalGpuSubmit, importRenderPipelineSurface, DEFERRED_COLOR_FORMATS, aggregateTemporalDemand, standardTemporalLaneAdmission, addTypedScenePass, addTypedSsaoPasses, typedFrameClearColor, addTypedSkyboxPass, createStandardSceneDataTarget, addStandardSceneDataPass, addTypedFrameObservationPass, temporalReadIndex, temporalWriteIndex, addReflectionFallbackObservationPass, BYTES_PER_DIRECT_LIGHT_SLOT, createRenderPipelineTarget, resolveOutputDither, addTypedTemporalResolvePass, addTypedBloomPasses, addTypedOutputTransformPass, addTypedFullscreenPass, addTypedCompositePostEffects, standardTopologyVariantSet, geometryRenderStateForPass, standardStorageVariantSet, getOrCreateHdrpBuffers, encodeDirectionalShadowPass, encodePointShadowPass, encodeSpotShadowPass, VIEW_UNIFORM_BYTES, variantSetFromVertexLayoutProjection, MATERIAL_PER_ENTITY_STRIDE, isTemporalFullscreenBinding, createFullscreenBindGroup, applyParamSnapshotToUbo, residentTextureView, TYPED_BLOOM_PASS_NAMES } from './chunk-TCLDX7SZ.mjs';
+import { assertStorageBufferCap, GpuBuffer, GpuTexture, deriveRenderDataTexture, deriveRenderDataMesh, deriveRenderDataCubemap, createIblPipelines, CUBEMAP_FACE_VERTICES, runIblPrecompute, InstanceProjectionStore, createClusterBinScratch, resetHdrpBuffers, retireTemporalGpuState, PostProcessError, entryHasDepthRead, DEPTH_MIN_PARAMS_BYTE_SIZE, postProcessShaderModuleLabel, resolveSsaoParameters, buildPerFrameBindGroups, postProcessShaderEntrySignature, PipelineSpecError, CAPTURE_VIEW_PROJS, PREFILTER_MIP_LEVELS, selectSwapChainFormat, setIblComposedShaders, POINTS_LINES_MATERIAL_SHADER_ID, createHdrpClusterMembershipBindGroupLayoutDescriptor, createSkylightFallback, buildSpecConstTable, buildLinearLdrMaterialSpecTable, getOrBuildPipeline, cacheKeyOf, REFLECTION_PROBE_VIEW_SLOT_BASE, VIEW_UNIFORM_SLOT_STRIDE, getOrCreateIblCache, postProcessShaderPipelineLabel, createPointsLinesLaneAdapter, computeViewMatrix, computeProjectionMatrix, prepareFrameLighting, warnMultiSkylight, warnMultiSkybox, selectLazyEquirectHandle, driveLazyEquirectProjection, warnZeroLightStandard, writeShadowParamsBuffer, writeSpotModifierTextures, writeHdrpClusterAndSsaoBuffers, resolveSkyboxActive, computeSplitLdrSprite, writeViewUbo, writePointsLinesViewUbo, writeShadowCasterUniforms, uploadMeshSsboBatch, passKindPolicyTable, colorFormatsForPassKind, configureSurface, VIEW_UNIFORM_BUFFER_SIZE, POINTS_LINES_VIEW_BUFFER_SIZE, SHADOW_CASTER_BUFFER_SIZE, FALLBACK_BYTES_PER_ROW, PREFILTER_SIZE, geometryRenderStateForTopology, assembleMaterialWithSkylightEntries, MESH_SSBO_BYTES, createPointsLinesLaneContract, foldDispatchBuckets, CUBE_CAPTURE_VIEW_SLOT_BASE, variantSetFromDefines, cleanPerEntityCache, ensureMeshSsboCapacity, buildFoldDispatchPlan, evaluateFoldBucketUniformCap, incrementFoldedDrawsMetric, writePbrMaterialUboPayload, applyParamSnapshotToUbo, applyMaterialTextureUvScales, residentTextureView, MATERIAL_PER_ENTITY_STRIDE, detectNineSliceScaleTooSmall, resolveGeometryInstanceBuffer, buildFullscreenPostProcessPass, getTemporalGpuState, getTemporalParamsBuffer, getTemporalBindGroupResources, resolveSurfaceFormatPair, resolveSurfaceProfile, encodeMainPass, STANDARD_PBR_UBO_SIZE, abortTemporalGpuSubmit, commitTemporalGpuSubmit, retireTemporalGpuStateAfterFence, hasPendingTemporalGpuSubmit, importRenderPipelineSurface, DEFERRED_COLOR_FORMATS, aggregateTemporalDemand, standardTemporalLaneAdmission, addTypedScenePass, addTypedSsaoPasses, typedFrameClearColor, addTypedSkyboxPass, createStandardSceneDataTarget, addStandardSceneDataPass, addTypedFrameObservationPass, temporalReadIndex, temporalWriteIndex, addReflectionFallbackObservationPass, BYTES_PER_DIRECT_LIGHT_SLOT, createRenderPipelineTarget, resolveOutputDither, addTypedTemporalResolvePass, addTypedBloomPasses, addTypedOutputTransformPass, addTypedFullscreenPass, addTypedCompositePostEffects, standardTopologyVariantSet, geometryRenderStateForPass, standardStorageVariantSet, getOrCreateHdrpBuffers, encodeDirectionalShadowPass, encodePointShadowPass, encodeSpotShadowPass, VIEW_UNIFORM_BYTES, variantSetFromVertexLayoutProjection, isTemporalFullscreenBinding, createFullscreenBindGroup, TYPED_BLOOM_PASS_NAMES } from './chunk-TMIASV2N.mjs';
 import { getTransparentSortConfig, TRANSPARENT_SORT_MODE_DISTANCE, TRANSPARENT_SORT_MODE_LAYER_Z, TRANSPARENT_SORT_MODE_LAYER_Y, TRANSPARENT_SORT_MODE_LAYER_YZ } from './chunk-RXZ3RGOU.mjs';
 import { DEFAULT_STANDARD_PROFILE, DEFAULT_CLUSTER_GRID, createSceneDataCatalog, STANDARD_PIPELINE_ID, STANDARD_LIGHT_COUNTS, STANDARD_POST_STAGE_NAMES, resolveVolumetricFogProfile, isSceneDataTarget } from './chunk-E34VL5VI.mjs';
-import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './chunk-JSEDTZYS.mjs';
+import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './chunk-GF523LHF.mjs';
 import { DeviceScope, SKIN_MATERIAL_SHADER_ID, EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES, GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ, resolveRenderTargetMaterialSource, createRenderTargetMaterialSource, deriveExtendedLightingCapability, GPU_BUFFER_USAGE_VERTEX, GPU_BUFFER_USAGE_INDEX, EXTENDED_LIGHTING_TOPOLOGY, GPU_BUFFER_USAGE_UNIFORM, getTextureIdentity, worldEntityKey, createHdrpBindGroupLayoutDescriptor, createHdrpSkinBindGroupLayoutDescriptor, IES_SLICE_WIDTH, IES_SLICE_HEIGHT, COOKIE_SLICE_SIZE, COOKIE_MATRIX_BYTES, makeZeroCameraFallbackSnapshot, GPU_BUFFER_USAGE_QUERY_RESOLVE, GPU_BUFFER_USAGE_COPY_SRC, buildPbrPipelineLayouts, buildPbrSkinLayouts, GPU_BUFFER_USAGE_STORAGE, resolvePipelineGroup2Contract, GPU_SHADER_STAGE_FRAGMENT, instanceCollectionCacheKey, validateGraphTargetCaptureReadback, isCanonicalStandardPbrMaterialShader, isStandardPbrMaterialShader, buildBindGroupLayoutDescriptor, GPU_BUFFER_USAGE_INDIRECT, buildPbrMaterialUserRegionEntries, extendedLightingSampledTextureCapacityAvailable, GPU_SHADER_STAGE_VERTEX, SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET, shadowCasterVariantSet, SHADOW_CASTER_SHADER_ID, LifecycleTransaction } from './chunk-HKXTW355.mjs';
 import { RendererContractFailureError, RendererOperationError, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, RenderTargetStateInvalidError, RenderTargetOperationFailedError, RenderTargetCapabilityMissingError, RenderTargetDescriptorInvalidError, GPU_TEXTURE_USAGE_TEXTURE_BINDING, GPU_TEXTURE_USAGE_COPY_DST, RENDER_PHASE_CATALOG, FrameReceiptStaleError, RenderFeatureStageFailedError, RenderFeatureCapabilityMissingError, RenderFeatureRegistrationConflictError, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING, GPU_TEXTURE_USAGE_COPY_SRC, EnvironmentGenerationFailedError, PointsLinesMaterialUnsupportedError, StandardProfileInvalidError, TransmissionCapabilityMissingError, SHADOW_ATLAS_DEFAULT_LAYERS, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT, TemporalFrameSubmitError, ObservationUnavailableError, RenderFeaturePreparationFailedError, PointsLinesPrepareFailedError, SHADOW_ATLAS_DEFAULT_FACE_SIZE, SceneDataUnavailableError, RenderFeatureDrawRecordingFailedError, PointShadowAtlasUninitializedError, SkinPaletteOverflowError, RenderFeaturePreparedStateMismatchError, FXAA_POST_PROCESS_ID } from './chunk-ZZ4YQ474.mjs';
 import { ok, err, RhiError, validateDrawArgs } from '@forgeax/engine-rhi';
@@ -5904,7 +5904,7 @@ function pipelineCreationHint(error) {
 }
 function buildPipelineForMaterialShader(id, entry, ctx, renderState, geometry, vertexEntry, fragmentEntry, defines, passKind = "forward", sampleCount = 1) {
   const label = ctx.label ?? `pbr-pipeline-${id}`;
-  const vsEntry = (passKind === "temporal" ? "vs_temporal" : "vs_main");
+  const vsEntry = vertexEntry ?? (passKind === "temporal" ? "vs_temporal" : "vs_main");
   const fsEntry = fragmentEntry ?? (passKind === "temporal" ? "fs_temporal" : passKind === "deferred" ? "fs_gbuffer" : passKind === "shadow-caster" ? "fs_shadow" : "fs_main");
   let source = entry.source;
   const moduleResult = ctx.shaderModuleFactory.createShaderModule({
@@ -11746,6 +11746,118 @@ function inspectStandardLighting(input) {
   }
   return inspectStandardClusterTransport(input.transport, input.prepared);
 }
+function uploadMaterialUniforms(c) {
+  const {
+    runtime,
+    world,
+    store,
+    pipelineState,
+    validatedOrdered,
+    frameState,
+    materialSlots,
+    materialSlotOwners,
+    materialSlotCount
+  } = c;
+  if (materialSlotCount === 0) return;
+  const cachedMaterialUboPayload = c.materialUboPayloadCache;
+  let materialUboPayload;
+  if (cachedMaterialUboPayload?.materialSlots === materialSlots && cachedMaterialUboPayload.materialSlotCount === materialSlotCount) {
+    materialUboPayload = cachedMaterialUboPayload.payload;
+  } else {
+    materialUboPayload = new Uint8Array(materialSlotCount * MATERIAL_PER_ENTITY_STRIDE);
+    const slotPayload = new Uint8Array(STANDARD_PBR_UBO_SIZE);
+    const slotPayloadF32 = new Float32Array(
+      slotPayload.buffer,
+      slotPayload.byteOffset,
+      slotPayload.byteLength / 4
+    );
+    for (let materialSlot = 0; materialSlot < materialSlots.length; materialSlot += 1) {
+      const mat = materialSlots[materialSlot];
+      const entry = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
+      if (mat === void 0 || entry === void 0) continue;
+      writePbrMaterialUboPayload(slotPayloadF32, mat);
+      const materialShaderId = mat.materialShaderId;
+      const schema = mat.materialParamSchema ?? (materialShaderId !== void 0 ? runtime.getParamSchema?.(materialShaderId) : void 0);
+      applyParamSnapshotToUbo(slotPayloadF32, schema, mat.paramSnapshot);
+      const processValue = globalThis.process;
+      if (processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === "1" && (materialShaderId === "forgeax::default-standard-pbr" || materialShaderId === "forgeax::pbr-skin")) {
+        console.error(
+          `[render-material] UBO receipt: ${JSON.stringify({
+            entityIndex: entry.renderableIndex,
+            materialHandle: mat.materialHandle,
+            materialShaderId,
+            clearcoat: slotPayloadF32[32],
+            clearcoatRoughness: slotPayloadF32[33],
+            clearcoatNormalScale: slotPayloadF32[34],
+            paramSnapshot: mat.paramSnapshot
+          })}`
+        );
+      }
+      applyMaterialTextureUvScales(slotPayloadF32, mat, world);
+      {
+        const matHandleRaw = mat.baseColorTexture;
+        if (matHandleRaw !== void 0) {
+          const view = residentTextureView(entry.world ?? world, store, runtime, matHandleRaw);
+          if (view === void 0) {
+            const rawId = matHandleRaw;
+            if (!frameState.warnedMissingBaseColorTextureHandles.has(rawId)) {
+              frameState.warnedMissingBaseColorTextureHandles.add(rawId);
+              console.warn(
+                `[forgeax] baseColor texture ${rawId} missing GPU view, rendering debug pink (shader=${materialShaderId ?? "<none>"} entityIndex=${entry.renderableIndex})`
+              );
+            }
+            runtime.errorRegistry.fire(
+              new RhiError({
+                code: "asset-not-registered",
+                expected: "material baseColor TextureAsset uploaded to GPU",
+                hint: "register + uploadTexture the baseColor texture before draw([world], { cameraOwner: 0, resourceOwner: 0 }); rendering falls back to debug pink until then",
+                detail: { assetHandle: rawId }
+              })
+            );
+            slotPayloadF32[0] = 1;
+            slotPayloadF32[1] = 0.4;
+            slotPayloadF32[2] = 0.7;
+          }
+        }
+      }
+      materialUboPayload.set(slotPayload, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
+    }
+    for (const entry of validatedOrdered) {
+      const mat = entry.source.material;
+      const materialShaderId = mat.materialShaderId;
+      if (materialShaderId !== "forgeax::sprite" && materialShaderId !== "forgeax::sprite-lit")
+        continue;
+      const slicesAndMode = mat.paramSnapshot?.slicesAndMode;
+      if (slicesAndMode === void 0 || slicesAndMode.length < 4) continue;
+      const slicesArr = [
+        slicesAndMode[0] ?? 0,
+        slicesAndMode[1] ?? 0,
+        slicesAndMode[2] ?? 0,
+        slicesAndMode[3] ?? 0
+      ];
+      if (slicesArr[0] === 0 && slicesArr[1] === 0 && slicesArr[2] === 0 && slicesArr[3] === 0)
+        continue;
+      detectNineSliceScaleTooSmall(
+        entry.source.transform.world,
+        slicesArr,
+        entry.renderableIndex,
+        frameState.warnedNineSliceScaleEntities,
+        runtime.metrics
+      );
+    }
+    c.materialUboPayloadCache = {
+      materialSlots,
+      materialSlotCount,
+      payload: materialUboPayload
+    };
+  }
+  const materialUboUpload = runtime.device.queue.writeBuffer(
+    pipelineState.materialUniformBuffer.buffer,
+    0,
+    materialUboPayload
+  );
+  if (!materialUboUpload.ok) throw materialUboUpload.error;
+}
 
 // src/volume/temporal.ts
 function resolveVolumeTemporalReset(previous, next, options = {}) {
@@ -14934,7 +15046,11 @@ function recordFrame(internals, world, cameras, lights, renderables, transparent
     const materialSlots = dispatchPlan.materialSlots;
     const materialSlotOwners = dispatchPlan.materialSlotOwners;
     const materialSlotCount = dispatchPlan.materialSlotCount;
-    const splitLdrSprite = computeSplitLdrSprite(validatedOrdered, tonemapActive);
+    const splitLdrSprite = computeSplitLdrSprite(
+      validatedOrdered,
+      tonemapActive,
+      transparentDispatch
+    );
     let ldrSpritePassView = null;
     if (splitLdrSprite) {
       const unormViewRes = internals.device.createTextureView(currentTexture, {});
@@ -15110,6 +15226,7 @@ function recordFrame(internals, world, cameras, lights, renderables, transparent
       directionalShadowCacheReuse: directionalShadowCache.reuse,
       ...profilePhase !== void 0 ? { profilePhase } : {}
     };
+    uploadMaterialUniforms(passCtx);
     const fallbackReadbackRequest = createReflectionFallbackReadbackRequest(internals, frameState);
     if (fallbackReadbackRequest !== void 0) {
       frameState.reflectionFallbackReadback = fallbackReadbackRequest;
@@ -16685,7 +16802,11 @@ function createRenderSystemRecovery(deps) {
         validated: candidateValidated,
         dispatch: seed.frame.dispatch,
         shadowCastersActive: seed.frame.lights.pointShadow.length > 0 || seed.frame.lights.spot.some((spot) => spot.castShadow === true) || (seed.frame.lights.lightViewProj?.length ?? 0) > 0,
-        splitLdrSprite: computeSplitLdrSprite(candidateValidated, camera.tonemap !== "none"),
+        splitLdrSprite: computeSplitLdrSprite(
+          candidateValidated,
+          camera.tonemap !== "none",
+          seed.frame.dispatch
+        ),
         reflectionFallbackAvailable: candidateFrameState.reflectionFallbackDemand === true
       });
       const candidatePostProcessIds = /* @__PURE__ */ new Set([
@@ -23039,6 +23160,18 @@ function createRenderSystem(internals) {
               internals.getPipelineState(),
               persistentRenderScene.materialSnapshotCacheStore(),
               {
+                ...internals.device.caps.backendKind === "null" ? {} : {
+                  materialContext: {
+                    backend: internals.device.caps.backendKind === "wgpu-webgl2" ? "webgl2" : internals.device.caps.backendKind,
+                    capability: internals.device.caps.storageBuffer ? "storage-buffer" : "uniform-fallback",
+                    pipeline: "forward",
+                    geometry: "mesh",
+                    pass: "forward",
+                    profile: "forgeax-material-wgsl-v1",
+                    toolchain: "naga-oil",
+                    instrumentation: "none"
+                  }
+                },
                 cull: "none",
                 renderables: request === "none" ? "none" : "full",
                 ...request === "none" || request === "full" ? {} : { renderableEntitiesByWorld: request.entitiesByWorld },
@@ -32073,7 +32206,7 @@ async function makeWebGPURenderer(internals) {
       ...layoutKind === "pbr-skin" ? { layoutKind } : {}
     };
   };
-  const buildAndCachePipeline = (cacheKey, entry, label, moduleLabel, isHdr, renderState, topology, stripIndexFormat, variantSet, passKind = "forward", materialShaderId, meshAttributes, sampleCount = 1, colorFormatOverride, depthFormatOverride, vertexLayout, vertexLayoutProjection, shaderModuleMode, layoutKindOverride, additionalColorFormats) => {
+  const buildAndCachePipeline = (cacheKey, entry, label, moduleLabel, isHdr, renderState, topology, stripIndexFormat, variantSet, passKind = "forward", materialShaderId, meshAttributes, sampleCount = 1, colorFormatOverride, depthFormatOverride, vertexLayout, vertexLayoutProjection, shaderModuleMode, layoutKindOverride, additionalColorFormats, vertexEntry, authoredFragmentEntry) => {
     const group2Contract = resolvePipelineGroup2Contract(entry.source);
     const ctx = buildPipelineContext(
       variantSet,
@@ -32089,7 +32222,7 @@ async function makeWebGPURenderer(internals) {
     const currentState = currentPipelineState();
     if (currentState === null) return null;
     const ldrColorFormat = colorFormatOverride ?? currentState.colorAttachmentFormat;
-    const fragmentEntry = isHdr && (materialShaderId === "forgeax::sprite" || materialShaderId === "forgeax::sprite-lit") ? "fs_main_hdr" : void 0;
+    const fragmentEntry = authoredFragmentEntry ?? (isHdr && (materialShaderId === "forgeax::sprite" || materialShaderId === "forgeax::sprite-lit") ? "fs_main_hdr" : void 0);
     const built = buildPipelineForMaterialShader(
       cacheKey,
       // The catalog entry is projected into the material-shader entry shape.
@@ -32118,8 +32251,7 @@ async function makeWebGPURenderer(internals) {
         topology,
         ...topology === "line-strip" || topology === "triangle-strip" ? { stripIndexFormat: stripIndexFormat ?? "uint32" } : {}
       } : void 0,
-      void 0,
-      // vertexEntry — default vs_main
+      vertexEntry,
       fragmentEntry,
       void 0,
       // defines — none
@@ -32139,7 +32271,7 @@ async function makeWebGPURenderer(internals) {
     );
     return built.value;
   };
-  const getMaterialShaderPipeline = (materialShaderId, isHdr, renderState, topology, indexFormat, variantSet, passKind = "forward", meshAttributes, sampleCount = 1, colorFormatOverride, shaderUvSetCount, depthFormatOverride, vertexLayout, vertexLayoutProjection, shaderModuleMode = "validated", layoutKindOverride, additionalColorFormats) => {
+  const getMaterialShaderPipeline = (materialShaderId, isHdr, renderState, topology, indexFormat, variantSet, passKind = "forward", meshAttributes, sampleCount = 1, colorFormatOverride, shaderUvSetCount, depthFormatOverride, vertexLayout, vertexLayoutProjection, shaderModuleMode = "validated", layoutKindOverride, additionalColorFormats, vertexEntry, fragmentEntry) => {
     const currentState = currentPipelineState();
     const ldrColorFormat = colorFormatOverride ?? (currentState !== null ? currentState.colorAttachmentFormat : "bgra8unorm-srgb");
     const pipelineShaderId = resolveMaterialShaderBackendArtifactKey(
@@ -32188,7 +32320,13 @@ async function makeWebGPURenderer(internals) {
     const colorFormat = isHdr ? "rgba16float" : ldrColorFormat;
     const isDepthOnlyPass = passKindPolicyTable[passKind]?.shape === "depth-only";
     const spec = {
-      shader: { id: pipelineShaderId, passKind, variantSet: effectiveVariantSet },
+      shader: {
+        id: pipelineShaderId,
+        passKind,
+        variantSet: effectiveVariantSet,
+        ...vertexEntry === void 0 ? {} : { vertexEntry },
+        ...fragmentEntry === void 0 ? {} : { fragmentEntry }
+      },
       attachments: {
         colorFormats: additionalColorFormats === void 0 ? colorFormatsForPassKind(passKind, colorFormat) : [colorFormat, ...additionalColorFormats],
         depthFormat: isDepthOnlyPass ? "depth32float" : depthFormatOverride === null ? void 0 : depthFormatOverride ?? "depth24plus-stencil8",
@@ -32365,7 +32503,9 @@ async function makeWebGPURenderer(internals) {
       vertexLayoutProjection,
       shaderModuleMode,
       layoutKindOverride,
-      additionalColorFormats
+      additionalColorFormats,
+      vertexEntry,
+      fragmentEntry
     );
   };
   const getMaterialShaderPipelineEntry = (...args) => {