Add animation sync docs and descriptor infra

Add detailed design and implementation scaffolding for TiltedEvolution-style animation synchronization. New documentation: animation-architecture-alignment.md, animation-sync-analysis.md, f4-animation-descriptor.md, phase1-3-completion-report.md and updates to dev-log.md describing Phase 1-3 progress. Plugin: introduce F4AnimationDescriptor (plugin/include/F4AnimationDescriptor.h, plugin/src/F4AnimationDescriptor.cpp) and extend remote state handling (plugin/include/F4TRemotePlayerState.h). Integrate protocol/state extensions and refactor points: plugin/src/F4TNetworking.cpp now parses optional actorStateFlags and actionEvents; proxy controller and animation sync files (F4TProxyActorController.cpp, F4TProxyAnimationSync.cpp) updated to support descriptor-based bulk variable snapshots and actor state replication. Server/tools: update server/dev_server_app.py and server/fake_client.py to handle and display the new optional fields. These changes are additive and backward-compatible and set up phases for action capture, dynamic proxy spawn, and action-replay integration.

server/dev_server_app.py

@@ -50,6 +50,7 @@ class DevServerWindow(QMainWindow):
         )
 
         self.stat_labels: dict[str, QLabel] = {}
+        self.selected_fake_client_key: int | None = None
 
         self.setWindowTitle("Fallout 4 Together Dev Server")
         self.resize(1100, 760)
@@ -362,8 +363,15 @@ class DevServerWindow(QMainWindow):
     def _get_selected_fake_client_key_for_control(self) -> int | None:
         client_key = self._get_selected_fake_client_key()
         if client_key is None:
-            self._append_log("Select a fake client first.")
-            return None
+            snapshots = self.fake_player_manager.get_snapshots()
+            if len(snapshots) == 1:
+                client_key = self._get_optional_int(snapshots[0].get("clientKey"))
+                if client_key is not None:
+                    self.selected_fake_client_key = client_key
+                    self._append_log("No fake client row selected; using the only fake client.")
+            if client_key is None:
+                self._append_log("Select a fake client first.")
+                return None
 
         if not self.server.is_running():
             self._append_log("Start the server before controlling fake clients.")
@@ -383,7 +391,9 @@ class DevServerWindow(QMainWindow):
 
         client_key = name_item.data(Qt.ItemDataRole.UserRole)
         try:
-            return int(client_key)
+            selected_key = int(client_key)
+            self.selected_fake_client_key = selected_key
+            return selected_key
         except (TypeError, ValueError):
             return None
 
@@ -449,10 +459,16 @@ class DevServerWindow(QMainWindow):
                 self.clients_table.setItem(row, column, self._create_table_item(str(value)))
 
     def _refresh_fake_clients_table(self) -> None:
+        selected_key = self._get_selected_fake_client_key()
+        if selected_key is None:
+            selected_key = self.selected_fake_client_key
+
         snapshots = self.fake_player_manager.get_snapshots()
         self.fake_clients_table.setRowCount(len(snapshots))
+        row_to_select: int | None = None
 
         for row, snapshot in enumerate(snapshots):
+            client_key = self._get_optional_int(snapshot.get("clientKey"))
             player_id = snapshot.get("playerId")
             values = [
                 snapshot.get("name", "-"),
@@ -466,13 +482,27 @@ class DevServerWindow(QMainWindow):
             for column, value in enumerate(values):
                 item = self._create_table_item(str(value))
                 if column == 0:
-                    item.setData(Qt.ItemDataRole.UserRole, snapshot.get("clientKey"))
+                    item.setData(Qt.ItemDataRole.UserRole, client_key)
                 self.fake_clients_table.setItem(row, column, item)
 
+            if client_key is not None and client_key == selected_key:
+                row_to_select = row
+
+        if row_to_select is not None:
+            self.fake_clients_table.selectRow(row_to_select)
+            self.selected_fake_client_key = selected_key
+
     @staticmethod
     def _create_table_item(value: str) -> QTableWidgetItem:
         return QTableWidgetItem(value)
 
+    @staticmethod
+    def _get_optional_int(value: Any) -> int | None:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
     @staticmethod
     def _get_optional_float(value: Any) -> float | None:
         try:

server/fake_client.py

@@ -21,6 +21,18 @@ def warn(message: str) -> None:
     log(f"Warning: {message}")
 
 
+def get_optional_uint32(packet: dict[str, Any], field_name: str, default: int = 0) -> int:
+    """Get optional unsigned 32-bit integer field."""
+    value = packet.get(field_name, default)
+    try:
+        parsed_value = int(value)
+        if 0 <= parsed_value <= 0xFFFFFFFF:
+            return parsed_value
+    except (TypeError, ValueError):
+        pass
+    return default
+
+
 def get_optional_bool(packet: dict[str, Any], field_name: str, default: bool = False) -> bool:
     value = packet.get(field_name, default)
     if isinstance(value, bool):
@@ -82,6 +94,8 @@ def update_remote_player_state(packet: dict[str, Any]) -> None:
         "isJumping": get_optional_bool(packet, "isJumping"),
         "weaponDrawn": get_optional_bool(packet, "weaponDrawn"),
         "movementSpeed": get_optional_float(packet, "movementSpeed"),
+        "actorStateFlags1": get_optional_uint32(packet, "actorStateFlags1"),
+        "actorStateFlags2": get_optional_uint32(packet, "actorStateFlags2"),
         "lastReceivedLocalTime": time.time(),
     }
 
@@ -105,6 +119,7 @@ def print_remote_player(player: dict[str, Any]) -> None:
                     f"sneaking={player['isSneaking']}, jumping={player['isJumping']}, "
                     f"weaponDrawn={player['weaponDrawn']}, speed={player['movementSpeed']:.1f}"
                 ),
+                f"Actor State: flags1={player['actorStateFlags1']:08X}, flags2={player['actorStateFlags2']:08X}",
                 f"Cell: {player['cellId']}",
                 f"Worldspace: {player['worldspaceId']}",
                 f"Client Time: {client_time}",
@@ -130,6 +145,7 @@ def print_remote_players() -> None:
             f"moving={player['isMoving']}, sprinting={player['isSprinting']}, "
             f"sneaking={player['isSneaking']}, jumping={player['isJumping']}, "
             f"weaponDrawn={player['weaponDrawn']}, speed={player['movementSpeed']:.1f}, "
+            f"flags1={player['actorStateFlags1']:08X}, flags2={player['actorStateFlags2']:08X}, "
             f"cell={player['cellId']}, worldspace={player['worldspaceId']}, "
             f"serverTime={player['serverTime']}"
         )