@fps-games/vfx 0.1.1

package/packages/effects/run-footstep-dust/assets/runtime/runFootstepDust.v1.js

@@ -0,0 +1,215 @@
+export const runtimeId = "runFootstepDust/v1";
+
+export const runtimeContract = {
+  runtimeId,
+  kind: "runFootstepDust",
+  fields: {
+    count: "Particles emitted per burst.",
+    frequency: "Dust burst frequency in bursts per second.",
+    particleColor: "Base particle tint as a #rrggbb color.",
+    spread: "Dust spawn jitter behind the character.",
+    effectScale: "Overall spatial scale for spawn spacing, particle size, speed, and gravity.",
+  },
+};
+
+function num(value, fallback = 0) {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : fallback;
+}
+
+function fract(value) {
+  return value - Math.floor(value);
+}
+
+function sequence01(index, axis) {
+  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);
+}
+
+function readVec(BABYLON, value, fallback = new BABYLON.Vector3(1, 0, 0)) {
+  if (!value) return fallback;
+  return new BABYLON.Vector3(num(value.x, fallback.x), num(value.y, fallback.y), num(value.z, fallback.z));
+}
+
+function readColor(BABYLON, value, fallback = new BABYLON.Color4(0.78, 0.7, 0.54, 1)) {
+  if (typeof value === "string") {
+    const match = /^#?([0-9a-f]{6})$/i.exec(value);
+    if (match) {
+      const hex = match[1];
+      return new BABYLON.Color4(
+        parseInt(hex.slice(0, 2), 16) / 255,
+        parseInt(hex.slice(2, 4), 16) / 255,
+        parseInt(hex.slice(4, 6), 16) / 255,
+        1,
+      );
+    }
+  }
+  if (value && typeof value === "object") {
+    return new BABYLON.Color4(num(value.r, fallback.r), num(value.g, fallback.g), num(value.b, fallback.b), num(value.a, 1));
+  }
+  return fallback;
+}
+
+function tintColor(BABYLON, color, brightness, alpha) {
+  return new BABYLON.Color4(
+    Math.min(1, Math.max(0, color.r * brightness)),
+    Math.min(1, Math.max(0, color.g * brightness)),
+    Math.min(1, Math.max(0, color.b * brightness)),
+    alpha,
+  );
+}
+
+function makeTexture(BABYLON, scene) {
+  const texture = new BABYLON.DynamicTexture("runFootstepDustTexture", { width: 128, height: 128 }, scene, true);
+  const context = texture.getContext();
+  context.clearRect(0, 0, 128, 128);
+  for (const puff of [
+    { x: 48, y: 69, radius: 34, alpha: 0.72 },
+    { x: 70, y: 60, radius: 31, alpha: 0.64 },
+    { x: 86, y: 76, radius: 27, alpha: 0.5 },
+  ]) {
+    const shadow = context.createRadialGradient(puff.x, puff.y + 2, puff.radius * 0.22, puff.x, puff.y + 2, puff.radius + 5);
+    shadow.addColorStop(0, `rgba(86, 78, 64, ${puff.alpha * 0.22})`);
+    shadow.addColorStop(1, "rgba(86, 78, 64, 0)");
+    context.fillStyle = shadow;
+    context.beginPath();
+    context.arc(puff.x, puff.y + 2, puff.radius + 5, 0, Math.PI * 2);
+    context.fill();
+  }
+  for (const puff of [
+    { x: 48, y: 69, radius: 34, alpha: 0.72 },
+    { x: 70, y: 60, radius: 31, alpha: 0.64 },
+    { x: 86, y: 76, radius: 27, alpha: 0.5 },
+  ]) {
+    const core = context.createRadialGradient(puff.x, puff.y, puff.radius * 0.12, puff.x, puff.y, puff.radius);
+    core.addColorStop(0, `rgba(255, 255, 255, ${puff.alpha})`);
+    core.addColorStop(0.58, `rgba(235, 229, 210, ${puff.alpha * 0.52})`);
+    core.addColorStop(1, "rgba(220, 212, 188, 0)");
+    context.fillStyle = core;
+    context.beginPath();
+    context.arc(puff.x, puff.y, puff.radius, 0, Math.PI * 2);
+    context.fill();
+  }
+  texture.hasAlpha = true;
+  texture.update(false);
+  return texture;
+}
+
+export async function createRunFootstepDustRuntime({ BABYLON, scene, emitter, shouldStart = false }) {
+  if (!BABYLON) throw new Error("createRunFootstepDustRuntime requires BABYLON.");
+  if (!scene) throw new Error("createRunFootstepDustRuntime requires scene.");
+  if (!emitter) throw new Error("createRunFootstepDustRuntime requires emitter.");
+
+  const particlesPerStep = Math.max(0, Math.round(num(emitter.count ?? emitter.particleCount, 6)));
+  const effectScale = Math.max(0.01, num(emitter.effectScale, 1));
+  const spread = Math.max(0, num(emitter.spread, 0.3)) * effectScale;
+  const frequency = Math.max(0, num(emitter.frequency ?? emitter.stepFrequency, 4.5));
+  const lifeTime = Math.max(0.05, num(emitter.lifeTime ?? emitter.particleLifeTime, 0.42));
+  const particleSize = Math.max(0.001, num(emitter.particleSize, 0.18)) * effectScale;
+  const speed = Math.max(0, num(emitter.speed, 0.56)) * effectScale;
+  const trailOffset = Math.max(0, num(emitter.trailOffset, 0.22)) * effectScale;
+  const dustColor = readColor(BABYLON, emitter.particleColor);
+  const capacity = Math.max(48, Math.round(num(emitter.capacity, Math.ceil(particlesPerStep * Math.max(6, frequency * lifeTime * 3)))));
+  const movementDirection = readVec(BABYLON, emitter.emissionDirection, new BABYLON.Vector3(1, 0, 0));
+  movementDirection.y = 0;
+  if (movementDirection.lengthSquared() < 0.0001) movementDirection.set(1, 0, 0);
+  movementDirection.normalize();
+  const sideDirection = new BABYLON.Vector3(-movementDirection.z, 0, movementDirection.x);
+  const backwardDirection = movementDirection.scale(-1);
+  const system = new BABYLON.ParticleSystem(emitter.name || "run_footstep_dust", capacity, scene);
+
+  system.particleTexture = makeTexture(BABYLON, scene);
+  system.emitter = readVec(BABYLON, emitter.origin, BABYLON.Vector3.Zero());
+  system.emitRate = 0;
+  system.manualEmitCount = 0;
+  system.updateSpeed = 1 / 60;
+  system.minLifeTime = lifeTime;
+  system.maxLifeTime = lifeTime;
+  system.minSize = particleSize;
+  system.maxSize = particleSize;
+  system.minEmitPower = speed;
+  system.maxEmitPower = speed;
+  system.minAngularSpeed = 0;
+  system.maxAngularSpeed = 0;
+  system.gravity = readVec(BABYLON, emitter.gravity, new BABYLON.Vector3(0, -0.08, 0)).scale(effectScale);
+  system.blendMode = BABYLON.ParticleSystem.BLENDMODE_STANDARD;
+  system.color1 = tintColor(BABYLON, dustColor, 1.04, 0.58);
+  system.color2 = tintColor(BABYLON, dustColor, 0.78, 0.4);
+  system.colorDead = tintColor(BABYLON, dustColor, 0.52, 0);
+  system.addColorGradient(0, tintColor(BABYLON, dustColor, 1.04, 0));
+  system.addColorGradient(0.12, tintColor(BABYLON, dustColor, 1.04, 0.6));
+  system.addColorGradient(0.58, tintColor(BABYLON, dustColor, 0.86, 0.42));
+  system.addColorGradient(1, tintColor(BABYLON, dustColor, 0.58, 0));
+  system.addSizeGradient(0, particleSize * 0.5);
+  system.addSizeGradient(0.28, particleSize * 1.18);
+  system.addSizeGradient(0.72, particleSize * 1.65);
+  system.addSizeGradient(1, particleSize * 1.95);
+  system.addVelocityGradient(0, 1);
+  system.addVelocityGradient(0.35, 0.34);
+  system.addVelocityGradient(1, 0.03);
+  system.addDragGradient(0, 0.85);
+  system.addDragGradient(1, 1.9);
+
+  let positionIndex = 0;
+  let directionIndex = 0;
+  system.startPositionFunction = (worldMatrix, positionToUpdate, _particle, isLocal) => {
+    const index = positionIndex;
+    positionIndex += 1;
+    const sideJitter = (sequence01(index, 1) - 0.5) * spread * 0.55;
+    const backwardJitter = sequence01(index, 2) * spread * 0.75;
+    const lift = sequence01(index, 3) * 0.012 * effectScale;
+    const x = backwardDirection.x * (trailOffset + backwardJitter) + sideDirection.x * sideJitter;
+    const y = lift;
+    const z = backwardDirection.z * (trailOffset + backwardJitter) + sideDirection.z * sideJitter;
+    if (isLocal) positionToUpdate.set(x, y, z);
+    else BABYLON.Vector3.TransformCoordinatesFromFloatsToRef(x, y, z, worldMatrix, positionToUpdate);
+  };
+  system.startDirectionFunction = (worldMatrix, directionToUpdate, _particle, isLocal) => {
+    const index = directionIndex;
+    directionIndex += 1;
+    const backward = backwardDirection.scale(0.28 + sequence01(index, 4) * 0.26);
+    const sideways = sideDirection.scale((sequence01(index, 5) - 0.5) * 0.28);
+    const x = backward.x + sideways.x;
+    const y = 0.08 + sequence01(index, 6) * 0.1;
+    const z = backward.z + sideways.z;
+    if (isLocal) directionToUpdate.set(x, y, z);
+    else BABYLON.Vector3.TransformNormalFromFloatsToRef(x, y, z, worldMatrix, directionToUpdate);
+  };
+
+  let observer = null;
+  let timeToNextStep = 0;
+  const interval = frequency > 0 ? 1 / frequency : Number.POSITIVE_INFINITY;
+  const start = () => {
+    if (observer) return;
+    system.start();
+    observer = scene.onBeforeRenderObservable.add(() => {
+      if (particlesPerStep <= 0 || !Number.isFinite(interval)) return;
+      timeToNextStep -= scene.getEngine().getDeltaTime() / 1000;
+      while (timeToNextStep <= 0) {
+        system.manualEmitCount += particlesPerStep;
+        timeToNextStep += interval;
+      }
+    });
+  };
+
+  const preview = {
+    start,
+    stop: () => {
+      if (observer) scene.onBeforeRenderObservable.remove(observer);
+      observer = null;
+      system.stop();
+    },
+    dispose: () => {
+      if (observer) scene.onBeforeRenderObservable.remove(observer);
+      observer = null;
+      system.particleTexture?.dispose();
+      system.dispose();
+    },
+    isStarted: () => Boolean(observer),
+    duration: Math.max(1, lifeTime + 1 / Math.max(0.001, frequency)),
+    system,
+  };
+  if (shouldStart) preview.start();
+  return preview;
+}

package/packages/effects/run-footstep-dust/effect.json

@@ -0,0 +1,183 @@
+{
+  "schemaVersion": "build.particle/v1",
+  "id": "build.particle.run_footstep_dust",
+  "effectId": "run_footstep_dust",
+  "displayName": {
+    "en": "Run Footstep Dust",
+    "zh": "跑动脚步烟尘"
+  },
+  "kind": "runFootstepDust",
+  "runtime": {
+    "runtimeId": "runFootstepDust/v1",
+    "path": "assets/runtime/runFootstepDust.v1.js",
+    "entry": "createRunFootstepDustRuntime"
+  },
+  "assets": {
+    "runtime": [
+      {
+        "id": "run_footstep_dust_runtime",
+        "packagePath": "assets/runtime/runFootstepDust.v1.js"
+      }
+    ],
+    "source": [
+      {
+        "kind": "typescript",
+        "id": "run_footstep_dust_source_ts",
+        "packagePath": "source/src/effects/runFootstepDust.ts",
+        "sourcePath": "D:/project/loy_babylon_particle_test/src/effects/runFootstepDust.ts"
+      }
+    ]
+  },
+  "emitters": [
+    {
+      "name": "run_footstep_dust",
+      "enabled": true,
+      "deterministic": true,
+      "type": "ParticleSystem",
+      "capacity": 64,
+      "count": 6,
+      "frequency": 4.5,
+      "particleColor": "#ffffff",
+      "spread": 0.3,
+      "lifeTime": 0.42,
+      "speed": 0.56,
+      "particleSize": 0.18,
+      "effectScale": 1,
+      "trailOffset": 0.22,
+      "emissionDirection": {
+        "x": 1,
+        "y": 0.2,
+        "z": 0
+      },
+      "gravity": {
+        "x": 0,
+        "y": -0.08,
+        "z": 0
+      },
+      "origin": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "runtime": {
+        "continuous": true,
+        "disposeOnComplete": false
+      }
+    }
+  ],
+  "parameters": [
+    {
+      "key": "count",
+      "label": "Count",
+      "type": "number",
+      "default": 6,
+      "min": 0,
+      "max": 999,
+      "step": 1,
+      "mapsTo": "emitters[0].count",
+      "note": "Particles emitted per dust burst behind the character."
+    },
+    {
+      "key": "frequency",
+      "label": "Frequency",
+      "type": "number",
+      "default": 4.5,
+      "min": 0,
+      "max": 30,
+      "step": 0.01,
+      "mapsTo": "emitters[0].frequency",
+      "note": "Dust bursts per second for continuous playback."
+    },
+    {
+      "key": "particleColor",
+      "label": "Color",
+      "type": "color",
+      "default": "#ffffff",
+      "mapsTo": "emitters[0].particleColor",
+      "note": "Base tint for the dust particles."
+    },
+    {
+      "key": "spread",
+      "label": "Spread",
+      "type": "number",
+      "default": 0.3,
+      "min": 0,
+      "max": 20,
+      "step": 0.01,
+      "mapsTo": "emitters[0].spread"
+    },
+    {
+      "key": "life",
+      "label": "Life",
+      "type": "number",
+      "default": 0.42,
+      "min": 0.01,
+      "max": 20,
+      "step": 0.01,
+      "mapsTo": "emitters[0].lifeTime"
+    },
+    {
+      "key": "speed",
+      "label": "Speed",
+      "type": "number",
+      "default": 0.56,
+      "min": 0,
+      "max": 20,
+      "step": 0.01,
+      "mapsTo": "emitters[0].speed"
+    },
+    {
+      "key": "size",
+      "label": "Size",
+      "type": "number",
+      "default": 1,
+      "min": 0,
+      "max": 20,
+      "step": 0.01,
+      "mapsTo": "emitters[0].particleSize",
+      "note": "Editor multiplies this by base particleSize 0.18."
+    },
+    {
+      "key": "scale",
+      "label": "Scale",
+      "type": "number",
+      "default": 1,
+      "min": 0.01,
+      "max": 20,
+      "step": 0.01,
+      "mapsTo": "emitters[0].effectScale"
+    },
+    {
+      "key": "dirX",
+      "label": "Dir X",
+      "type": "range",
+      "default": 100,
+      "min": -100,
+      "max": 100,
+      "mapsTo": "emitters[0].emissionDirection.x"
+    },
+    {
+      "key": "dirY",
+      "label": "Dir Y",
+      "type": "range",
+      "default": 20,
+      "min": 20,
+      "max": 120,
+      "mapsTo": "emitters[0].emissionDirection.y"
+    },
+    {
+      "key": "dirZ",
+      "label": "Dir Z",
+      "type": "range",
+      "default": 0,
+      "min": -100,
+      "max": 100,
+      "mapsTo": "emitters[0].emissionDirection.z"
+    }
+  ],
+  "notes": [
+    "Continuous Unity-style particle playback: the runtime emits deterministic cartoon dust puffs behind the character at the configured frequency.",
+    "Count controls particles per burst, not total lifetime particles.",
+    "Dust is spawned behind the emitter based on the current direction controls."
+  ]
+}