Configuration

All primary settings are located in ChaosMod/config.lua. Edit the file and restart the resource for configuration changes to be reloaded. Values ending in Ms are in milliseconds (1,000 ms = 1 second).

Recommended presets

Restricted event profile (recommended for live RP)

Config.Enabled = true
Config.IntervalMs = 120000
Config.EffectDurationMs = 30000
Config.LiveSafeMode = true
Config.AllowDestructiveEffects = false
Config.WeatherEffects = false

This preset limits the event pool to the six IDs listed in Config.LiveSafeEffects and keeps weather effects disabled. These are intended as visual/audio events; they may still obstruct players' views or alter lighting. Test before deploying.

Full chaos night

Config.Enabled = true
Config.IntervalMs = 120000
Config.EffectDurationMs = 30000
Config.LiveSafeMode = false
Config.AllowDestructiveEffects = true
Config.WeatherEffects = false

This matches the shipped safety filters. It allows the full set of non-weather events, including events marked destructive. Only use it in situations where players understand that chaos can interfere with normal gameplay.

Admin-controlled / manual-only

Config.Enabled = false
Config.LiveSafeMode = true
Config.AllowDestructiveEffects = false

The automatic timer starts off. Administrators may still explicitly trigger an eligible effect using /chaos force <id>. Use /chaos on to enable automatic rotation if needed.

Core settings

Setting	Shipped default	Meaning
Config.Enabled	true	Whether automatic chaos is enabled on startup.
Config.IntervalMs	120000	Time between automatic effect starts.
Config.EffectDurationMs	30000	Default runtime for timed effects.
Config.SkipWhenEmpty	true	Skip effect rolls with zero players and reset the idle countdown.
Config.RecentHistory	5	Avoid recently used random effect IDs where alternatives are available.
Config.AdminAce	'chaosmod.admin'	ACE permission required for in-game commands.
Config.Debug	false	Verbose debug logging.

The server clamps the effective automatic interval to 5 seconds–60 minutes and individual effect durations to 0–120 seconds. Some registered effects specify their own duration; instant effects have 0.

Timer convar override

The server reads chaosmod_eventtimer if set. For example, in server.cfg:

set chaosmod_eventtimer 90000

This overrides Config.IntervalMs and gives a 90-second start-to-start timer. If the convar is not set, the config value is used. To enable extra debug logging via convar:

set chaosmod_debug true

Effect selection and safety

Setting	Shipped default	Meaning
Config.LiveSafeMode	false	If enabled, only effect IDs with true in Config.LiveSafeEffects are eligible.
Config.AllowDestructiveEffects	true	If false, block effects marked destructive in the shared catalog.
Config.WeatherEffects	false	If false, exclude all Weather-category effects.
Config.DisabledEffects	{}	Explicitly exclude IDs from random rotation and admin force/queue.

The current live-safe allowlist contains exactly:

Config.LiveSafeEffects = {
    miscFireworks = true,
    miscNightVision = true,
    miscHeatVision = true,
    miscBlackout = true,
    miscPortraitMode = true,
    miscIntenseMusic = true,
}

To remove effects from the pool entirely:

Config.DisabledEffects = {
    ['miscDVD'] = true,
    ['teleportSky'] = true,
    ['playerGiveWeapons'] = true,
}

If Config.LiveSafeMode = true, adding an ID to Config.LiveSafeEffects only permits that ID to pass the allowlist check; the destructive, weather, and disabled-ID checks still apply. Simply setting AllowDestructiveEffects = false is not the same as enabling live-safe mode: non-destructive effects that alter camera, UI, or gameplay may remain eligible.

:::warning Irreversible changes Several instant events can cause real gameplay consequences that are not restored when chaos ends, such as weapon grants, teleportation, wanted level changes, broken doors, or punctured tyres. Use explicit exclusions when necessary. The destructive marker is an author-supplied classification, not a guarantee that every unmarked effect is harmless. :::

Performance and entity limits

Setting	Default	Purpose
Config.MaxNearbyVehicles	12	Maximum nearby vehicles considered by supported effects.
Config.MaxNearbyPeds	12	Maximum nearby peds considered by supported effects.
Config.NearbyRadius	70.0	Nearby search radius in game units.
Config.MaxSpawnedEntities	5	Per-effect-context limit for tracked spawned entities.
Config.ModelLoadTimeoutMs	4000	Time to wait for requested models or particle assets.
Config.CleanupSpawnedVehicles	true	Try to remove tracked spawned vehicles during cleanup when empty.

Some effects create local entities rather than persistent networked entities. Spawned vehicles may remain if occupied or if cleanup cannot obtain entity control. Choose cautious caps for busy servers.

Announcements

Setting	Default	Description
Config.AnnounceEffects	false	Post a native GTA feed notification when an effect starts.
Config.UseChatMessages	false	Send command replies/notifications to the FiveM chat resource when invoked by the script; requires the chat resource.

The UI's own effect announcement is controlled separately with Config.UI.ShowAnnouncements.

HUD settings

Setting	Default	Description
Config.UI.Enabled	true	Enable the local NUI overlay.
Config.UI.Title	'CHAOS MODE'	Short title displayed on the HUD.
Config.UI.Accent	'#ef4444'	Six-digit hex accent color.
Config.UI.WidthPx	420	HUD width (clamped by the JS renderer).
Config.UI.TopPx	24	Distance from the top of the screen.
Config.UI.ShowAnnouncements	true	Show a temporary effect card when an effect begins.
Config.UI.AnnouncementMs	4200	How long the effect card remains visible.
Config.UI.ShowWhenPaused	true	Keep HUD visible when chaos is paused or disabled.
Config.UI.RefreshMs	5000	Server state synchronization interval (minimum 1000 ms).

The UI is non-interactive and does not take cursor focus. Its source files are web/index.html, web/style.css, and web/app.js.

Example appearance changes:

Config.UI.Title = 'HSC CHAOS'
Config.UI.Accent = '#ff3b30'
Config.UI.WidthPx = 380
Config.UI.TopPx = 40

Weather synchronization

Config.WeatherEffects = false is the shipped default. Leave it off if your server uses another weather manager, such as vSync or qb-weathersync. If enabled, weather-category effects use local client weather overrides, which may compete with existing weather scripts.