Introduce $ sigil for value variables and reserve @ for node refs; update parser, writer, lexer, docs and templates

docs/Animation.md

@@ -2,6 +2,10 @@
 
 Perro animation has two resource files and two scene nodes.
 
+Sigils:
+- `$` => value var define/use.
+- `@` => node ref (scene key / NodeID target), in scenes + animation bindings.
+
 - `.panim`: one animation clip.
 - `.panimtree`: one animation graph.
 - `AnimationPlayer`: plays one `.panim`.
@@ -53,7 +57,7 @@ Use `AnimationPlayer` when one clip drives one set of bindings.
 [IdlePlayer]
     [AnimationPlayer]
         animation = "res://animations/idle.panim"
-        bindings = { Hero = Hero }
+        bindings = { Hero = @Hero }
         speed = 1.0
         paused = false
         playback = loop
@@ -204,9 +208,9 @@ The scene node supplies:
     [AnimationTree]
         tree = "res://animations/player.panimtree"
         animations = [
-            { animation = "res://animations/idle.panim", bindings = { Hero = Hero }, playback = loop, speed = 1.0, paused = false },
-            { animation = "res://animations/run.panim", bindings = { Hero = Hero }, playback = loop, speed = 1.0, paused = false },
-            { animation = "res://animations/aim.panim", bindings = { Hero = Hero }, playback = boomerang, speed = 1.0, paused = false },
+            { animation = "res://animations/idle.panim", bindings = { Hero = @Hero }, playback = loop, speed = 1.0, paused = false },
+            { animation = "res://animations/run.panim", bindings = { Hero = @Hero }, playback = loop, speed = 1.0, paused = false },
+            { animation = "res://animations/aim.panim", bindings = { Hero = @Hero }, playback = boomerang, speed = 1.0, paused = false },
         ]
         speed = 1.0
         paused = false

docs/resources/panimtree.md

@@ -7,6 +7,10 @@ The `.panimtree` owns slot names and graph connections.
 The scene `AnimationTree` node owns runtime clip IDs and per-slot bindings.
 Slot bindings connect `.panim` object names to scene node keys.
 
+Sigils in scene-side bindings:
+- `$` => value vars.
+- `@` => node refs (`NodeID` targets), same as scene parent/root refs.
+
 ## Example
 
 ```ini
@@ -195,9 +199,9 @@ Scene node template:
         speed = 1.0
         paused = false
         animations = [
-            { animation = "res://animations/idle.panim", bindings = { Hero = PlayerRoot }, playback = loop, speed = 1.0, paused = false },
-            { animation = "res://animations/run.panim", bindings = { Hero = PlayerRoot }, playback = loop, speed = 1.0, paused = false },
-            { animation = "res://animations/aim.panim", bindings = { Hero = PlayerRoot }, playback = boomerang, speed = 1.0, paused = false },
+            { animation = "res://animations/idle.panim", bindings = { Hero = @PlayerRoot }, playback = loop, speed = 1.0, paused = false },
+            { animation = "res://animations/run.panim", bindings = { Hero = @PlayerRoot }, playback = loop, speed = 1.0, paused = false },
+            { animation = "res://animations/aim.panim", bindings = { Hero = @PlayerRoot }, playback = boomerang, speed = 1.0, paused = false },
         ]
     [/AnimationTree]
 [/AnimTree]
@@ -251,9 +255,9 @@ Bind it to a real scene node in `animations`:
     [AnimationTree]
         tree = "res://animations/player.panimtree"
         animations = [
-            { animation = "res://animations/idle.panim", bindings = { Hero = PlayerRoot }, playback = loop },
-            { animation = "res://animations/run.panim", bindings = { Hero = PlayerRoot }, playback = loop },
-            { animation = "res://animations/aim.panim", bindings = { Hero = PlayerRoot }, playback = boomerang },
+            { animation = "res://animations/idle.panim", bindings = { Hero = @PlayerRoot }, playback = loop },
+            { animation = "res://animations/run.panim", bindings = { Hero = @PlayerRoot }, playback = loop },
+            { animation = "res://animations/aim.panim", bindings = { Hero = @PlayerRoot }, playback = boomerang },
         ]
     [/AnimationTree]
 [/anim_tree]
@@ -362,9 +366,9 @@ Scene:
     [AnimationTree]
         tree = "res://animations/player.panimtree"
         animations = [
-            { animation = "res://animations/idle.panim", bindings = { Hero = PlayerRoot }, playback = loop, speed = 1.0 },
-            { animation = "res://animations/run.panim", bindings = { Hero = PlayerRoot }, playback = loop, speed = 1.0 },
-            { animation = "res://animations/aim.panim", bindings = { Hero = PlayerRoot }, playback = boomerang, speed = 0.8 },
+            { animation = "res://animations/idle.panim", bindings = { Hero = @PlayerRoot }, playback = loop, speed = 1.0 },
+            { animation = "res://animations/run.panim", bindings = { Hero = @PlayerRoot }, playback = loop, speed = 1.0 },
+            { animation = "res://animations/aim.panim", bindings = { Hero = @PlayerRoot }, playback = boomerang, speed = 0.8 },
         ]
     [/AnimationTree]
 [/AnimTree]

docs/scripting/contexts/resource_modules/animations.md

@@ -53,5 +53,5 @@ Binding note:
 
 - `ClipObjectName` is the object key declared in `.panim [Objects]` (without `@`).
 - Bind each clip object to a runtime node with the expected node type for that track data.
-- scene authoring bindings use map entries: `{ ClipObjectName = SceneKey }` or `{ "ClipObjectName": SceneKey }`.
+- scene authoring bindings use map entries: `{ ClipObjectName = @SceneKey }` or `{ "ClipObjectName": @SceneKey }`.
 

docs/scripting/contexts/runtime_modules/animations.md

@@ -101,7 +101,7 @@ let _ = anim_player_play!(ctx, animation_player_id);
 - `animation = "res://animations/clip.panim"`
 - `bindings = [{ Hero = HeroNode }, { Weapon = WeaponNode }]`
 - `bindings = [{ "Hero": HeroNode }, { "Weapon": WeaponNode }]`
-- bindings are map entries: `AnimationObject -> SceneKey`
+- bindings are map entries: `AnimationObject -> @SceneKey`
 - scene key (`HeroNode`) is resolved to runtime `NodeID` during scene merge
 - `speed = 1.0`
 - `paused = true|false`
@@ -125,4 +125,3 @@ Example scene-key binding:
 ```
 
 Scripts can override or update these values at runtime.
-

docs/scripting/nodes.md

@@ -240,22 +240,22 @@ Example: sword in hand.
 [/Character]
 
 [CharacterSkeleton]
-parent = Character
+parent = @Character
     [Skeleton3D]
         skeleton = "res://characters/knight.glb:skeleton[0]"
     [/Skeleton3D]
 [/CharacterSkeleton]
 
 [CharacterMesh]
-parent = Character
+parent = @Character
     [MeshInstance3D]
         mesh = "res://characters/knight.glb:mesh[0]"
         skeleton = "CharacterSkeleton"
     [/MeshInstance3D]
 [/CharacterMesh]
 
 [RightHandSocket]
-parent = Character
+parent = @Character
     [BoneAttachment3D]
         skeleton = "CharacterSkeleton"
         bone = 15
@@ -269,7 +269,7 @@ parent = Character
 [/RightHandSocket]
 
 [Sword]
-parent = RightHandSocket
+parent = @RightHandSocket
     [MeshInstance3D]
         mesh = "res://weapons/sword.glb:mesh[0]"
         material = "res://weapons/sword.pmat"