@fps-games/vfx 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -12,6 +12,14 @@
 
 <!-- release.mjs 在此行下方插入新版本区块 -->
 
+## v0.3.7 — 2026-07-02
+
+### 改动
+- feat(effects): update trail debris shield and building upgrade controls
+
+### 特效
+- 无新增 / 删除(仍 37 个)。
+
 ## v0.3.6 — 2026-07-01
 
 ### 改动

package/dist/effects/building-upgrade/index.d.ts

@@ -1,13 +1,10 @@
 import { VfxColorValue, VfxEffectPackage, VfxParamValues } from '../../types';
+type BuildingUpgradeFootprintShape = 'rectangle' | 'circle';
 interface BuildingUpgradeParams extends VfxParamValues {
     lifetime: number;
-    scale: number;
-    initialHeight: number;
     color: VfxColorValue;
     opacity: number;
-    scaleX: number;
-    scaleY: number;
-    scaleZ: number;
+    footprintShape: BuildingUpgradeFootprintShape;
     centerCount: number;
     outlineCount: number;
     strandWidth: number;

package/dist/effects/building-upgrade/index.js

@@ -15,18 +15,15 @@ const manifest = {
 };
 const BASE_FOOTPRINT_X = 3.2;
 const BASE_FOOTPRINT_Z = 2.6;
+const BASE_CIRCLE_RADIUS = 1.4;
 const BASE_CENTER_HEIGHT = 2.2;
 const BASE_OUTLINE_HEIGHT = 3.1;
 const BASE_GLOW_THICKNESS = 0.38;
 const DEFAULT_PARAMS = {
   lifetime: 1.8,
-  scale: 1,
-  initialHeight: 0.02,
   color: { r: 1, g: 0.84, b: 0.12 },
   opacity: 1,
-  scaleX: 1,
-  scaleY: 1,
-  scaleZ: 1,
+  footprintShape: "rectangle",
   centerCount: 46,
   outlineCount: 150,
   strandWidth: 0.035,
@@ -43,13 +40,12 @@ const buildingUpgradeEffectPackage = {
   debugAnchor: "playerRight",
   debugParams: [
     { key: "lifetime", label: "生命周期", kind: "lifetime", min: 0.2, max: 6, step: 0.01 },
-    { key: "scale", label: "整体缩放", kind: "scale", min: 0.1, max: 6, step: 0.01 },
-    { key: "initialHeight", label: "初始高度", kind: "number", min: -1, max: 3, step: 0.01 },
     { key: "color", label: "金光颜色", kind: "color" },
     { key: "opacity", label: "透明度", kind: "opacity", min: 0, max: 1, step: 0.01 },
-    { key: "scaleX", label: "X 轴缩放", kind: "number", min: 0.1, max: 6, step: 0.01 },
-    { key: "scaleY", label: "Y 轴缩放", kind: "number", min: 0.1, max: 6, step: 0.01 },
-    { key: "scaleZ", label: "Z 轴缩放", kind: "number", min: 0.1, max: 6, step: 0.01 },
+    { key: "footprintShape", label: "发射形状", kind: "enum", options: [
+      { value: "rectangle", label: "矩形" },
+      { value: "circle", label: "圆形" }
+    ] },
     { key: "centerCount", label: "中心金丝数量", kind: "number", min: 0, max: 240, step: 1 },
     { key: "outlineCount", label: "轮廓金丝数量", kind: "number", min: 0, max: 420, step: 1 },
     { key: "strandWidth", label: "金丝粗细", kind: "number", min: 5e-3, max: 0.2, step: 1e-3 },
@@ -58,14 +54,15 @@ const buildingUpgradeEffectPackage = {
     { key: "outlineThickness", label: "轮廓厚度", kind: "number", min: 0, max: 1, step: 0.01 },
     { key: "glowOpacity", label: "光芒强度", kind: "opacity", min: 0, max: 1, step: 0.01 }
   ],
-  create({ scene, root, position, params }) {
-    root.position.copyFrom(position).addInPlace(new Vector3(0, params.initialHeight, 0));
-    const centerStrands = createStrandSystem(scene, root, params, "center");
-    const outlineStrands = createStrandSystem(scene, root, params, "outline");
-    const glow = createOutlineGlow(scene, root, params);
+  create({ scene, root, position, params, scale }) {
+    root.position.copyFrom(position);
+    const visualScale = normalizeBuildingUpgradeScale(scale);
+    const centerStrands = createStrandSystem(scene, root, params, visualScale, "center");
+    const outlineStrands = createStrandSystem(scene, root, params, visualScale, "outline");
+    const glow = createOutlineGlow(scene, root, params, visualScale);
     const disposeTimer = window.setTimeout(
       () => disposeAll(),
-      Math.max(0.05, params.lifetime + getMaxStrandHeight(params) / Math.max(0.1, params.riseSpeed) * 0.18 + 0.45) * 1e3
+      Math.max(0.05, params.lifetime + getMaxStrandHeight(visualScale) / Math.max(0.1, params.riseSpeed) * 0.18 + 0.45) * 1e3
     );
     let disposed = false;
     centerStrands.start();
@@ -88,12 +85,12 @@ const buildingUpgradeEffectPackage = {
     }
   }
 };
-function createStrandSystem(scene, root, params, mode) {
+function createStrandSystem(scene, root, params, visualScale, mode) {
   const count = Math.max(0, Math.round(mode === "center" ? params.centerCount : params.outlineCount));
   const system = new ParticleSystem(`building-upgrade.${mode}-strands`, Math.max(1, count), scene);
   const color = params.color;
-  const height = mode === "center" ? getCenterHeight(params) : getOutlineHeight(params);
-  const width = params.strandWidth * getHorizontalScale(params) * (mode === "center" ? 1.35 : 0.92);
+  const height = mode === "center" ? getCenterHeight(visualScale) : getOutlineHeight(visualScale);
+  const width = params.strandWidth * visualScale.horizontal * (mode === "center" ? 1.35 : 0.92);
   configureVfxParticleSystem(system);
   system.particleTexture = getGoldStrandTexture(scene);
   system.emitter = root;
@@ -110,9 +107,9 @@ function createStrandSystem(scene, root, params, mode) {
   system.maxScaleX = Math.max(system.minScaleX, width * 1.8);
   system.minScaleY = 1;
   system.maxScaleY = mode === "center" ? 1.45 : 1.75;
-  system.minEmitPower = Math.max(0.01, params.riseSpeed * getVerticalScale(params) * (mode === "center" ? 0.5 : 0.7));
-  system.maxEmitPower = Math.max(system.minEmitPower, params.riseSpeed * getVerticalScale(params) * (mode === "center" ? 1.15 : 1.65));
-  system.gravity = new Vector3(0, 0.38 * getVerticalScale(params), 0);
+  system.minEmitPower = Math.max(0.01, params.riseSpeed * (mode === "center" ? 0.5 : 0.7));
+  system.maxEmitPower = Math.max(system.minEmitPower, params.riseSpeed * (mode === "center" ? 1.15 : 1.65));
+  system.gravity = new Vector3(0, 0.38, 0);
   system.blendMode = ParticleSystem.BLENDMODE_ADD;
   system.color1 = toColor4(color, params.opacity * (mode === "center" ? 0.72 : 0.86));
   system.color2 = toColor4({ r: 1, g: 0.98, b: 0.52 }, params.opacity);
@@ -136,7 +133,7 @@ function createStrandSystem(scene, root, params, mode) {
   system.startDirectionFunction = (worldMatrix, directionToUpdate, particle, isLocal) => {
     const index = particle.id + directionIndex;
     directionIndex += 1;
-    const sway = (mode === "center" ? 0.22 : 0.12) * getHorizontalScale(params);
+    const sway = mode === "center" ? 0.22 : 0.12;
     const local = new Vector3(
       (sequence01(index, 4) - 0.5) * sway,
       0.8 + sequence01(index, 5) * 0.65,
@@ -147,11 +144,11 @@ function createStrandSystem(scene, root, params, mode) {
   };
   return system;
 }
-function createOutlineGlow(scene, root, params) {
+function createOutlineGlow(scene, root, params, visualScale) {
   const count = Math.max(1, Math.round(params.outlineCount * 0.82));
   const system = new ParticleSystem("building-upgrade.outline-glow-rays", count, scene);
-  const height = getOutlineHeight(params) * 1.06;
-  const glowWidth = Math.max(0.04, BASE_GLOW_THICKNESS * getHorizontalScale(params));
+  const height = getOutlineHeight(visualScale) * 1.06;
+  const glowWidth = Math.max(0.04, BASE_GLOW_THICKNESS * visualScale.horizontal);
   const alpha = params.glowOpacity * params.opacity;
   configureVfxParticleSystem(system);
   system.particleTexture = getOutlineGlowTexture(scene);
@@ -169,9 +166,9 @@ function createOutlineGlow(scene, root, params) {
   system.maxScaleX = glowWidth * 1.18;
   system.minScaleY = 1.05;
   system.maxScaleY = 1.75;
-  system.minEmitPower = Math.max(0.01, params.riseSpeed * getVerticalScale(params) * 0.58);
-  system.maxEmitPower = Math.max(system.minEmitPower, params.riseSpeed * getVerticalScale(params) * 1.38);
-  system.gravity = new Vector3(0, 0.3 * getVerticalScale(params), 0);
+  system.minEmitPower = Math.max(0.01, params.riseSpeed * 0.58);
+  system.maxEmitPower = Math.max(system.minEmitPower, params.riseSpeed * 1.38);
+  system.gravity = new Vector3(0, 0.3, 0);
   system.blendMode = ParticleSystem.BLENDMODE_ADD;
   system.color1 = toColor4(params.color, alpha * 0.62);
   system.color2 = toColor4({ r: 1, g: 0.98, b: 0.58 }, alpha * 0.86);
@@ -195,7 +192,7 @@ function createOutlineGlow(scene, root, params) {
   system.startDirectionFunction = (worldMatrix, directionToUpdate, particle, isLocal) => {
     const index = particle.id + directionIndex + 31;
     directionIndex += 1;
-    const sway = 0.08 * getHorizontalScale(params);
+    const sway = 0.08;
     const local = new Vector3(
       (sequence01(index, 4) - 0.5) * sway,
       0.82 + sequence01(index, 5) * 0.58,
@@ -207,49 +204,78 @@ function createOutlineGlow(scene, root, params) {
   return system;
 }
 function sampleCenterPosition(index, params) {
+  const shape = getFootprintShape(params);
+  if (shape === "circle") return sampleCircleCenterPosition(index, params);
   const angle = sequence01(index, 0) * Math.PI * 2;
   const radius = Math.sqrt(0.16 + sequence01(index, 1) * 0.84);
-  const xRadius = getFootprintX(params) * 0.5 * params.centerSpread;
-  const zRadius = getFootprintZ(params) * 0.5 * params.centerSpread;
+  const xRadius = getFootprintX() * 0.5 * params.centerSpread;
+  const zRadius = getFootprintZ() * 0.5 * params.centerSpread;
   const jitterX = (sequence01(index, 7) - 0.5) * xRadius * 0.18;
   const jitterZ = (sequence01(index, 8) - 0.5) * zRadius * 0.18;
   const x = Math.cos(angle) * radius * xRadius + jitterX;
   const z = Math.sin(angle) * radius * zRadius + jitterZ;
-  const y = sequence01(index, 2) * 0.12 * getVerticalScale(params);
+  const y = sequence01(index, 2) * 0.12;
   return new Vector3(x, y, z);
 }
 function sampleOutlinePosition(index, params) {
-  const width = getFootprintX(params);
-  const depth = getFootprintZ(params);
+  const shape = getFootprintShape(params);
+  if (shape === "circle") return sampleCircleOutlinePosition(index, params);
+  return sampleRectOutlinePosition(index, getFootprintX(), getFootprintZ(), params.outlineThickness);
+}
+function sampleCircleCenterPosition(index, params) {
+  const angle = sequence01(index, 0) * Math.PI * 2;
+  const radius = Math.sqrt(sequence01(index, 1)) * BASE_CIRCLE_RADIUS * params.centerSpread;
+  const jitterRadius = (sequence01(index, 7) - 0.5) * BASE_CIRCLE_RADIUS * 0.08;
+  const r = Math.max(0, radius + jitterRadius);
+  const y = sequence01(index, 2) * 0.12;
+  return new Vector3(Math.cos(angle) * r, y, Math.sin(angle) * r);
+}
+function sampleCircleOutlinePosition(index, params) {
+  const angle = sequence01(index, 0) * Math.PI * 2;
+  const jitter = (sequence01(index, 1) - 0.5) * params.outlineThickness;
+  const radius = Math.max(1e-3, BASE_CIRCLE_RADIUS + jitter);
+  const y = sequence01(index, 2) * 0.16;
+  return new Vector3(Math.cos(angle) * radius, y, Math.sin(angle) * radius);
+}
+function sampleRectOutlinePosition(index, width, depth, thickness) {
   const perimeter = Math.max(1e-3, width * 2 + depth * 2);
   const distance = sequence01(index, 0) * perimeter;
-  const jitter = (sequence01(index, 1) - 0.5) * params.outlineThickness * getHorizontalScale(params);
-  const y = sequence01(index, 2) * 0.16 * getVerticalScale(params);
+  const jitter = (sequence01(index, 1) - 0.5) * thickness;
+  const y = sequence01(index, 2) * 0.16;
   if (distance < width) return new Vector3(-width * 0.5 + distance, y, -depth * 0.5 + jitter);
   if (distance < width + depth) return new Vector3(width * 0.5 + jitter, y, -depth * 0.5 + distance - width);
   if (distance < width * 2 + depth) return new Vector3(width * 0.5 - (distance - width - depth), y, depth * 0.5 + jitter);
   return new Vector3(-width * 0.5 + jitter, y, depth * 0.5 - (distance - width * 2 - depth));
 }
-function getFootprintX(params) {
-  return BASE_FOOTPRINT_X * Math.max(0.05, params.scale) * Math.max(0.05, params.scaleX);
+function getFootprintShape(params) {
+  if (params.footprintShape === "circle") return params.footprintShape;
+  return "rectangle";
 }
-function getFootprintZ(params) {
-  return BASE_FOOTPRINT_Z * Math.max(0.05, params.scale) * Math.max(0.05, params.scaleZ);
+function getFootprintX() {
+  return BASE_FOOTPRINT_X;
 }
-function getVerticalScale(params) {
-  return Math.max(0.05, params.scale) * Math.max(0.05, params.scaleY);
+function getFootprintZ() {
+  return BASE_FOOTPRINT_Z;
 }
-function getHorizontalScale(params) {
-  return Math.max(0.05, params.scale) * Math.max(0.05, (params.scaleX + params.scaleZ) * 0.5);
+function getCenterHeight(visualScale) {
+  return BASE_CENTER_HEIGHT * visualScale.y;
 }
-function getCenterHeight(params) {
-  return BASE_CENTER_HEIGHT * getVerticalScale(params);
+function getOutlineHeight(visualScale) {
+  return BASE_OUTLINE_HEIGHT * visualScale.y;
 }
-function getOutlineHeight(params) {
-  return BASE_OUTLINE_HEIGHT * getVerticalScale(params);
+function getMaxStrandHeight(visualScale) {
+  return Math.max(getCenterHeight(visualScale), getOutlineHeight(visualScale));
 }
-function getMaxStrandHeight(params) {
-  return Math.max(getCenterHeight(params), getOutlineHeight(params));
+function normalizeBuildingUpgradeScale(scale) {
+  const x = Math.max(0.05, Math.abs(scale.x));
+  const y = Math.max(0.05, Math.abs(scale.y));
+  const z = Math.max(0.05, Math.abs(scale.z));
+  return {
+    x,
+    y,
+    z,
+    horizontal: Math.max(0.05, (x + z) * 0.5)
+  };
 }
 function getGoldStrandTexture(scene) {
   const key = "__vfx_building_upgrade_gold_strand_texture";

package/dist/effects/debris-smoke/index.d.ts

@@ -3,6 +3,14 @@ interface DebrisSmokeParams extends VfxParamValues {
     debrisCount: number;
     debrisSize: number;
     debrisRadius: number;
+    debrisSpeed: number;
+    debrisHorizontalSpeed: number;
+    debrisUpSpeed: number;
+    debrisDirectionX: number;
+    debrisDirectionY: number;
+    debrisDirectionZ: number;
+    debrisGravity: number;
+    debrisLifetime: number;
     smokeCount: number;
     smokeSize: number;
 }

package/dist/effects/debris-smoke/index.js

@@ -11,6 +11,14 @@ const DEFAULT_PARAMS = {
   debrisCount: 14,
   debrisSize: 0.35,
   debrisRadius: 1.8,
+  debrisSpeed: 1,
+  debrisHorizontalSpeed: 1,
+  debrisUpSpeed: 1,
+  debrisDirectionX: 0,
+  debrisDirectionY: 0,
+  debrisDirectionZ: 0,
+  debrisGravity: 7,
+  debrisLifetime: 1.2,
   smokeCount: 10,
   smokeSize: 1
 };
@@ -51,6 +59,14 @@ const debrisSmokeEffectPackage = {
     { key: "debrisCount", label: "碎石·数量", kind: "number", min: 0, max: 30, step: 1 },
     { key: "debrisSize", label: "碎石·大小", kind: "number", min: 0.1, max: 1, step: 0.01 },
     { key: "debrisRadius", label: "碎石·范围", kind: "scale", min: 0.5, max: 5, step: 0.1 },
+    { key: "debrisSpeed", label: "碎石·整体速度", kind: "number", min: 0, max: 5, step: 0.05 },
+    { key: "debrisHorizontalSpeed", label: "碎石·横向速度", kind: "number", min: 0, max: 5, step: 0.05 },
+    { key: "debrisUpSpeed", label: "碎石·上抛速度", kind: "number", min: 0, max: 5, step: 0.05 },
+    { key: "debrisDirectionX", label: "碎石·方向 X", kind: "number", min: -1, max: 1, step: 0.01 },
+    { key: "debrisDirectionY", label: "碎石·方向 Y", kind: "number", min: -1, max: 1, step: 0.01 },
+    { key: "debrisDirectionZ", label: "碎石·方向 Z", kind: "number", min: -1, max: 1, step: 0.01 },
+    { key: "debrisGravity", label: "碎石·下落重力", kind: "number", min: 0, max: 20, step: 0.1 },
+    { key: "debrisLifetime", label: "碎石·可见时长", kind: "lifetime", min: 0.2, max: 4, step: 0.05 },
     // 段2 · 烟雾
     { key: "smokeCount", label: "烟雾·数量", kind: "number", min: 0, max: 40, step: 1 },
     { key: "smokeSize", label: "烟雾·尺寸", kind: "scale", min: 0.2, max: 3, step: 0.05 }
@@ -85,12 +101,12 @@ const debrisSmokeEffectPackage = {
         d.isPickable = false;
         d.normalizeToUnitCube();
         d.scaling.scaleInPlace(r * params.debrisSize * (0.5 + Math.random() * 0.8));
-        pool.spawn(d, position, new Vector3((Math.random() - 0.5) * 13, Math.random() * 6.75 + 2.25, (Math.random() - 0.5) * 13), 7, 1.2);
+        pool.spawn(d, position, makeDebrisVelocity(params), params.debrisGravity, params.debrisLifetime);
       }
     }).catch((e) => {
       console.warn("[VFX] debris-smoke load failed", e);
     });
-    const disposeTimer = window.setTimeout(() => disposeAll(), 2200);
+    const disposeTimer = window.setTimeout(() => disposeAll(), Math.max(2200, params.debrisLifetime * 1e3 + 1e3));
     function disposeAll() {
       if (disposed) return;
       disposed = true;
@@ -104,6 +120,25 @@ const debrisSmokeEffectPackage = {
     } };
   }
 };
+function makeDebrisVelocity(params) {
+  const velocity = new Vector3(
+    (Math.random() - 0.5) * 13 * params.debrisHorizontalSpeed,
+    (Math.random() * 6.75 + 2.25) * params.debrisUpSpeed,
+    (Math.random() - 0.5) * 13 * params.debrisHorizontalSpeed
+  );
+  const direction = new Vector3(params.debrisDirectionX, params.debrisDirectionY, params.debrisDirectionZ);
+  const directionLength = direction.length();
+  if (directionLength > 1e-4) {
+    direction.scaleInPlace(1 / directionLength);
+    const directionSpeed = 6.5 * Math.min(directionLength, 1);
+    velocity.addInPlace(new Vector3(
+      direction.x * directionSpeed * params.debrisHorizontalSpeed,
+      direction.y * directionSpeed * params.debrisUpSpeed,
+      direction.z * directionSpeed * params.debrisHorizontalSpeed
+    ));
+  }
+  return velocity.scaleInPlace(params.debrisSpeed);
+}
 export {
   debrisSmokeEffectPackage
 };

package/dist/effects/energy-shield/index.js

@@ -7,6 +7,9 @@ import { MeshBuilder } from "@babylonjs/core/Meshes/meshBuilder";
 import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
 import { V as VFX_RENDERING_GROUP_ID } from "../../chunks/rendering-CV3nhygX.js";
 const SHADER_NAME = "vfxEnergyShield";
+const HALO_ALPHA_SCALE_MAX = 0.3;
+const HALO_FEATHER_ALPHA_RATIO = 0.72;
+const HALO_FEATHER_SCALE_OFFSET = 0.018;
 const DEFAULT_PARAMS = {
   radius: 3.18,
   verticalScale: 1.02,
@@ -25,7 +28,7 @@ const DEFAULT_PARAMS = {
   flowIntensity: 1.15,
   marbleContrast: 0.67,
   bloomIntensity: 0.45,
-  haloScale: 1.012,
+  haloScale: 1.018,
   showHalo: false,
   segments: 64
 };
@@ -146,7 +149,8 @@ void main(void) {
   vec3 normalW = normalize(vNormalW);
   vec3 viewDir = normalize(cameraPosition - vWorldPos);
   float ndv = saturate(dot(normalW, viewDir));
-  float fresnel = pow(1.0 - ndv, max(0.05, uFresnelPower)) * uFresnelStrength;
+  float viewRim = saturate(1.0 - ndv);
+  float fresnel = pow(viewRim, max(0.05, uFresnelPower)) * uFresnelStrength;
 
   float t = uTime * uFlowSpeed;
   vec3 spherePos = normalize(vObjPos + vec3(0.0001)) * max(0.05, uNoiseScale);
@@ -175,12 +179,25 @@ void main(void) {
   alpha += fresnel * uOpacity * 0.58;
   alpha += noiseEdge * uNoiseEdgeIntensity * 0.05;
 
-  if (uHaloMode > 0.5) {
-    float haloRim = pow(saturate(1.0 - ndv), max(0.35, uFresnelPower * 0.55));
-    float softRim = smoothstep(0.08, 0.86, haloRim);
-    float edgeTaper = 1.0 - smoothstep(0.78, 1.0, haloRim) * 0.62;
-    color = uColor * (0.82 + softRim * 0.32) * (0.9 + cloud * 0.1);
-    alpha = (0.06 + softRim * 0.62 + noiseEdge * 0.12) * edgeTaper;
+  if (uHaloMode > 1.5) {
+    float haloRim = pow(viewRim, max(0.28, uFresnelPower * 0.44));
+    float featherIn = smoothstep(0.1, 0.46, haloRim);
+    float featherOut = 1.0 - smoothstep(0.72, 1.0, haloRim);
+    float featherRim = featherIn * featherOut;
+    float outerFade = 1.0 - smoothstep(0.88, 1.0, haloRim);
+    color = uColor * (0.2 + featherRim * 0.24 + cloud * 0.04);
+    alpha = featherRim * 0.58 * outerFade;
+  } else if (uHaloMode > 0.5) {
+    float haloRim = pow(viewRim, max(0.3, uFresnelPower * 0.48));
+    float bodyIn = smoothstep(0.34, 0.68, haloRim);
+    float bodyOut = 1.0 - smoothstep(0.72, 1.0, haloRim);
+    float bodyRim = bodyIn * bodyOut;
+    float featherIn = smoothstep(0.12, 0.44, haloRim);
+    float featherOut = 1.0 - smoothstep(0.48, 1.0, haloRim);
+    float featherRim = featherIn * featherOut;
+    float outerFade = 1.0 - smoothstep(0.86, 1.0, haloRim);
+    color = uColor * (0.24 + bodyRim * 0.34 + featherRim * 0.12 + cloud * 0.05);
+    alpha = (bodyRim * 0.5 + featherRim * 0.14 + noiseEdge * 0.01) * outerFade;
   }
 
   alpha *= uHaloAlphaScale;
@@ -254,47 +271,78 @@ function createEnergyShield(scene, options = {}) {
   shield.material = material;
   let halo = null;
   let haloMaterial = null;
+  let haloFeather = null;
+  let haloFeatherMaterial = null;
   const disposeHalo = () => {
     halo?.dispose(false, false);
     haloMaterial?.dispose();
+    haloFeather?.dispose(false, false);
+    haloFeatherMaterial?.dispose();
     halo = null;
     haloMaterial = null;
+    haloFeather = null;
+    haloFeatherMaterial = null;
   };
   const ensureHalo = () => {
     if (!params.showHalo || params.bloomIntensity <= 1e-3) {
       disposeHalo();
       return;
     }
-    if (halo && haloMaterial) return;
-    halo = MeshBuilder.CreateSphere(
-      "vfx_energyShield_halo",
-      {
-        diameter: 2,
-        segments: Math.max(16, Math.round(params.segments)),
-        slice: 0.5,
-        updatable: false
-      },
-      scene
-    );
-    halo.parent = shield;
-    halo.isPickable = false;
-    halo.alwaysSelectAsActiveMesh = true;
-    halo.renderingGroupId = shield.renderingGroupId;
-    halo.alphaIndex = shield.alphaIndex + 1;
-    halo.scaling.setAll(Math.max(1, params.haloScale));
-    haloMaterial = createShieldMaterial(scene, {
-      name: "vfx_energyShield_halo_material",
-      alphaMode: Constants.ALPHA_ADD
-    });
-    halo.material = haloMaterial;
+    if (!halo || !haloMaterial) {
+      halo = MeshBuilder.CreateSphere(
+        "vfx_energyShield_halo",
+        {
+          diameter: 2,
+          segments: Math.max(16, Math.round(params.segments)),
+          slice: 0.5,
+          updatable: false
+        },
+        scene
+      );
+      halo.parent = shield;
+      halo.isPickable = false;
+      halo.alwaysSelectAsActiveMesh = true;
+      halo.renderingGroupId = shield.renderingGroupId;
+      halo.alphaIndex = shield.alphaIndex + 1;
+      halo.scaling.setAll(Math.max(1, params.haloScale));
+      haloMaterial = createShieldMaterial(scene, {
+        name: "vfx_energyShield_halo_material",
+        alphaMode: Constants.ALPHA_ADD
+      });
+      halo.material = haloMaterial;
+    }
+    if (!haloFeather || !haloFeatherMaterial) {
+      haloFeather = MeshBuilder.CreateSphere(
+        "vfx_energyShield_halo_feather",
+        {
+          diameter: 2,
+          segments: Math.max(16, Math.round(params.segments)),
+          slice: 0.5,
+          updatable: false
+        },
+        scene
+      );
+      haloFeather.parent = shield;
+      haloFeather.isPickable = false;
+      haloFeather.alwaysSelectAsActiveMesh = true;
+      haloFeather.renderingGroupId = shield.renderingGroupId;
+      haloFeather.alphaIndex = shield.alphaIndex + 2;
+      haloFeather.scaling.setAll(getHaloFeatherScale(params));
+      haloFeatherMaterial = createShieldMaterial(scene, {
+        name: "vfx_energyShield_halo_feather_material",
+        alphaMode: Constants.ALPHA_ADD
+      });
+      haloFeather.material = haloFeatherMaterial;
+    }
   };
   ensureHalo();
-  applyParams(material, shield, halo, haloMaterial, params);
+  applyParams(material, shield, halo, haloMaterial, haloFeather, haloFeatherMaterial, params);
   let elapsed = 0;
   const observer = scene.onBeforeRenderObservable.add(() => {
     elapsed += Math.min(scene.getEngine().getDeltaTime() / 1e3, 0.05);
     material.setFloat("uTime", elapsed);
     haloMaterial?.setFloat("uTime", elapsed);
+    haloFeatherMaterial?.setFloat("uTime", elapsed);
   });
   let disposed = false;
   const dispose = () => {
@@ -313,7 +361,7 @@ function createEnergyShield(scene, options = {}) {
     update(partial) {
       params = mergeParams(partial, params);
       ensureHalo();
-      applyParams(material, shield, halo, haloMaterial, params);
+      applyParams(material, shield, halo, haloMaterial, haloFeather, haloFeatherMaterial, params);
     },
     dispose
   };
@@ -356,19 +404,30 @@ function createShieldMaterial(scene, options = {}) {
   material.fogEnabled = false;
   return material;
 }
-function applyParams(material, shield, halo, haloMaterial, params) {
+function applyParams(material, shield, halo, haloMaterial, haloFeather, haloFeatherMaterial, params) {
   shield.scaling.set(params.radius, params.radius * params.verticalScale, params.radius);
   applyMaterialParams(material, params, params.opacity, 1, 0);
+  const haloAlphaScale = Math.min(HALO_ALPHA_SCALE_MAX, params.opacity * Math.min(1, params.bloomIntensity));
   if (halo && haloMaterial) {
     halo.scaling.setAll(Math.max(1, params.haloScale));
     applyMaterialParams(
       haloMaterial,
       params,
       1,
-      params.opacity * 0.95 * Math.min(2.2, params.bloomIntensity),
+      haloAlphaScale,
       1
     );
   }
+  if (haloFeather && haloFeatherMaterial) {
+    haloFeather.scaling.setAll(getHaloFeatherScale(params));
+    applyMaterialParams(
+      haloFeatherMaterial,
+      params,
+      1,
+      haloAlphaScale * HALO_FEATHER_ALPHA_RATIO,
+      2
+    );
+  }
 }
 function applyMaterialParams(material, params, opacity, haloAlphaScale, haloMode) {
   material.setColor3("uColor", toColor3(params.color));
@@ -398,6 +457,9 @@ function mergeParams(patch, base = DEFAULT_PARAMS) {
 function toColor3(color) {
   return new Color3(color.r, color.g, color.b);
 }
+function getHaloFeatherScale(params) {
+  return Math.max(1, params.haloScale + HALO_FEATHER_SCALE_OFFSET);
+}
 function registerShaders() {
   Effect.ShadersStore[`${SHADER_NAME}VertexShader`] = VERTEX_SHADER;
   Effect.ShadersStore[`${SHADER_NAME}FragmentShader`] = FRAGMENT_SHADER;

package/dist/effects/weapon-trail/index.d.ts

@@ -3,6 +3,7 @@ interface WeaponTrailParams extends VfxParamValues {
     lifetimeMode: string;
     lifetime: number;
     playbackMode: string;
+    historySpace: string;
     orientation: string;
     showGlow: boolean;
     showOuter: boolean;

package/dist/effects/weapon-trail/index.js

@@ -12,6 +12,7 @@ const trailTextureUrl = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP4AAABNC
 const DEFAULT_PARAMS = {
   ...LIFETIME_DEFAULTS,
   playbackMode: "follow",
+  historySpace: "world",
   orientation: "horizontal",
   showGlow: true,
   showOuter: true,
@@ -101,6 +102,7 @@ const weaponTrailEffectPackage = {
   nameZh: "武器拖尾",
   placement: "socket",
   geometrySpace: "world",
+  optionalInputs: ["reference"],
   debugAnchor: "player",
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -109,6 +111,10 @@ const weaponTrailEffectPackage = {
       { value: "follow", label: "跟随挂点" },
       { value: "orbit", label: "环绕预览" }
     ] },
+    { key: "historySpace", label: "历史空间", kind: "enum", options: [
+      { value: "world", label: "世界坐标" },
+      { value: "reference", label: "参考点相对" }
+    ] },
     { key: "orientation", label: "拖尾朝向", kind: "enum", options: [
       { value: "horizontal", label: "水平面" },
       { value: "vertical", label: "竖直" }
@@ -134,7 +140,7 @@ const weaponTrailEffectPackage = {
     { key: "flowSpeed", label: "能量流动速度", kind: "number", min: 0, max: 4, step: 0.05 },
     { key: "tint", label: "颜色", kind: "color" }
   ],
-  create({ scene, root, position, params, renderingGroupId }) {
+  create({ scene, root, position, params, renderingGroupId, inputs }) {
     root.position.copyFrom(position);
     const rgid = renderingGroupId ?? 0;
     registerShaders();
@@ -199,6 +205,10 @@ const weaponTrailEffectPackage = {
     let outerInit = false, coreInit = false, glowInit = false;
     const cur = sample();
     const mountPos = new Vector3();
+    const referencePos = new Vector3();
+    const sampleWorldPos = new Vector3();
+    let usingReferenceHistory = false;
+    let warnedMissingReference = false;
     const lastWidthAxis = new Vector3(0, 0, 1);
     const tmpDir = new Vector3();
     const tailDir = new Vector3(1, 0, 0);
@@ -208,6 +218,32 @@ const weaponTrailEffectPackage = {
       if (params.playbackMode === "follow" || params.playbackMode === "orbit") return params.playbackMode;
       return params.orbitRadius > 0 ? "orbit" : "follow";
     }
+    function resolveHistorySpace() {
+      return params.historySpace === "reference" ? "reference" : "world";
+    }
+    function updateReferencePosition() {
+      if (resolveHistorySpace() !== "reference") return false;
+      const provider = inputs?.reference;
+      if (!provider) {
+        if (!warnedMissingReference) {
+          console.warn('[weapon-trail] historySpace="reference" 需要 inputs.reference; 已回退到世界坐标历史。');
+          warnedMissingReference = true;
+        }
+        return false;
+      }
+      const value = provider();
+      if (!value) return false;
+      referencePos.copyFrom(value);
+      return true;
+    }
+    function clearHistory() {
+      rawCount = 0;
+      for (let i = 0; i < targetCount; i++) {
+        points[i].position.set(0, 0, 0);
+        points[i].widthAxis.copyFrom(lastWidthAxis);
+        pointPathT[i] = 0;
+      }
+    }
     function sampleMinDistance() {
       return Math.max(3e-3, Math.min(0.04, params.worldLength / Math.max(16, targetCount * 3)));
     }
@@ -262,15 +298,24 @@ const weaponTrailEffectPackage = {
       rawCount += 1;
       trimRawHistory();
     }
-    function sampleEmitter(out) {
+    function sampleEmitter(out, useReference) {
       const playbackMode = resolvePlaybackMode();
       const orbitRadius = playbackMode === "orbit" ? params.orbitRadius : 0;
       const c = Math.cos(angle), s = Math.sin(angle);
-      out.position.set(
+      sampleWorldPos.set(
         mountPos.x + c * orbitRadius,
         mountPos.y + params.height,
         mountPos.z + s * orbitRadius
       );
+      if (useReference) {
+        out.position.set(
+          sampleWorldPos.x - referencePos.x,
+          sampleWorldPos.y - referencePos.y,
+          sampleWorldPos.z - referencePos.z
+        );
+      } else {
+        out.position.copyFrom(sampleWorldPos);
+      }
       if (params.orientation === "vertical") {
         out.widthAxis.set(0, 1, 0);
         return;
@@ -330,7 +375,7 @@ const weaponTrailEffectPackage = {
         if (!found) extrapolateTailSample(targetDist, distBefore, t);
       }
     }
-    function buildRibbon(mesh, halfWidth, wasInit) {
+    function buildRibbon(mesh, halfWidth, wasInit, useReference) {
       positions.length = 0;
       uvs.length = 0;
       colors.length = 0;
@@ -343,7 +388,10 @@ const weaponTrailEffectPackage = {
         const tailAlpha = Math.max(0, 1 - Math.pow(pathT, params.tailFadeExponent) * params.tailFadeStrength);
         const alpha = tailAlpha;
         const ox = s.widthAxis.x * halfWidth, oy = s.widthAxis.y * halfWidth, oz = s.widthAxis.z * halfWidth;
-        positions.push(s.position.x + ox, s.position.y + oy, s.position.z + oz, s.position.x - ox, s.position.y - oy, s.position.z - oz);
+        const px = useReference ? s.position.x + referencePos.x : s.position.x;
+        const py = useReference ? s.position.y + referencePos.y : s.position.y;
+        const pz = useReference ? s.position.z + referencePos.z : s.position.z;
+        positions.push(px + ox, py + oy, pz + oz, px - ox, py - oy, pz - oz);
         uvs.push(u, 0, u, 1);
         colors.push(1, 1, 1, alpha, 1, 1, 1, alpha);
         if (i < targetCount - 1) {
@@ -373,13 +421,18 @@ const weaponTrailEffectPackage = {
       if (resolvePlaybackMode() === "orbit") angle += params.orbitSpeed * dt;
       root.computeWorldMatrix(true);
       mountPos.copyFrom(root.getAbsolutePosition());
-      sampleEmitter(cur);
+      const useReference = updateReferencePosition();
+      if (useReference !== usingReferenceHistory) {
+        usingReferenceHistory = useReference;
+        clearHistory();
+      }
+      sampleEmitter(cur, useReference);
       if (rawCount === 0 || Vector3.Distance(cur.position, raw[0].position) > sampleMinDistance()) insertRawSample(cur);
       resample();
       const halfW = params.width * 0.5;
-      if (glow) glowInit = buildRibbon(glow, halfW * 2.2, glowInit);
-      if (outer) outerInit = buildRibbon(outer, halfW, outerInit);
-      if (core) coreInit = buildRibbon(core, halfW * params.coreWidth, coreInit);
+      if (glow) glowInit = buildRibbon(glow, halfW * 2.2, glowInit, useReference);
+      if (outer) outerInit = buildRibbon(outer, halfW, outerInit, useReference);
+      if (core) coreInit = buildRibbon(core, halfW * params.coreWidth, coreInit, useReference);
       outerMat?.setFloat("uTime", time);
       coreMat?.setFloat("uTime", time);
       glowMat?.setFloat("uTime", time);

package/dist/index.js

@@ -192,6 +192,7 @@ function normalizeInputs(inputs) {
   if (inputs.normal != null) out.normal = asFn(inputs.normal);
   if (inputs.endpoints) out.endpoints = inputs.endpoints.map((e) => asFn(e)).filter(Boolean);
   if (inputs.target) out.target = inputs.target;
+  if (inputs.reference != null) out.reference = asFn(inputs.reference);
   if (inputs.scalars) {
     out.scalars = {};
     for (const [k, v] of Object.entries(inputs.scalars)) {

package/dist/types.d.ts

@@ -4,13 +4,14 @@ import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
 export type VfxDebugAnchor = 'playerRight' | 'player';
 export type VfxInput<T> = T | (() => T);
-export type VfxInputKey = 'aim' | 'normal' | 'endpoints' | 'target';
+export type VfxInputKey = 'aim' | 'normal' | 'endpoints' | 'target' | 'reference';
 /** 调用方提供的 inputs(放在 VfxSpawnTransform.inputs)。 */
 export interface VfxEffectInputs {
     aim?: VfxInput<Vector3>;
     normal?: VfxInput<Vector3>;
     endpoints?: Array<VfxInput<Vector3>>;
     target?: AbstractMesh;
+    reference?: VfxInput<Vector3>;
     /** 运行时标量(throttle/intensity 等),值可静态或 provider;特效每帧读取做活改(G5)。 */
     scalars?: Record<string, VfxInput<number>>;
 }
@@ -20,6 +21,7 @@ export interface VfxResolvedInputs {
     normal?: () => Vector3;
     endpoints?: Array<() => Vector3>;
     target?: AbstractMesh;
+    reference?: () => Vector3;
     scalars?: Record<string, () => number>;
 }
 export type VfxParamValue = number | string | boolean | VfxColorValue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fps-games/vfx",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "description": "Shared VFX library for Playable projects: engine-injected effect packages + runtime. Project-pure (no imports of host project code).",
   "publishConfig": {

package/packages/effects/building-upgrade/vfx-params.json

@@ -3,17 +3,13 @@
   "__generation.offsetY": 0,
   "__generation.offsetZ": 0,
   "lifetime": 1,
-  "scale": 2,
-  "initialHeight": 0.05,
   "color": {
     "r": 1,
     "g": 0.8392156862745098,
     "b": 0.12156862745098039
   },
   "opacity": 1,
-  "scaleX": 2,
-  "scaleY": 0.2,
-  "scaleZ": 2,
+  "footprintShape": "rectangle",
   "centerCount": 100,
   "outlineCount": 300,
   "strandWidth": 0.1,

package/packages/effects/energy-shield/vfx-params.json

@@ -23,7 +23,7 @@
     "flowIntensity": 1.15,
     "marbleContrast": 0.67,
     "bloomIntensity": 0.45,
-    "haloScale": 1.012,
+    "haloScale": 1.018,
     "showHalo": false,
     "segments": 64
   }