@fps-games/vfx 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -12,6 +12,14 @@
 
 <!-- release.mjs 在此行下方插入新版本区块 -->
 
+## v0.3.8 — 2026-07-02
+
+### 改动
+- fix(building-upgrade): treat offset scale as footprint scale
+
+### 特效
+- 无新增 / 删除(仍 37 个)。
+
 ## v0.3.7 — 2026-07-02
 
 ### 改动

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

@@ -38,6 +38,7 @@ const buildingUpgradeEffectPackage = {
   manifest,
   defaultParams: DEFAULT_PARAMS,
   debugAnchor: "playerRight",
+  applyRootScale: false,
   debugParams: [
     { key: "lifetime", label: "生命周期", kind: "lifetime", min: 0.2, max: 6, step: 0.01 },
     { key: "color", label: "金光颜色", kind: "color" },
@@ -56,13 +57,13 @@ const buildingUpgradeEffectPackage = {
   ],
   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 footprintScale = normalizeBuildingUpgradeScale(scale);
+    const centerStrands = createStrandSystem(scene, root, params, footprintScale, "center");
+    const outlineStrands = createStrandSystem(scene, root, params, footprintScale, "outline");
+    const glow = createOutlineGlow(scene, root, params, footprintScale);
     const disposeTimer = window.setTimeout(
       () => disposeAll(),
-      Math.max(0.05, params.lifetime + getMaxStrandHeight(visualScale) / Math.max(0.1, params.riseSpeed) * 0.18 + 0.45) * 1e3
+      Math.max(0.05, params.lifetime + getMaxStrandHeight() / Math.max(0.1, params.riseSpeed) * 0.18 + 0.45) * 1e3
     );
     let disposed = false;
     centerStrands.start();
@@ -85,12 +86,12 @@ const buildingUpgradeEffectPackage = {
     }
   }
 };
-function createStrandSystem(scene, root, params, visualScale, mode) {
+function createStrandSystem(scene, root, params, footprintScale, 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(visualScale) : getOutlineHeight(visualScale);
-  const width = params.strandWidth * visualScale.horizontal * (mode === "center" ? 1.35 : 0.92);
+  const height = mode === "center" ? getCenterHeight() : getOutlineHeight();
+  const width = params.strandWidth * (mode === "center" ? 1.35 : 0.92);
   configureVfxParticleSystem(system);
   system.particleTexture = getGoldStrandTexture(scene);
   system.emitter = root;
@@ -126,7 +127,7 @@ function createStrandSystem(scene, root, params, visualScale, mode) {
   system.startPositionFunction = (worldMatrix, positionToUpdate, particle, isLocal) => {
     const index = particle.id + positionIndex;
     positionIndex += 1;
-    const local = mode === "center" ? sampleCenterPosition(index, params) : sampleOutlinePosition(index, params);
+    const local = mode === "center" ? sampleCenterPosition(index, params, footprintScale) : sampleOutlinePosition(index, params, footprintScale);
     if (isLocal) positionToUpdate.copyFrom(local);
     else Vector3.TransformCoordinatesToRef(local, worldMatrix, positionToUpdate);
   };
@@ -144,11 +145,11 @@ function createStrandSystem(scene, root, params, visualScale, mode) {
   };
   return system;
 }
-function createOutlineGlow(scene, root, params, visualScale) {
+function createOutlineGlow(scene, root, params, footprintScale) {
   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(visualScale) * 1.06;
-  const glowWidth = Math.max(0.04, BASE_GLOW_THICKNESS * visualScale.horizontal);
+  const height = getOutlineHeight() * 1.06;
+  const glowWidth = Math.max(0.04, BASE_GLOW_THICKNESS);
   const alpha = params.glowOpacity * params.opacity;
   configureVfxParticleSystem(system);
   system.particleTexture = getOutlineGlowTexture(scene);
@@ -185,7 +186,7 @@ function createOutlineGlow(scene, root, params, visualScale) {
   system.startPositionFunction = (worldMatrix, positionToUpdate, particle, isLocal) => {
     const index = particle.id + positionIndex + 31;
     positionIndex += 1;
-    const local = sampleOutlinePosition(index, params);
+    const local = sampleOutlinePosition(index, params, footprintScale);
     if (isLocal) positionToUpdate.copyFrom(local);
     else Vector3.TransformCoordinatesToRef(local, worldMatrix, positionToUpdate);
   };
@@ -203,13 +204,13 @@ function createOutlineGlow(scene, root, params, visualScale) {
   };
   return system;
 }
-function sampleCenterPosition(index, params) {
+function sampleCenterPosition(index, params, footprintScale) {
   const shape = getFootprintShape(params);
-  if (shape === "circle") return sampleCircleCenterPosition(index, params);
+  if (shape === "circle") return sampleCircleCenterPosition(index, params, footprintScale);
   const angle = sequence01(index, 0) * Math.PI * 2;
   const radius = Math.sqrt(0.16 + sequence01(index, 1) * 0.84);
-  const xRadius = getFootprintX() * 0.5 * params.centerSpread;
-  const zRadius = getFootprintZ() * 0.5 * params.centerSpread;
+  const xRadius = getFootprintX(footprintScale) * 0.5 * params.centerSpread;
+  const zRadius = getFootprintZ(footprintScale) * 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;
@@ -217,23 +218,24 @@ function sampleCenterPosition(index, params) {
   const y = sequence01(index, 2) * 0.12;
   return new Vector3(x, y, z);
 }
-function sampleOutlinePosition(index, params) {
+function sampleOutlinePosition(index, params, footprintScale) {
   const shape = getFootprintShape(params);
-  if (shape === "circle") return sampleCircleOutlinePosition(index, params);
-  return sampleRectOutlinePosition(index, getFootprintX(), getFootprintZ(), params.outlineThickness);
+  if (shape === "circle") return sampleCircleOutlinePosition(index, params, footprintScale);
+  return sampleRectOutlinePosition(index, getFootprintX(footprintScale), getFootprintZ(footprintScale), params.outlineThickness);
 }
-function sampleCircleCenterPosition(index, params) {
+function sampleCircleCenterPosition(index, params, footprintScale) {
   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 baseRadius = BASE_CIRCLE_RADIUS * footprintScale.horizontal;
+  const radius = Math.sqrt(sequence01(index, 1)) * baseRadius * params.centerSpread;
+  const jitterRadius = (sequence01(index, 7) - 0.5) * baseRadius * 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) {
+function sampleCircleOutlinePosition(index, params, footprintScale) {
   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 radius = Math.max(1e-3, BASE_CIRCLE_RADIUS * footprintScale.horizontal + jitter);
   const y = sequence01(index, 2) * 0.16;
   return new Vector3(Math.cos(angle) * radius, y, Math.sin(angle) * radius);
 }
@@ -251,28 +253,26 @@ function getFootprintShape(params) {
   if (params.footprintShape === "circle") return params.footprintShape;
   return "rectangle";
 }
-function getFootprintX() {
-  return BASE_FOOTPRINT_X;
+function getFootprintX(footprintScale) {
+  return BASE_FOOTPRINT_X * footprintScale.x;
 }
-function getFootprintZ() {
-  return BASE_FOOTPRINT_Z;
+function getFootprintZ(footprintScale) {
+  return BASE_FOOTPRINT_Z * footprintScale.z;
 }
-function getCenterHeight(visualScale) {
-  return BASE_CENTER_HEIGHT * visualScale.y;
+function getCenterHeight() {
+  return BASE_CENTER_HEIGHT;
 }
-function getOutlineHeight(visualScale) {
-  return BASE_OUTLINE_HEIGHT * visualScale.y;
+function getOutlineHeight() {
+  return BASE_OUTLINE_HEIGHT;
 }
-function getMaxStrandHeight(visualScale) {
-  return Math.max(getCenterHeight(visualScale), getOutlineHeight(visualScale));
+function getMaxStrandHeight() {
+  return Math.max(getCenterHeight(), getOutlineHeight());
 }
 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)
   };

package/dist/effects/wood_crusher_sawdust/index.d.ts

@@ -16,5 +16,6 @@ export declare const woodCrusherSawdustEffectPackage: {
     requiredInputs?: import('../..').VfxInputKey[];
     optionalInputs?: import('../..').VfxInputKey[];
     geometrySpace?: "local" | "world";
+    applyRootScale?: boolean;
     create(context: import('../..').VfxEffectPackageContext<import('../..').VfxParamValues>): import('../..').VfxEffectHandle;
 };

package/dist/effects/wood_cutter_sawdust/index.d.ts

@@ -16,5 +16,6 @@ export declare const woodCutterSawdustEffectPackage: {
     requiredInputs?: import('../..').VfxInputKey[];
     optionalInputs?: import('../..').VfxInputKey[];
     geometrySpace?: "local" | "world";
+    applyRootScale?: boolean;
     create(context: import('../..').VfxEffectPackageContext<import('../..').VfxParamValues>): import('../..').VfxEffectHandle;
 };

package/dist/index.js

@@ -114,7 +114,8 @@ class EffectPackageService {
     warnMissingRequiredInputs(effectId, effectPackage.requiredInputs, spawn.inputs);
     const runtimeParams = stripSpawnParams(params, effectPackage.spawnParams);
     const root = new TransformNode(`vfx_package_${effectId}`, this.scene);
-    applySpawnToRoot(root, spawn);
+    const applyRootScale = effectPackage.applyRootScale !== false;
+    applySpawnToRoot(root, spawn, applyRootScale);
     const worldPosition = root.getAbsolutePosition().clone();
     let handle;
     try {
@@ -128,7 +129,7 @@ class EffectPackageService {
         scale: spawn.scale,
         inputs: spawn.inputs
       });
-      applySpawnToRoot(root, spawn);
+      applySpawnToRoot(root, spawn, applyRootScale);
     } catch (error) {
       console.warn(`[EffectPackageService] effect "${effectId}" create() failed; skipped.`, error);
       try {
@@ -212,10 +213,11 @@ function warnMissingRequiredInputs(effectId, required, inputs) {
     console.warn(`[EffectPackageService] effect "${effectId}" 声明 requiredInputs [${missing.join(", ")}] 但未提供 → 可能静默降级。`);
   }
 }
-function applySpawnToRoot(root, spawn) {
+function applySpawnToRoot(root, spawn, applyRootScale = true) {
   if (spawn.parent) root.parent = spawn.parent;
   root.rotation.copyFrom(spawn.rotation);
-  root.scaling.copyFrom(spawn.scale);
+  if (applyRootScale) root.scaling.copyFrom(spawn.scale);
+  else root.scaling.set(1, 1, 1);
   if (spawn.parent && !spawn.offsetIsLocal) {
     root.computeWorldMatrix(true);
     root.setAbsolutePosition(spawn.position);

package/dist/types.d.ts

@@ -157,6 +157,12 @@ export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValue
      * 默认随 placement 推断('socket'→local,其余→world)。
      */
     geometrySpace?: 'local' | 'world';
+    /**
+     * 是否把 spawnTransform.scale 应用到 root.scaling。默认 true。
+     * 对需要自行解释 scale 的特效(例如只把 scale 当作发射 footprint 尺寸)可设为 false,
+     * 此时 service 仍会把 scale 传入 create(context.scale),但 root 保持单位缩放。
+     */
+    applyRootScale?: boolean;
     /**
      * 构建特效。**约定(G6):root 的 transform(position/rotation/scaling/parent)归 service 独占** ——
      * service 在 create() 后会二次 `applySpawnToRoot` 覆盖,create 内写 `root.position/rotation/scaling` 会被静默清掉。

package/package.json

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