feat: add AnimationTrack class, Animator.GetPlayingAnimationTracks, and Humanoid.MoveTo

- Added AnimationTrack datastructure with Animation, Animator, Speed, Looped, IsPlaying properties
- Added GetPlayingAnimationTracks() for Animator instances (linked list traversal with validation)
- Added MoveTo(target, wait) for Humanoid instances (supports Vector3 and Part targets, sync/async)
- Bumped version to 0.2.0

Author: notpoiu

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "robloxmemoryapi"
-version = "0.1.9.2"
+version = "0.2.0"
 description = "Python Library that abstracts reading and writing data from the Roblox DataModel"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.9"

src/robloxmemoryapi/utils/memory.py

@@ -211,12 +211,20 @@ def __init__(self, pid: int, access: DWORD):
         if status != STATUS_SUCCESS:
             raise ctypes.WinError(f"NtOpenProcess failed with NTSTATUS: 0x{status:X}")
         self.base = _get_module_base(self.handle)
+        self.is_closed = False
         if self.base == 0:
             self.close()
             raise ConnectionError("Failed to get module base address.")
 
+    @property
+    def is_invalid_handle(self) -> bool:
+        return self.handle and self.handle.value == 0
+
     def read(self, address: int, size: int) -> bytes:
-        if not self.handle or self.handle.value == 0:
+        if self.is_closed:
+            return b""
+        
+        if self.is_invalid_handle:
             raise ValueError("Process handle is not valid.")
         buffer = ctypes.create_string_buffer(size)
         bytes_read = ctypes.c_ulong(0)
@@ -232,7 +240,7 @@ def read(self, address: int, size: int) -> bytes:
         return buffer.raw[:bytes_read.value]
 
     def write(self, address: int, data: bytes | bytearray) -> int:
-        if not self.handle or self.handle.value == 0:
+        if self.is_invalid_handle:
             raise ValueError("Process handle is not valid.")
         if not isinstance(data, (bytes, bytearray)):
             raise TypeError("data must be bytes-like.")
@@ -256,7 +264,10 @@ def virtual_alloc(self, size: int, allocation_type: int = MEM_COMMIT | MEM_RESER
         if size <= 0:
             raise ValueError("size must be greater than zero.")
 
-        if not self.handle or self.handle.value == 0:
+        if self.is_closed:
+            return
+        
+        if self.is_invalid_handle:
             raise ValueError("Process handle is not valid.")
 
         base_address = LPVOID()
@@ -417,6 +428,7 @@ def get_address(self, address: int, pointer: bool) -> int:
 
     #########
     def close(self):
-        if self.handle and self.handle.value != 0:
+        if not self.is_invalid_handle:
+            self.is_closed = True
             nt_close_syscall(self.handle)
             self.handle = HANDLE(0)

src/robloxmemoryapi/utils/rbx/datastructures.py

@@ -353,4 +353,40 @@ def GetComponents(self):
             self.RightVector.Y, self.UpVector.Y, self.LookVector.Y,
             self.RightVector.Z, self.UpVector.Z, self.LookVector.Z,
             self.Position.X, self.Position.Y, self.Position.Z
-        ])
+        ])
+
+class AnimationTrack:
+    def __init__(self, address, memory_module, offsets):
+        self.raw_address = address
+        self.memory_module = memory_module
+        self._offsets = offsets
+
+    def __repr__(self):
+        return f"AnimationTrack(0x{self.raw_address:X})"
+
+    def __eq__(self, other):
+        return isinstance(other, AnimationTrack) and self.raw_address == other.raw_address
+
+    @property
+    def Animation(self):
+        from .instance import RBXInstance
+        ptr = self.memory_module.get_pointer(self.raw_address, self._offsets["Animation"])
+        return RBXInstance(ptr, self.memory_module) if ptr != 0 else None
+
+    @property
+    def Animator(self):
+        from .instance import RBXInstance
+        ptr = self.memory_module.get_pointer(self.raw_address, self._offsets["Animator"])
+        return RBXInstance(ptr, self.memory_module) if ptr != 0 else None
+
+    @property
+    def Speed(self):
+        return self.memory_module.read_float(self.raw_address, self._offsets["Speed"])
+
+    @property
+    def Looped(self):
+        return self.memory_module.read_bool(self.raw_address, self._offsets["Looped"])
+
+    @property
+    def IsPlaying(self):
+        return self.memory_module.read_bool(self.raw_address, self._offsets["IsPlaying"])

src/robloxmemoryapi/utils/rbx/instance.py

@@ -16,6 +16,8 @@
 clickdetector_offsets = Offsets["ClickDetector"]
 statsitem_offsets = Offsets["StatsItem"]
 inputobject_offsets = Offsets["MouseService"]  # InputObject uses MouseService offsets
+animator_offsets = Offsets["Animator"]
+animationtrack_offsets = Offsets["AnimationTrack"]
 
 ROTATION_MATRIX_FLOATS = 9
 
@@ -115,7 +117,6 @@ def primitive_address(self):
             self.raw_address,
             basepart_offsets["Primitive"]
         )
-    
 
     # props #
     @property
@@ -173,7 +174,7 @@ def ClassName(self):
             instance_offsets["ClassName"]
         )
         return self.memory_module.read_string(class_name_address)
-    
+
     @property
     def CFrame(self):
         className = self.ClassName
@@ -557,6 +558,36 @@ def CanTouch(self, value: bool):
             flags &= ~Offsets["PrimitiveFlags"]["CanTouch"]
         self._write_primitive_flags(flags)
 
+    # Animator props #
+    def GetPlayingAnimationTracks(self):
+        if self.ClassName != "Animator":
+            raise AttributeError("GetPlayingAnimationTracks is only available on Animator instances.")
+
+        head = self.memory_module.get_pointer(
+            self.raw_address,
+            animator_offsets["ActiveAnimations"]
+        )
+        if head == 0:
+            return []
+
+        node = self.memory_module.get_pointer(head)
+        result = []
+
+        while node != 0 and node != head:
+            track_address = self.memory_module.get_pointer(node, 0x10)
+            animation_track = AnimationTrack(track_address, self.memory_module, animationtrack_offsets)
+            
+            try:
+                if animation_track.Animation.AnimationId is None:
+                    raise Exception("AnimationId is None")
+                
+                result.append(animation_track)
+            except Exception:
+                pass
+            node = self.memory_module.get_pointer(node)
+
+        return result
+
     # ProximityPrompt props #
     @property
     def MaxActivationDistance(self):
@@ -1137,6 +1168,58 @@ def HumanoidState(self, value: int):
             int(value)
         )
 
+    def MoveTo(self, target, wait=True):
+        if self.ClassName != "Humanoid":
+            raise AttributeError("MoveTo is only available on Humanoid instances.")
+        
+        self._ensure_writable()
+
+        if isinstance(target, RBXInstance):
+            self.memory_module.write_long(
+                self.raw_address + humanoid_offsets["MoveToPart"],
+                target.raw_address
+            )
+            position = target.Position
+        else:
+            position = self._as_vector3(target, "MoveTo target")
+
+        character = self.Parent
+        if character is None:
+            raise RuntimeError("Humanoid has no parent Character model.")
+
+        hrp = character.PrimaryPart
+        if hrp is None:
+            raise RuntimeError("Could not find PrimaryPart in Character.")
+
+        def execute_move():
+            while True:
+                try:
+                    if self.memory_module.is_invalid_handle or self.memory_module.is_closed:
+                        break
+
+                    if hrp.Parent is None or self.Health <= 0:
+                        break
+
+                    current = hrp.Position
+                    if abs(current.X - position.X) <= 1.0 and abs(current.Z - position.Z) <= 1.0:
+                        break
+
+                    self.memory_module.write_floats(
+                        self.raw_address + humanoid_offsets["MoveToPoint"],
+                        (position.X, position.Y, position.Z)
+                    )
+                    self.memory_module.write_bool(
+                        self.raw_address + humanoid_offsets["IsWalking"],
+                        True
+                    )
+                except Exception:
+                    break
+
+        if wait:
+            execute_move()
+        else:
+            threading.Thread(target=execute_move, daemon=True).start()
+
     # adornee / animation props #
     @property
     def Adornee(self):
@@ -1183,7 +1266,6 @@ def AnimationId(self, value: str):
             str(value)
         )
 
-
     # model props #
     @property
     def PrimaryPart(self):