From 28e45c29791f38aa64f064f6a4b4aa01e8478904 Mon Sep 17 00:00:00 2001
From: johnb432 <58661205+johnb432@users.noreply.github.com>
Date: Wed, 7 Feb 2024 17:49:36 +0100
Subject: [PATCH] Laser - Public getter and setter for laser codes (#9772)

* Getter and setter for laser codes

* Documentation

* Sanitising input
---
 addons/laser/XEH_PREP.hpp                   |  2 ++
 addons/laser/functions/fnc_getLaserCode.sqf | 24 +++++++++++++++
 addons/laser/functions/fnc_setLaserCode.sqf | 21 +++++++++++++
 docs/wiki/framework/laser-framework.md      | 34 +++++++++++++++++++++
 4 files changed, 81 insertions(+)
 create mode 100644 addons/laser/functions/fnc_getLaserCode.sqf
 create mode 100644 addons/laser/functions/fnc_setLaserCode.sqf
 create mode 100644 docs/wiki/framework/laser-framework.md

diff --git a/addons/laser/XEH_PREP.hpp b/addons/laser/XEH_PREP.hpp
index 9b9be64752..2d26ff81f2 100644
--- a/addons/laser/XEH_PREP.hpp
+++ b/addons/laser/XEH_PREP.hpp
@@ -3,6 +3,7 @@ PREP(addLaserTarget);
 PREP(addMapHandler);
 PREP(dev_drawVisibleLaserTargets);
 PREP(findLaserSource);
+PREP(getLaserCode);
 PREP(handleLaserTargetCreation);
 PREP(keyLaserCodeChange);
 PREP(laserOff);
@@ -13,6 +14,7 @@ PREP(onLaserDesignatorDraw);
 PREP(rotateVectLine);
 PREP(rotateVectLineGetMap);
 PREP(seekerFindLaserSpot);
+PREP(setLaserCode);
 PREP(shootCone);
 PREP(shootRay);
 PREP(showVehicleHud);
diff --git a/addons/laser/functions/fnc_getLaserCode.sqf b/addons/laser/functions/fnc_getLaserCode.sqf
new file mode 100644
index 0000000000..0a0fce363f
--- /dev/null
+++ b/addons/laser/functions/fnc_getLaserCode.sqf
@@ -0,0 +1,24 @@
+#include "..\script_component.hpp"
+/*
+ * Author: johnb43
+ * Gets the laser code of a laser source.
+ *
+ * Argument:
+ * 0: Laser source <OBJECT>
+ *
+ * Return Value:
+ * Laser code <NUMBER>
+ *
+ * Example:
+ * player call ace_laser_fnc_getLaserCode;
+ *
+ * Public: Yes
+ */
+
+params [["_laserSource", objNull, [objNull]]];
+
+if (isNull _laserSource) exitWith {
+    -1
+};
+
+_laserSource getVariable [QGVAR(code), ACE_DEFAULT_LASER_CODE]
diff --git a/addons/laser/functions/fnc_setLaserCode.sqf b/addons/laser/functions/fnc_setLaserCode.sqf
new file mode 100644
index 0000000000..23f7e5c82f
--- /dev/null
+++ b/addons/laser/functions/fnc_setLaserCode.sqf
@@ -0,0 +1,21 @@
+#include "..\script_component.hpp"
+/*
+ * Author: johnb43
+ * Sets the laser code on a laser source.
+ *
+ * Argument:
+ * 0: Laser source <OBJECT>
+ * 1: Laser code <NUMBER>
+ *
+ * Return Value:
+ * None
+ *
+ * Example:
+ * [player, 1111] call ace_laser_fnc_setLaserCode;
+ *
+ * Public: Yes
+ */
+
+params [["_laserSource", objNull, [objNull]], ["_laserCode", ACE_DEFAULT_LASER_CODE, [0]]];
+
+_laserSource setVariable [QGVAR(code), _laserCode, true];
diff --git a/docs/wiki/framework/laser-framework.md b/docs/wiki/framework/laser-framework.md
new file mode 100644
index 0000000000..1a7bbf7d6b
--- /dev/null
+++ b/docs/wiki/framework/laser-framework.md
@@ -0,0 +1,34 @@
+---
+layout: wiki
+title: Laser
+description: Explains the functions available for laser designators.
+group: framework
+order: 5
+parent: wiki
+mod: ace
+version:
+  major: 3
+  minor: 16
+  patch: 4
+---
+
+## 1. Scripting
+
+### 1.1. Get object's laser code
+
+`ace_laser_fnc_getLaserCode`
+
+|   | Arguments | Type | Optional (default value)
+---| --------- | ---- | ------------------------
+0  | Unit/Vehicle | Object | Required
+**R** | Laser code | Number | Return value
+
+### 1.2. Set object's laser code
+
+`ace_laser_fnc_setLaserCode`
+
+|   | Arguments | Type | Optional (default value)
+---| --------- | ---- | ------------------------
+0  | Unit/Vehicle | Object | Required
+1  | Laser code | Number | Required
+**R** | None | None | Return value