@fps-games/vfx 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -12,6 +12,22 @@
 
 <!-- release.mjs 在此行下方插入新版本区块 -->
 
+## v0.3.9 — 2026-07-03
+
+### 改动
+- feat: add magnet suction effect
+
+### 特效
+- 新增:magnet-suction
+
+## 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/magnet-suction/effect.json.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+  "id": "magnet-suction",
+  "nameZh": "磁铁吸入线",
+  "assets": [],
+  "source": "procedural"
+}
+;
+
+export default _default;

package/dist/effects/magnet-suction/index.d.ts

@@ -0,0 +1,35 @@
+import { VfxColorValue, VfxEffectPackage, VfxParamValues } from '../../types';
+interface MagnetSuctionParams extends VfxParamValues {
+    lifetimeMode: string;
+    lifetime: number;
+    scale: number;
+    initialHeight: number;
+    color: VfxColorValue;
+    opacity: number;
+    intensity: number;
+    forwardOffset: number;
+    suctionLength: number;
+    startRadius: number;
+    spreadY: number;
+    endRadius: number;
+    mouthPadding: number;
+    fadeDistance: number;
+    spawnFade: number;
+    suctionSpeed: number;
+    lineCount: number;
+    lineLength: number;
+    lineWidth: number;
+    lineOpacity: number;
+    lineSpread: number;
+    lineTwist: number;
+    particleCount: number;
+    particleSize: number;
+    particleSpeed: number;
+    particleDrift: number;
+    particleOuterOffset: number;
+    particleOpacity: number;
+    directionX: number;
+    directionZ: number;
+}
+export declare const magnetSuctionEffectPackage: VfxEffectPackage<MagnetSuctionParams>;
+export default magnetSuctionEffectPackage;

package/dist/effects/magnet-suction/index.js

@@ -0,0 +1,419 @@
+import { Constants } from "@babylonjs/core/Engines/constants";
+import { ShaderStore } from "@babylonjs/core/Engines/shaderStore";
+import { Color3 } from "@babylonjs/core/Maths/math.color";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector";
+import { VertexBuffer } from "@babylonjs/core/Buffers/buffer";
+import { Material } from "@babylonjs/core/Materials/material";
+import { ShaderMaterial } from "@babylonjs/core/Materials/shaderMaterial";
+import { Mesh } from "@babylonjs/core/Meshes/mesh";
+import { VertexData } from "@babylonjs/core/Meshes/mesh.vertexData";
+import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
+import { V as VFX_RENDERING_GROUP_ID } from "../../chunks/rendering-CV3nhygX.js";
+import { s as scheduleLifetime } from "../../chunks/space-shared-BXV1hc0k.js";
+const id = "magnet-suction";
+const nameZh = "磁铁吸入线";
+const assets = [];
+const source = "procedural";
+const manifest = {
+  id,
+  nameZh,
+  assets,
+  source
+};
+const DEFAULT_PARAMS = {
+  lifetimeMode: "infinite",
+  lifetime: 2.5,
+  scale: 1.15,
+  initialHeight: 0,
+  color: { r: 0.82, g: 0.95, b: 1 },
+  opacity: 1,
+  intensity: 1,
+  forwardOffset: 0,
+  suctionLength: 2.25,
+  startRadius: 0.7,
+  spreadY: 0.34,
+  endRadius: 0.08,
+  mouthPadding: 0.18,
+  fadeDistance: 0.58,
+  spawnFade: 0.45,
+  suctionSpeed: 1.65,
+  lineCount: 32,
+  lineLength: 0.46,
+  lineWidth: 0.045,
+  lineOpacity: 1,
+  lineSpread: 1,
+  lineTwist: 0,
+  particleCount: 14,
+  particleSize: 0.032,
+  particleSpeed: 2.15,
+  particleDrift: 0,
+  particleOuterOffset: 0,
+  particleOpacity: 0.55,
+  directionX: 0,
+  directionZ: -1
+};
+const magnetSuctionEffectPackage = {
+  id: "magnet-suction",
+  nameZh: "磁铁吸入线",
+  placement: "socket",
+  geometrySpace: "local",
+  manifest,
+  defaultParams: DEFAULT_PARAMS,
+  debugAnchor: "playerRight",
+  debugParams: [
+    { key: "lifetimeMode", label: "生命周期模式", kind: "enum", options: [
+      { value: "infinite", label: "无限" },
+      { value: "duration", label: "自定义时间" }
+    ] },
+    { key: "lifetime", label: "自定义时长", kind: "lifetime", min: 0.1, max: 30, step: 0.01 },
+    { key: "scale", label: "整体缩放", kind: "scale", min: 0.05, max: 6, step: 0.01 },
+    { key: "initialHeight", label: "局部高度", kind: "number", min: -2, max: 4, step: 0.01 },
+    { key: "color", label: "吸入颜色", kind: "color" },
+    { key: "opacity", label: "整体透明度", kind: "opacity", min: 0, max: 1, step: 0.01 },
+    { key: "intensity", label: "强度", kind: "opacity", min: 0, max: 1, step: 0.01 },
+    { key: "forwardOffset", label: "入口前偏移", kind: "number", min: -2, max: 4, step: 0.01 },
+    { key: "suctionLength", label: "远近长度", kind: "number", min: 0.1, max: 8, step: 0.01 },
+    { key: "startRadius", label: "远处横向半径", kind: "number", min: 0.02, max: 5, step: 0.01 },
+    { key: "spreadY", label: "远处纵向半径", kind: "number", min: 0.02, max: 4, step: 0.01 },
+    { key: "endRadius", label: "近处半径", kind: "number", min: 0, max: 2, step: 0.01 },
+    { key: "mouthPadding", label: "入口保护距离", kind: "number", min: 0.01, max: 2, step: 0.01 },
+    { key: "fadeDistance", label: "入口淡出距离", kind: "number", min: 0.01, max: 3, step: 0.01 },
+    { key: "spawnFade", label: "外侧淡入距离", kind: "number", min: 0.01, max: 3, step: 0.01 },
+    { key: "suctionSpeed", label: "线条速度", kind: "number", min: 0, max: 8, step: 0.01 },
+    { key: "lineCount", label: "白线数量", kind: "number", min: 0, max: 96, step: 1 },
+    { key: "lineLength", label: "白线长度", kind: "number", min: 0.02, max: 2, step: 0.01 },
+    { key: "lineWidth", label: "白线尾宽", kind: "number", min: 2e-3, max: 0.18, step: 1e-3 },
+    { key: "lineOpacity", label: "白线透明度", kind: "opacity", min: 0, max: 1.5, step: 0.01 },
+    { key: "lineSpread", label: "散布缩放", kind: "number", min: 0.1, max: 2, step: 0.01 },
+    { key: "particleCount", label: "粒子数量", kind: "number", min: 0, max: 80, step: 1 },
+    { key: "particleSize", label: "粒子大小", kind: "number", min: 5e-3, max: 0.3, step: 1e-3 },
+    { key: "particleSpeed", label: "粒子速度", kind: "number", min: 0, max: 10, step: 0.01 },
+    { key: "particleOpacity", label: "粒子透明度", kind: "opacity", min: 0, max: 1, step: 0.01 },
+    { key: "directionX", label: "吸入方向 X", kind: "number", min: -1, max: 1, step: 0.01 },
+    { key: "directionZ", label: "吸入方向 Z", kind: "number", min: -1, max: 1, step: 0.01 }
+  ],
+  create({ scene, root, params, renderingGroupId }) {
+    const fieldRoot = new TransformNode("magnet-suction.root", scene);
+    fieldRoot.parent = root;
+    fieldRoot.position.set(0, params.initialHeight, 0);
+    const effect = createMagnetSuctionField(scene, fieldRoot, params, renderingGroupId ?? VFX_RENDERING_GROUP_ID);
+    let disposed = false;
+    let lifetimeTimer = 0;
+    effect.start();
+    lifetimeTimer = scheduleLifetime(params, disposeAll);
+    return {
+      root,
+      dispose: disposeAll
+    };
+    function disposeAll() {
+      if (disposed) return;
+      disposed = true;
+      if (lifetimeTimer) window.clearTimeout(lifetimeTimer);
+      effect.dispose();
+      fieldRoot.dispose();
+      root.dispose();
+    }
+  }
+};
+function createMagnetSuctionField(scene, root, params, renderingGroupId) {
+  const material = createSuctionMaterial(scene);
+  const mesh = createSuctionMesh(scene, root, params, material, renderingGroupId);
+  let observer = null;
+  let disposed = false;
+  return { start, dispose };
+  function start() {
+    if (observer) return;
+    observer = scene.onBeforeRenderObservable.add(() => {
+      if (disposed) return;
+      const deltaSeconds = Math.min(0.05, scene.getEngine().getDeltaTime() / 1e3);
+      mesh.update(deltaSeconds);
+    });
+  }
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (observer) scene.onBeforeRenderObservable.remove(observer);
+    observer = null;
+    mesh.dispose();
+    material.dispose();
+  }
+}
+function createSuctionMesh(scene, root, params, material, renderingGroupId) {
+  const lineCount = Math.max(0, Math.round(params.lineCount));
+  const particleCount = Math.max(0, Math.round(params.particleCount));
+  const lineVertexCount = lineCount * 3;
+  const particleVertexCount = particleCount * 4;
+  const totalVertexCount = lineVertexCount + particleVertexCount;
+  const positions = new Float32Array(totalVertexCount * 3);
+  const colors = new Float32Array(totalVertexCount * 4);
+  const indices = [];
+  const lines = [];
+  const particles = [];
+  let resetIndex = 1;
+  for (let index = 0; index < lineCount; index += 1) {
+    const base = index * 3;
+    indices.push(base, base + 1, base + 2);
+    lines.push(resetLine({}, true));
+  }
+  for (let index = 0; index < particleCount; index += 1) {
+    const base = lineVertexCount + index * 4;
+    indices.push(base, base + 1, base + 2, base, base + 2, base + 3);
+    particles.push(resetParticle({}, true));
+  }
+  const mesh = new Mesh("magnet-suction.mesh", scene);
+  mesh.parent = root;
+  mesh.material = material;
+  mesh.hasVertexAlpha = true;
+  mesh.useVertexColors = true;
+  mesh.alwaysSelectAsActiveMesh = true;
+  mesh.renderingGroupId = renderingGroupId;
+  mesh.isPickable = false;
+  const vertexData = new VertexData();
+  vertexData.positions = positions;
+  vertexData.colors = colors;
+  vertexData.indices = indices;
+  vertexData.applyToMesh(mesh, true);
+  writeGeometry();
+  return { update, dispose };
+  function update(deltaSeconds) {
+    const basis = createSuctionBasis(params);
+    for (const line of lines) {
+      line.d -= line.speed * deltaSeconds;
+      if (line.d < basis.mouthPadding) resetLine(line, false);
+    }
+    for (const particle of particles) {
+      particle.d -= particle.speed * deltaSeconds;
+      if (particle.d < basis.mouthPadding) resetParticle(particle, false);
+    }
+    writeGeometry();
+  }
+  function dispose() {
+    mesh.dispose();
+  }
+  function writeGeometry() {
+    const basis = createSuctionBasis(params);
+    const cameraBasis = createCameraBasis(scene, root, basis);
+    const color = toColor3(params.color);
+    const alphaScale = clamp01(params.opacity) * Math.max(0, params.intensity);
+    let vertexIndex = 0;
+    const putVertex = (position, alpha, brightness = 1) => {
+      const positionOffset = vertexIndex * 3;
+      const colorOffset = vertexIndex * 4;
+      positions[positionOffset] = position.x;
+      positions[positionOffset + 1] = position.y;
+      positions[positionOffset + 2] = position.z;
+      colors[colorOffset] = clamp01(color.r * brightness);
+      colors[colorOffset + 1] = clamp01(color.g * brightness);
+      colors[colorOffset + 2] = clamp01(color.b * brightness);
+      colors[colorOffset + 3] = clamp01(alpha * alphaScale);
+      vertexIndex += 1;
+    };
+    for (const line of lines) {
+      const alpha = lineFade(line.d, basis) * params.lineOpacity * line.alphaMul;
+      const headD = Math.max(basis.mouthPadding, line.d);
+      const tailD = Math.min(basis.length, line.d + line.len);
+      const head = suctionPosition(headD, line.u, line.v, basis);
+      const tail = suctionPosition(tailD, line.u, line.v, basis);
+      const shrink = Math.max(lateralScale(headD, basis), 0.18);
+      const half = cameraBasis.ribbonSide.scale(line.width * shrink * 0.5);
+      putVertex(tail.subtract(half), alpha, line.brightness);
+      putVertex(tail.add(half), alpha * 0.92, line.brightness);
+      putVertex(head, alpha * 0.22, line.brightness);
+    }
+    for (const particle of particles) {
+      const alpha = lineFade(particle.d, basis) * params.particleOpacity * particle.alphaMul;
+      const center = suctionPosition(particle.d, particle.u, particle.v, basis);
+      const shrink = Math.max(lateralScale(particle.d, basis), 0.22);
+      const right = cameraBasis.particleRight.scale(particle.size * shrink);
+      const up = cameraBasis.particleUp.scale(particle.size * shrink * 0.7);
+      putVertex(center.subtract(right).subtractInPlace(up), alpha, particle.brightness);
+      putVertex(center.add(right).subtractInPlace(up), alpha, particle.brightness);
+      putVertex(center.add(right).addInPlace(up), alpha * 0.8, particle.brightness);
+      putVertex(center.subtract(right).addInPlace(up), alpha * 0.8, particle.brightness);
+    }
+    mesh.updateVerticesData(VertexBuffer.PositionKind, positions, false, false);
+    mesh.updateVerticesData(VertexBuffer.ColorKind, colors, false, false);
+  }
+  function resetLine(line, initial) {
+    const basis = createSuctionBasis(params);
+    line.d = initial ? randomRange(basis.mouthPadding + 0.05, basis.length) : basis.length + randomRange(0, basis.spawnFade);
+    line.u = randomRange(-basis.spreadX * 0.5, basis.spreadX * 0.5);
+    line.v = randomRange(-basis.spreadY * 0.5, basis.spreadY * 0.5);
+    line.len = randomRange(basis.lineLength * 0.65, basis.lineLength * 1.35);
+    line.width = randomRange(basis.lineWidth * 0.65, basis.lineWidth * 1.35);
+    line.speed = Math.max(0, params.suctionSpeed * Math.max(0.01, params.scale)) * randomRange(0.78, 1.25);
+    line.alphaMul = randomRange(0.65, 1);
+    line.brightness = randomRange(0.82, 1);
+    return line;
+  }
+  function resetParticle(particle, initial) {
+    const basis = createSuctionBasis(params);
+    particle.d = initial ? randomRange(basis.mouthPadding + 0.05, basis.length) : basis.length + randomRange(0, basis.spawnFade);
+    particle.u = randomRange(-basis.spreadX * 0.55, basis.spreadX * 0.55);
+    particle.v = randomRange(-basis.spreadY * 0.55, basis.spreadY * 0.55);
+    particle.size = randomRange(basis.particleSize * 0.45, basis.particleSize * 1.15);
+    particle.speed = Math.max(0, params.particleSpeed * Math.max(0.01, params.scale)) * randomRange(0.75, 1.35);
+    particle.alphaMul = randomRange(0.35, 0.9);
+    particle.brightness = randomRange(0.75, 1);
+    return particle;
+  }
+  function randomRange(min, max) {
+    const id2 = resetIndex;
+    resetIndex += 1;
+    return lerp(min, max, sequence01(id2, resetIndex % 8));
+  }
+}
+function createSuctionBasis(params) {
+  const scale = Math.max(0.01, params.scale);
+  const axis = new Vector3(params.directionX, 0, params.directionZ);
+  if (axis.lengthSquared() < 1e-4) axis.set(0, 0, 1);
+  axis.normalize();
+  let up = Vector3.Up();
+  if (Math.abs(Vector3.Dot(up, axis)) > 0.94) up = Vector3.Forward();
+  let right = Vector3.Cross(up, axis);
+  if (right.lengthSquared() < 1e-4) right = Vector3.Right();
+  right.normalize();
+  let realUp = Vector3.Cross(axis, right);
+  if (realUp.lengthSquared() < 1e-4) realUp = Vector3.Up();
+  realUp.normalize();
+  const lineSpread = Math.max(0.1, params.lineSpread);
+  const length = Math.max(0.01, params.suctionLength * scale);
+  const mouthPadding = Math.max(1e-3, (params.mouthPadding || params.endRadius || 0.12) * scale);
+  const outerRadius = Math.max(1e-3, Math.max(params.startRadius, params.spreadY) * lineSpread * scale);
+  const endRadius = Math.max(0, params.endRadius * scale);
+  return {
+    axis,
+    right,
+    up: realUp,
+    mouth: axis.scale(params.forwardOffset * scale),
+    length,
+    spreadX: Math.max(1e-3, params.startRadius * lineSpread * scale),
+    spreadY: Math.max(1e-3, params.spreadY * lineSpread * scale),
+    mouthPadding: Math.min(length, mouthPadding),
+    fadeDistance: Math.max(1e-3, params.fadeDistance * scale),
+    spawnFade: Math.max(1e-3, params.spawnFade * scale),
+    endRadiusRatio: clamp01(endRadius / outerRadius),
+    lineLength: Math.max(0.01, params.lineLength * scale),
+    lineWidth: Math.max(1e-3, params.lineWidth * scale),
+    particleSize: Math.max(1e-3, params.particleSize * scale)
+  };
+}
+function suctionPosition(distance, u, v, basis) {
+  const laneScale = lateralScale(distance, basis);
+  const lane = basis.right.scale(u * laneScale).addInPlace(basis.up.scale(v * laneScale));
+  return basis.mouth.subtract(basis.axis.scale(distance)).addInPlace(lane);
+}
+function lateralScale(distance, basis) {
+  const travel = clamp01((distance - basis.mouthPadding) / Math.max(1e-5, basis.length - basis.mouthPadding));
+  const eased = travel * travel;
+  return lerp(basis.endRadiusRatio, 1, eased);
+}
+function createCameraBasis(scene, root, basis) {
+  let ribbonSide = basis.right.clone();
+  let particleRight = basis.right.clone();
+  let particleUp = basis.up.clone();
+  const camera = scene.activeCamera;
+  if (camera) {
+    const cameraPosition = camera.globalPosition ?? camera.position;
+    if (cameraPosition) {
+      const inverseRoot = root.getWorldMatrix().clone();
+      inverseRoot.invert();
+      const localCameraPosition = Vector3.TransformCoordinates(cameraPosition, inverseRoot);
+      const view = localCameraPosition.subtract(basis.mouth);
+      if (view.lengthSquared() > 1e-4) {
+        view.normalize();
+        const side = Vector3.Cross(basis.axis, view);
+        if (side.lengthSquared() > 1e-4) {
+          side.normalize();
+          ribbonSide = side;
+        }
+      }
+    }
+    if (camera.getDirection) {
+      const inverseRoot = root.getWorldMatrix().clone();
+      inverseRoot.invert();
+      const worldRight = camera.getDirection(Vector3.Right());
+      const worldUp = camera.getDirection(Vector3.Up());
+      const localRight = Vector3.TransformNormal(worldRight, inverseRoot);
+      const localUp = Vector3.TransformNormal(worldUp, inverseRoot);
+      if (localRight.lengthSquared() > 1e-4) {
+        localRight.normalize();
+        particleRight = localRight;
+      }
+      if (localUp.lengthSquared() > 1e-4) {
+        localUp.normalize();
+        particleUp = localUp;
+      }
+    }
+  }
+  return { ribbonSide, particleRight, particleUp };
+}
+function createSuctionMaterial(scene) {
+  registerSuctionShaders();
+  const material = new ShaderMaterial("magnet-suction.material", scene, {
+    vertex: "magnetSuction",
+    fragment: "magnetSuction"
+  }, {
+    attributes: ["position", "color"],
+    uniforms: ["worldViewProjection"],
+    needAlphaBlending: true
+  });
+  material.backFaceCulling = false;
+  material.transparencyMode = Material.MATERIAL_ALPHABLEND;
+  material.alphaMode = Constants.ALPHA_COMBINE;
+  material.disableDepthWrite = true;
+  return material;
+}
+function registerSuctionShaders() {
+  if (!ShaderStore.ShadersStore.magnetSuctionVertexShader) {
+    ShaderStore.ShadersStore.magnetSuctionVertexShader = `
+      precision highp float;
+      attribute vec3 position;
+      attribute vec4 color;
+      uniform mat4 worldViewProjection;
+      varying vec4 vColor;
+      void main(void) {
+        gl_Position = worldViewProjection * vec4(position, 1.0);
+        vColor = color;
+      }
+    `;
+  }
+  if (!ShaderStore.ShadersStore.magnetSuctionFragmentShader) {
+    ShaderStore.ShadersStore.magnetSuctionFragmentShader = `
+      precision highp float;
+      varying vec4 vColor;
+      void main(void) {
+        if (vColor.a <= 0.01) discard;
+        gl_FragColor = vColor;
+      }
+    `;
+  }
+}
+function lineFade(distance, basis) {
+  const mouthFade = smoothstep(basis.mouthPadding, basis.mouthPadding + basis.fadeDistance, distance);
+  const clampedDistance = Math.min(distance, basis.length);
+  const outerFade = smoothstep(0, basis.spawnFade, basis.length - clampedDistance);
+  return mouthFade * outerFade;
+}
+function toColor3(color) {
+  return new Color3(clamp01(color.r), clamp01(color.g), clamp01(color.b));
+}
+function lerp(min, max, t) {
+  return min + (max - min) * t;
+}
+function clamp01(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function smoothstep(edge0, edge1, value) {
+  const t = clamp01((value - edge0) / Math.max(1e-5, edge1 - edge0));
+  return t * t * (3 - 2 * t);
+}
+function sequence01(index, axis) {
+  if (index === 0) return 0.5;
+  const strides = [0.618033988749895, 0.414213562373095, 0.732050807568877, 0.324717957244746, 0.754877666246693, 0.569840290998053, 0.438744359656398, 0.280776406404415];
+  return (0.5 + index * strides[axis % strides.length] + axis * 0.173205080756888) % 1;
+}
+export {
+  magnetSuctionEffectPackage as default,
+  magnetSuctionEffectPackage
+};

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/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "vfx-index/1.0",
-  "count": 37,
+  "count": 38,
   "effects": [
     {
       "id": "build.particle.lumber_debris_scatter",
@@ -217,6 +217,16 @@
       "media": {},
       "path": "packages/effects/lumber-cart-suction"
     },
+    {
+      "id": "magnet-suction",
+      "dir": "magnet-suction",
+      "nameZh": "磁铁吸入线",
+      "kind": "code",
+      "category": "magnet-suction",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/magnet-suction"
+    },
     {
       "id": "monster-hit",
       "dir": "monster-hit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fps-games/vfx",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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/magnet-suction/vfx-params.json

@@ -0,0 +1,36 @@
+{
+  "lifetimeMode": "infinite",
+  "lifetime": 2.5,
+  "scale": 1.15,
+  "initialHeight": 0,
+  "color": {
+    "r": 0.82,
+    "g": 0.95,
+    "b": 1
+  },
+  "opacity": 1,
+  "intensity": 1,
+  "forwardOffset": 0,
+  "suctionLength": 2.25,
+  "startRadius": 0.7,
+  "spreadY": 0.34,
+  "endRadius": 0.08,
+  "mouthPadding": 0.18,
+  "fadeDistance": 0.58,
+  "spawnFade": 0.45,
+  "suctionSpeed": 1.65,
+  "lineCount": 32,
+  "lineLength": 0.46,
+  "lineWidth": 0.045,
+  "lineOpacity": 1,
+  "lineSpread": 1,
+  "lineTwist": 0,
+  "particleCount": 14,
+  "particleSize": 0.032,
+  "particleSpeed": 2.15,
+  "particleDrift": 0,
+  "particleOuterOffset": 0,
+  "particleOpacity": 0.55,
+  "directionX": 0,
+  "directionZ": -1
+}