Utilizing Particles

# Course Introduction

From the [Using Particles](/docs/?postId=1036) guide, we learned the concepts and types of particle components. This time, we'll see examples of particle use by using scripts.

# Particle Scripts

## Controling Particle Properties

Let's see how to control particle properties through an example in which the play speed of particles changes according to the distance from the character.

  1. Set a dark background so that the particles can be seen clearly, place the topography, and place the desired particles. In this example, back-16 is set as the Background and Nova is placed as the particle. [png](1660613012572797db96a127d4a01a0ecd37f02c3ae02)

  2. Generate the new script component  ParticlePlaySpeed in  Workspace -  MyDesk.

  3. Add [png](Ect) ParticlePlaySpeed to the particle Entity's  Property placed in the map.

  4. Open  ParticlePlaySpeed, add `OnUpdate()` function, and write the script as follows.
         
         @Component
         script ProximityParticleSpeedController extends Component
         @ExecSpace("ClientOnly")
         method void OnUpdate(number delta)
         local positionA = Vector2(self.Entity.TransformComponent.Position.x,self.Entity.TransformComponent.Position.y)
         local positionB = Vector2(_UserService.LocalPlayer.TransformComponent.Position.x,_UserService.LocalPlayer.TransformComponent.Position.y)
         local distance = Vector2.Distance(positionA, positionB)
         
         self.Entity.BasicParticleComponent.PlaySpeed = distance
         end
         end
         



    
    
    5. Let's press  Start and test. You can check the particle playing slowly as the character gets closer to the particle and faster as they move away.
        [gif](16606131392543e4d5902b9d74e7ba57dadb7ad920fb5)
    
    ## Changing Particle Playing State
    Let's see how to play a particle or stop a particle that is playing when a certain event occurs. You can make these functions via the `Play()` and `Stop()` functions. Let's look at an example that stops a particle from playing when a character collides with a specific entity.
    
    1. In  Workspace -  DefaultPlayer's  Property, add BasicParticleComponent by pressing the "+" button.
    [png](1660290482559d3eb4baea5eb46a3b16be66aba558091)
    
    2. Set ParticleType to FireField.
    [png](1660290572916bf1ddbdf34bb4d799dca05964b5c5712)
    
    3. Generate the new script component  ParticleController in  Workspace -  MyDesk.
    
    4. Add [png](Ect) ParticleController to  DefaultPlayer's  Property.
    
    5. Open  ParticleController, add  TriggerEnterEvent in Event Handler, and write as follows.
        ```lua
    @Component
    script TriggerParticleStopper extends Component
        @EventSender("Self")
        handler HandleTriggerEnterEvent(TriggerEnterEvent event)
        -- Parameters
        local TriggerBodyEntity = event.TriggerBodyEntity
        --------------------------------------------------------
        self.Entity.BasicParticleComponent:Stop()
        end
    end
    

  6. Place Entity to activate a trigger and add [png](collision) TriggerComponent. This example used  Preset List - object-1814. [png](16602924504597b005ed1a05d4844ae69349f39372d47)

  7. Now press  Start and test. You can see that the FireField particle attached to the character's body disappears when it hits the waterfall entity. [gif](16602925276347f42645d58414436a13cd40260c6744b)




# Particle Services

Let's learn how to control particles using particle services.

## One-Time Particle Generation

  1. Set a dark background so that the particles can be seen clearly, place the topography, and place the desired entity. In this example, Background - back-51 is set, and Object - object-174 is placed in the  Preset List. [png](1660614857422a2b18c5225874b859938ae7d87d119e1)

  2. Generate the new script component  ParticleServiceTest in  Workspace -  MyDesk.

  3. Add [png](Ect) ParticleServiceTest to the placed Entity (object-174)'s  Property.

  4. Add [png](Ect) TweenCircularComponent to it and set as follows. [png](166061571192425e9d621c5c54d8f8d64fad989e65a7e)   


  5. Open  ParticleServiceTest, add the `AddParticle()` function, and then write the script as follows.
         
         @Component
         script FireworkPlayer extends Component
         method void AddParticle()
         local option = {["Color"] = Color(0.25,0.5,0.5, 1), ["ParticleCount"] = 3}
         
         _ParticleService:PlayBasicParticle(BasicParticleType.Firework, self.Entity, self.Entity.TransformComponent.WorldPosition, 0, Vector3(1,1,1), false, option)
         -- Play the particles through ParticleService's PlayBasicParticle() function. Loop is set to false so that the particle would only play once.
         end
         end
         



    
    
       
    6. Add the `OnBeginPlay()` function and write as follows.
        ```lua
    @Component
    script TimedParticleSpawner extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
        _TimerService:SetTimerRepeat(self.AddParticle, 2, 0) 
        -- Make the AddParticle function work once every 2 seconds.
        end
    end
    

  7. Press  Start and test. You can see that the entity generates particles once every 2 seconds. [gif](1660617146781af026d51a0bc46e1acf08c4ab0ea2158)



## Generation and Deletion of Repeating Particles

Let's learn how to generate and delete the repeatedly playing particles. Let's create an exercise where particles get generated when a character touches a specific entity and then stop when the character arrives at a target point.

  1. Place the entity that will emit particles and the target entity. In this example, the entity to emit particles is set as object-24 (vial), and the target Entity as object-928 (fire extinguisher). [png](1660626870398bc48f56357f64b8896d961b26265f31a)

  2. Add [png](collision) TriggerComponent to all placed entities.

  3. Generate the new script component  ParticleServiceTest02 in  Workspace -  MyDesk.

  4. Open  ParticleServiceTest02 and add the property as follows.
         
         @Component
         script RespawnManager extends Component
         property Entity ResetEntity = nil
         property SyncTable SpawnList
         end
         



    
    
        
    5. Let's say the particles must be generated once the character touches the vial and disappear when it touches the fire extinguisher. Add  TriggerEnterEvent to  ParticleServiceTest02's Event Handler and write as below.
        ```lua
    @Component
    script TriggeredParticleManager extends Component
        @EventSender("Self")
        handler HandleTriggerEnterEvent(TriggerEnterEvent event)
        -- Parameters
        local TriggerBodyEntity = event.TriggerBodyEntity
        --------------------------------------------------------
        if TriggerBodyEntity ~= self.ResetEntity then
           local serial = _ParticleService:PlayBasicParticleAttached(BasicParticleType.ToonTallFire, TriggerBodyEntity, Vector3.zero, 0, Vector3.one, true)
           table.insert(self.SpawnList, serial)
           -- When a character hits an entity other than the target entity, a particle will be generated from that entity via the PlayBasicParticleAttached() function.
        else
           for idx, serial in pairs(self.SpawnList) do
               _ParticleService:RemoveParticle(serial)
           -- When the character touches the target entity, all previously generated particles will be removed through the RemoveParticle() function.
           end
           table.clear(self.SpawnList)
    
        end
        end
    end
    

  6. Add [png](Ect) ParticleServiceTest02 to  Workspace -  DefaultPlayer. Then specify the target Entity (ResetEntity). [png](16606287624144a1602d085b94be9a8a2a82da2df2c2c)

  7. Press  Start and test. You can see that when the character's body touches the vial, the flame particles are played, and touching the fire extinguisher makes the flame particles disappear. [gif](16606269436796b58e75202444fc39e8d8bb970970fe7)




# Particle Events

You can use particle events to inflict damage or show direction whenever particles are repeatedly generated. Let's take a look at how to use particle events with an example where the attack function activates and damages the character whenever lightning strikes.

  1. Place the  Preset List - LightningStrikeSharp particle. [png](16606310495644b54ab47cff543aaada7c7264539eadc)

  2. Extend AttackComponent and generate the new script component  ExtendAttackComponent. [png](16606293771586eb9e239b50d424d8d0c5f5d79e31eb5)

  3. Open  ExtendAttackComponent and add the `OnLightning()` function.
         
         @Component
         script LightningAttacker extends Component
         method void OnLightning()
         self:Attack(Vector2(2, 2), Vector2.zero, nil)
         -- Use the Attack() function to determine the attack.
         end
         end
         



    
    
    4. In Event Handler, add  ParticleEmitStartEvent and write as follows.
        ```lua
    @Component
    script ParticleLightningTrigger extends Component
        @EventSender("Self")
        handler HandleParticleEmitStartEvent(ParticleEmitStartEvent event)
        -- Parameters
        local ParticleEntity = event.ParticleEntity
        --------------------------------------------------------
        self:OnLightning()
        -- Make the OnLightning function work when starting particles.
        end
    end
    

  5. In Event Handler, add  ParticleLoopEvent and write as follows. 
         
         @Component
         script LightningEffectHandler extends Component
         @EventSender("Self")
         handler HandleParticleLoopEvent(ParticleLoopEvent event)
         -- Parameters
         local ParticleEntity = event.ParticleEntity
         --------------------------------------------------------
         self:OnLightning()
         -- Make the OnLightning function work when starting particles.
         end
         end
         



    
    
    6. Add [png](Ect) ExtendAttackComponent to the initially placed LightningStrikeSharp particle's  Property.
        
    7. Press  Start and test. You can see that the character takes damage when struck by lightning.
        [gif](166063078658715693caafe5c498cb4d1afb74ab490ca)
    
    > **Learn More**
    > [Attack and Hit](/docs?postId=206) Let's try a variety of effects by referring to the guide.
    
    
    # Using Particles in UI
    
    If you want to play particles in UI, you must use UIBasicParticleComponent, UIAreaParticleComponent, and UISpriteParticleComponent. Let's learn how to use particles in UI through an example using UIBasicParticleComponent.
    [gif](1738820159173bac2118a2b8e4fb3939212dacdec4c30)
    
    #### Making UI
    Let's make a UI that can play particles. 
    
    1.  Add a new **UIGroup** to **Hierachy - World - ui**.
    2. Set the **DefaultShow** propery under **UIGroupComponent** from the added UIGroup to **true**.
    [png](1738820526946c8b71422566e4a919660cc52294d2f78)
    3. From UIGroup, press **Context Menu - Create Empty - Create Button** to add a new **UIButton**.
    4. From UIButton, select **Context Menu - Create Entity as Child - Create UIEmpty**. Change the created entity's name to **UIParticle**.
    [png](1738821689063de9df9de3eb24d1ca3aaab61c30a0d34)
       
    
    #### Creating Particles
    1. Add **UIBasicParticleComponent** to **UIParticle**.
    
    2. Set the ParticleType as **CircleBust** and adjust to the desired particle size, speed, etc.
    3. Set the **Loop** for **UIBasicParticleComponent** as **false** to make the particle play only once when the button is pressed. Also set **PlayOnEnable** to **false** to ensure the particle doesn't play immediately upon entering a world. 
    [png](1738824957555795b8fa96c3b4e31a73bd9d943735ea5)
    4. Select **Workspace - Create Script - Create Component** to create a new **UIButtonParticle**.
    5. Add the created **UIButtonParticle** to the **UIButton** entity.
    [png](17388237882156f14f1b12db546a1a445464f92d57fa1)
    6. Add a **particleEntity** property to UIButtonParticle. Set the property type to **Entity** and link the **UIParticle** entity.
       [png](173882498272778923333c4a64ed8ad7b1c6c67ddbb18)
    

@Component script ParticleEntityReference extends Component property Entity particleEntity = "/ui/UIGroup/UIButton/UIParticle" end
    
    
    7. Add **ButtonClickEvent** to Event Handler.
    Write the following so that the particle will play when pressing the button.
    
    

@Component script ButtonParticlePlayer extends Component @EventSender("Self") handler HandleButtonClickEvent(ButtonClickEvent event) \--------------- Native Event Sender Info ---------------- \-- Sender: ButtonComponent \-- Space: Client \---------------------------------------------------------
    
    
    -- Parameters
    -- local Entity = event.Entity
    ---------------------------------------------------------
    local Entity = event.Entity
    ---------------------------------------------------------
    if self.particleEntity.UIBasicParticleComponent.IsEmitting == true then
        self.particleEntity.UIBasicParticleComponent:Stop()
    end
        self.particleEntity.UIBasicParticleComponent:Play()
    end
    

end
    
    
    8. After adjusting the entity's size, press the  **[Start]** button to see if the particle plays each time a button is pressed.