From 82896f6514777f3f8183c054fc726473d168e348 Mon Sep 17 00:00:00 2001
From: Luis Michaelis <me@lmichaelis.de>
Date: Thu, 28 Dec 2023 15:31:08 +0100
Subject: [PATCH] docs(VAnimate): add documentation for `zCVobAnimate`

---
 docs/engine/objects/zCVobAnimate.md | 36 +++++++++++++++++++++++++++++
 include/zenkit/vobs/Misc.hh         | 22 ++++++++++++------
 mkdocs.yml                          |  1 +
 3 files changed, 52 insertions(+), 7 deletions(-)
 create mode 100644 docs/engine/objects/zCVobAnimate.md

diff --git a/docs/engine/objects/zCVobAnimate.md b/docs/engine/objects/zCVobAnimate.md
new file mode 100644
index 00000000..232a8901
--- /dev/null
+++ b/docs/engine/objects/zCVobAnimate.md
@@ -0,0 +1,36 @@
+# zCVobAnimate
+
+!!! abstract inline end "Quick Infos"
+    **Type:** Virtual Object<br/>
+    **Format Name:** ZenGin Archive<br/>
+    **File Extension:** `.ZEN`<br/>
+    **Class Name:** `zCVobAnimate`<br/>
+    **Version Identifiers:**<br />
+    — Gothic I: `12289`<br/>
+    — Gothic II: `52224`<br/>
+    **ZenKit Class:** `VAnimate`
+
+A VObject used to create animated models. The visual of such objects can either be a
+[morph mesh](../../engine/formats/morph-mesh.md) or a model with a skeletal animation
+(i.e. a [model script](../../engine/formats/model-script.md)). The animation of these objects can be started
+and stopped using `OnTrigger` and `OnUntrigger` events.
+
+<ul class="sp-list">
+    <li class="sp-type"><a href="../zCVob/">zCVob</a></li>
+    <li class="sp-type">
+        <span>zCVobLight</span>
+        <ul class="sp-list">
+            <li class="sp-bool"><a  href="#startOn">startOn</a> = TRUE</li>
+        </ul>
+    </li>
+</ul>
+
+## Properties
+
+<a name="startOn" class="t-bool"></a> `startOn`
+
+:   Whether to start this animation when loading the level.
+    
+    * `TRUE` — Immediately start the animation when the level is loaded.
+    * `FALSE` — Don't automatically start the animation.
+
diff --git a/include/zenkit/vobs/Misc.hh b/include/zenkit/vobs/Misc.hh
index 08cccb59..aff2da9f 100644
--- a/include/zenkit/vobs/Misc.hh
+++ b/include/zenkit/vobs/Misc.hh
@@ -56,25 +56,33 @@ namespace zenkit {
 		point ZKREM("renamed to TouchCollisionType::POINT") = POINT,
 	};
 
-	/// \brief An animated VOb.
+	/// \brief A VObject used to create animated models.
+	///
+	/// The visual of such objects can either be a morph mesh or a model with a skeletal animation. The animation
+	/// of these objects can be started and stopped using `OnTrigger` and `OnUntrigger` events.
+	///
+	/// \see https://zk.gothickit.dev/engine/objects/zCVobAnimate/
 	struct VAnimate : VirtualObject {
 		ZK_OBJECT(ObjectType::zCVobAnimate);
 
 	public:
+		/// \brief Whether to start this animation when loading the level.
+		/// \see https://zk.gothickit.dev/engine/objects/zCVobAnimate/#startOn
 		bool start_on {false};
 
 		// Save-game only variables
 		bool s_is_running {false};
 
-		/// \brief Parses an animated 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(VAnimate& 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;
 	};
 
diff --git a/mkdocs.yml b/mkdocs.yml
index f86f8239..661e1bb4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -38,6 +38,7 @@ nav:
           - 'ZenGin Archive': 'engine/formats/archive.md'
       - 'Objects':
           - 'zCVob': 'engine/objects/zCVob.md'
+          - 'zCVobAnimate': 'engine/objects/zCVobAnimate.md'
           - 'zCVobLevelCompo': 'engine/objects/zCVobLevelCompo.md'
           - 'zCVobLight': 'engine/objects/zCVobLight.md'
           - 'zCVobSpot': 'engine/objects/zCVobSpot.md'