Direct Effects

#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)

Each entry in the effects array has three fields:

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:

#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

Sound Fields

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

Loop Settings

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.