Refactor headshot

[gameplay]/headshot/docs/README.md

@@ -0,0 +1,76 @@
+# Headshot
+Headshot feature for enhanced combat realism and damage effect — Made with 💖 by Multi Theft Developers.
+
+> [!NOTE]
+> This resource is a part of the [mtasa-blue](https://github.com/multitheftauto/mtasa-resources) repository, any updates, fixes or patches are only available there.
+
+> [!IMPORTANT]
+> The minimum version requirement for the server is 1.6.0. You can always download the latest binaries [here](https://nightly.multitheftauto.com/).
+
+## Settings
+| name  | description                                                     | default | accept      |
+|-------|-----------------------------------------------------------------|---------|-------------|
+| decap | determines whether the player becomes headless after a headshot | true    | false, true |
+
+## Events
+
+### onPlayerHeadshot
+This event is called when a player is shot in the head and dies.
+
+#### Parameters
+```lua
+player attacker, int cause
+```
+- attacker: a player element who was the attacker
+- cause: a number representing the attacker weapon or other damage type
+
+#### Cancel
+This event cannot be cancelled.
+
+#### Example
+```lua
+addEventHandler("onPlayerHeadshot", root,
+    function(attacker, cause)
+        local name = getPlayerName(source)
+
+        if attacker and isElement(attacker) and getElementType(attacker) == "player" then
+            attacker = getPlayerName(attacker)
+        else
+            attacker = "Unknown"
+        end
+
+        if cause and type(cause) == "number" then
+            cause = getWeaponNameFromID(cause)
+        else
+            cause = "Unknown"
+        end
+
+        outputServerLog(name .. " was shot in the head by " .. attacker .. " using " .. cause)
+    end
+)
+```
+
+### onPlayerPreHeadshot
+This event is called when a player is shot in the head but has not yet been killed by the resource.
+
+#### Parameters
+```lua
+player attacker, int cause, int damage 
+```
+- attacker: a player element who was the attacker
+- cause: a number representing the attacker weapon or other damage type
+- damage: a number representing the health originally lost by the shot
+
+#### Cancel
+This event can be cancelled, preventing the player from being killed.
+
+#### Example
+```lua
+addEventHandler("onPlayerPreHeadshot", root,
+    function(_, _, damage)
+        if damage < 5 then
+            cancelEvent()
+        end
+    end
+)
+```

[gameplay]/headshot/meta.xml

@@ -1,11 +1,12 @@
 <meta>
-	<info author="jbeta" type="script" version="1.1.0" />
-	<script src="headshot.lua" type="server" />
-	<settings>
-		<setting name="*removeHeadOnHeadshot" value="true"
-			friendlyname="Blows off player's head on headshot"
-			group="General"
-			accept="false,true"
-			desc="Should player lose his head when he gets headshot?" />
-	</settings>
-</meta>
+    <info name="Headshot" description="Headshot feature for enhanced combat realism and damage effect" author="Multi Theft Developers" version="1.0.0" type="script" />
+    <min_mta_version server="1.6.0" />
+
+    <settings>
+        <setting name="*decap" desc="determines whether the player becomes headless after a headshot" value="true" accept="false, true" />
+    </settings>
+
+    <script type="server" src="src/headshotSettings.lua" />
+    <script type="server" src="src/headshotDamage.lua" />
+    <script type="server" src="src/headshotSpawn.lua" />
+</meta>

[gameplay]/headshot/src/headshotDamage.lua

@@ -0,0 +1,30 @@
+addEvent("onPlayerHeadshot", false)
+addEvent("onPlayerPreHeadshot", false)
+
+addEventHandler("onPlayerDamage", root,
+    function(headshotAttacker, headshotCause, headshotBodypart, headshotDamage)
+        if not headshotAttacker or not isElement(headshotAttacker) or getElementType(headshotAttacker) ~= "player" then
+            return
+        end
+
+        if headshotBodypart ~= 9 then
+            return
+        end
+
+        triggerEvent("onPlayerPreHeadshot", source, headshotAttacker, headshotCause, headshotDamage)
+
+        if wasEventCancelled() then
+            return
+        end
+
+        killPed(source, headshotAttacker, headshotCause, headshotBodypart)
+
+        triggerEvent("onPlayerHeadshot", source, headshotAttacker, headshotCause)
+
+        if not headshotSettingsGet("decap") then
+            return
+        end
+
+        setPedHeadless(source, true)
+    end
+)

[gameplay]/headshot/src/headshotSettings.lua

@@ -0,0 +1,77 @@
+local headshotSettings = {}
+local headshotSettingsAvailable = {
+    {"decap", "boolean"}
+}
+
+function headshotSettingsGet(headshotSetting)
+    if not headshotSetting or type(headshotSetting) ~= "string" then
+        return
+    end
+
+    return headshotSettings[headshotSetting]
+end
+
+function headshotSettingsBooleanize(headshotValue)
+    if not headshotValue or type(headshotValue) ~= "string" then
+        return
+    end
+
+    if string.find(headshotValue, "true") then
+        return true
+    end
+
+    return false
+end
+
+addEventHandler("onResourceStart", resourceRoot,
+    function()
+        for _, headshotEntry in pairs(headshotSettingsAvailable) do
+            local headshotSetting = headshotEntry[1]
+            local headshotType = headshotEntry[2]
+            local headshotValue = get(headshotSetting)
+
+            if headshotValue and type(headshotValue) == "string" then
+                if headshotType == "boolean" then
+                    headshotSettings[headshotSetting] = headshotSettingsBooleanize(headshotValue)
+                else
+                    headshotSettings[headshotSetting] = headshotValue
+                end
+            end
+        end
+    end
+)
+
+addEventHandler("onSettingChange", root,
+    function(headshotSetting, _, headshotValue)
+        local headshotDot = string.find(headshotSetting, "%.")
+
+        if headshotDot and type(headshotDot) == "number" then
+            headshotSetting = string.sub(headshotSetting, headshotDot + 1)
+        end
+
+        local headshotFound
+
+        for _, headshotEntry in pairs(headshotSettingsAvailable) do
+            if headshotEntry[1] == headshotSetting then
+                headshotFound = headshotEntry
+                break
+            end
+        end
+
+        if not headshotFound then
+            return
+        end
+
+        local headshotType = headshotFound[2]
+
+        if not headshotValue or type(headshotValue) ~= "string" then
+            return
+        end
+
+        if headshotType == "boolean" then
+            headshotSettings[headshotSetting] = headshotSettingsBooleanize(headshotValue)
+        else
+            headshotSettings[headshotSetting] = headshotValue
+        end
+    end
+)

[gameplay]/headshot/src/headshotSpawn.lua

@@ -0,0 +1,13 @@
+addEventHandler("onPlayerSpawn", root,
+    function()
+        if not isPedHeadless(source) then
+            return
+        end
+
+        if not headshotSettingsGet("decap") then
+            return
+        end
+
+        setPedHeadless(source, false)
+    end
+)