feat: add esx_halloween

[simpleC0de]

Description

This PR introduces esx_halloween, a complete Halloween event system that adds immersive ghost gameplay to ESX Legacy servers. When players die, they have a chance to return as ghosts with special abilities including increased movement speed, partial invisibility, and the ability to scare nearby players with jumpscare effects.

The resource includes a modern Svelte 5-based UI with smooth animations, comprehensive admin controls, and a flexible notification system themed for Halloween events. All components are production-ready with full server-side validation, performance optimizations, and ESX theme integration.

---

Motivation

ESX Legacy currently lacks seasonal event systems that can engage players during special occasions. This Halloween addon provides servers with a ready-to-use event system that:

• Enhances player engagement through unique post-death gameplay mechanics
• Adds seasonal variety without requiring permanent changes to core gameplay
• Maintains ESX standards with proper framework integration and security practices
• Provides admin flexibility through comprehensive configuration options

The ghost system creates memorable player interactions while respecting server performance and preventing exploits through strict server-side validation.

---

Implementation Details

Core Architecture:

• Event-driven client-server communication with request-response pattern for ghost mode activation
• Centralized event constants in shared/events.lua to prevent naming conflicts
• Server-side validation for all ghost actions (cooldowns, range checks, concurrent limits)
• Config validator on resource start with automatic fallback to safe defaults

Security Features:

• All ghost mode requests require server approval with 5-second timeout
• Cooldown system prevents spam (60s ghost request, 30s scare ability, 2s death cooldown)
• Scare range validation on server-side (10m default)
• Input sanitization prevents XSS attacks in notifications
• Parameter validation on all exports

Performance Optimizations:

• Adaptive visibility checks: 500ms when ghosts active, 2000ms when idle
• Control disabling runs at Wait(0) as required by GTA natives
• Model loading with 10-second timeout
• No constant loops - purely event-driven architecture

UI/UX:

• Modern Svelte 5 with runes ($state, $effect) for reactive state management
• Jumpscare effect with 2-second delayed notification showing ghost player name
• ESX theme integration via convars (colors, logo)
• Queue-based notification system prevents UI overlap

Database:

• No database requirements - fully stateless server-side tracking
• Compatible with existing ESX player tables

---

Usage Example

-- Admin command to trigger ghost choice dialog
/ghost          -- Show choice for yourself
/ghost 5        -- Show choice for player ID 5

-- Exports for other resources
local isGhost = exports['esx_halloween']:IsPlayerGhost(playerId)

exports['esx_halloween']:SetPlayerGhost(playerId, true)  -- Enable ghost mode
exports['esx_halloween']:SetPlayerGhost(playerId, false) -- Disable ghost mode

-- Trigger notification from any resource
exports['esx_halloween']:showNotification({
    size = 'large',
    position = 'bottom-center',
    header = 'Halloween Event',
    description = 'You found a rare Halloween item!',
    duration = 4000
})

Configuration:

Config = {
    Ghost = {
        enabled = true,
        spawnChance = 20,              -- 20% chance on death
        maxDuration = 600000,          -- 10 minutes max
        exitKeybind = 'X',             -- Exit ghost mode key

        visibility = {
            range = 25.0,              -- Visible within 25m
            alpha = 77                 -- 30% opacity
        },

        abilities = {
            scare = {
                enabled = true,
                cooldown = 30000,      -- 30 second cooldown
                range = 10.0,          -- 10 meter range
                keybind = 'E'
            }
        },

        security = {
            ghostRequestCooldown = 60000,
            maxConcurrentGhosts = 10,
            deathCooldown = 2000,
            requestTimeout = 5000
        }
    },

    AdminGroups = { 'admin', 'superadmin' }
}

---

PR Checklist

• My commit messages and PR title follow the Conventional Commits standard.
• My changes have been tested locally and function as expected.
• My PR does not introduce any breaking changes.
• I have provided a clear explanation of what my PR does, including the reasoning behind the changes and any relevant context.

[Zykem]

Both these threads should not be having an infinite loop.
Start the threads whenever player is becoming a ghost and do conditional while loop, such as:

while ghostState.isGhost do

[simpleC0de]

fixed:
1e1214e

[Zykem]

ClearTimeout is not working in fivem's environment.

For every usage of SetTimeout and ClearTimeout, replace it with ESX.SetTimeout and ESX.ClearTimeout please

[simpleC0de]

fixed:
d6ffa52

[CLAassistant]

All committers have signed the CLA.