diff --git a/crates/blenvy/OLD.md b/crates/blenvy/OLD.md
index 090f897..b292480 100644
--- a/crates/blenvy/OLD.md
+++ b/crates/blenvy/OLD.md
@@ -15,55 +15,4 @@ see https://github.com/kaosat-dev/Blenvy/tree/main/examples/blenvy/basic for how
 
 
 
-## Animation
-
-```blenvy``` provides some lightweight helpers to deal with animations stored in gltf files
-
- * an ```Animations``` component that gets inserted into spawned (root) entities that contains a hashmap of all animations contained inside that entity/gltf file .
- (this is a copy of the ```named_animations``` inside Bevy's gltf structures )
- * an ```AnimationPlayerLink``` component that gets inserted into spawned (root) entities, to make it easier to trigger/ control animations than it usually is inside Bevy + Gltf files
-
-The workflow for animations is as follows:
-* create a gltf file with animations (using Blender & co) as you would normally do
-* inside Bevy, use the ```blenvy``` boilerplate (see sections above), no specific setup beyond that is required
-* to control the animation of an entity, you need to query for entities that have both ```AnimationPlayerLink``` and ```Animations``` components (added by ```blenvy```) AND entities with the ```AnimationPlayer``` component
- 
-For example:
-
-```rust no_run
-// example of changing animation of entities based on proximity to the player, for "fox" entities (Tag component)
-pub fn animation_change_on_proximity_foxes(
-    players: Query<&GlobalTransform, With<Player>>,
-    animated_foxes: Query<(&GlobalTransform, &AnimationPlayerLink, &Animations ), With<Fox>>,
-
-    mut animation_players: Query<&mut AnimationPlayer>,
-
-){
-    for player_transforms in players.iter() {
-        for (fox_tranforms, link, animations) in animated_foxes.iter() {
-            let distance = player_transforms
-                .translation()
-                .distance(fox_tranforms.translation());
-            let mut anim_name = "Walk"; 
-            if distance < 8.5 {
-                anim_name = "Run"; 
-            }
-            else if distance >= 8.5 && distance < 10.0{
-                anim_name = "Walk";
-            }
-            else if distance >= 10.0 && distance < 15.0{
-                anim_name = "Survey";
-            }
-            // now play the animation based on the chosen animation name
-            let mut animation_player = animation_players.get_mut(link.0).unwrap();
-            animation_player.play_with_transition(
-                animations.named_animations.get(anim_name).expect("animation name should be in the list").clone(), 
-                Duration::from_secs(3)
-            ).repeat();
-        }
-    }
-}
-```
-
-see https://github.com/kaosat-dev/Blenvy/tree/main/examples/blenvy/animation for how to set it up correctly
 
diff --git a/crates/blenvy/README.md b/crates/blenvy/README.md
index d079f25..12a966c 100644
--- a/crates/blenvy/README.md
+++ b/crates/blenvy/README.md
@@ -229,9 +229,60 @@ Ff you enable it on the blender side, Blenvy will be using "material libraries"
 Ie for example without this option, 56 different blueprints using the same material with a large texture would lead to the material/texture being embeded
 56 times !!
 
-
 Generating optimised blueprints and material libraries can be automated using the [Blender plugin](https://github.com/kaosat-dev/Blenvy/tree/main/tools/blenvy)
 
+## Animation
+
+```blenvy``` provides some lightweight helpers to deal with animations stored in gltf files
+
+It has both support for blueprint level animations (shared by all blueprint instance of the same blueprint)
+
+ * an ```BlueprintAnimations``` component that gets inserted into spawned (root) entities that contains a hashmap of all animations contained inside that entity/gltf file .
+ * an ```BlueprintAnimationPlayerLink``` component that gets inserted into spawned (root) entities, to make it easier to find Bevy's ```AnimationPlayer``` and ```AnimationTransitions``` components
+
+And instance level animations (specific to one instance)
+
+ * an ```InstanceAnimations``` component that gets inserted into spawned (root) entities that contains a hashmap of all animations **specific to that instance** .
+ * an ```InstanceAnimationPlayerLink``` component that gets inserted into spawned (root) entities, to make it easier to find Bevy's ```AnimationPlayer``` and ```AnimationTransitions``` components for the animations above
+
+
+The workflow for animations is as follows:
+* create a gltf file with animations (using Blender & co) as you would normally do
+* inside Bevy, use the ```blenvy``` boilerplate (see sections above), no specific setup beyond that is required
+* to control the animation of an entity, you need to query for entities that have both ```BlueprintAnimationPlayerLink``` and ```BlueprintAnimations``` components (added by ```blenvy```) AND entities with the ```AnimationPlayer``` component
+ 
+For example (blueprint animations):
+
+```rust no_run
+pub fn trigger_blueprint_animations(
+    animated_foxes: Query<(&BlueprintAnimationPlayerLink, &BlueprintAnimations), With<Fox>>,
+    mut animation_players: Query<(&mut AnimationPlayer, &mut AnimationTransitions)>,
+    keycode: Res<ButtonInput<KeyCode>>,
+){
+    if keycode.just_pressed(KeyCode::KeyW) {
+        for (link, animations) in animated_foxes.iter() {
+            let (mut animation_player, mut animation_transitions) =
+            animation_players.get_mut(link.0).unwrap();
+
+            let anim_name = "Walk";
+            animation_transitions
+                .play(
+                    &mut animation_player,
+                    animations
+                        .named_indices
+                        .get(anim_name)
+                        .expect("animation name should be in the list")
+                        .clone(),
+                    Duration::from_secs(5),
+                )
+                .repeat();
+        }
+    }
+}
+```
+
+see https://github.com/kaosat-dev/Blenvy/tree/main/examples/blenvy/animation for how to set it up correctly
+
 
 ## Additional features