From 9adccd279bf10a1b2c96da070878ad0ec79bf1ab Mon Sep 17 00:00:00 2001
From: Nathan Falvey <nathanfalvey@gmail.com>
Date: Sat, 17 Jan 2026 21:27:51 +0000
Subject: [PATCH] Add effect template for GTA V Chaos Mod effects

---
 README.md           | 22 ++++++++++++++++++++++
 effect_template.lua | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 README.md
 create mode 100644 effect_template.lua

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9346183
--- /dev/null
+++ b/README.md
@@ -0,0 +1,22 @@
+# effect_template.lua
+
+A minimal template for creating new GTA V Chaos Mod effects. Use this file as the starting point for all future effect scripts.
+
+## Purpose
+Provide a consistent structure and common conventions (metadata, configuration, initialization, per-tick logic, and cleanup) so effects are easy to read, maintain, and extend.
+
+## Usage
+Copy the `effect_template.lua` file into your effects directory, change as needed and rename it for the new effect.
+
+## Editing checklist
+- Update metadata (name, description, author, toggle key, priority).
+- Set configurable parameters (duration, intensity, cooldown).
+- Add comments for any non-obvious behavior.
+
+## Conventions
+- Use clear, consistent naming for variables and functions.
+- Keep per-tick work minimal to avoid performance issues.
+- Restore all modified game state(s) in `OnStop()`.
+
+## Updates
+- This script template will get minimal updates for additional function or changes.
\ No newline at end of file
diff --git a/effect_template.lua b/effect_template.lua
new file mode 100644
index 0000000..db4a131
--- /dev/null
+++ b/effect_template.lua
@@ -0,0 +1,37 @@
+-- Short coherent template for a Chaos Mod effect.
+-- Edit the fields below to describe the effect and adjust timing/weighting.
+-- Full reference: https://github.com/gta-chaos-mod/ChaosModV/wiki/Lua-Scripting
+
+EffectInfo = { -- ScriptInfo for mod version < 2.0
+    Name = "Template Effect",
+    EffectId = "effect_template", -- ScriptId for mod version < 2.0, must be unique
+    Description = "A short one-line description of what this effect does.",
+    TimedType = "Normal", -- None, Normal, Short, Permanent, or "Custom"
+    -- CustomTime = 10, -- (seconds) only if TimedType = "Custom"
+    WeightMultiplier = 1, -- Relative probability of being chosen
+    HideRealNameOnStart = false, -- true to hide the effect's real name when it starts
+    EffectCategory = "None", -- Optional category
+    EffectGroup = "", -- Optional grouping (leave empty if unused)
+    IncompatibleIds = {
+        -- Example: "other_effect_id", -- add EffectIds that cannot run simultaneously
+    }
+}
+
+-- Called once when the effect starts
+function OnStart()
+    print("[effect_template] OnStart: " .. ((EffectInfo and EffectInfo.Name) or "unknown"))
+    -- Initialize effect state here (e.g. set timers, spawn helpers)
+end
+
+-- Called once when the effect stops/ends
+function OnStop()
+    print("[effect_template] OnStop: " .. ((EffectInfo and EffectInfo.Name) or "unknown"))
+    -- Cleanup state here (e.g. remove entities, clear timers)
+end
+
+-- Called every game tick while the effect is active
+function OnTick()
+    -- Keep this lightweight. Use this for per-frame checks or gradual changes.
+end
+
+-- Add custom helper functions below.