ADD: Scene animation

docs/Scene.md

@@ -41,6 +41,51 @@ Thin scene layer that produces `RenderObject`s for the renderer. It gathers opaq
 - GLTF instances
   - `addGLTFInstance(name, LoadedGLTF, transform)`, `removeGLTFInstance(name)`, `clearGLTFInstances()`.
 
+### GLTF Animation / “Actions”
+
+GLTF files can contain one or more animation clips (e.g. `Idle`, `Walk`, `Run`). The loader (`LoadedGLTF`) parses these into `LoadedGLTF::Animation` objects, and `SceneManager` exposes a thin API to pick which clip is currently playing.
+
+> Note: a `LoadedGLTF` is typically shared by multiple instances. Changing the active animation on a shared `LoadedGLTF` will affect all instances that point to it. If you want per‑character independent actions, load separate `LoadedGLTF` objects (one per character) or duplicate the asset in your game layer.
+
+**Static scenes (loaded via `loadScene`)**
+
+Example: engine default scene in `VulkanEngine::init()`:
+
+- `structure` is loaded and registered via:
+  - `sceneManager->loadScene("structure", structureFile);`
+
+To control its animation:
+
+- By index:
+  - `scene->setSceneAnimation("structure", 0);        // first clip`
+  - `scene->setSceneAnimation("structure", 1, true);  // second clip, reset time`
+- By name (matches glTF animation name):
+  - `scene->setSceneAnimation("structure", "Idle");`
+  - `scene->setSceneAnimation("structure", "Run");`
+- Looping:
+  - `scene->setSceneAnimationLoop("structure", true);   // enable loop`
+  - `scene->setSceneAnimationLoop("structure", false);  // play once and stop at end`
+
+All functions return `bool` to indicate whether the scene name was found.
+
+**Runtime GLTF instances**
+
+GLTF instances are created via:
+
+- `scene->addGLTFInstance("player", playerGltf, playerTransform);`
+
+You can treat each instance as an “actor” and drive its current action from your game state:
+
+- By index:
+  - `scene->setGLTFInstanceAnimation("player", 0);`
+- By name:
+  - `scene->setGLTFInstanceAnimation("player", "Idle");`
+  - `scene->setGLTFInstanceAnimation("player", "Run");`
+- Looping:
+  - `scene->setGLTFInstanceAnimationLoop("player", true);`
+
+These helpers forward to the underlying `LoadedGLTF`’s `setActiveAnimation(...)` and `animationLoop` fields. `SceneManager::update_scene()` advances animations every frame using a per‑frame `dt`, so once you select an action, it will keep playing automatically until you change it or disable looping.
+
 ### GPU Scene Data
 
 - `GPUSceneData` carries camera matrices and lighting constants for the frame.