ParticleEmitter.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/ECS.h"
#include "common/RenderTypes.h"
#include "common/Time.h"
#include "particles/ParticleCurve.h"
 
#include <algorithm>
#include <cstdint>
#include <random>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace eve {
class IParticleSdfField;
}
 
namespace eve::graphics {
class Graphics;
class Camera2D;
class Canvas;
class Light2D;
class Shader;
class Texture;
}
 
namespace eve::animation {
class AnimPose;
class AnimSkeleton;
class AnimSkin;
class SpineSkeleton;
}
 
namespace eve::ik {
class Skeleton2D;
class Skeleton3D;
}
 
namespace eve::particles {
 
using eve::Color;
 
struct Particle {
    float x = 0.f;
    float y = 0.f;
    float vx = 0.f;
    float vy = 0.f;
    float ax = 0.f;
    float ay = 0.f;
    float radial = 0.f;
    float tangential = 0.f;
    float life = 0.f;
    float lifetime = 1.f;
    float size = 1.f;
    float rot = 0.f;
    float spin = 0.f;
    float frame = 0.f;
    float noisePhase = 0.f;
};
 
class EVENGINE_API_DOMAINS ParticleEmitter : public ecs::Entity {
public:
    ENTITY(ParticleEmitter, ecs::Entity)
 
    
    void release() override;
 
    struct Config {
        struct Burst {
            float time = 0.f;
            int count = 0;
            bool emitted = false;
        };
 
        float x = 0.f;
        float y = 0.f;
        float emissionRate = 0.f;
        float emissionRateOverDistance = 0.f;
        float lifeMin = 1.f;
        float lifeMax = 1.f;
        float emitterLife = -1.f;  // -1 = forever
        bool looping = false;
        float playbackSpeed = 1.f;
        float fixedTimeStep = 0.f;
        int maxSubSteps = 8;
        int randomSeed = 0;
        bool autoRandomSeed = true;
        struct ParameterBinding {
            std::string parameter;
            float       scale  = 1.f;
            float       offset = 0.f;
        };
        std::unordered_map<std::string, float>            floatParameters;
        std::unordered_map<std::string, ParameterBinding> parameterBindings;
        float                                             resolvedParameterScale(const std::string& target) const {
            auto binding = parameterBindings.find(target);
            if (binding == parameterBindings.end()) return 1.f;
            auto value = floatParameters.find(binding->second.parameter);
            if (value == floatParameters.end()) return 1.f;
            return std::max(0.f, value->second * binding->second.scale + binding->second.offset);
        }
        float direction = 0.f;
        float spread = 0.f;
        float speedMin = 0.f;
        float speedMax = 0.f;
        float accelXMin = 0.f, accelYMin = 0.f;
        float accelXMax = 0.f, accelYMax = 0.f;
        float radialMin = 0.f, radialMax = 0.f;
        float tangentialMin = 0.f, tangentialMax = 0.f;
        float particleW = 8.f;
        float particleH = 8.f;
        float sizeStart = 1.f;
        float sizeEnd = 1.f;
        float sizeVariation = 0.f;  // 0..1
        float spinMin = 0.f;
        float spinMax = 0.f;
        float gravityX = 0.f;
        float gravityY = 0.f;
        float damping = 0.f;
        float limitVelocity = 0.f;
        ParticleCurve velocityCurve;
        float inheritVelocity = 0.f;
        std::string simSpace = "world";
        float noiseStrength = 0.f;
        float noiseFrequency = 1.f;
        float noiseSpeed = 1.f;
        std::string collisionMode = "none";
        float collisionRadius = 0.f;          // 0 = particle size/2
        float collisionRestitution = 0.6f;
        float collisionLifetimeLoss = 0.f;    // fraction of life removed per hit
        bool collisionBoundsEnabled = false;
        float boundsMinX = 0.f;
        float boundsMinY = 0.f;
        float boundsMaxX = 0.f;
        float boundsMaxY = 0.f;
        bool worldCollision = false;
        eve::IParticleSdfField* sdfField = nullptr;
        std::string motionVectorPolicy = "none";
        std::string renderMode = "billboard";
        float stretchFactor = 1.f;
        float renderAxisDegrees = 0.f;
        std::string sortMode = "none";
        std::string materialMode = "unlit";
        float distortionStrength = 8.f;
        float ribbonWidth            = 1.f;
        float ribbonMinSegmentLength = 1.f;
        bool  softParticles     = false;
        float softParticleDepth = 0.5f;
        float softFadeDistance  = 0.05f;
        std::string overflowMode = "drop";
        float maxDeltaTime = 0.f;
        float prewarmSeconds = 0.f;
        bool gpuSimulation = false;
        int priority = 0;
        int minimumQuality = 0;
        std::string cullingMode = "automatic";
        float cullDistance = 0.f;
        int maxSpawnPerFrame = 0;
        std::vector<Burst> bursts;
        struct ForceField {
            float x = 0.f;
            float y = 0.f;
            float radius = 0.f;
            float strength = 0.f;
            float falloff = 1.f;  // exponent; 1 = linear
        };
        std::vector<ForceField> forceFields;
        struct LightCfg {
            bool enabled = false;
            int max = 4;              // capped at 8 per emitter (engine limit per canvas)
            float radius = 120.f;
            float intensity = 1.f;
            float r = 1.f;
            float g = 1.f;
            float b = 1.f;
        } lights;
        struct SubEmitter {
            ParticleEmitter *target = nullptr;
            std::string trigger = "birth";  // "birth" | "death" | "collision"
            float inheritVelocity = 0.f;
        };
        std::vector<SubEmitter> subEmitters;
        float startRotMin = 0.f;
        float startRotMax = 0.f;
        int hframes = 1;
        int vframes = 1;
        float frameRate = 0.f;
        float frameRandomStart = 0.f;
        ParticleGradient colorGradient;
        ParticleCurve sizeCurve;
        ParticleCurve rotationCurve;
        std::string areaType = "none";
        float areaX = 0.f;
        float areaY = 0.f;
        Color colorStart{1.f, 1.f, 1.f, 1.f};
        Color colorEnd{1.f, 1.f, 1.f, 0.f};
        ParticleEmitter *entity = nullptr;
    };
 
    struct Sim {
        std::vector<Particle> particles;
        int alive = 0;
        float emitAccum = 0.f;
        float distanceEmitAccum = 0.f;
        float fixedTimeAccum = 0.f;
        float emitterAge = 0.f;
        bool active = false;
        bool paused = false;
        bool hasLastPos = false;
        float lastX = 0.f;
        float lastY = 0.f;
        bool overflowWarned = false;
        int activeSeed = 0;
        eve::SimulationTick simulationTick    = eve::SimulationTick::zero();
        bool                hasSimulationTick = false;
        int spawnQuota = -1;
        int spawnedThisFrame = 0;
        int droppedSpawnsThisFrame = 0;
        std::mt19937 rng;
    };
 
    struct Draw {
        graphics::Texture *texture = nullptr;
        graphics::Texture*  normalTexture = nullptr;
        graphics::Canvas *canvas = nullptr;     // nullptr → screen
        graphics::Camera2D *camera = nullptr;   // nullptr → screen space (no camera)
        BlendMode blend = BlendMode::Alpha;
        graphics::Shader *shader = nullptr;     // custom fragment pipeline (textured quads only)
        int layer = 0;
        bool visible = true;
    };
 
    struct Resource {
        enum class ReloadObservation {
            Unbound,
            AutoReloadDisabled,
            MtimePollingUnchanged,
            MtimePollingReloaded,
            MtimeUnavailable,
            MtimePollingReloadFailed,
        };
        std::string path;
        std::string texturePath;
        std::string normalTexturePath;
        int64_t modtime = -1;
        bool autoReload = true;
        ReloadObservation lastReloadObservation = ReloadObservation::Unbound;
    };
 
    struct Attach {
        enum class Kind { None, AnimPose, Spine, Ik2D, Ik3D };
 
        Kind kind = Kind::None;
        animation::AnimPose *pose = nullptr;
        animation::AnimSkeleton *skeleton = nullptr;  // optional (name lookup)
        animation::SpineSkeleton *spine = nullptr;
        eve::ik::Skeleton2D *ik2d = nullptr;
        eve::ik::Skeleton3D *ik3d = nullptr;
        int boneIndex = -1;
        float offsetX = 0.f;
        float offsetY = 0.f;
        float offsetZ = 0.f;
        std::string plane = "xy";
        float scale = 1.f;
        bool followRotation = false;
        bool enabled = false;
    };
 
    struct SkinSource {
        animation::AnimSkin *skin = nullptr;
        animation::AnimPose *pose = nullptr;
        animation::AnimSkeleton *skeleton = nullptr;  // optional (name filter)
        int filterBone = -1;                          // skeleton bone index, -1 = all
        float minWeight = 0.f;
        std::string plane = "xy";
        float scale = 1.f;
        bool enabled = false;
        std::vector<int> candidates;
        bool candidatesDirty = true;
        int lastSkinnedFrame = -1;
    };
 
    struct Lights {
        std::vector<graphics::Light2D *> pool;
    };
 
    struct GpuSim {
        bool enabled = false;
        bool failed = false;
        std::uint64_t residentHandle = 0;
        bool residentActive = false;
        int estimatedAlive = 0;
        double timeline = 0.0;
        std::vector<float> deathTimes;
        float pendingWorldOffsetX = 0.f;
        float pendingWorldOffsetY = 0.f;
        std::uint32_t nextBirthSerial = 1;
    };
 
    COMPONENT(Config, config)
    COMPONENT(Sim, sim)
    COMPONENT(Draw, draw)
    COMPONENT(Resource, resource)
    COMPONENT(Attach, attach)
    COMPONENT(SkinSource, skinSource)
    COMPONENT(Lights, lights)
    COMPONENT(GpuSim, gpuSim)
 
    static ParticleEmitter *createEmitter(int bufferSize = 1000);
 
    void setPosition(float x, float y);
    void moveTo(float x, float y);
    float getX();
    float getY();
 
    void setEmissionRate(float rate);
    float getEmissionRate();
    void setEmissionRateOverDistance(float rate);
    float getEmissionRateOverDistance();
 
    void setParticleLifetime(float minLife, float maxLife);
    float getParticleLifetimeMin();
    float getParticleLifetimeMax();
 
    void setEmitterLifetime(float seconds);
    float getEmitterLifetime();
    void setLooping(bool looping);
    bool getLooping();
    void setPlaybackSpeed(float speed);
    float getPlaybackSpeed();
    void setFixedTimeStep(float seconds, int maxSubSteps = 8);
    float getFixedTimeStep();
    void setRandomSeed(int seed);
    int getRandomSeed();
    void setAutoRandomSeed(bool enabled);
    bool getAutoRandomSeed();
 
    void setDirection(float radians);
    float getDirection();
 
    void setSpread(float radians);
    float getSpread();
 
    void setSpeed(float minSpeed, float maxSpeed);
    void setLinearAcceleration(float xmin, float ymin, float xmax, float ymax);
    void setRadialAcceleration(float minA, float maxA);
    void setTangentialAcceleration(float minA, float maxA);
 
    void setEmissionArea(const std::string &type, float x, float y);
    std::string getEmissionAreaType();
    float getEmissionAreaX();
    float getEmissionAreaY();
 
    void setParticleSize(float width, float height);
    float getParticleWidth();
    float getParticleHeight();
 
    void setSizes(float startScale, float endScale);
    void setSizeVariation(float variation);
    float getSizeVariation();
 
    void setSpin(float minSpin, float maxSpin);
    void setStartRotation(float minDeg, float maxDeg);
 
    void addBurst(float time, int count);
    void clearBursts();
    void setPrewarm(float seconds);
    float getPrewarmSeconds();
 
    void setGravity(float x, float y);
    void setDamping(float perSecond);
    void setLimitVelocity(float maxSpeed);
    void clearVelocityCurve();
    void addVelocityCurvePoint(float t, float v);
    void setInheritVelocity(float fraction);
    void setSimulationSpace(const std::string &space);
    void setNoise(float strength, float frequency = 1.f, float speed = 1.f);
    void setGpuSimulation(bool enable);
    bool getGpuSimulation();
    bool isGpuSimulationActive();
    bool isGpuFeatureSetSupported();
    std::string getSimulationBackend();
    std::string getGpuFallbackReason();
 
    void setFloatParameter(const std::string& name, float value);
    float getFloatParameter(const std::string& name, float fallback = 0.f);
    bool hasFloatParameter(const std::string& name);
    void clearFloatParameters();
    void bindFloatParameter(const std::string& name, const std::string& target, float scale = 1.f, float offset = 0.f);
    void clearFloatParameterBindings();
    float getResolvedParameterScale(const std::string& target);
 
    void setPriority(int priority);
    int getPriority();
    void setMinimumQuality(int quality);
    int getMinimumQuality();
    void setCullingMode(const std::string &mode);
    std::string getCullingMode();
    void setCullDistance(float distance);
    float getCullDistance();
    void setMaxSpawnPerFrame(int count);
    int getMaxSpawnPerFrame();
 
    void setCollision(const std::string &mode, float radius = 0.f, float restitution = 0.6f,
                      float lifetimeLoss = 0.f);
    void setCollisionBounds(bool enabled, float minX, float minY, float maxX, float maxY);
    void setWorldCollision(bool enabled);
    void setSdfField(eve::IParticleSdfField* field);
    eve::IParticleSdfField* getSdfField();
    void setMotionVectorPolicy(const std::string& policy);
    std::string getMotionVectorPolicy();
    bool isMotionVectorActive();
 
    void setRenderMode(const std::string &mode, float stretchFactor = 1.f);
    void setRibbon(float width = 1.f, float minSegmentLength = 1.f);
    void setSoftParticles(bool enabled, float particleDepth = 0.5f, float fadeDistance = 0.05f);
    bool isSoftParticlesActive();
    void setRenderAxis(float degrees);
    void setSortMode(const std::string& mode);
    std::string getSortMode();
    void setMaterialMode(const std::string& mode);
    std::string getMaterialMode();
    void setDistortionStrength(float strengthPixels);
    float getDistortionStrength();
    void setOverflowMode(const std::string &mode);
    void setMaxDeltaTime(float seconds);
 
    void addSubEmitter(ParticleEmitter *target, const std::string &trigger,
                       float inheritVelocity = 0.f);
    void clearSubEmitters();
 
    void addForceField(float x, float y, float radius, float strength, float falloff = 1.f);
    void clearForceFields();
 
    void setShader(graphics::Shader *shader);
    graphics::Shader *getShader();
 
    void setLights(bool enabled, float radius = 120.f, float intensity = 1.f, float r = 1.f,
                   float g = 1.f, float b = 1.f, int maxLights = 4);
    bool getLightsEnabled();
 
    void setBlendMode(const std::string &mode);
    std::string getBlendMode();
 
    void setFlipbook(int hframes, int vframes, float framesPerSecond = 0.f,
                     float randomStart = 0.f);
 
    void clearColorGradient();
    void addColorStop(float t, float r, float g, float b, float a);
    void clearSizeCurve();
    void addSizeCurvePoint(float t, float v);
    void clearRotationCurve();
    void addRotationCurvePoint(float t, float v);
 
    void setColorStart(float r, float g, float b, float a = 1.f);
    void setColorEnd(float r, float g, float b, float a = 1.f);
 
    void setTexture(graphics::Texture *texture);
    graphics::Texture *getTexture();
    void setNormalTexture(graphics::Texture* texture);
    graphics::Texture* getNormalTexture();
 
    void setCanvas(graphics::Canvas *canvas);
    void setCamera(graphics::Camera2D *camera);
 
    void setLayer(int layer);
    int getLayer();
 
    void setVisible(bool visible);
    bool isVisible();
 
    void start();
    void stop();
    void pause();
    void reset();
    void emit(int count);
 
    [[nodiscard]] eve::Result<void> advance(const eve::SimulationStep &step);
 
    [[nodiscard]] eve::SimulationTick currentSimulationTick() const noexcept {
        // ECS.hpp's generated accessor has no const overload and would create
        // a missing component. Query the existing table buffer directly so a
        // read-only tick query neither casts away constness nor mutates ECS.
        auto *const buffer = storage ? storage->getComponentBuffer<Sim>() : nullptr;
        if (!buffer || id >= buffer->size()) return eve::SimulationTick::zero();
        // The size guard makes this existing-slot read non-mutating; ECS.hpp's
        // const overload currently attempts to resize its deque.
        return buffer->get(id).simulationTick;
    }
 
    bool isActive();
    bool isPaused();
    bool isStopped();
 
    int getCount();
    int getBufferSize();
 
    void applyPreset(const std::string &name);
 
    bool applyConfig(const std::string &json);
    bool loadConfig(const std::string &path);
    bool reloadConfig();
    void setAutoReload(bool enable);
    bool getAutoReload();
    std::string getConfigPath();
    [[nodiscard]] std::string getConfigReloadObservation() const;
 
    // --- Bone attachment (3D AnimPose / 2D Spine / IK 2D·3D) ---
    void attachToBone(animation::AnimPose *pose, int boneIndex);
    void attachToBoneByName(animation::AnimPose *pose, animation::AnimSkeleton *skeleton,
                            const std::string &boneName);
    void attachToSpineBone(animation::SpineSkeleton *spine, int boneIndex);
    void attachToSpineBoneByName(animation::SpineSkeleton *spine, const std::string &boneName);
    void attachToSkeleton2D(eve::ik::Skeleton2D *skeleton, int boneId);
    void attachToSkeleton3D(eve::ik::Skeleton3D *skeleton, int boneId);
    void setAttachOffset(float x, float y, float z);
    void setAttachPlane(const std::string &plane);
    void setAttachScale(float scale);
    void setFollowBoneRotation(bool enable);
    void detach();
    bool isAttached();
    int getAttachBone();
    std::string getAttachKind();
    void syncAttach();
 
    // --- Skinned mesh surface emission ---
    void setSkinSource(animation::AnimSkin *skin, animation::AnimPose *pose);
    void setSkinBoneFilter(int skeletonBoneIndex, float minWeight = 0.f);
    void setSkinBoneFilterByName(animation::AnimSkeleton *skeleton, const std::string &boneName,
                                 float minWeight = 0.f);
    void setSkinPlane(const std::string &plane);
    void setSkinScale(float scale);
    void clearSkinSource();
    bool hasSkinSource();
    void emitFromSkin(int count);
};
 
bool spawnParticle(ParticleEmitter::Config &cfg, ParticleEmitter::Sim &sim);
bool spawnParticleAt(ParticleEmitter::Config &cfg, ParticleEmitter::Sim &sim, float x, float y);
void stepEmitterSim(ParticleEmitter::Config &cfg, ParticleEmitter::Sim &sim, float dt);
EVENGINE_API_DOMAINS float advanceEmitterSim(ParticleEmitter::Config &cfg, ParticleEmitter::Sim &sim, float dt);
[[nodiscard]] EVENGINE_API_DOMAINS eve::Result<void> advanceEmitterSim(ParticleEmitter::Config   &cfg,
                                                                       ParticleEmitter::Sim      &sim,
                                                                       const eve::SimulationStep &step);
using WorldCollisionFn = bool (*)(float x, float y, float radius, float &nx, float &ny);
void setWorldCollisionResolver(WorldCollisionFn fn);
WorldCollisionFn getWorldCollisionResolver();
void syncEmitterSources(ParticleEmitter::Config &cfg, ParticleEmitter::Sim &sim,
                        ParticleEmitter::Attach &attach, ParticleEmitter::SkinSource &skinSrc);
bool sampleSkinSpawn(ParticleEmitter::SkinSource &skinSrc, ParticleEmitter::Sim &sim, float &outX,
                     float &outY);
 
}  // namespace eve::particles