Add offhand spyglass animation (#34)

Closes GeyserMC/Geyser#3192

animation_controllers/player.animation_controllers.json

@@ -0,0 +1,154 @@
+{
+	"format_version" : "1.10.0",
+	"animation_controllers" : {
+		"controller.animation.player.root" : {
+			"initial_state" : "first_person",
+			"states" : {
+				"first_person" : {
+					"animations" : [
+						{
+							"first_person_swap_item": "!query.blocking"
+						},
+						{
+							"first_person_shield_block": "query.blocking"
+						},
+						{
+							"first_person_attack_controller" : "variable.attack_time > 0.0f && query.get_equipped_item_name != 'filled_map'"
+						},
+						"first_person_base_pose",
+						{
+							"first_person_empty_hand" : "query.get_equipped_item_name(0, 1) != 'filled_map'"
+						},
+						{
+							"first_person_walk" : "variable.bob_animation"
+						},
+						{
+							"first_person_map_controller" : "(query.get_equipped_item_name(0, 1) == 'filled_map' || query.get_equipped_item_name('off_hand') == 'filled_map')"
+						},
+						{
+							"first_person_crossbow_equipped": "query.get_equipped_item_name == 'crossbow' && (variable.item_use_normalized > 0 && variable.item_use_normalized < 1.0)"
+						},
+						{
+							"first_person_breathing_bob": "variable.attack_time <= 0.0"
+						}
+					],
+					"transitions" : [
+						{
+							"paperdoll" : "variable.is_paperdoll"
+						},
+						{
+							"map_player" : "variable.map_face_icon"
+						},
+						{
+							"third_person" : "!variable.is_first_person"
+						}
+					]
+				},
+				"map_player" : {
+					"transitions" : [
+						{
+							"paperdoll" : "variable.is_paperdoll"
+						},
+						{
+							"first_person" : "variable.is_first_person"
+						},
+						{
+							"third_person" : "!variable.map_face_icon && !variable.is_first_person"
+						}
+					]
+				},
+				"paperdoll" : {
+					"animations" : [ "humanoid_base_pose", "look_at_target_ui", "move.arms", "move.legs", "cape" ],
+					"transitions" : [
+						{
+							"first_person" : "!variable.is_paperdoll && variable.is_first_person"
+						},
+						{
+							"map_player" : "variable.map_face_icon"
+						},
+						{
+							"third_person" : "!variable.is_paperdoll && !variable.is_first_person"
+						}
+					]
+				},
+				"third_person" : {
+					"animations" : [
+						"humanoid_base_pose",
+						{
+							"look_at_target" : "!query.is_sleeping && !query.is_emoting"
+						},
+						"move.arms",
+						"move.legs",
+						"cape",
+						{
+							"riding.arms" : "query.is_riding"
+						},
+						{
+							"riding.legs" : "query.is_riding"
+						},
+						"holding",
+						{
+							"brandish_spear" : "variable.is_brandishing_spear"
+						},
+						{
+							"holding_spyglass": "variable.is_holding_spyglass || (q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') && q.is_emerging)"
+						},
+						{
+							"charging" : "query.is_charging"
+						},
+						{
+							"sneaking" : "query.is_sneaking && !query.is_sleeping"
+						},
+						{
+							"bob": "!variable.is_holding_spyglass && !(q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') && q.is_emerging)"
+						},
+						{
+							"damage_nearby_mobs" : "variable.damage_nearby_mobs"
+						},
+						{
+							"swimming" : "variable.swim_amount > 0.0"
+						},
+						{
+							"swimming.legs" : "variable.swim_amount > 0.0"
+						},
+						{
+							"use_item_progress" : "( variable.use_item_interval_progress > 0.0 ) || ( variable.use_item_startup_progress > 0.0 ) && !variable.is_brandishing_spear && !variable.is_holding_spyglass &&  !(q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') && q.is_emerging)"
+						},
+						{
+							"sleeping" : "query.is_sleeping && query.is_alive"
+						},
+						{
+							"attack.positions" : "variable.attack_time >= 0.0"
+						},
+						{
+							"attack.rotations" : "variable.attack_time >= 0.0"
+						},
+						{
+							"shield_block_main_hand" : "query.blocking && query.get_equipped_item_name('off_hand') != 'shield' && query.get_equipped_item_name == 'shield'"
+						},
+						{
+							"shield_block_off_hand" : "query.blocking && query.get_equipped_item_name('off_hand') == 'shield'"
+						},
+						{
+							"crossbow_controller" : "query.get_equipped_item_name == 'crossbow'"
+						},
+						{
+							"third_person_bow_equipped" : "query.get_equipped_item_name == 'bow' && (variable.item_use_normalized > 0 && variable.item_use_normalized < 1.0)"
+						}
+					],
+					"transitions" : [
+						{
+							"paperdoll" : "variable.is_paperdoll"
+						},
+						{
+							"first_person" : "variable.is_first_person"
+						},
+						{
+							"map_player" : "variable.map_face_icon"
+						}
+					]
+				}
+			}
+		}
+	}
+}

animations/humanoid.animation.json

@@ -0,0 +1,16 @@
+{
+    "format_version" : "1.8.0",
+    "animations" : {
+        "animation.humanoid.holding_spyglass" : {
+			"loop" : true,
+			"bones" : {
+				"rightarm" : {
+					"rotation" : [ "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? math.clamp(query.target_x_rotation - 105 - (v.is_sneaking ? 15 : 0), -170, 180)", "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? math.clamp(q.target_y_rotation - 15, -60, 90)", "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? 5.0" ]
+				},
+                "leftarm" : {
+					"rotation" : [ "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? math.clamp(query.target_x_rotation - 105 - (v.is_sneaking ? 15 : 0), -170, 180)", "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? math.clamp(q.target_y_rotation + 15, -60, 90)", "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? -5.0" ]
+				}
+			}
+		}
+    }
+}

animations/spyglass.animation.json

@@ -0,0 +1,14 @@
+{
+    "format_version": "1.10.0",
+    "animations": {
+      "animation.spyglass.holding": {
+        "loop": true,
+        "bones": {
+          "spyglass": {
+            "position": [ "c.is_first_person ? 2.0 : (q.is_emerging ? 3.0 : 1.0)", "c.is_first_person ? 25.0 : (q.is_emerging ? 27.0 : 22.0)", "c.is_first_person ? -1.0 : (q.is_emerging ? -3.0 : 0.0)" ],
+            "rotation": [ "c.is_first_person ? 58.0 : 0.0", "c.is_first_person ? -48.0 : -90.0", "c.is_first_person ? -44.0 : 0.0" ]
+          }
+        }
+      }
+    }
+  }

developer_documentation.md

@@ -11,6 +11,7 @@
    * [Player skin parts](#Player-skin-parts)
    * [Shulkers](#Shulkers)
    * [Spectral arrow entities](#Spectral-arrow-entities)
+   * [Spyglass animations](#Spyglass-animations)
    * [Zombie villager textures](#Zombie-villager-textures)
 <!--te-->
 
@@ -163,6 +164,70 @@ The glowing effect and the spectral arrow item and entities do not exist on Bedr
 
 The texture required for this to be displayed can be retrieved during the build process.
 
+### Spyglass animations
+
+The spyglass does not display at all in the offhand on Bedrock edition. Consequently, when using /geyser offhand, the spyglass simply appears in the main hand. This is also true of Bedrock players viewing Java players with an offhand spyglass. The animation for offhand use of the spyglass also does not play properly. Multiple changes are required to remedy this.
+
+The spyglass effectively functions as an attachable, but has no user-facing attachable definition. Nonetheless, many of the principles of attachables can still be applied.
+
+Firstly, the spyglass geometry must be bound to offhand of the player when proper. This is possible with the 1.16.0 geometry format, which has the field "binding". The original spyglass binding expression only allows it to be bound to the mainhand or head. It is replaced with the following expression. The query `q.is_emerging` is set by Geyser specifically for OptionalPack when the client is using an offand item, and is therefore effectively a proxy for `q.main_hand_item_use_duration > 0`. The query `q.is_item_name_any` is then used to check which hand slot the spyglass resides in.
+
+```json
+{
+  "binding": "q.item_slot_to_bone_name((q.main_hand_item_use_duration || q.is_emerging) > 0.0f ? 'head' : (q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? 'main_hand' : 'off_hand'))"
+}
+```
+
+Next, the vanilla player animation controller must be modified to account for the possibility the spyglass is in the offhand.When in the mainhand, the hardcoded variable `variable.is_holding_spyglass` is used to check for the use of the spyglass in the mainhand, as a proxy for this in the offhand, using the Geyser specific query defined above, the following Molang expression is used to check for the use of the spyglass in the offhand. It is used at various points in the animation controller, including to engage the spyglass animation, cancel the bobbing animation, and cancel other item use animations.
+
+```c
+(q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') && q.is_emerging)
+```
+
+The player animation itself must be modified to account for the axis flip of the players arm holding the spyglass on the opposite side. This simply requires flipping the Y and Z axis of rotation, as well as ensuring the slots are use of mainhand and offhand is properly distinguished.
+
+```json
+
+{
+  "rightarm" : {
+    "rotation" : [ 
+      "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? math.clamp(query.target_x_rotation - 105 - (v.is_sneaking ? 15 : 0), -170, 180)", 
+      "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? math.clamp(q.target_y_rotation - 15, -60, 90)", 
+      "q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? 5.0"
+      ]
+  },
+  "leftarm" : {
+    "rotation" : [ 
+      "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? math.clamp(query.target_x_rotation - 105 - (v.is_sneaking ? 15 : 0), -170, 180)", 
+      "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? math.clamp(q.target_y_rotation + 15, -60, 90)", 
+      "q.is_item_name_any('slot.weapon.offhand', 0, 'minecraft:spyglass') ? -5.0"
+      ]
+  }
+}
+```
+
+Lastly, the spyglass animation must be modified to account for the spyglass being on the opposite side of the player's head. Unfortunately, the scoping animation cannot be used for this, as its triggering appears to be hardcoded on the client side. Instead, the holding animation is conditionally modified when `q.is_emerging` is true, meaning the spyglass is in use.
+
+```json
+{
+  "spyglass": {
+    "position": [ 
+      "c.is_first_person ? 2.0 : (q.is_emerging ? 3.0 : 1.0)", 
+      "c.is_first_person ? 25.0 : (q.is_emerging ? 27.0 : 22.0)", 
+      "c.is_first_person ? -1.0 : (q.is_emerging ? -3.0 : 0.0)" 
+      ],
+    "rotation": [ 
+      "c.is_first_person ? 58.0 : 0.0", 
+      "c.is_first_person ? -48.0 : -90.0", 
+      "c.is_first_person ? -44.0 : 0.0" 
+      ]
+  }
+}
+```
+
+Unfortunately, the spyglass cannot actually be used in the offhand by Bedrock players, as the triggering of the first person "animation" for it is hardcoded on the client side. However, these changes allow the spyglass to be properly displayed when in the offhand of a Bedrock player, as well as when used in the offhand of a Java player. Furthermore, `q.is_emerging` could be utilized by other resource pack creators working with Geyser to identify if an item is being used in the offhand.
+
+
 ### Zombie villager textures
 
 Like villagers, zombie villagers in Java Edition have visible biome and profession variants. It appears that initial implementation of this was started in the Bedrock vanilla resources, given the presence of the entity with the identifier `minecraft:zombie_villager_v2`. However, the textures specified in this vanilla entity definition appear to be entirely blank TGA files. Luckily, the profession textures of zombie villagers and villagers are essentially identical, so the entity definition was updated to reference the villager profession textures. 

manifest.json

@@ -4,7 +4,7 @@
         "description": "Optional Bedrock resource pack to extend Geyser functionality",
         "name": "GeyserOptionalPack",
         "uuid": "e5f5c938-a701-11eb-b2a3-047d7bb283ba",
-        "version": [1, 0, 5],
+        "version": [1, 0, 6],
         "min_engine_version": [ 1, 16, 0 ]
     },
     "modules": [
@@ -12,7 +12,7 @@
             "description": "GeyserOptionalPack",
             "type": "resources",
             "uuid": "eebb4ea8-a701-11eb-95ba-047d7bb283ba",
-            "version": [1, 0, 5]
+            "version": [1, 0, 6]
         }
     ]
 }

models/entity/spyglass.geo.json

@@ -0,0 +1,35 @@
+{
+    "format_version": "1.16.0",
+    "minecraft:geometry": [
+      {
+        "description": {
+          "identifier": "geometry.spyglass",
+          "texture_width": 16,
+          "texture_height": 16,
+          "visible_bounds_width": 3,
+          "visible_bounds_height": 1.5,
+          "visible_bounds_offset": [ 0, 0.25, 0 ]
+        },
+        "bones": [
+          {
+            "name": "spyglass",
+            "binding": "q.item_slot_to_bone_name((q.main_hand_item_use_duration || q.is_emerging) > 0.0f ? 'head' : (q.is_item_name_any('slot.weapon.mainhand', 0, 'minecraft:spyglass') ? 'main_hand' : 'off_hand'))",
+            "pivot": [ 0, 0, 0 ],
+            "cubes": [
+              {
+                "origin": [ -11.1, -0.1, -0.1 ],
+                "size": [ 6.2, 2.2, 2.2 ],
+                "uv": [ 0, 0 ]
+              },
+              {
+                "origin": [ -5, 0, 0 ],
+                "size": [ 5, 2, 2 ],
+                "uv": [ 0, 4 ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+