====== Effekseer (effect) ======

This is used to play effects in VCI.\\
For the details of how to use the component, refer to [[en:vci:component:sdk:effekseer| Effekseer (for VCI)]].

===== List of functions =====

**For the latest list of the methods, refer to "types.lua" file in "EmbeddedScriptWorkspace" folder. **

^ Function ^ Description ^
| EffectName | Acquire the effect name as a  string. |
| Play() | Loop play the effect until it is stopped. |
| PlayOneShot() | Play the effect once. |
| Stop() | Stop the effect. It disappears gradually. |
| StopImmediate() | Stop the effect.\\ The effect disappears instantaneously. |
| StopRoot() |  |
| SetAllColor(color: Color) | Change the color of the effect. |
| SetTargetLocation(targetLocation: Vector3) | Specify the target location of the effect. |
| SetPause (paused: bool) | Pause the effect at the specified timing. |
| SetShow (shown: bool) | Switch between show/hide of the effect. |
| SetSpeed (speed: number) | Change the speed of the effect.\\ The base speed is 1 and the speed can be specified with its multiple. |
| SetLoop (isLoop: bool) | The effect will loop when set to true.\\ The default is the value set in Effekseer Emitter. |

The methods with ''_ALL_'' are synchronized and run on other clients as well.\\
If you want the result to be the same in all clients, use methods with ''_ALL_'' prefix.

^ Method ^ Description ^
| _ALL_Play () | Loop play the effect until it is stopped. |
| _ALL_PlayOneShot () | Play the effect once. |
| _ALL_Stop () | Stop the effect. It disappears gradually. |
| _ALL_StopImmediate () | Stop the effect.\\ The effect disappears instantaneously. |
| _ALL_StopRoot () |  |
| _ALL_SetAllColor (color: Color) | Change the color of the effect. |
| _ALL_SetTargetLocation (targetLocation: Vector3) | Specify the target location of the effect. |
| _ALL_SetPause (paused: bool) | Pause the effect at the specified timing. |
| _ALL_SetShow (shown: bool) | Switch between show/hide of the effect. |
| _ALL_SetSpeed (speed: number) | Change the speed of the effect.\\ The base speed is 1 and the speed can be specified with its multiple. |
| _ALL_SetLoop (isLoop: bool) | The effect will loop when set to true.\\ The default is the value set in Effekseer Emitter. |

===== The basic how to use  =====

  - Attach an EffekseerEmitter component on a SubItem.
  - Execute ''vci.assets.GetEffekseerEmitter("SubItem")'' or\\ ''vci.assets.GetEffekseerEmitters("SubItem")'' to store the effect from SubItem into a variable. For the argument, specify the name of the target gemeobject with string.\\
  - Execute functions against the variable storing the effect to play, store and execute other actions.

** *For the details on the component and how to set it up**, refer to [[en:vci:component:sdk:effekseer|Effekseer (for VCI)]].

Example\\
<file lua main.lua>
-- Specify the name of the GameObject with the effect attached to store the effect.
-- Store the effect attached to the GameObject named "Effect" in a variable "effect"
local effect = vci.assets.GetEffekseerEmitter("Effect")

-- Print the effect name
print(effect.EffectName)

function onUse()
    -- Play the stored effect once
    effect.PlayOneShot()
end
</file>

The result\\
<code lua>
(The effect is played once when the subitem is used)
</code>

===== EffectName =====

**Return value: string**

  * Acquire the file name of the effect assigned to the EffectAsset of the EffekseerEmitter.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")

-- Print the name of the effect to play
print("Play the effect: ".._Effect.EffectName)

-- Start playing the effect
_Effect._ALL_Play()
</file>

The result\\
<code lua>
Play the effect: Effect
(The effect stored in _Effect starts to play)
</code>

===== Play() =====

**Argument: none**

  * Start playing the effect
  * If the effect is set to loop, it will continue to play until Stop() is called.
  * If the loop is not set, the effect will stop playing when the duration of the effect has ended.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")

function onUse()
    -- Start playing the effect when used
    _Effect._ALL_Play()
    print("Start playing the effect: ".._Effect.EffectName)
end

function onUnuse()
    -- Stop playing the effect when unused
    _Effect._ALL_Stop()
    print("Stop playing the effect: ".._Effect.EffectName)
end
</file>

The result\\
<code lua>
(The effect starts to play when used)
(The effect stops playing when unused)
</code>

===== PlayOneShot() =====

**Argument: none**

  * Play the effect once even when the effect is set to loop.
  * Executing this while the effect is playing will stop the currently playing effect and start over.

<file lua main.lua>

-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItemLoop")

function onUse()
    -- Play the effect once  
    _Effect._ALL_PlayOneShot()
end

</file>

The result\\
<code lua>
(The effect is played once)
</code>

===== Stop() =====

**Argument: none**

  * Stop the effect being played with Play().

<file lua main.lua>

-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")

function onUse()
    -- Start playing the effect when used
    _Effect._ALL_Play()
    print("Start playing the effect: ".._Effect.EffectName)
end

function onUnuse()
    -- Stop playing the effect when unused
    _Effect._ALL_Stop()
    print("Stop playing the effect: ".._Effect.EffectName)
end
</file>

The result\\
<code lua>
(The effect starts to play when used)
(The effect stops playing when unused)
</code>

===== StopImmediate() =====

**Argument: none**

  * tips1
  * tips2

<file lua main.lua>
</file>

The result\\
<code lua>
</code>

===== StopRoot() =====

**Argument: none**

  * tips1
  * tips2

<file lua main.lua>
</file>

The result\\
<code lua>
</code>

===== SetAllColor() =====

**1st argument: color (color)**

  * When using SetAllColor(), use white for the texture color.
  * Specify the color with [[en:vci:script:reference:color|Color]] type.
  * The color returns to the original color when the effect stops playing.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")
-- Start playing the effect
_Effect._ALL_Play()

function onUse()
    -- Create a random color
    local color = Color.__new(math.random(0,100) * 0.01, math.random(0,100) * 0.01, math.random(0,100) * 0.01, 1)
    _Effect.SetAllColor(color)
end
</file>

The result\\
<code lua>
(The color of the effect changes randomly when used)
</code>

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")
-- Start playing the effect
_Effect._ALL_Play()

function onUse()
    -- Change the color of the effect to blue
    _Effect.SetAllColor(Color.blue)
end

function onUnuse()
    -- Change the color of the effect to red
    _Effect.SetAllColor(Color.red)
end
</file>

The result\\
<code lua>
(The color of the effect changes to blue when used)
(The color of the effect changes to red when unused)
</code>

===== SetTargetLocation() =====

**1st argument: targetLocation (Vector3)**

  * tips1
  * tips2

<file lua main.lua>
</file>

The result\\
<code lua>
</code>

===== SetPause() =====

**1st argument: paused (bool)**

  * true to pause the effect, false to resume the effect.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItemLoop")
-- Start playing the effect
_Effect._ALL_Play()

function onUse()
    -- Pause the effect
    _Effect._ALL_SetPause(true)
end

function onUnuse()
    -- Resume the effect
    _Effect._ALL_SetPause(false)
end
</file>

The result\\
<code lua>
(Spawn the item to play the effect)
(The effect pauses when used)
(The effect resumes when unused)
</code>

===== SetShow() =====

**1st argument: shown (bool)**

  * True will show the effect, false will hide the effect.
  * When the effect ended with the false state, re-playing the effect will turn state back to the show state.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItemLoop")
-- Start playing the effect
_Effect._ALL_Play()

function onUse()
    -- Hide the effect
    _Effect._ALL_SetShow(false)

end

function onUnuse()
    -- Show the effect
    _Effect._ALL_SetShow(true)
end
</file>

The result\\
<code lua>
(Spawn the item to play the effect)
(When used, the effect will be hidden)
(When unused, the effect will be shown)
</code>

===== SetSpeed () =====

**1st argument: Speed(number)**

  * Change the play speed of the effect.

<file lua main.lua>

-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")

function onUse()
    -- Assign a random value between 1.0 and 3.0 into the speed
    local speed = 0.1 * math.random(10, 30)

    -- Change the play speed of the effect
    _Effect._ALL_SetSpeed(speed)

    -- Play the effect only once
    _Effect.PlayOneShot()
end
</file>

The result\\
<code lua>
(When used, play the effect once with a random speed between 1x and 3x)
</code>

===== SetLoop () =====

**1st argument: isLoop (bool)**

  * true will set the effect to play in a loop, false will disable the loop play.

<file lua main.lua>
-- Store the effect attached to the GameObject
local _Effect = vci.assets.GetEffekseerEmitter("EffectItem")

function onGrab()
    -- Set the effect to play in loop
    _Effect._ALL_SetLoop(true)
    -- Start playing the effect
    _Effect._ALL_Play()
end

function onUse()
    -- Disable the loop play of the effect
    _Effect._ALL_SetLoop(false)
    -- Start playing the effect
    _Effect._ALL_Play()
end
</file>

The result\\
<code lua>
(Grab will start the loop play of the effect)
(Use will play the effect only one and ends)
</code>