add setElementHealth and getElementHealth wiki pages

Author: ffsPLASMA

functions/Element/examples/getElementHealth-1.lua

@@ -0,0 +1,13 @@
+function getMyHealth()
+	-- output player ped health to chat
+	outputChatBox("My health is: "..getElementHealth(localPlayer));
+
+	-- check if we are in a vehicle
+	local uVehicle = getPedOccupiedVehicle(localPlayer);
+
+	-- if valid vehicle, output its health to chat
+	if(uVehicle) then
+		outputChatBox("My vehicle health is: "..getElementHealth(uVehicle));
+	end
+end
+addCommandHandler("health", getMyHealth);

functions/Element/examples/getElementHealth-2.lua

@@ -0,0 +1,8 @@
+function healMePlease()
+    -- heal the player if health is 50 or lower
+    if(getElementHealth(localPlayer) <= 50) then
+        setElementHealth(localPlayer, 100);
+        outputChatBox("You got healed!");
+    end
+end
+addCommandHandler("healme", healMePlease);

functions/Element/examples/setElementHealth-1.lua

@@ -0,0 +1,13 @@
+function setMyHealth(uPlayer, strCommand, fAmount)
+    -- safety check if we got a valid new health value
+    local fAmount = tonumber(fAmount);
+
+    if(not fAmount) then
+        return outputChatBox("Invalid health value entered!", uPlayer, 255, 0, 0);
+    end
+
+    -- change the player's health
+    setElementHealth(uPlayer, fAmount);
+    outputChatBox("Your health was set to "..fAmount.." HP!", uPlayer, 0, 255, 0);
+end
+addCommandHandler("sethealth", setMyHealth)

functions/Element/examples/setElementHealth-2.lua

@@ -0,0 +1,17 @@
+function repairMyVehicle()
+    -- check if we are in a vehicle
+    local uVehicle = getPedOccupiedVehicle(localPlayer);
+
+    if(uVehicle) then
+        -- does our vehicle need repair? remember, vehicle health ranges from 0 to 1000
+        if(getElementHealth(uVehicle) < 1000) then
+            -- note: setElementHealth does not repair the visual aspect of vehicles, use fixVehicle instead!
+            setElementHealth(uVehicle, 1000);
+        else
+            outputChatBox("Your vehicle is already at full health!", 255, 0, 0);
+        end
+    else
+        outputChatBox("You are not in a vehicle!", 255, 0, 0);
+    end
+end
+addCommandHandler("repairvehicle", repairMyVehicle);

functions/Element/getElementHealth.yaml

@@ -0,0 +1,35 @@
+shared: &shared
+  name: 'getElementHealth'
+  oop:
+    entity: player
+    method: getHealth
+    variable: health
+  pair: 'setElementHealth'
+  description: |
+    This function returns the current health for the specified element. This can be a [[player]], [[ped]], [[vehicle]], or [[object]]. 
+  returns:
+    description: |
+      Returns a *float* indicating the element's health, *false* otherwise.
+    values:
+      - type: 'float'
+        name: 'health'
+  examples:
+    - path: 'examples/getElementHealth-1.lua'
+      description: |
+        This example outputs the player and vehicle health (if player is in a vehicle) to chatbox using /health command:
+    - path: 'examples/getElementHealth-2.lua'
+      description: |
+        This example heals the player to 100 HP using /healme command if he's at 50 HP or lower:
+  issues:
+    - id: 3791
+      description: 'setPedArmor and setElementHealth synchronization problems from Client to Server'
+    - id: 2223
+      description: 'setElementHealth in onClientPlayerDamage bug'
+    - id: 1423
+      description: 'When you setElementHealth under onClientPlayerDamage, the local (hit) player rotates automatically'
+
+server:
+  <<: *shared
+
+client:
+  <<: *shared

functions/Element/setElementHealth.yaml

@@ -0,0 +1,47 @@
+shared: &shared
+  name: 'setElementHealth'
+  oop:
+    entity: player
+    method: setHealth
+    variable: health
+  pair: 'getElementHealth'
+  description: |
+    This function sets the health of a [[player]], [[ped]], [[vehicle]] or [[object]] element.
+  notes:
+    - |
+      info: In the case of the [[vehicle]] element, the following effects appear, depending on the health value: 
+    - |
+      - *650:* white steam 0%, black smoke 0%
+      - *450:* white steam 100%, black smoke 50%
+      - *250:* white steam 0%, black smoke 100%
+      - *249:* fire with big black smoke
+  returns:
+    description: |
+      Returns *true* if the new health was set successfully, *false* otherwise.
+    values:
+      - type: 'bool'
+        name: 'result'
+  examples:
+    - path: 'examples/setElementHealth-1.lua'
+      description: |
+        This example changes the player health to new specified value using /sethealth <value> command:
+    - path: 'examples/setElementHealth-2.lua'
+      description: |
+        This example heals the player vehicle using the command /repairvehicle if it's below 1000 HP:
+  issues:
+    - id: 3807
+      description: 'hpbar on hud is not compatible visually with MAX_HEALTH stat'
+    - id: 3791
+      description: 'setPedArmor and setElementHealth synchronization problems from Client to Server'
+    - id: 2223
+      description: 'setElementHealth in onClientPlayerDamage bug'
+    - id: 1423
+      description: 'When you setElementHealth under onClientPlayerDamage, the local (hit) player rotates automatically'
+    - id: 448
+      description: 'Crash when plane explode'
+
+server:
+  <<: *shared
+
+client:
+  <<: *shared