@fps-games/vfx 0.1.1

package/packages/effects/ground-tile-upgrade/index.ts

@@ -0,0 +1,410 @@
+import { Color4 } from '@babylonjs/core/Maths/math.color';
+import { Matrix, Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { Particle } from '@babylonjs/core/Particles/particle';
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import type { Scene } from '@babylonjs/core/scene';
+import type { VfxColorValue, VfxEffectPackage, VfxParamValues } from '../../types';
+import { configureVfxParticleSystem } from '../../rendering';
+import manifest from './effect.json';
+
+interface GroundTileUpgradeParams extends VfxParamValues {
+  lifetime: number;
+  scale: number;
+  initialHeight: number;
+  color: VfxColorValue;
+  opacity: number;
+  scaleX: number;
+  scaleY: number;
+  scaleZ: number;
+  centerCount: number;
+  outlineCount: number;
+  strandWidth: number;
+  riseSpeed: number;
+  centerSpread: number;
+  outlineThickness: number;
+  glowOpacity: number;
+}
+
+const BASE_FOOTPRINT_X = 3.2;
+const BASE_FOOTPRINT_Z = 2.6;
+const BASE_CENTER_HEIGHT = 2.2;
+const BASE_OUTLINE_HEIGHT = 3.1;
+const BASE_GLOW_THICKNESS = 0.38;
+
+const DEFAULT_PARAMS: GroundTileUpgradeParams = {
+  lifetime: 1.8,
+  scale: 1,
+  initialHeight: 0.02,
+  color: { r: 1, g: 0.84, b: 0.12 },
+  opacity: 1,
+  scaleX: 0.82,
+  scaleY: 0.24,
+  scaleZ: 0.82,
+  centerCount: 46,
+  outlineCount: 150,
+  strandWidth: 0.035,
+  riseSpeed: 1.15,
+  centerSpread: 0.92,
+  outlineThickness: 0.18,
+  glowOpacity: 0.62,
+};
+
+export const groundTileUpgradeEffectPackage: VfxEffectPackage<GroundTileUpgradeParams> = {
+  id: 'ground-tile-upgrade',
+  nameZh: '地块升级光效',
+  manifest,
+  defaultParams: DEFAULT_PARAMS,
+  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: '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: 0.005, max: 0.2, step: 0.001 },
+    { key: 'riseSpeed', label: '上升速度', kind: 'number', min: 0, max: 5, step: 0.01 },
+    { key: 'centerSpread', label: '中心散布', kind: 'number', min: 0, max: 1.5, step: 0.01 },
+    { 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);
+    let disposed = false;
+    const disposeTimer = window.setTimeout(
+      () => disposeAll(),
+      Math.max(0.05, params.lifetime + getMaxStrandHeight(params) / Math.max(0.1, params.riseSpeed) * 0.18 + 0.45) * 1000,
+    );
+
+    centerStrands.start();
+    outlineStrands.start();
+    glow.start();
+
+    return {
+      root,
+      dispose() {
+        disposeAll();
+      },
+    };
+
+    function disposeAll(): void {
+      if (disposed) return;
+      disposed = true;
+      window.clearTimeout(disposeTimer);
+      centerStrands.dispose(false);
+      outlineStrands.dispose(false);
+      glow.dispose(false);
+      root.dispose();
+    }
+  },
+};
+
+function createStrandSystem(
+  scene: Scene,
+  root: TransformNode,
+  params: GroundTileUpgradeParams,
+  mode: 'center' | 'outline',
+): ParticleSystem {
+  const count = Math.max(0, Math.round(mode === 'center' ? params.centerCount : params.outlineCount));
+  const system = new ParticleSystem(`ground-tile-upgrade.${mode}-strands`, Math.max(1, count), scene);
+  const color = params.color;
+  const brightColor = getBrightColor(color);
+  const height = mode === 'center' ? getCenterHeight(params) : getOutlineHeight(params);
+  const width = params.strandWidth * getHorizontalScale(params) * (mode === 'center' ? 1.35 : 0.92);
+
+  configureVfxParticleSystem(system);
+  system.particleTexture = getStrandTexture(scene);
+  system.emitter = root as any;
+  system.manualEmitCount = count;
+  system.emitRate = count * 60;
+  system.disposeOnStop = false;
+  system.updateSpeed = 1 / 60;
+  system.minLifeTime = Math.max(0.12, params.lifetime * (mode === 'center' ? 0.48 : 0.62));
+  system.maxLifeTime = Math.max(system.minLifeTime + 0.01, params.lifetime * (mode === 'center' ? 0.86 : 1.08));
+  system.minSize = Math.max(0.01, height * 0.34);
+  system.maxSize = Math.max(system.minSize, height * (mode === 'center' ? 0.72 : 0.98));
+  system.minScaleX = Math.max(0.02, width);
+  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.blendMode = ParticleSystem.BLENDMODE_ADD;
+  system.color1 = toColor4(color, params.opacity * (mode === 'center' ? 0.72 : 0.86));
+  system.color2 = toColor4(brightColor, params.opacity);
+  system.colorDead = toColor4(color, 0);
+  system.addColorGradient(0, toColor4(color, 0));
+  system.addColorGradient(0.12, toColor4(brightColor, params.opacity));
+  system.addColorGradient(0.72, toColor4(color, params.opacity * 0.62));
+  system.addColorGradient(1, toColor4(color, 0));
+  system.addVelocityGradient(0, 1);
+  system.addVelocityGradient(0.65, 0.55);
+  system.addVelocityGradient(1, 0.12);
+
+  let positionIndex = 0;
+  let directionIndex = 0;
+  system.startPositionFunction = (worldMatrix: Matrix, positionToUpdate: Vector3, particle: Particle, isLocal: boolean) => {
+    const index = particle.id + positionIndex;
+    positionIndex += 1;
+    const local = mode === 'center'
+      ? sampleCenterPosition(index, params)
+      : sampleOutlinePosition(index, params);
+    if (isLocal) positionToUpdate.copyFrom(local);
+    else Vector3.TransformCoordinatesToRef(local, worldMatrix, positionToUpdate);
+  };
+  system.startDirectionFunction = (worldMatrix: Matrix, directionToUpdate: Vector3, particle: Particle, isLocal: boolean) => {
+    const index = particle.id + directionIndex;
+    directionIndex += 1;
+    const sway = (mode === 'center' ? 0.22 : 0.12) * getHorizontalScale(params);
+    const local = new Vector3(
+      (sequence01(index, 4) - 0.5) * sway,
+      0.8 + sequence01(index, 5) * 0.65,
+      (sequence01(index, 6) - 0.5) * sway,
+    );
+    if (isLocal) directionToUpdate.copyFrom(local);
+    else Vector3.TransformNormalToRef(local, worldMatrix, directionToUpdate);
+  };
+
+  return system;
+}
+
+function createOutlineGlow(scene: Scene, root: TransformNode, params: GroundTileUpgradeParams): ParticleSystem {
+  const count = Math.max(1, Math.round(params.outlineCount * 0.82));
+  const system = new ParticleSystem('ground-tile-upgrade.outline-glow-rays', count, scene);
+  const height = getOutlineHeight(params) * 1.06;
+  const glowWidth = Math.max(0.04, BASE_GLOW_THICKNESS * getHorizontalScale(params));
+  const alpha = params.glowOpacity * params.opacity;
+  const brightColor = getBrightColor(params.color);
+
+  configureVfxParticleSystem(system);
+  system.particleTexture = getOutlineGlowTexture(scene);
+  system.emitter = root as any;
+  system.manualEmitCount = count;
+  system.emitRate = count * 60;
+  system.disposeOnStop = false;
+  system.updateSpeed = 1 / 60;
+  system.minLifeTime = Math.max(0.12, params.lifetime * 0.62);
+  system.maxLifeTime = Math.max(system.minLifeTime + 0.01, params.lifetime * 1.08);
+  system.minSize = Math.max(0.01, height * 0.42);
+  system.maxSize = Math.max(system.minSize, height * 1.08);
+  system.minScaleX = glowWidth * 0.42;
+  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.blendMode = ParticleSystem.BLENDMODE_ADD;
+  system.color1 = toColor4(params.color, alpha * 0.62);
+  system.color2 = toColor4(brightColor, alpha * 0.86);
+  system.colorDead = toColor4(params.color, 0);
+  system.addColorGradient(0, toColor4(params.color, 0));
+  system.addColorGradient(0.1, toColor4(brightColor, alpha * 0.82));
+  system.addColorGradient(0.56, toColor4(params.color, alpha * 0.52));
+  system.addColorGradient(1, toColor4(params.color, 0));
+  system.addVelocityGradient(0, 1);
+  system.addVelocityGradient(0.65, 0.52);
+  system.addVelocityGradient(1, 0.12);
+
+  let positionIndex = 0;
+  let directionIndex = 0;
+  system.startPositionFunction = (worldMatrix: Matrix, positionToUpdate: Vector3, particle: Particle, isLocal: boolean) => {
+    const index = particle.id + positionIndex + 31;
+    positionIndex += 1;
+    const local = sampleOutlinePosition(index, params);
+    if (isLocal) positionToUpdate.copyFrom(local);
+    else Vector3.TransformCoordinatesToRef(local, worldMatrix, positionToUpdate);
+  };
+  system.startDirectionFunction = (worldMatrix: Matrix, directionToUpdate: Vector3, particle: Particle, isLocal: boolean) => {
+    const index = particle.id + directionIndex + 31;
+    directionIndex += 1;
+    const sway = 0.08 * getHorizontalScale(params);
+    const local = new Vector3(
+      (sequence01(index, 4) - 0.5) * sway,
+      0.82 + sequence01(index, 5) * 0.58,
+      (sequence01(index, 6) - 0.5) * sway,
+    );
+    if (isLocal) directionToUpdate.copyFrom(local);
+    else Vector3.TransformNormalToRef(local, worldMatrix, directionToUpdate);
+  };
+
+  return system;
+}
+
+function sampleCenterPosition(index: number, params: GroundTileUpgradeParams): Vector3 {
+  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 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);
+  return new Vector3(x, y, z);
+}
+
+function sampleOutlinePosition(index: number, params: GroundTileUpgradeParams): Vector3 {
+  const width = getFootprintX(params);
+  const depth = getFootprintZ(params);
+  const perimeter = Math.max(0.001, 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);
+
+  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: GroundTileUpgradeParams): number {
+  return BASE_FOOTPRINT_X * Math.max(0.05, params.scale) * Math.max(0.05, params.scaleX);
+}
+
+function getFootprintZ(params: GroundTileUpgradeParams): number {
+  return BASE_FOOTPRINT_Z * Math.max(0.05, params.scale) * Math.max(0.05, params.scaleZ);
+}
+
+function getVerticalScale(params: GroundTileUpgradeParams): number {
+  return Math.max(0.05, params.scale) * Math.max(0.05, params.scaleY);
+}
+
+function getHorizontalScale(params: GroundTileUpgradeParams): number {
+  return Math.max(0.05, params.scale) * Math.max(0.05, (params.scaleX + params.scaleZ) * 0.5);
+}
+
+function getCenterHeight(params: GroundTileUpgradeParams): number {
+  return BASE_CENTER_HEIGHT * getVerticalScale(params);
+}
+
+function getOutlineHeight(params: GroundTileUpgradeParams): number {
+  return BASE_OUTLINE_HEIGHT * getVerticalScale(params);
+}
+
+function getMaxStrandHeight(params: GroundTileUpgradeParams): number {
+  return Math.max(getCenterHeight(params), getOutlineHeight(params));
+}
+
+function getStrandTexture(scene: Scene): DynamicTexture {
+  const key = '__vfx_ground_tile_upgrade_strand_texture';
+  const metadata = scene.metadata && typeof scene.metadata === 'object' ? scene.metadata as Record<string, unknown> : {};
+  scene.metadata = metadata;
+  const existing = metadata[key] as DynamicTexture | undefined;
+  if (existing && !isTextureDisposed(existing)) return existing;
+
+  const texture = new DynamicTexture('ground_tile_upgrade_strand_texture', { width: 48, height: 192 }, scene, true);
+  const context = texture.getContext();
+  context.clearRect(0, 0, 48, 192);
+  const glow = context.createLinearGradient(0, 0, 0, 192);
+  glow.addColorStop(0, 'rgba(255, 255, 255, 0)');
+  glow.addColorStop(0.18, 'rgba(255, 255, 255, 0.92)');
+  glow.addColorStop(0.62, 'rgba(255, 255, 255, 0.52)');
+  glow.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  context.fillStyle = glow;
+  context.fillRect(19, 0, 10, 192);
+  context.fillStyle = 'rgba(255, 255, 255, 0.95)';
+  context.fillRect(23, 8, 2, 168);
+  const halo = context.createRadialGradient(24, 64, 0, 24, 64, 24);
+  halo.addColorStop(0, 'rgba(255, 255, 255, 0.5)');
+  halo.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  context.fillStyle = halo;
+  context.fillRect(0, 16, 48, 96);
+  texture.hasAlpha = true;
+  texture.update(false);
+  metadata[key] = texture;
+  texture.onDisposeObservable.addOnce(() => {
+    if (metadata[key] === texture) delete metadata[key];
+  });
+  return texture;
+}
+
+function getOutlineGlowTexture(scene: Scene): DynamicTexture {
+  const key = '__vfx_ground_tile_upgrade_outline_glow_texture';
+  const metadata = scene.metadata && typeof scene.metadata === 'object' ? scene.metadata as Record<string, unknown> : {};
+  scene.metadata = metadata;
+  const existing = metadata[key] as DynamicTexture | undefined;
+  if (existing && !isTextureDisposed(existing)) return existing;
+
+  const texture = new DynamicTexture('ground_tile_upgrade_outline_glow_texture', { width: 96, height: 192 }, scene, true);
+  const context = texture.getContext();
+  const compositeContext = context as unknown as CanvasRenderingContext2D;
+  context.clearRect(0, 0, 96, 192);
+  const sideFade = context.createLinearGradient(0, 0, 96, 0);
+  sideFade.addColorStop(0, 'rgba(255, 255, 255, 0)');
+  sideFade.addColorStop(0.28, 'rgba(255, 255, 255, 0.36)');
+  sideFade.addColorStop(0.5, 'rgba(255, 255, 255, 0.78)');
+  sideFade.addColorStop(0.72, 'rgba(255, 255, 255, 0.36)');
+  sideFade.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  const verticalFade = context.createLinearGradient(0, 0, 0, 192);
+  verticalFade.addColorStop(0, 'rgba(255, 255, 255, 0)');
+  verticalFade.addColorStop(0.16, 'rgba(255, 255, 255, 0.65)');
+  verticalFade.addColorStop(0.55, 'rgba(255, 255, 255, 0.46)');
+  verticalFade.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  context.fillStyle = sideFade;
+  context.fillRect(0, 0, 96, 192);
+  compositeContext.globalCompositeOperation = 'source-in';
+  context.fillStyle = verticalFade;
+  context.fillRect(0, 0, 96, 192);
+  compositeContext.globalCompositeOperation = 'source-over';
+  const core = context.createLinearGradient(0, 0, 0, 192);
+  core.addColorStop(0, 'rgba(255, 255, 255, 0)');
+  core.addColorStop(0.22, 'rgba(255, 255, 255, 0.64)');
+  core.addColorStop(0.66, 'rgba(255, 255, 255, 0.28)');
+  core.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  context.fillStyle = core;
+  context.fillRect(44, 8, 8, 166);
+  texture.hasAlpha = true;
+  texture.update(false);
+  metadata[key] = texture;
+  texture.onDisposeObservable.addOnce(() => {
+    if (metadata[key] === texture) delete metadata[key];
+  });
+  return texture;
+}
+
+function getBrightColor(color: VfxColorValue): VfxColorValue {
+  return {
+    r: lerp(color.r, 1, 0.68),
+    g: lerp(color.g, 1, 0.68),
+    b: lerp(color.b, 1, 0.68),
+  };
+}
+
+function toColor4(color: VfxColorValue, alpha: number): Color4 {
+  return new Color4(clamp01(color.r), clamp01(color.g), clamp01(color.b), clamp01(alpha));
+}
+
+function isTextureDisposed(texture: DynamicTexture): boolean {
+  const maybeTexture = texture as DynamicTexture & { isDisposed?: () => boolean; _isDisposed?: boolean };
+  return maybeTexture.isDisposed?.() ?? maybeTexture._isDisposed === true;
+}
+
+function lerp(min: number, max: number, t: number): number {
+  return min + (max - min) * t;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function fract(value: number): number {
+  return value - Math.floor(value);
+}
+
+function sequence01(index: number, axis: number): number {
+  if (index === 0) return 0.5;
+  const strides = [0.618033988749895, 0.414213562373095, 0.732050807568877, 0.324717957244746, 0.754877666246693, 0.569840290998053];
+  return fract(0.5 + index * strides[axis % strides.length] + axis * 0.173205080756888);
+}

package/packages/effects/ground-tile-upgrade/vfx-params.json

@@ -0,0 +1,21 @@
+{
+  "lifetime": 2,
+  "scale": 1,
+  "initialHeight": 0.2,
+  "color": {
+    "r": 0.984313725490196,
+    "g": 1,
+    "b": 0
+  },
+  "opacity": 1,
+  "scaleX": 0.82,
+  "scaleY": 0.24,
+  "scaleZ": 0.82,
+  "centerCount": 60,
+  "outlineCount": 300,
+  "strandWidth": 0.05,
+  "riseSpeed": 3,
+  "centerSpread": 1,
+  "outlineThickness": 0.2,
+  "glowOpacity": 1
+}

package/packages/effects/hit-flash/index.ts

@@ -0,0 +1,69 @@
+// 命中蓝白爆闪(移植自 babylon-laser createHitParticles/burstHit, 特效#3)。
+// 一次性 ParticleSystem 爆发:程序光斑贴图,蓝白渐变到透明,BLENDMODE_ADD 全向四散。
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Color4 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { Scene } from '@babylonjs/core/scene';
+import type { VfxEffectPackage, VfxParamValues } from '../../types';
+
+interface HitFlashParams extends VfxParamValues {
+  count: number;
+  sizeMax: number;
+  power: number;
+}
+
+const DEFAULT_PARAMS: HitFlashParams = { count: 24, sizeMax: 0.5, power: 7 };
+
+function makeFlareTexture(scene: Scene, inner = '255,255,255', outer = '90,160,255'): DynamicTexture {
+  const dt = new DynamicTexture('vfx_hit_flare', 128, scene, false);
+  const ctx = dt.getContext();
+  const g = ctx.createRadialGradient(64, 64, 0, 64, 64, 64);
+  g.addColorStop(0, `rgba(${inner},1)`);
+  g.addColorStop(0.35, `rgba(${outer},0.55)`);
+  g.addColorStop(1, `rgba(${outer},0)`);
+  ctx.clearRect(0, 0, 128, 128);
+  ctx.fillStyle = g; ctx.fillRect(0, 0, 128, 128);
+  dt.update(); dt.hasAlpha = true;
+  return dt;
+}
+
+export const hitFlashEffectPackage: VfxEffectPackage<HitFlashParams> = {
+  id: 'hit-flash',
+  nameZh: '命中蓝白爆闪',
+  debugAnchor: 'playerRight',
+  defaultParams: DEFAULT_PARAMS,
+  debugParams: [
+    { key: 'count', label: '粒子数', kind: 'number', min: 1, max: 200, step: 1 },
+    { key: 'sizeMax', label: '最大尺寸', kind: 'scale', min: 0.1, max: 2, step: 0.01 },
+    { key: 'power', label: '四散速度', kind: 'number', min: 0.5, max: 20, step: 0.5 },
+  ],
+
+  create({ scene, root, position, params }) {
+    root.position.copyFrom(position);
+    const flareTex = makeFlareTexture(scene);
+    const ps = new ParticleSystem('vfx_hit_ps', 400, scene);
+    ps.particleTexture = flareTex;
+    ps.emitter = position.clone();
+    ps.minEmitBox = new Vector3(-0.1, -0.1, -0.1); ps.maxEmitBox = new Vector3(0.1, 0.1, 0.1);
+    ps.direction1 = new Vector3(-1, -1, -1); ps.direction2 = new Vector3(1, 1, 1);
+    ps.color1 = new Color4(0.85, 0.95, 1, 1); ps.color2 = new Color4(0.35, 0.6, 1, 1); ps.colorDead = new Color4(0.1, 0.2, 0.6, 0);
+    ps.minSize = 0.12; ps.maxSize = params.sizeMax;
+    ps.minLifeTime = 0.15; ps.maxLifeTime = 0.45;
+    ps.minEmitPower = params.power * 0.36; ps.maxEmitPower = params.power;
+    ps.updateSpeed = 0.016;
+    ps.blendMode = ParticleSystem.BLENDMODE_ADD;
+    ps.emitRate = 0;
+    ps.start();
+    ps.manualEmitCount = Math.round(params.count); // 一次性爆发
+
+    let disposed = false;
+    const disposeTimer = window.setTimeout(() => disposeAll(), 800);
+    function disposeAll(): void {
+      if (disposed) return; disposed = true;
+      window.clearTimeout(disposeTimer);
+      ps.dispose(); flareTex.dispose(); root.dispose();
+    }
+    return { root, dispose() { disposeAll(); } };
+  },
+};

package/packages/effects/hit-flash/vfx-params.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": "vfx-params/1.0",
+  "effectId": "hit-flash",
+  "params": {}
+}

package/packages/effects/laser-beam/index.ts

@@ -0,0 +1,6 @@
+// 主激光束(特效#1)。共享实现见 ../laser-beam-factory;本包只定 id/中文名/默认参数(主束 width0.55/intensity1.0)。
+import { createLaserBeamEffectPackage } from '../laser-beam-factory';
+
+export const laserBeamEffectPackage = createLaserBeamEffectPackage('laser-beam', '激光束', {
+  width: 0.55, intensity: 1.0, laserSpeed: 7, targetDistance: 12,
+});

package/packages/effects/laser-beam/vfx-params.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": "vfx-params/1.0",
+  "effectId": "laser-beam",
+  "params": {}
+}

package/packages/effects/laser-beam-factory.ts

@@ -0,0 +1,135 @@
+// 激光束共享工厂(移植自 babylon-laser LaserBeam,被 laser-beam(主#1)与 laser-splash-beam(副#2)复用)。
+// 非 effect(无 index.ts);两个特效 index.ts 经 `../laser-beam-factory` 引用,差异只在 defaultParams(width/intensity)。
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { VertexData } from '@babylonjs/core/Meshes/mesh.vertexData';
+import { CreatePlane } from '@babylonjs/core/Meshes/Builders/planeBuilder';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Constants } from '@babylonjs/core/Engines/constants';
+import type { Scene } from '@babylonjs/core/scene';
+import type { VfxEffectPackage, VfxParamValues } from '../types';
+import { makeFlareTexture, LIFETIME_DEBUG_PARAMS, LIFETIME_DEFAULTS, scheduleLifetime } from './space-shared';
+import arcTextureUrl from './laser-beam/assets/textures/laser_glow.webp?url';
+import noiseTextureUrl from './laser-beam/assets/textures/laser_noise.webp?url';
+
+export interface LaserBeamParams extends VfxParamValues {
+  lifetimeMode: string;
+  lifetime: number;
+  width: number;
+  intensity: number;
+  laserSpeed: number;
+  targetDistance: number;
+}
+type LaserCoreDefaults = Omit<LaserBeamParams, 'lifetimeMode' | 'lifetime'>;
+
+// 十字面片:局部 +Z 长度=1(beamRoot.scaling.z=dist 拉伸);U 沿长度 → uOffset 滚动即流动
+function createBeamPlaneGeo(name: string, width: number, axis: 'x' | 'y', scene: Scene): Mesh {
+  const h = width / 2;
+  const positions = axis === 'x'
+    ? [-h, 0, 0, h, 0, 0, h, 0, 1, -h, 0, 1]
+    : [0, -h, 0, 0, h, 0, 0, h, 1, 0, -h, 1];
+  const normals = axis === 'x' ? [0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0] : [1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0];
+  const uvs = [0, 0, 0, 1, 1, 1, 1, 0];
+  const indices = [0, 1, 2, 0, 2, 3];
+  const mesh = new Mesh(name, scene);
+  const vd = new VertexData();
+  vd.positions = positions; vd.normals = normals; vd.uvs = uvs; vd.indices = indices;
+  vd.applyToMesh(mesh);
+  return mesh;
+}
+
+export function createLaserBeamEffectPackage(id: string, nameZh: string, core: LaserCoreDefaults): VfxEffectPackage<LaserBeamParams> {
+  const defaultParams = { ...LIFETIME_DEFAULTS, ...core } as LaserBeamParams;
+  return {
+    id, nameZh, defaultParams, debugAnchor: 'playerRight',
+    debugParams: [
+      ...LIFETIME_DEBUG_PARAMS,
+      { key: 'width', label: '束宽', kind: 'scale', min: 0.05, max: 2, step: 0.01 },
+      { key: 'intensity', label: '强度', kind: 'number', min: 0.1, max: 3, step: 0.05 },
+      { key: 'laserSpeed', label: '纹理流速', kind: 'number', min: 0, max: 20, step: 0.5 },
+      { key: 'targetDistance', label: '目标距离', kind: 'number', min: 2, max: 40, step: 0.5 },
+    ],
+    create({ scene, root, position, rotationY, params }) {
+      root.position.copyFrom(position);
+      root.rotation.y = rotationY;
+      const { width, intensity } = params;
+      const segLen = width * 5;
+
+      const arcTex = new Texture(arcTextureUrl, scene); arcTex.wrapU = Texture.WRAP_ADDRESSMODE;
+      const arcMat = new StandardMaterial('vfx_laser_arcMat', scene);
+      arcMat.emissiveTexture = arcTex; arcMat.opacityTexture = arcTex;
+      arcMat.emissiveColor = new Color3(0.45 * intensity, 0.62 * intensity, 1.35 * intensity);
+      arcMat.disableLighting = true; arcMat.backFaceCulling = false; arcMat.alphaMode = Constants.ALPHA_ADD;
+
+      const noiseTex = new Texture(noiseTextureUrl, scene); noiseTex.wrapU = Texture.WRAP_ADDRESSMODE;
+      const noiseMat = new StandardMaterial('vfx_laser_noiseMat', scene);
+      noiseMat.emissiveTexture = noiseTex; noiseMat.opacityTexture = noiseTex;
+      noiseMat.opacityTexture.getAlphaFromRGB = true;
+      noiseMat.emissiveColor = new Color3(0.2 * intensity, 0.35 * intensity, 0.9 * intensity);
+      noiseMat.disableLighting = true; noiseMat.backFaceCulling = false; noiseMat.alphaMode = Constants.ALPHA_ADD;
+
+      const beamRoot = new TransformNode('vfx_laser_beamRoot', scene);
+      beamRoot.parent = root;
+      const planes: Mesh[] = [];
+      const layout: Array<['x' | 'y', StandardMaterial, number]> = [
+        ['x', arcMat, width], ['y', arcMat, width], ['x', noiseMat, width * 1.9], ['y', noiseMat, width * 1.9],
+      ];
+      for (const [axis, mat, w] of layout) {
+        const p = createBeamPlaneGeo(`vfx_laser_p${planes.length}`, w, axis, scene);
+        p.material = mat; p.parent = beamRoot; p.isPickable = false;
+        planes.push(p);
+      }
+
+      const flareTex = makeFlareTexture(scene, 'vfx_laser_flare');
+      function makeFlare(name: string, size: number): Mesh {
+        const f = CreatePlane(name, { size }, scene);
+        f.billboardMode = Mesh.BILLBOARDMODE_ALL;
+        const m = new StandardMaterial(name + 'Mat', scene);
+        m.emissiveTexture = flareTex; m.opacityTexture = flareTex;
+        m.emissiveColor = new Color3(0.7, 0.85, 1.6);
+        m.disableLighting = true; m.alphaMode = Constants.ALPHA_ADD;
+        f.material = m; f.isPickable = false; f.parent = root;
+        return f;
+      }
+      const muzzleFlare = makeFlare('vfx_laser_muzzle', width * 3.2);
+      const hitFlare = makeFlare('vfx_laser_hit', width * 3.2);
+
+      let time = 0;
+      const observer = scene.onBeforeRenderObservable.add(() => {
+        const dt = Math.min(scene.getEngine().getDeltaTime() / 1000, 0.05);
+        time += dt;
+        const dist = params.targetDistance;
+        beamRoot.scaling.z = dist;
+        const tiles = Math.max(1, dist / segLen);
+        (arcMat.emissiveTexture as Texture).uScale = tiles; (arcMat.opacityTexture as Texture).uScale = tiles;
+        (arcMat.emissiveTexture as Texture).uOffset -= params.laserSpeed * dt;
+        (arcMat.opacityTexture as Texture).uOffset = (arcMat.emissiveTexture as Texture).uOffset;
+        (noiseMat.emissiveTexture as Texture).uScale = tiles * 0.6;
+        (noiseMat.emissiveTexture as Texture).uOffset -= params.laserSpeed * 0.31 * dt;
+        (noiseMat.opacityTexture as Texture).uScale = tiles * 0.6;
+        (noiseMat.opacityTexture as Texture).uOffset = (noiseMat.emissiveTexture as Texture).uOffset;
+        const pulse = 1 + Math.sin(time * 24) * 0.18;
+        muzzleFlare.position.set(0, 0, 0); muzzleFlare.scaling.setAll(pulse);
+        hitFlare.position.set(0, 0, dist); hitFlare.scaling.setAll(pulse * 1.4);
+      });
+
+      let disposed = false;
+      let ltTimer = 0;
+      const dispose = (): void => {
+        if (disposed) return; disposed = true;
+        if (ltTimer) window.clearTimeout(ltTimer);
+        scene.onBeforeRenderObservable.remove(observer);
+        for (const p of planes) p.dispose();
+        muzzleFlare.material?.dispose(); muzzleFlare.dispose();
+        hitFlare.material?.dispose(); hitFlare.dispose();
+        beamRoot.dispose();
+        arcMat.dispose(); arcTex.dispose(); noiseMat.dispose(); noiseTex.dispose(); flareTex.dispose();
+        root.dispose();
+      };
+      ltTimer = scheduleLifetime(params, dispose);  // 自定义时间模式:到时自动停;无限=循环
+      return { root, dispose };
+    },
+  };
+}

package/packages/effects/lumber-cart-suction/effect.json

@@ -0,0 +1,6 @@
+{
+  "id": "lumber-cart-suction",
+  "nameZh": "收集车吸入圆环",
+  "assets": [],
+  "source": "procedural"
+}