# Status Effects

More information about status effects and the associated job can be found on the store: [Status Effects](https://billing.tmc.bj/store/fivem/tmc-status-effects-and-job).

## Framework Integrations

### TMC.Common.TryApplyLuck

Attempts to apply luck to a value if statuseffects is running and the player has luck effects. For more info look at the [ApplyLuck](#applyluck) section.

```lua
local reward = TMC.Common.TryApplyLuck(
    50, --[[ original value ]],
    false, -- [[ negative check, if the luck should reduce the output instead ]])
    1, -- [[ If called from the server, this is the player server id. Otherwise unused.]]
)
```

### TMC.Common.RandomChanceWithLuck

This works the same way as TMC.Common.RandomChance however will apply luck internally to return a true/false value

```lua
TMC.Common.RandomChanceWithLuck(
    1, -- [[ min ]]
    100, -- [[ max ]]
    50, -- [[ chance ]]
    false, -- [[ negative check, if the luck should reduce the chance instead ]]
    70, -- [[ optional, a maximum possible percentage after adjustment ]]
    1 -- [[ required on server side, player server id ]]
)
```

## Client Exports

### GetEffectValue

A client function that can be used to get the current (total) value of an effect.

```lua
local effectVal = exports.statuseffects:GetEffectValue('hardening')
```

### ApplyLuck

Apply luck onto a value using the luck status effect. This is used to increase/decrease returned values based on the luck the player has. Useful for increasing robbery payouts, reducing rob chances, etc.

```lua
local rewardAmount = exports.statuseffects:ApplyLuck(
    50 --[[ original value ]],
    false --[[ negative check, if the luck should reduce the output value instead ]]
)
```

## Server Exports

### ApplyLuck

This works in the same way as the client function however must be provided with the player's server id.

```lua
local rewardAmount = exports.statuseffects:ApplyLuck(
    50 --[[ original value ]],
    false, --[[ negative check, if the luck should reduce the output value instead ]]
    1 --[[ The player's server id ]]
)
```

## Player Functions

Player functions are available via the player object (TMC.Functions.GetPlayer)

### GetStatusEffectValue

Gets the current (total) value of an effect for a player.

```lua
local effectVal = player.Functions.GetStatusEffectValue('focus')
```

### GetStatusEffect

Returns the full list of items contributing to the status effect value.

```lua
local effectList = player.Functions.GetStatusEffect('focus')
```

### HasStatusEffects

Returns true if there are any active status effects for the player

```lua
if player.Functions.HasStatusEffects() then
    print('Has Status Effects')
end
```

### AddStatusEffect

Used to add a status effect to a player

```lua
player.Functions.AddStatusEffect(
    'focus', --[[ The type of status to add ]]
    'groupref', --[[ The group to add the status effect to. Groups are used to limit when a status effect is used within calculation. If 2 effects have the same groupref only the highest, non-expired one will be used. ]]
    'uniqueref', --[[ The unique reference to use. 
                      If the same effect is added with the same unique ref it will be overridden.
                      Multiple different effects can have the same unique ref without overwriting. ]]
    50, --[[ The strength of the effect to add (1- 100) ]]
    TMC.Common.GetTime() + 60000 --[[ An millisecond timestamp of when the effect should expire.
                                      This is optional. ]]
)
```

### RemoveStatuseffect

Remove status effect by the unique reference

```lua
local success = player.Functions.RemoveStatusEffect('uniqueref')
```