doc: inline code documentation.

network/mhfpacket/mhfpacket.go

@@ -1,3 +1,50 @@
+// Package mhfpacket provides Monster Hunter Frontier packet definitions and interfaces.
+//
+// This package contains:
+//   - MHFPacket interface: The common interface all packets implement
+//   - 400+ packet type definitions in msg_*.go files
+//   - Packet parsing (client -> server) and building (server -> client) logic
+//   - Opcode-to-packet-type mapping via FromOpcode()
+//
+// Packet Structure:
+//
+// MHF packets follow this wire format:
+//   [2 bytes: Opcode][N bytes: Packet-specific data][2 bytes: Footer 0x00 0x10]
+//
+// Each packet type defines its own structure matching the binary format expected
+// by the Monster Hunter Frontier client.
+//
+// Implementing a New Packet:
+//
+//  1. Create msg_mhf_your_packet.go with packet struct
+//  2. Implement Parse() to read data from ByteFrame
+//  3. Implement Build() to write data to ByteFrame
+//  4. Implement Opcode() to return the packet's ID
+//  5. Register in opcodeToPacketMap in opcode_mapping.go
+//  6. Add handler in server/channelserver/handlers_table.go
+//
+// Example:
+//
+//	type MsgMhfYourPacket struct {
+//	    AckHandle uint32 // Common field for request/response matching
+//	    SomeField uint16
+//	}
+//
+//	func (m *MsgMhfYourPacket) Opcode() network.PacketID {
+//	    return network.MSG_MHF_YOUR_PACKET
+//	}
+//
+//	func (m *MsgMhfYourPacket) Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
+//	    m.AckHandle = bf.ReadUint32()
+//	    m.SomeField = bf.ReadUint16()
+//	    return nil
+//	}
+//
+//	func (m *MsgMhfYourPacket) Build(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error {
+//	    bf.WriteUint32(m.AckHandle)
+//	    bf.WriteUint16(m.SomeField)
+//	    return nil
+//	}
 package mhfpacket
 
 import (
@@ -6,22 +53,52 @@ import (
 	"erupe-ce/network/clientctx"
 )
 
-// Parser is the interface that wraps the Parse method.
+// Parser is the interface for deserializing packets from wire format.
+//
+// The Parse method reads packet data from a ByteFrame (binary stream) and
+// populates the packet struct's fields. It's called when a packet arrives
+// from the client.
+//
+// Parameters:
+//   - bf: ByteFrame positioned after the opcode (contains packet payload)
+//   - ctx: Client context (version info, capabilities) for version-specific parsing
+//
+// Returns an error if the packet data is malformed or incomplete.
 type Parser interface {
 	Parse(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error
 }
 
-// Builder is the interface that wraps the Build method.
+// Builder is the interface for serializing packets to wire format.
+//
+// The Build method writes the packet struct's fields to a ByteFrame (binary stream)
+// in the format expected by the client. It's called when sending a packet to the client.
+//
+// Parameters:
+//   - bf: ByteFrame to write packet data to (opcode already written by caller)
+//   - ctx: Client context (version info, capabilities) for version-specific building
+//
+// Returns an error if serialization fails.
 type Builder interface {
 	Build(bf *byteframe.ByteFrame, ctx *clientctx.ClientContext) error
 }
 
-// Opcoder is the interface that wraps the Opcode method.
+// Opcoder is the interface for identifying a packet's opcode.
+//
+// The Opcode method returns the unique packet identifier used for routing
+// packets to their handlers and for packet logging/debugging.
 type Opcoder interface {
 	Opcode() network.PacketID
 }
 
-// MHFPacket is the interface that groups the Parse, Build, and Opcode methods.
+// MHFPacket is the unified interface that all Monster Hunter Frontier packets implement.
+//
+// Every packet type must be able to:
+//   - Parse itself from binary data (Parser)
+//   - Build itself into binary data (Builder)
+//   - Identify its opcode (Opcoder)
+//
+// This interface allows the packet handling system to work generically across
+// all packet types while maintaining type safety through type assertions in handlers.
 type MHFPacket interface {
 	Parser
 	Builder

network/mhfpacket/msg_mhf_enumerate_quest.go

@@ -8,14 +8,34 @@ import (
 	"erupe-ce/network/clientctx"
 )
 
-// MsgMhfEnumerateQuest represents the MSG_MHF_ENUMERATE_QUEST
+// MsgMhfEnumerateQuest is sent by the client to request a paginated list of available quests.
+//
+// This packet is used when:
+//   - Accessing the quest counter/board in town
+//   - Scrolling through quest lists
+//   - Switching between quest categories/worlds
+//
+// The server responds with quest metadata and binary file paths. The client then
+// loads quest details from binary files on disk or via MSG_SYS_GET_FILE.
+//
+// Pagination:
+// Quest lists can be very large (hundreds of quests). The client requests quests
+// in batches using the Offset field:
+//   - Offset 0: First batch (quests 0-N)
+//   - Offset N: Next batch (quests N-2N)
+//   - Continues until server returns no more quests
+//
+// World Types:
+//   - 0: Newbie World (beginner quests)
+//   - 1: Normal World (standard quests)
+//   - 2+: Other world categories (events, special quests)
 type MsgMhfEnumerateQuest struct {
-	AckHandle uint32
-	Unk0      uint8 // Hardcoded 0 in the binary
-	World     uint8
-	Counter   uint16
-	Offset    uint16 // Increments to request following batches of quests
-	Unk4      uint8  // Hardcoded 0 in the binary
+	AckHandle uint32 // Response handle for matching server response to request
+	Unk0      uint8  // Hardcoded 0 in the binary (purpose unknown)
+	World     uint8  // World ID/category to enumerate quests for
+	Counter   uint16 // Client counter for tracking sequential requests
+	Offset    uint16 // Pagination offset - increments by batch size for next page
+	Unk4      uint8  // Hardcoded 0 in the binary (purpose unknown)
 }
 
 // Opcode returns the ID associated with this packet type.

network/mhfpacket/msg_sys_enter_stage.go

@@ -9,11 +9,29 @@ import (
 	"erupe-ce/network/clientctx"
 )
 
-// MsgSysEnterStage represents the MSG_SYS_ENTER_STAGE
+// MsgSysEnterStage is sent by the client to enter an existing stage.
+//
+// This packet is used when:
+//   - Moving from one town area to another (e.g., Mezeporta -> Pallone)
+//   - Joining another player's room or quest
+//   - Entering a persistent stage that already exists
+//
+// The stage must already exist on the server. For creating new stages (quests, rooms),
+// use MSG_SYS_CREATE_STAGE followed by MSG_SYS_ENTER_STAGE.
+//
+// Stage ID Format:
+// Stage IDs are encoded strings like "sl1Ns200p0a0u0" that identify specific
+// game areas:
+//   - sl1Ns200p0a0u0: Mezeporta (main town)
+//   - sl1Ns211p0a0u0: Rasta bar
+//   - Quest stages: Dynamic IDs created when quests start
+//
+// After entering, the session's stage pointer is updated and the player receives
+// broadcasts from other players in that stage.
 type MsgSysEnterStage struct {
-	AckHandle uint32
-	UnkBool   uint8
-	StageID   string
+	AckHandle uint32 // Response handle for acknowledgment
+	UnkBool   uint8  // Boolean flag (purpose unknown, possibly force-enter)
+	StageID   string // ID of the stage to enter (length-prefixed string)
 }
 
 // Opcode returns the ID associated with this packet type.