@fps-games/vfx 0.1.1 → 0.3.2

package/packages/effects/vehicle-upgrade/index.ts

@@ -54,8 +54,11 @@ const DEFAULT_PARAMS: VehicleUpgradeParams = {
 export const vehicleUpgradeEffectPackage: VfxEffectPackage<VehicleUpgradeParams> = {
   id: 'vehicle-upgrade',
   nameZh: '建筑&地块&设备升级',
+  placement: 'socket',
   manifest,
   defaultParams: DEFAULT_PARAMS,
+  // initialHeight 走 service 存活的 Y 偏移通道(G6/M12)。
+  spawnParams: { offsetY: 'initialHeight' },
   debugAnchor: 'playerRight',
   debugParams: [
     { key: 'lifetime', label: '生命周期', kind: 'lifetime', min: 0.2, max: 6, step: 0.01 },
@@ -75,7 +78,7 @@ export const vehicleUpgradeEffectPackage: VfxEffectPackage<VehicleUpgradeParams>
     { 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));
+    root.position.copyFrom(position);   // 高度偏移由 service 经 spawnParams.offsetY 施加(存活)
 
     const centerStrands = createStrandSystem(scene, root, params, 'center');
     const outlineStrands = createStrandSystem(scene, root, params, 'outline');

package/packages/effects/weapon-trail/index.ts

@@ -31,7 +31,7 @@ interface WeaponTrailParams extends VfxParamValues {
 const DEFAULT_PARAMS: WeaponTrailParams = {
   ...LIFETIME_DEFAULTS,
   orientation: 'horizontal',
-  orbitRadius: 1.6, orbitSpeed: 7, height: 0,
+  orbitRadius: 0, orbitSpeed: 7, height: 0,   // 默认 0:真实跟随挂点(orbit>0 是演示用的幻影圆周轨道)
   trailLength: 16, worldLength: 4.0, width: 1.01, coreWidth: 0.4,
   tailFadeStrength: 0.58, tailFadeExponent: 1.35,
   opacity: 1.35, saturation: 1.45, contrast: 1.32,
@@ -95,6 +95,8 @@ function lerpSample(a: Sample, b: Sample, t: number, dst: Sample): void {
 export const weaponTrailEffectPackage: VfxEffectPackage<WeaponTrailParams> = {
   id: 'weapon-trail',
   nameZh: '武器拖尾',
+  placement: 'socket',
+  geometrySpace: 'world',
   debugAnchor: 'player',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -124,8 +126,9 @@ export const weaponTrailEffectPackage: VfxEffectPackage<WeaponTrailParams> = {
     { key: 'tint', label: '颜色', kind: 'color' },
   ],
 
-  create({ scene, root, position, params }) {
+  create({ scene, root, position, params, renderingGroupId }) {
     root.position.copyFrom(position);
+    const rgid = renderingGroupId ?? 0;
     registerShaders();
     const blend = params.blendMode === 'combine' ? Constants.ALPHA_COMBINE : Constants.ALPHA_ADD;
 
@@ -159,7 +162,7 @@ export const weaponTrailEffectPackage: VfxEffectPackage<WeaponTrailParams> = {
     function makeMesh(name: string, mat: ShaderMaterial, ai: number): Mesh {
       const m = new Mesh(name, scene);
       m.material = mat; m.isPickable = false; m.alwaysSelectAsActiveMesh = true;
-      m.useVertexColors = true; m.hasVertexAlpha = true; m.renderingGroupId = 0; m.alphaIndex = ai;
+      m.useVertexColors = true; m.hasVertexAlpha = true; m.renderingGroupId = rgid; m.alphaIndex = ai;
       return m;
     }
     const outer = makeMesh('vfx_weaponTrail_outer', outerMat, 10);
@@ -181,6 +184,7 @@ export const weaponTrailEffectPackage: VfxEffectPackage<WeaponTrailParams> = {
       const c255 = `${Math.round(params.tint.r * 255)},${Math.round(params.tint.g * 255)},${Math.round(params.tint.b * 255)}`;
       const flare = makeFlareTexture(scene, 'vfx_weaponTrail_sparkTex', '255,255,255', c255);
       sparkPs = new ParticleSystem('vfx_weaponTrail_sparks', 160, scene);
+      sparkPs.renderingGroupId = rgid;
       sparkPs.particleTexture = flare;
       sparkPs.emitter = sparkEmitter;
       sparkPs.minSize = 0.07; sparkPs.maxSize = 0.26;

package/packages/types.ts

@@ -1,9 +1,35 @@
 import type { Scene } from '@babylonjs/core/scene';
 import type { Vector3 } from '@babylonjs/core/Maths/math.vector';
 import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
 
 export type VfxDebugAnchor = 'playerRight' | 'player';
 
+// ── 运行时外部信息(inputs)──────────────────────────────────────────────
+// 与 params(设计期可调、保存)区分:inputs 是运行时由游戏逻辑提供的外部上下文,常动态。
+// 值可为静态值或 provider(() => 值);动态目标(移动)用 provider 每帧取。见 docs/vfx-placement-design.md。
+export type VfxInput<T> = T | (() => T);
+export type VfxInputKey = 'aim' | 'normal' | 'endpoints' | 'target';
+
+/** 调用方提供的 inputs(放在 VfxSpawnTransform.inputs)。 */
+export interface VfxEffectInputs {
+  aim?: VfxInput<Vector3>;            // 瞄准点(激光/定向武器)
+  normal?: VfxInput<Vector3>;         // 表面法线(贴花/冲击)
+  endpoints?: Array<VfxInput<Vector3>>; // link/链式(≥2 端点)
+  target?: AbstractMesh;              // target-material 类(改目标自身材质)
+  /** 运行时标量(throttle/intensity 等),值可静态或 provider;特效每帧读取做活改(G5)。 */
+  scalars?: Record<string, VfxInput<number>>;
+}
+
+/** create() 收到的、已归一化为访问器的 inputs(provider 与静态值都变成可调用的函数)。 */
+export interface VfxResolvedInputs {
+  aim?: () => Vector3;
+  normal?: () => Vector3;
+  endpoints?: Array<() => Vector3>;
+  target?: AbstractMesh;
+  scalars?: Record<string, () => number>;
+}
+
 export type VfxParamValue = number | string | VfxColorValue;
 export type VfxParamValues = Record<string, VfxParamValue>;
 
@@ -58,12 +84,22 @@ export interface VfxEffectPackageContext<PParams extends VfxParamValues = VfxPar
   rotationY: number;
   renderingGroupId?: number;
   params: PParams;
+  /**
+   * 解析后的三轴缩放(来自 spawnTransform.scale,默认 (1,1,1))。
+   * root 的缩放由 service 写好;但**几何不挂 root 的 world/detached 特效**(粒子/抛物池/世界坐标 emitter)
+   * root.scaling 作用不到,须自行把 ctx.scale 乘进几何尺寸/初速(G3)。
+   */
+  scale: Vector3;
+  /** 运行时外部信息(已归一化为访问器)。link/target/定向武器/活改标量等按 required/optionalInputs 读取。 */
+  inputs?: VfxResolvedInputs;
 }
 
 export interface VfxEffectHandle {
   root: TransformNode;
   ready?: Promise<void>;
   dispose(): void;
+  /** 可选:运行时活改 params(无须 dispose+replay,避免重置缓动/可见闪)。声明即纳入契约(G5)。 */
+  update?(params: Partial<VfxParamValues>): void;
 }
 
 export interface VfxEffectManifest {
@@ -79,10 +115,35 @@ export interface VfxSpawnParamKeys {
   offsetZ?: string;
 }
 
+/** 欧拉角(弧度)/ 三轴缩放的纯数据三元组。 */
+export interface VfxVector3Like {
+  x: number;
+  y: number;
+  z: number;
+}
+
 export interface VfxSpawnTransform {
   position?: Vector3;
+  /**
+   * 兼容别名:绕 Y 轴旋转(弧度)。
+   * 若同时给了 `rotation`,以 `rotation` 为准;否则回退到 `rotationY`。
+   */
   rotationY?: number;
+  /** 完整欧拉角旋转(弧度);给了就覆盖 `rotationY`。 */
+  rotation?: VfxVector3Like;
+  /** 等比缩放(number)或三轴缩放;默认 1。 */
+  scale?: number | VfxVector3Like;
+  /** 挂载点节点;给了就把特效 root parent 到它(特效随之跟随)。 */
+  parent?: TransformNode;
+  /**
+   * position/rotation/scale 的坐标系解释:
+   * - 给了 `parent` 时默认 `true`:按相对 parent 的 **local** transform 解释;
+   * - 没给 `parent` 时默认 `false`:按 **世界坐标** 解释(保持现状行为)。
+   */
+  offsetIsLocal?: boolean;
   renderingGroupId?: number;
+  /** 运行时外部信息(瞄准点/法线/端点/目标 mesh);值可为静态或 provider(动态每帧取)。 */
+  inputs?: VfxEffectInputs;
 }
 
 export interface VfxParamsFile {
@@ -92,6 +153,16 @@ export interface VfxParamsFile {
   params?: Partial<VfxParamValues>;
 }
 
+/**
+ * 特效的放置本质(内禀标记)。决定系统/binding/面板怎么放它,不靠猜。见 docs/vfx-placement-design.md。
+ * - 'socket' local:挂对象命名挂点、随它走(parent + follow)。
+ * - 'world'  global:放世界某点、不跟随(fire-and-forget,可按法线定向)。
+ * - 'screen' global:屏幕/相机层(后处理/相机扰动/DOM 全屏),无 3D transform。
+ * - 'target' 改目标自身材质/渲染态,没有可 spawn 的 root。
+ * - 'link'   连 ≥2 个端点(每帧重建几何),单 parent 表达不了。
+ */
+export type VfxPlacement = 'socket' | 'world' | 'screen' | 'target' | 'link';
+
 export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValues> {
   id: string;
   nameZh: string;
@@ -101,6 +172,23 @@ export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValue
   spawnParams?: VfxSpawnParamKeys;
   savedParams?: Partial<VfxParamValues>;
   debugParams: VfxParamDefinition[];
+  /** 放置本质标记(默认 'world')。 */
+  placement?: VfxPlacement;
+  /** 声明**必需**的运行时 inputs(link 必须给 endpoints/aim、target 类必须给 target mesh);service 缺失时 warn。 */
+  requiredInputs?: VfxInputKey[];
+  /** 声明**可选**的运行时 inputs(给了就用、不给走默认,如定向武器的 aim:给了朝目标、不给走挂点朝向);不触发缺失 warn(G2)。 */
+  optionalInputs?: VfxInputKey[];
+  /**
+   * 几何空间:'local'=几何挂 root 子节点随它刚性变换;'world'=几何用世界坐标、root 仅作每帧采样源(拖尾)。
+   * 默认随 placement 推断('socket'→local,其余→world)。
+   */
+  geometrySpace?: 'local' | 'world';
+  /**
+   * 构建特效。**约定(G6):root 的 transform(position/rotation/scaling/parent)归 service 独占** ——
+   * service 在 create() 后会二次 `applySpawnToRoot` 覆盖,create 内写 `root.position/rotation/scaling` 会被静默清掉。
+   * 需要内部局部偏移(如抬升)请用 root 下的**子 TransformNode** 承载,或声明 `spawnParams.offsetY` 走 service 存活通道。
+   * 几何挂 root 子树即随挂载跟随;world/拖尾类几何走世界坐标、读 ctx.scale 缩放。
+   */
   create(context: VfxEffectPackageContext<PParams>): VfxEffectHandle;
 }