protocol: Document aim assist features

minecraft/protocol/camera.go

@@ -188,7 +188,7 @@ type CameraPreset struct {
 	// AlignTargetAndCameraForward determines whether the camera should align the target and the camera forward
 	// or not.
 	AlignTargetAndCameraForward Optional[bool]
-	// AimAssist ...
+	// AimAssist defines the aim assist to use when using this preset.
 	AimAssist Optional[CameraPresetAimAssist]
 }
 
@@ -215,34 +215,49 @@ func (x *CameraPreset) Marshal(r IO) {
 	OptionalFunc(r, &x.AlignTargetAndCameraForward, r.Bool)
 }
 
+// CameraPresetAimAssist represents a preset for aim assist settings.
 type CameraPresetAimAssist struct {
-	PresetID   Optional[string]
+	// Preset is the ID of the preset that has previously been defined in the CameraAimAssistPresets packet.
+	Preset Optional[string]
+	// TargetMode is the mode that the camera should use for detecting targets. This is one of the constants
+	// above.
 	TargetMode Optional[int32]
-	Angle      Optional[mgl32.Vec2]
-	Distance   Optional[float32]
+	// Angle is the maximum angle around the playes's cursor that the aim assist should check for a target,
+	// if TargetMode is set to protocol.AimAssistTargetModeAngle.
+	Angle Optional[mgl32.Vec2]
+	// Distance is the maximum distance from the player's cursor should check for a target, if TargetMode is
+	// set to protocol.AimAssistTargetModeDistance.
+	Distance Optional[float32]
 }
 
 // Marshal encodes/decodes a CameraPresetAimAssist.
 func (x *CameraPresetAimAssist) Marshal(r IO) {
-	OptionalFunc(r, &x.PresetID, r.String)
+	OptionalFunc(r, &x.Preset, r.String)
 	OptionalFunc(r, &x.TargetMode, r.Int32)
 	OptionalFunc(r, &x.Angle, r.Vec2)
 	OptionalFunc(r, &x.Distance, r.Float32)
 }
 
-type CameraAimAssistCategories struct {
+// CameraAimAssistCategoryGroup is a group of categories which can be used by a CameraAimAssistPreset.
+type CameraAimAssistCategoryGroup struct {
+	// Identifier is the unique identifier of the group.
 	Identifier string
+	// Categories is a list of categories within this group.
 	Categories []CameraAimAssistCategory
 }
 
-// Marshal encodes/decodes a CameraAimAssistCategories.
-func (x *CameraAimAssistCategories) Marshal(r IO) {
+// Marshal encodes/decodes a CameraAimAssistCategoryGroup.
+func (x *CameraAimAssistCategoryGroup) Marshal(r IO) {
 	r.String(&x.Identifier)
 	Slice(r, &x.Categories)
 }
 
+// CameraAssistCategory is an aim assist category that defines priorities for specific blocks and entities.
 type CameraAimAssistCategory struct {
-	Name       string
+	// Name is the name of the category which can be used by a CameraAimAssistPreset.
+	Name string
+	// Priorities represents the block and entity specific priorities as well as the default priorities for
+	// this category.
 	Priorities CameraAimAssistPriorities
 }
 
@@ -252,11 +267,17 @@ func (x *CameraAimAssistCategory) Marshal(r IO) {
 	Single(r, &x.Priorities)
 }
 
+// CameraAimAssistPriorities represents the block and entity specific priorities for targetting. The aim
+// assist will select the block or entity with the highest priority within the specified thresholds.
 type CameraAimAssistPriorities struct {
-	Entities      []CameraAimAssistPriority
-	Blocks        []CameraAimAssistPriority
+	// Entities is a list of priorities for specific entity identifiers.
+	Entities []CameraAimAssistPriority
+	// Blocks is a list of priorities for specific block identifiers.
+	Blocks []CameraAimAssistPriority
+	// EntityDefault is the default priority for entities.
 	EntityDefault Optional[int32]
-	BlockDefault  Optional[int32]
+	// BlockDefault is the default priority for blocks.
+	BlockDefault Optional[int32]
 }
 
 // Marshal encodes/decodes a CameraAimAssistPriorities.
@@ -267,45 +288,65 @@ func (x *CameraAimAssistPriorities) Marshal(r IO) {
 	OptionalFunc(r, &x.BlockDefault, r.Int32)
 }
 
+// CameraAimAssistPriority represents a non-default priority for a specific target.
 type CameraAimAssistPriority struct {
-	ID       string
+	// Identifier is the identifier of a target to define the priority for.
+	Identifier string
+	// Priority is the priority for this specific target.
 	Priority int32
 }
 
 // Marshal encodes/decodes a CameraAimAssistPriority.
 func (x *CameraAimAssistPriority) Marshal(r IO) {
-	r.String(&x.ID)
+	r.String(&x.Identifier)
 	r.Int32(&x.Priority)
 }
 
+// CameraAimAssistPreset defines a base preset that can be extended upon when sending an aim assist.
 type CameraAimAssistPreset struct {
-	Identifier          string
-	Categories          string
-	BlockExclusions     []string
-	LiquidTargets       []string
-	ItemSettings        []CameraAimAssistItemSettings
+	// Identifier represents the identifier of this preset.
+	Identifier string
+	// CategoryGroup is the name of a CameraAimAssistCategoryGroup to use for the preset.
+	CategoryGroup string
+	// BlockExclusions is a list of block identifiers that should be ignored by the aim assist.
+	BlockExclusions []string
+	// LiquidTargets is a list of entity identifiers that should be targetted when inside of a liquid.
+	LiquidTargets []string
+	// ItemSettings is a list of settings for specific item identifiers. If an item is not listed here, it
+	// will fallback to DefaultItemSettings or HandSettings if no item is held.
+	ItemSettings []CameraAimAssistItemSettings
+	// DefaultItemSettings is the identifier of a category to use when the player is not holding an item
+	// listed in ItemSettings. This must be the identifier of a category within the
+	// CameraAimAssistCategoryGroup references by CategoryGroup.
 	DefaultItemSettings Optional[string]
-	HandSettings        Optional[string]
+	// HandSettings is the identifier of a category to use when the player is not holding an item. This must
+	// be the identifier of a category within the CameraAimAssistCategoryGroup references by CategoryGroup.
+	HandSettings Optional[string]
 }
 
 // Marshal encodes/decodes a CameraAimAssistPreset.
 func (x *CameraAimAssistPreset) Marshal(r IO) {
 	r.String(&x.Identifier)
-	r.String(&x.Categories)
+	r.String(&x.CategoryGroup)
 	FuncSlice(r, &x.BlockExclusions, r.String)
 	FuncSlice(r, &x.LiquidTargets, r.String)
 	Slice(r, &x.ItemSettings)
 	OptionalFunc(r, &x.DefaultItemSettings, r.String)
 	OptionalFunc(r, &x.HandSettings, r.String)
 }
 
+// CameraAimAssistItemSettings defines settings for how specific items should behave when using aim assist.
 type CameraAimAssistItemSettings struct {
-	ItemID   string
+	// Item is the identifier of the item to apply the settings to.
+	Item string
+	// Category is the identifier of a category to use which has been defined by a CameraAimAssistCategory.
+	// Only categories defined in the CameraAimAssistCategoryGroup used by the CameraAimAssistPreset can be
+	// used here.
 	Category string
 }
 
 // Marshal encodes/decodes a CameraAimAssistItemSettings.
 func (x *CameraAimAssistItemSettings) Marshal(r IO) {
-	r.String(&x.ItemID)
+	r.String(&x.Item)
 	r.String(&x.Category)
 }

minecraft/protocol/packet/camera_aim_assist.go

@@ -12,15 +12,15 @@ const (
 
 // CameraAimAssist is sent by the server to the client to set up aim assist for the client's camera.
 type CameraAimAssist struct {
-	// PresetID is the ID of the preset that has previously been defined in the CameraAimAssistPresets packet.
-	PresetID string
-	// ViewAngle is the angle that the camera should aim at, if TargetMode is set to
-	// protocol.AimAssistTargetModeAngle.
-	ViewAngle mgl32.Vec2
-	// Distance is the distance that the camera should keep from the target, if TargetMode is set to
-	// protocol.AimAssistTargetModeDistance.
+	// Preset is the ID of the preset that has previously been defined in the CameraAimAssistPresets packet.
+	Preset string
+	// Angle is the maximum angle around the playes's cursor that the aim assist should check for a target,
+	// if TargetMode is set to protocol.AimAssistTargetModeAngle.
+	Angle mgl32.Vec2
+	// Distance is the maximum distance from the player's cursor should check for a target, if TargetMode is
+	// set to protocol.AimAssistTargetModeDistance.
 	Distance float32
-	// TargetMode is the mode that the camera should use to aim at the target. This is currently one of
+	// TargetMode is the mode that the camera should use for detecting targets. This is currently one of
 	// protocol.AimAssistTargetModeAngle or protocol.AimAssistTargetModeDistance.
 	TargetMode byte
 	// Action is the action that should be performed with the aim assist. This is one of the constants above.
@@ -33,8 +33,8 @@ func (*CameraAimAssist) ID() uint32 {
 }
 
 func (pk *CameraAimAssist) Marshal(io protocol.IO) {
-	io.String(&pk.PresetID)
-	io.Vec2(&pk.ViewAngle)
+	io.String(&pk.Preset)
+	io.Vec2(&pk.Angle)
 	io.Float32(&pk.Distance)
 	io.Uint8(&pk.TargetMode)
 	io.Uint8(&pk.Action)

minecraft/protocol/packet/camera_aim_assist_presets.go

@@ -4,9 +4,13 @@ import (
 	"github.com/sandertv/gophertunnel/minecraft/protocol"
 )
 
+// CameraAimAssistPresets is sent by the server to the client to provide a list of categories and presets
+// that can be used when sending a CameraAimAssist packet or a CameraInstruction including aim assist.
 type CameraAimAssistPresets struct {
-	Categories []protocol.CameraAimAssistCategories
-	Presets    []protocol.CameraAimAssistPreset
+	// CategoryGroups is a list of groups of categories which can be referenced by one of the Presets.
+	CategoryGroups []protocol.CameraAimAssistCategoryGroup
+	// Presets is a list of presets which define a base for how aim assist should behave
+	Presets []protocol.CameraAimAssistPreset
 }
 
 // ID ...
@@ -15,6 +19,6 @@ func (*CameraAimAssistPresets) ID() uint32 {
 }
 
 func (pk *CameraAimAssistPresets) Marshal(io protocol.IO) {
-	protocol.Slice(io, &pk.Categories)
+	protocol.Slice(io, &pk.CategoryGroups)
 	protocol.Slice(io, &pk.Presets)
 }

minecraft/protocol/packet/camera_instruction.go

@@ -14,7 +14,7 @@ type CameraInstruction struct {
 	Fade protocol.Optional[protocol.CameraInstructionFade]
 	// Target is a camera instruction that targets a specific entity.
 	Target protocol.Optional[protocol.CameraInstructionTarget]
-	// RemoveTarget can be set to true to remove the current target entity.
+	// RemoveTarget can be set to true to remove the current aim assist target.
 	RemoveTarget protocol.Optional[bool]
 }