docs(VTouchDamage): add documentation for zCTouchDamage

docs/engine/objects/zCTouchDamage.md

@@ -0,0 +1,113 @@
+# zCTouchDamage
+
+!!! abstract inline end "Quick Infos"
+    **Type:** Virtual Object<br/>
+    **Format Name:** ZenGin Archive<br/>
+    **File Extension:** `.ZEN`<br/>
+    **Class Name:** `zCTouchDamage`<br/>
+    **Version Identifiers:**<br />
+    — Gothic I: `36865`<br/>
+    — Gothic II: `36865`<br/>
+    **ZenKit Class:** `VTouchDamage`
+
+A VObject which damages other VObjects colliding with it.
+
+<ul class="sp-list">
+    <li class="sp-type"><a href="../zCVob/">zCVob</a></li>
+    <li class="sp-type">
+        <span>zCTouchDamage</span>
+        <ul class="sp-list">
+            <li class="sp-folder">
+                <span>TouchDamage</span>
+                <ul class="sp-list">
+                    <li class="sp-float"><a href="#damage">damage</a> = 0</li>
+                    <li class="sp-folder">
+                        <span>DamageType</span>
+                        <ul class="sp-list">
+                            <li class="sp-bool"><a href="#Barrier">Barrier</a> = TRUE</li>
+                            <li class="sp-bool"><a href="#Blunt">Blunt</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Edge">Edge</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Fire">Fire</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Fly">Fly</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Magic">Magic</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Point">Point</a> = FALSE</li>
+                            <li class="sp-bool"><a href="#Fall">Fall</a> = FALSE</li>
+                        </ul>
+                    </li>
+                    <li class="sp-float"><a href="#damageRepeatDelaySec">damageRepeatDelaySec</a> = 0</li>
+                    <li class="sp-float"><a href="#damageVolDownScale">damageVolDownScale</a> = 0</li>
+                    <li class="sp-enum"><a href="#damageCollType">damageCollType</a> = BOX</li>
+                </ul>
+            </li>
+        </ul>
+    </li>
+</ul>
+
+## Properties
+
+<a name="damage" class="t-float"></a> `damage`
+
+:   The amount of damage being dealt.
+
+<a name="Barrier" class="t-bool"></a> `Barrier`
+
+:   `TRUE` — Deal barrier damage. `FALSE` — Do not deal barrier damage.
+
+<a name="Blunt" class="t-bool"></a> `Blunt`
+
+:   `TRUE` — Deal blunt damage (blunt weapons). `FALSE` — Do not deal blunt damage.
+
+<a name="Edge" class="t-bool"></a> `Edge`
+
+:   `TRUE` — Deal edge damage (sharp weapons). `FALSE` — Do not deal edge damage.
+
+<a name="Fire" class="t-bool"></a> `Fire`
+
+:   `TRUE` — Deal fire damage. `FALSE` — Do not deal fire damage.
+
+<a name="Fly" class="t-bool"></a> `Fly`
+
+:   `TRUE` — Deal knockout damage. `FALSE` — Do not deal knockout damage.
+
+<a name="Magic" class="t-bool"></a> `Magic`
+
+:   `TRUE` — Deal magic damage. `FALSE` — Do not deal magic damage.
+
+<a name="Point" class="t-bool"></a> `Point`
+
+:   `TRUE` — Deal point damage (bows and crossbows). `FALSE` — Do not deal point damage.
+
+<a name="Fall" class="t-bool"></a> `Fall`
+
+:   `TRUE` — Deal fall damage. `FALSE` — Do not deal fall damage.
+
+
+<a name="damageRepeatDelaySec" class="t-float"></a> `damageRepeatDelaySec`
+
+:   The delay between damage ticks when applying continuous damage. If set to `0`, only deals the damage once per
+    collision. If set to a value greater than `0`, deals damage every `damageRepeatDelaySec` seconds.
+
+
+<a name="damageVolDownScale" class="t-float"></a> `damageVolDownScale`
+
+:   A scale value used in conjunction with [`damageCollType`](#damageCollType). Its function depends on the type of
+    collision detection used.
+
+
+<a name="damageCollType" class="t-enum"></a> `damageCollType`
+
+:   The type of collision detection to use for damage calculations.
+
+    * `NONE` — Disable collision detection and thus damage application.
+    * `BOX` — Scale the [`bbox3dws`](zCVob.md#bbox3dws) of the `zCTouchDamage` object by
+      [`damageVolDownScale`](#damageVolDownScale) and use this new bounding box to calculate
+      collisions with other VObjects
+    * `POINT` — Scale the [`bbox3dws`](zCVob.md#bbox3dws) of the colliding object by
+      [`damageVolDownScale`](#damageVolDownScale) and only deal damage if it contains the center
+      point of the `zCTouchDamage` object. If the [`visual`](zCVob.md#visual) of the `zCTouchDamage`
+      object is a particle effect, test against every particle instead.
+
+## Sources
+
+The help file for the Spacer, found [here](https://wiki.worldofgothic.de/doku.php?id=spacer:hilfedatei) and the
+Russian-language knowledge accumulator [gothic-library.ru](http://www.gothic-library.ru/publ/octouchdamage/1-1-0-522#damage).

include/zenkit/vobs/Misc.hh

@@ -45,9 +45,24 @@ namespace zenkit {
 		previous ZKREM("renamed to MoverMessageType::PREVIOUS") = PREVIOUS,
 	};
 
+	/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageCollType
 	enum class TouchCollisionType : std::uint32_t {
+		/// \brief Disable collision detection and thus damage application.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageCollType
 		NONE = 0,
+
+		/// \brief Scale the bounding box of the VTouchDamage object by VTouchDamage#volume_scale and
+		///        use this new bounding box to calculate collisions with other VObjects.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageCollType
 		BOX = 1,
+
+		/// \brief Scale the bounding box of the colliding object by VTouchDamage#volume_scale and only deal
+		///        damage if it contains the center point of the `zCTouchDamage` object.
+		///
+		/// If the VirtualObject#visual of the `zCTouchDamage` object is a particle effect, test against
+		/// every particle instead.
+		///
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageCollType
 		POINT = 2,
 
 		// Deprecated entries.
@@ -325,36 +340,76 @@ namespace zenkit {
 		[[nodiscard]] ZKAPI uint16_t get_version_identifier(GameVersion game) const override;
 	};
 
-	/// \brief A VOb which represents a damage source.
+	/// \brief A VObject which damages other VObjects colliding with it.
+	/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/
 	struct VTouchDamage : VirtualObject {
 		ZK_OBJECT(ObjectType::oCTouchDamage);
 
 	public:
+		/// \brief The amount of damage being dealt.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damage
 		float damage;
 
+		/// \brief `TRUE` — Deal barrier damage. `FALSE` — Do not deal barrier damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Barrier
 		bool barrier;
+
+		/// \brief `TRUE` — Deal blunt damage (blunt weapons). `FALSE` — Do not deal blunt damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Blunt
 		bool blunt;
+
+		/// \brief `TRUE` — Deal edge damage (sharp weapons). `FALSE` — Do not deal edge damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Edge
 		bool edge;
+
+		/// \brief TRUE` — Deal fire damage. `FALSE` — Do not deal fire damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Fire
 		bool fire;
+
+		/// \brief `TRUE` — Deal knockout damage. `FALSE` — Do not deal knockout damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Fly
 		bool fly;
+
+		/// \brief `TRUE` — Deal magic damage. `FALSE` — Do not deal magic damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Magic
 		bool magic;
+
+		/// \brief `TRUE` — Deal point damage (bows and crossbows). `FALSE` — Do not deal point damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Point
 		bool point;
+
+		/// \brief Deal fall damage. `FALSE` — Do not deal fall damage.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#Fall
 		bool fall;
 
+		/// \brief The delay between damage ticks when applying continuous damage.
+		///
+		/// If set to `0`, only deals the damage once per collision. If set to a value greater than `0`, deals
+		/// damage every `damageRepeatDelaySec` seconds.
+		///
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageRepeatDelaySec
 		float repeat_delay_sec;
+
+		/// \brief A scale value used in conjunction with #collision.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageVolDownScale
 		float volume_scale;
+
+		/// \brief The type of collision detection to use for damage calculations.
+		/// \see https://zk.gothickit.dev/engine/objects/zCTouchDamage/#damageCollType
 		TouchCollisionType collision;
 
-		/// \brief Parses a touch damage VOb the given *ZenGin* archive.
-		/// \param[out] obj The object to read.
-		/// \param[in,out] ctx The archive reader to read from.
-		/// \note After this function returns the position of \p ctx will be at the end of the parsed object.
-		/// \throws ParserError if parsing fails.
-		/// \see vob::parse
 		ZKREM("use ::load()") ZKAPI static void parse(VTouchDamage& obj, ReadArchive& ctx, GameVersion version);
 
+		/// \brief Load this object from the given archive.
+		/// \param r The archive to read from;
+		/// \param version The version of the game the object was made for.
 		ZKAPI void load(ReadArchive& r, GameVersion version) override;
+
+		/// \brief Save this object to the given archive.
+		/// \param w The archive to save to.
+		/// \param version The version of the game to save for.
 		ZKAPI void save(WriteArchive& w, GameVersion version) const override;
+
 		[[nodiscard]] ZKAPI uint16_t get_version_identifier(GameVersion game) const override;
 	};
 

mkdocs.yml

@@ -49,6 +49,7 @@ nav:
           - 'zCMessageFilter': 'engine/objects/zCMessageFilter.md'
           - 'zCMoverControler': 'engine/objects/zCMoverController.md'
           - 'zCPFXControler': 'engine/objects/zCPFXControler.md'
+          - 'zCTouchDamage': 'engine/objects/zCTouchDamage.md'
           - 'oCItem': 'engine/objects/oCItem.md'
           - 'zCVisual': 'engine/objects/zCVisual.md'
           - 'zCDecal': 'engine/objects/zCDecal.md'