refactor(mhfpacket): rename 15 Unk fields with identified meanings

Replace unknown field names with descriptive names based on handler logic analysis, switch dispatch patterns, DB query context, and inline comments: - ObjectHandleID, IsQuest, ItemIDCount, MaxCount, TokenLength, FormatVersion, LogoutType (high confidence from comments/constants) - QueryType, DataType, MissionIndex, CheckOnly, RequestType, ExchangeType, TournamentID (confirmed by handler switch/if usage) Also fix MsgSysLogout.Build calling ReadUint8 instead of WriteUint8.
2026-03-22 07:32:32 +01:00 · 2026-02-18 21:48:08 +01:00
parent 2bd5f98f32
commit 0d07a1f698
35 changed files with 104 additions and 104 deletions
--- a/network/mhfpacket/mhfpacket_test.go
+++ b/network/mhfpacket/mhfpacket_test.go
@@ -564,8 +564,8 @@ func TestMsgSysEnterStageParse(t *testing.T) {
 			if pkt.AckHandle != tt.wantHandle {
 				t.Errorf("AckHandle = %d, want %d", pkt.AckHandle, tt.wantHandle)
 			}
-			if pkt.Unk != tt.wantUnk {
-				t.Errorf("Unk = %v, want %v", pkt.Unk, tt.wantUnk)
+			if pkt.IsQuest != tt.wantUnk {
+				t.Errorf("Unk = %v, want %v", pkt.IsQuest, tt.wantUnk)
 			}
 			if pkt.StageID != tt.wantStageID {
 				t.Errorf("StageID = %q, want %q", pkt.StageID, tt.wantStageID)
@@ -754,8 +754,8 @@ func TestMsgSysLogoutParse(t *testing.T) {
 				t.Fatalf("Parse() error = %v", err)
 			}

-			if pkt.Unk0 != tt.wantUnk0 {
-				t.Errorf("Unk0 = %d, want %d", pkt.Unk0, tt.wantUnk0)
+			if pkt.LogoutType != tt.wantUnk0 {
+				t.Errorf("Unk0 = %d, want %d", pkt.LogoutType, tt.wantUnk0)
 			}
 		})
 	}
--- a/network/mhfpacket/msg_batch_parse_test.go
+++ b/network/mhfpacket/msg_batch_parse_test.go
@@ -141,7 +141,7 @@ func TestBatchParseMultiField(t *testing.T) {
 		if err := pkt.Parse(bf, ctx); err != nil {
 			t.Fatal(err)
 		}
-		if pkt.AckHandle != 1 || pkt.DistType != 2 || pkt.Unk1 != 3 || pkt.Unk2 != 4 {
+		if pkt.AckHandle != 1 || pkt.DistType != 2 || pkt.Unk1 != 3 || pkt.MaxCount != 4 {
 			t.Error("field mismatch")
 		}
 	})
@@ -206,7 +206,7 @@ func TestBatchParseMultiField(t *testing.T) {
 		if err := pkt.Parse(bf, ctx); err != nil {
 			t.Fatal(err)
 		}
-		if pkt.AckHandle != 1 || pkt.Unk0 != 2 || pkt.WorldID != 3 || pkt.LandID != 4 || !pkt.Unk1 {
+		if pkt.AckHandle != 1 || pkt.Unk0 != 2 || pkt.WorldID != 3 || pkt.LandID != 4 || !pkt.CheckOnly {
 			t.Error("field mismatch")
 		}
 	})
@@ -316,7 +316,7 @@ func TestBatchParseMultiField(t *testing.T) {
 		if err := pkt.Parse(bf, ctx); err != nil {
 			t.Fatal(err)
 		}
-		if pkt.Unk2 != 4 {
+		if pkt.DataType != 4 {
 			t.Error("field mismatch")
 		}
 	})
@@ -433,7 +433,7 @@ func TestBatchParseMultiField(t *testing.T) {
 		if err := pkt.Parse(bf, ctx); err != nil {
 			t.Fatal(err)
 		}
-		if pkt.Unk0 != 2 {
+		if pkt.RequestType != 2 {
 			t.Error("field mismatch")
 		}
 	})
--- a/network/mhfpacket/msg_build_test.go
+++ b/network/mhfpacket/msg_build_test.go
@@ -359,7 +359,7 @@ func TestBuildParseUpdateObjectBinary(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			original := &MsgSysUpdateObjectBinary{
-				Unk0: tt.unk0,
+				ObjectHandleID: tt.unk0,
 				Unk1: tt.unk1,
 			}

@@ -374,8 +374,8 @@ func TestBuildParseUpdateObjectBinary(t *testing.T) {
 				t.Fatalf("Parse() error = %v", err)
 			}

-			if parsed.Unk0 != original.Unk0 {
-				t.Errorf("Unk0 = %d, want %d", parsed.Unk0, original.Unk0)
+			if parsed.ObjectHandleID != original.ObjectHandleID {
+				t.Errorf("Unk0 = %d, want %d", parsed.ObjectHandleID, original.ObjectHandleID)
 			}
 			if parsed.Unk1 != original.Unk1 {
 				t.Errorf("Unk1 = %d, want %d", parsed.Unk1, original.Unk1)
@@ -767,7 +767,7 @@ func TestBuildParseEnumerateDistItem(t *testing.T) {
 				AckHandle: tt.ackHandle,
 				DistType:  tt.distType,
 				Unk1:      tt.unk1,
-				Unk2:      tt.unk2,
+				MaxCount:      tt.unk2,
 			}

 			bf := byteframe.NewByteFrame()
@@ -775,7 +775,7 @@ func TestBuildParseEnumerateDistItem(t *testing.T) {
 			bf.WriteUint32(original.AckHandle)
 			bf.WriteUint8(original.DistType)
 			bf.WriteUint8(original.Unk1)
-			bf.WriteUint16(original.Unk2)
+			bf.WriteUint16(original.MaxCount)
 			bf.WriteUint8(0) // Unk3 length (for Z1+ client mode)

 			_, _ = bf.Seek(0, io.SeekStart)
@@ -793,8 +793,8 @@ func TestBuildParseEnumerateDistItem(t *testing.T) {
 			if parsed.Unk1 != original.Unk1 {
 				t.Errorf("Unk1 = %d, want %d", parsed.Unk1, original.Unk1)
 			}
-			if parsed.Unk2 != original.Unk2 {
-				t.Errorf("Unk2 = %d, want %d", parsed.Unk2, original.Unk2)
+			if parsed.MaxCount != original.MaxCount {
+				t.Errorf("Unk2 = %d, want %d", parsed.MaxCount, original.MaxCount)
 			}
 		})
 	}
--- a/network/mhfpacket/msg_mhf_acquire_ud_item.go
+++ b/network/mhfpacket/msg_mhf_acquire_ud_item.go
@@ -23,8 +23,8 @@ type MsgMhfAcquireUdItem struct {
  // personal achievement = 6
  // guild achievement = 7
  RewardType uint8
-  Unk2 uint8 // Number of uint32s to read?
-	Unk3 []byte
+  ItemIDCount uint8
+	Unk3        []byte
 }

 // Opcode returns the ID associated with this packet type.
@@ -37,8 +37,8 @@ func (m *MsgMhfAcquireUdItem) Parse(bf *byteframe.ByteFrame, ctx *clientctx.Clie
  m.AckHandle = bf.ReadUint32()
 	m.Unk0 = bf.ReadUint8()
 	m.RewardType = bf.ReadUint8()
-  m.Unk2 = bf.ReadUint8()
-  for i := uint8(0); i < m.Unk2; i++ {
+  m.ItemIDCount = bf.ReadUint8()
+  for i := uint8(0); i < m.ItemIDCount; i++ {
    bf.ReadUint32()
  }
 	return nil
--- a/network/mhfpacket/msg_mhf_enumerate_dist_item.go
+++ b/network/mhfpacket/msg_mhf_enumerate_dist_item.go
@@ -13,7 +13,7 @@ type MsgMhfEnumerateDistItem struct {
 	AckHandle uint32
 	DistType  uint8
 	Unk1      uint8
-	Unk2      uint16
+	MaxCount  uint16
 	Unk3      []byte
 }

@@ -27,7 +27,7 @@ func (m *MsgMhfEnumerateDistItem) Parse(bf *byteframe.ByteFrame, ctx *clientctx.
 	m.AckHandle = bf.ReadUint32()
 	m.DistType = bf.ReadUint8()
 	m.Unk1 = bf.ReadUint8()
-	m.Unk2 = bf.ReadUint16() // Maximum? Hardcoded to 256
+	m.MaxCount = bf.ReadUint16() // Hardcoded to 256
 	if _config.ErupeConfig.RealClientMode >= _config.Z1 {
 		m.Unk3 = bf.ReadBytes(uint(bf.ReadUint8()))
 	}
--- a/network/mhfpacket/msg_mhf_exchange_weekly_stamp.go
+++ b/network/mhfpacket/msg_mhf_exchange_weekly_stamp.go
@@ -12,7 +12,7 @@ import (
 type MsgMhfExchangeWeeklyStamp struct {
 	AckHandle uint32
 	StampType string
-	Unk1      uint8
+	ExchangeType uint8
 }

 // Opcode returns the ID associated with this packet type.
@@ -30,7 +30,7 @@ func (m *MsgMhfExchangeWeeklyStamp) Parse(bf *byteframe.ByteFrame, ctx *clientct
 	case 2:
 		m.StampType = "ex"
 	}
-	m.Unk1 = bf.ReadUint8()
+	m.ExchangeType = bf.ReadUint8()
 	bf.ReadUint16() // Zeroed
 	return nil
 }
--- a/network/mhfpacket/msg_mhf_get_gem_info.go
+++ b/network/mhfpacket/msg_mhf_get_gem_info.go
@@ -11,7 +11,7 @@ import (
 // MsgMhfGetGemInfo represents the MSG_MHF_GET_GEM_INFO
 type MsgMhfGetGemInfo struct {
 	AckHandle uint32
-	Unk0      uint32
+	QueryType uint32
 	Unk1      uint32
 	Unk2      int32
 	Unk3      int32
@@ -28,7 +28,7 @@ func (m *MsgMhfGetGemInfo) Opcode() network.PacketID {
 // Parse parses the packet from binary
 func (m *MsgMhfGetGemInfo) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
-	m.Unk0 = bf.ReadUint32()
+	m.QueryType = bf.ReadUint32()
 	m.Unk1 = bf.ReadUint32()
 	m.Unk2 = bf.ReadInt32()
 	m.Unk3 = bf.ReadInt32()
--- a/network/mhfpacket/msg_mhf_get_paper_data.go
+++ b/network/mhfpacket/msg_mhf_get_paper_data.go
@@ -12,9 +12,9 @@ import (
 type MsgMhfGetPaperData struct {
 	// Communicator type, multi-format. This might be valid for only one type.
 	AckHandle uint32
-	Unk0      uint32
-	Unk1      uint32
-	Unk2      uint32
+	Unk0     uint32
+	Unk1     uint32
+	DataType uint32
 }

 // Opcode returns the ID associated with this packet type.
@@ -27,7 +27,7 @@ func (m *MsgMhfGetPaperData) Parse(bf *byteframe.ByteFrame, ctx *clientctx.Clien
 	m.AckHandle = bf.ReadUint32()
 	m.Unk0 = bf.ReadUint32()
 	m.Unk1 = bf.ReadUint32()
-	m.Unk2 = bf.ReadUint32()
+	m.DataType = bf.ReadUint32()
 	return nil
 }

--- a/network/mhfpacket/msg_mhf_get_tenrouirai.go
+++ b/network/mhfpacket/msg_mhf_get_tenrouirai.go
@@ -11,11 +11,11 @@ import (
 // MsgMhfGetTenrouirai represents the MSG_MHF_GET_TENROUIRAI
 type MsgMhfGetTenrouirai struct {
 	AckHandle uint32
-	Unk0      uint8
-	Unk1      uint8
-	GuildID   uint32
-	Unk3      uint8
-	Unk4      uint8
+	Unk0         uint8
+	DataType     uint8
+	GuildID      uint32
+	MissionIndex uint8
+	Unk4         uint8
 }

 // Opcode returns the ID associated with this packet type.
@@ -27,9 +27,9 @@ func (m *MsgMhfGetTenrouirai) Opcode() network.PacketID {
 func (m *MsgMhfGetTenrouirai) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
 	m.Unk0 = bf.ReadUint8()
-	m.Unk1 = bf.ReadUint8()
+	m.DataType = bf.ReadUint8()
 	m.GuildID = bf.ReadUint32()
-	m.Unk3 = bf.ReadUint8()
+	m.MissionIndex = bf.ReadUint8()
 	m.Unk4 = bf.ReadUint8()
 	return nil
 }
--- a/network/mhfpacket/msg_mhf_info_tournament.go
+++ b/network/mhfpacket/msg_mhf_info_tournament.go
@@ -11,8 +11,8 @@ import (
 // MsgMhfInfoTournament represents the MSG_MHF_INFO_TOURNAMENT
 type MsgMhfInfoTournament struct {
 	AckHandle uint32
-	Unk0      uint8
-	Unk1      uint32
+	QueryType    uint8
+	TournamentID uint32
 }

 // Opcode returns the ID associated with this packet type.
@@ -23,8 +23,8 @@ func (m *MsgMhfInfoTournament) Opcode() network.PacketID {
 // Parse parses the packet from binary
 func (m *MsgMhfInfoTournament) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
-	m.Unk0 = bf.ReadUint8()
-	m.Unk1 = bf.ReadUint32()
+	m.QueryType = bf.ReadUint8()
+	m.TournamentID = bf.ReadUint32()
 	return nil
 }

--- a/network/mhfpacket/msg_mhf_mercenary_huntdata.go
+++ b/network/mhfpacket/msg_mhf_mercenary_huntdata.go
@@ -11,7 +11,7 @@ import (
 // MsgMhfMercenaryHuntdata represents the MSG_MHF_MERCENARY_HUNTDATA
 type MsgMhfMercenaryHuntdata struct {
 	AckHandle uint32
-	Unk0      uint8
+	RequestType uint8
 }

 // Opcode returns the ID associated with this packet type.
@@ -22,7 +22,7 @@ func (m *MsgMhfMercenaryHuntdata) Opcode() network.PacketID {
 // Parse parses the packet from binary
 func (m *MsgMhfMercenaryHuntdata) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
-	m.Unk0 = bf.ReadUint8()
+	m.RequestType = bf.ReadUint8()
 	return nil
 }

--- a/network/mhfpacket/msg_mhf_register_event.go
+++ b/network/mhfpacket/msg_mhf_register_event.go
@@ -12,7 +12,7 @@ type MsgMhfRegisterEvent struct {
 	Unk0      uint16
 	WorldID   uint16
 	LandID    uint16
-	Unk1      bool
+	CheckOnly bool
 }

 // Opcode returns the ID associated with this packet type.
@@ -26,7 +26,7 @@ func (m *MsgMhfRegisterEvent) Parse(bf *byteframe.ByteFrame, ctx *clientctx.Clie
 	m.Unk0 = bf.ReadUint16()
 	m.WorldID = bf.ReadUint16()
 	m.LandID = bf.ReadUint16()
-	m.Unk1 = bf.ReadBool()
+	m.CheckOnly = bf.ReadBool()
 	bf.ReadUint8() // Zeroed
 	return nil
 }
--- a/network/mhfpacket/msg_mhf_set_enhanced_minidata.go
+++ b/network/mhfpacket/msg_mhf_set_enhanced_minidata.go
@@ -11,7 +11,7 @@ import (
 // MsgMhfSetEnhancedMinidata represents the MSG_MHF_SET_ENHANCED_MINIDATA
 type MsgMhfSetEnhancedMinidata struct {
 	AckHandle      uint32
-	Unk0           uint16 // Hardcoded 4 in the binary.
+	FormatVersion  uint16 // Hardcoded 4 in the binary.
 	RawDataPayload []byte
 }

@@ -23,7 +23,7 @@ func (m *MsgMhfSetEnhancedMinidata) Opcode() network.PacketID {
 // Parse parses the packet from binary
 func (m *MsgMhfSetEnhancedMinidata) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
-	m.Unk0 = bf.ReadUint16()
+	m.FormatVersion = bf.ReadUint16()
 	m.RawDataPayload = bf.ReadBytes(0x400)
 	return nil
 }
--- a/network/mhfpacket/msg_parse_coverage_test.go
+++ b/network/mhfpacket/msg_parse_coverage_test.go
@@ -298,7 +298,7 @@ func TestBuildCoverage_Implemented(t *testing.T) {
 		defer func() {
 			_ = recover() // may panic due to bug
 		}()
-		pkt := &MsgSysLogout{Unk0: 1}
+		pkt := &MsgSysLogout{LogoutType: 1}
 		bf := byteframe.NewByteFrame()
 		_ = pkt.Build(bf, ctx)
 	})
--- a/network/mhfpacket/msg_parse_large_test.go
+++ b/network/mhfpacket/msg_parse_large_test.go
@@ -16,7 +16,7 @@ func TestParseLargeMsgSysUpdateRightBuild(t *testing.T) {
 		ClientRespAckHandle: 0x12345678,
 		Bitfield:            0xDEADBEEF,
 		Rights:              nil,
-		UnkSize:             0,
+		TokenLength:             0,
 	}

 	bf := byteframe.NewByteFrame()
--- a/network/mhfpacket/msg_parse_small_test.go
+++ b/network/mhfpacket/msg_parse_small_test.go
@@ -123,8 +123,8 @@ func TestParseSmallLogout(t *testing.T) {
 			if err != nil {
 				t.Fatalf("Parse() error = %v", err)
 			}
-			if pkt.Unk0 != tt.unk0 {
-				t.Errorf("Unk0 = %d, want %d", pkt.Unk0, tt.unk0)
+			if pkt.LogoutType != tt.unk0 {
+				t.Errorf("Unk0 = %d, want %d", pkt.LogoutType, tt.unk0)
 			}
 		})
 	}
--- a/network/mhfpacket/msg_parse_test.go
+++ b/network/mhfpacket/msg_parse_test.go
@@ -124,8 +124,8 @@ func TestMsgSysLogoutDetailedParse(t *testing.T) {
 			t.Fatalf("Parse() error = %v", err)
 		}

-		if pkt.Unk0 != tt.unk0 {
-			t.Errorf("Unk0 = %d, want %d", pkt.Unk0, tt.unk0)
+		if pkt.LogoutType != tt.unk0 {
+			t.Errorf("Unk0 = %d, want %d", pkt.LogoutType, tt.unk0)
 		}
 	}
 }
--- a/network/mhfpacket/msg_sys_enter_stage.go
+++ b/network/mhfpacket/msg_sys_enter_stage.go
@@ -11,7 +11,7 @@ import (
 // MsgSysEnterStage represents the MSG_SYS_ENTER_STAGE
 type MsgSysEnterStage struct {
 	AckHandle uint32
-	Unk       bool
+	IsQuest   bool
 	StageID   string
 }

@@ -23,7 +23,7 @@ func (m *MsgSysEnterStage) Opcode() network.PacketID {
 // Parse parses the packet from binary
 func (m *MsgSysEnterStage) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
 	m.AckHandle = bf.ReadUint32()
-	m.Unk = bf.ReadBool() // IsQuest?
+	m.IsQuest = bf.ReadBool()
 	bf.ReadUint8()        // Length StageID
 	m.StageID = string(bf.ReadNullTerminatedBytes())
 	return nil
--- a/network/mhfpacket/msg_sys_logout.go
+++ b/network/mhfpacket/msg_sys_logout.go
@@ -8,7 +8,7 @@ import (

 // MsgSysLogout represents the MSG_SYS_LOGOUT
 type MsgSysLogout struct {
-	Unk0 uint8 // Hardcoded 1 in binary
+	LogoutType uint8 // Hardcoded 1 in binary
 }

 // Opcode returns the ID associated with this packet type.
@@ -18,12 +18,12 @@ func (m *MsgSysLogout) Opcode() network.PacketID {

 // Parse parses the packet from binary
 func (m *MsgSysLogout) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
-	m.Unk0 = bf.ReadUint8()
+	m.LogoutType = bf.ReadUint8()
 	return nil
 }

 // Build builds a binary packet from the current data.
 func (m *MsgSysLogout) Build(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
-	m.Unk0 = bf.ReadUint8()
+	bf.WriteUint8(m.LogoutType)
 	return nil
 }
--- a/network/mhfpacket/msg_sys_stage_test.go
+++ b/network/mhfpacket/msg_sys_stage_test.go
@@ -110,8 +110,8 @@ func TestMsgSysEnterStageFields(t *testing.T) {
 			if pkt.AckHandle != tt.handle {
 				t.Errorf("AckHandle = %d, want %d", pkt.AckHandle, tt.handle)
 			}
-			if pkt.Unk != tt.unk {
-				t.Errorf("Unk = %v, want %v", pkt.Unk, tt.unk)
+			if pkt.IsQuest != tt.unk {
+				t.Errorf("Unk = %v, want %v", pkt.IsQuest, tt.unk)
 			}
 			if pkt.StageID != tt.stageID {
 				t.Errorf("StageID = %q, want %q", pkt.StageID, tt.stageID)
--- a/network/mhfpacket/msg_sys_update_object_binary.go
+++ b/network/mhfpacket/msg_sys_update_object_binary.go
@@ -8,8 +8,8 @@ import (

 // MsgSysUpdateObjectBinary represents the MSG_SYS_UPDATE_OBJECT_BINARY
 type MsgSysUpdateObjectBinary struct {
-	Unk0 uint32 // Object handle ID
-	Unk1 uint32
+	ObjectHandleID uint32
+	Unk1           uint32
 }

 // Opcode returns the ID associated with this packet type.
@@ -19,14 +19,14 @@ func (m *MsgSysUpdateObjectBinary) Opcode() network.PacketID {

 // Parse parses the packet from binary
 func (m *MsgSysUpdateObjectBinary) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
-	m.Unk0 = bf.ReadUint32()
+	m.ObjectHandleID = bf.ReadUint32()
 	m.Unk1 = bf.ReadUint32()
 	return nil
 }

 // Build builds a binary packet from the current data.
 func (m *MsgSysUpdateObjectBinary) Build(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
-	bf.WriteUint32(m.Unk0)
+	bf.WriteUint32(m.ObjectHandleID)
 	bf.WriteUint32(m.Unk1)
 	return nil
 }
--- a/network/mhfpacket/msg_sys_update_right.go
+++ b/network/mhfpacket/msg_sys_update_right.go
@@ -14,7 +14,7 @@ type MsgSysUpdateRight struct {
 	ClientRespAckHandle uint32 // If non-0, requests the client to send back a MSG_SYS_ACK packet with this value.
 	Bitfield            uint32
 	Rights              []mhfcourse.Course
-	UnkSize             uint16 // Count of some buf up to 0x800 bytes following it.
+	TokenLength         uint16 // Length of the login token/password buffer (up to 0x800 bytes).
 }

 // Opcode returns the ID associated with this packet type.