Direct Effects

Apply temporary effects directly to players from your own scripts.

Overview

Direct effects let you apply temporary client-side effects to a player on-demand from any server-side script. Unlike status-driven effects (which activate automatically based on thresholds), direct effects are triggered explicitly by you through an export.

Use cases include:

• A drug script applying screen effects and stumbling for 60 seconds

• A flashbang applying blurry vision and camera shake

• An injury system slowing the player down

• A food item giving a temporary strength boost

Direct effects use the same effect system as statuses. They share the same queue, the same dominance resolution, and the same effect keys. If a status and a direct effect both try to control walkingStyle, the system picks the most severe one automatically.

---

Table of Contents

• Adding Effects

• Real-World Examples

• Effect Keys

• Simple vs Rich Values

• Reactions

• Duration & Stacking

• Activation Threshold

• FAQ

---

Adding Effects

Use the AddDirectEffect export from any server-side script:

exports["zyke_status"]:AddDirectEffect(playerId, effects, activationThreshold)

Parameter	Type	Required	Description
playerId	integer	Yes	The server-side player ID
effects	table[]	Yes	Array of effect entries (see below)
activationThreshold	integer	No	Seconds of total duration before effects kick in

Each entry in the effects array has three fields:

Field	Type	Description
name	string	The effect key (see table below)
value	string, number, boolean, or table	The effect value
duration	number	How long it lasts in seconds

Basic Example

-- Slow the player and shake their camera for 30 seconds
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 0.7, duration = 30},
    {name = "cameraShaking", value = {value = "DRUNK_SHAKE", intensity = 0.3}, duration = 30},
})

---

Real-World Examples

These examples show how you'd call AddDirectEffect from your own server scripts. All of them go inside a server-side event, callback, or item use handler.

Energy Drink — Temporary Speed Boost

A player drinks an energy drink and gets a short burst of speed and extra punch strength.

-- Inside your item use handler (server side)
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 1.2, duration = 120},
    {name = "strength", value = 1.5, duration = 120},
})

The player runs faster and hits harder for 2 minutes, then everything returns to normal automatically.

Smoking Weed — Trippy Visuals

A player smokes a joint. They get a screen overlay, wobbly walking, and a slight stumble for a few minutes.

exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "screenEffect", value = {value = "Dax_TripBlend01", intensity = 0.4}, duration = 180},
    {name = "walkingStyle", value = "move_m@drunk@slightlydrunk", duration = 180},
    {name = "stumble", value = 1.0, duration = 180},
})

If they smoke another one while the first is still active, the durations stack. They'll be stumbling around for even longer.

Flashbang — Intense Short Burst

A player gets hit by a flashbang. Heavy screen effect, blurry vision, and camera shake — but it only lasts a few seconds.

exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "screenEffect", value = {value = "BarryFadeOut", intensity = 1.5}, duration = 8},
    {name = "blurryVision", value = true, duration = 8},
    {name = "cameraShaking", value = {value = "DRUNK_SHAKE", intensity = 1.0}, duration = 8},
    {name = "blockSprinting", value = true, duration = 5},
})

Leg Injury — Slowed Down

A player gets injured and can't run properly. Combine reduced speed with blocked sprinting and jumping.

exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 0.6, duration = 300},
    {name = "blockSprinting", value = true, duration = 300},
    {name = "blockJumping", value = true, duration = 300},
    {name = "walkingStyle", value = "move_m@drunk@a", duration = 300},
})

The player limps around for 5 minutes. If they receive medical treatment, the effects expire naturally (or you can avoid adding them in the first place based on your logic).

Poisoned Food — Coughing Reaction

A player eats something dodgy. They start coughing with a looping animation and sound, plus a subtle screen tint.

exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "screenEffect", value = {value = "InchPurple02", intensity = 0.3}, duration = 90},
    {
        name = "reaction",
        value = {
            animation = {
                dict = "timetable@gardener@smoking_joint",
                clip = "idle_cough",
                flag = 49,
                start = 800,
                stop = 2000,
            },
            sound = {
                name = {"cough_m1.wav", "cough_m2.ogg"},
                volume = 0.2,
                distance = 5.0,
            },
            loop = {
                delay = {8000, 15000},
            },
        },
        duration = 90,
    },
})

The player coughs every 8–15 seconds with a random sound pick, while a subtle purple tint sits on their screen for 90 seconds.

---

Effect Keys

These are the same keys used in status configs. All of them work with direct effects:

Key	Value Type	Description
screenEffect	string or {value, intensity}	Applies a timecycle modifier as a screen overlay
cameraShaking	string or {value, intensity}	Shakes the gameplay camera
walkingStyle	string	Changes the player's movement clipset (walk animation)
blurryVision	boolean	Periodically fades a blur overlay in and out
blockJumping	boolean	Prevents the player from jumping
blockSprinting	boolean	Prevents the player from sprinting
movementSpeed	number	Scales run/sprint speed (1.0 = normal, lower = slower)
strength	number	Scales unarmed melee damage (1.0 = normal)
stumble	number	Chance-based stumbling/ragdoll (higher = more frequent)
reaction	table	Synchronized animation + sound (see below)

---

Simple vs Rich Values

Some effect keys accept either a simple value or a table with extra options. Both forms are valid:

-- Simple: just the effect name, uses default intensity of 1.0
{name = "screenEffect", value = "BarryFadeOut", duration = 30}

-- Rich: with explicit intensity
{name = "screenEffect", value = {value = "BarryFadeOut", intensity = 0.3}, duration = 30}

-- Simple
{name = "cameraShaking", value = "DRUNK_SHAKE", duration = 30}

-- Rich
{name = "cameraShaking", value = {value = "DRUNK_SHAKE", intensity = 0.5}, duration = 30}

For walkingStyle, blurryVision, blockJumping, blockSprinting, movementSpeed, strength, and stumble, the simple value is all you need.

---

Reactions

Reactions combine animations and/or sounds. They work the same way as in status configs, but you pass the full reaction table as the value:

exports["zyke_status"]:AddDirectEffect(playerId, {
    {
        name = "reaction",
        value = {
            animation = {
                dict = "timetable@gardener@smoking_joint",
                clip = "idle_cough",
                flag = 49,
                start = 800,
                stop = 2000,
            },
            sound = {
                name = "stomach_growl.ogg",
                volume = 0.2,
                distance = 2.0,
            },
            loop = {
                delay = {5000, 10000},
            },
        },
        duration = 60,
    }
})

You don't need both animation and sound, either one on its own works fine.

Animation Fields

Field	Type	Default	Description
dict	string		Animation dictionary
clip	string		Animation clip name
flag	integer	49	Animation flag (49 = upper body, doesn't freeze)
start	integer	nil	Start time in ms (skip the beginning)
stop	integer	nil	Stop time in ms (cut the animation short)
blendInSpeed	number	1.0	How fast the animation blends in
blendOutSpeed	number	1.0	How fast the animation blends out
forceAnim	boolean	false	Force replay even if already playing
speed	number	1.0	Playback speed

Sound Fields

Field	Type	Default	Description
name	string, string[], or table		Sound file(s). Supports {male = ..., female = ...} for gendered audio
volume	number	0.3	Playback volume
distance	number	10.0	How far other players can hear it

Sounds require zyke_sounds to be running. If it's not available, the sound part is silently skipped.

Loop Settings

Field	Type	Description
delay	integer or {min, max}	Delay in ms before repeating. Use a table for a random range

If loop is not defined, the reaction plays once and does not repeat.

---

Duration & Stacking

Duration is in seconds. The server counts down each effect's duration automatically. When it reaches zero, the effect is removed and the client is updated.

Stacking works intelligently:

• Same effect key, same value: Durations are merged (added together). Calling AddDirectEffect twice with movementSpeed = 0.7 for 30 seconds gives you 60 seconds total.

• Same effect key, different value: Both are tracked separately. The system uses the most dominant value. When the stronger one expires, the weaker one takes over automatically.

• Number values close together: If two numeric values are within 0.1 of each other (configurable via Config.Settings.directEffects.accuracyMerge), they are merged to keep things efficient.

-- First call: speed 0.7 for 30s
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 0.7, duration = 30},
})

-- Second call: same speed, durations add up (now 60s total)
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 0.7, duration = 30},
})

-- Third call: different speed, tracked separately
-- 0.5 is more severe, so it plays first. When it expires, 0.7 takes over.
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "movementSpeed", value = 0.5, duration = 10},
})

Boolean effects (like blockJumping) always merge into a single entry with the combined duration.

---

Activation Threshold

The optional activationThreshold parameter delays when effects actually start playing. The value is in seconds of total accumulated duration across all direct effects.

-- Effects won't kick in until the player has at least 15 seconds of total direct effect duration
exports["zyke_status"]:AddDirectEffect(playerId, {
    {name = "screenEffect", value = "BikerFilter", duration = 30},
}, 15)

This is useful for gradual build-up effects, where you don't want a single small dose to trigger visuals, but repeated doses should. The timer ticks in the background even before the threshold is met.

Most of the time you can ignore this parameter and effects will start immediately.

---

FAQ

Q: Is this a server-side or client-side export? Server-side only. The system handles syncing to the client automatically.

Q: Are direct effects saved to the database? Yes. They persist across reconnects and restarts. The remaining duration picks up where it left off.

Q: Do direct effects conflict with status effects? They share the same queue. If both a status and a direct effect control the same key, the most severe value wins. They don't stack (except damage).

Q: Can I apply multiple effects in one call? Yes. Pass multiple entries in the effects array and they are all applied at once.

Q: What happens when duration runs out? The effect is automatically removed and the client is updated. If there is another effect of the same type still active (from stacking), it takes over seamlessly.

Q: Can I remove a direct effect early? There is currently no dedicated export for early removal. The duration-based expiry handles cleanup automatically.

Q: Can I use effect keys that aren't listed here? Only the keys listed above are supported. Custom keys require registering a new queue key in the effect manager.