package model import "time" // Town represents a fixed settlement along the hero's travel road. type Town struct { ID int64 `json:"id"` Name string `json:"name"` Biome string `json:"biome"` WorldX float64 `json:"worldX"` WorldY float64 `json:"worldY"` Radius float64 `json:"radius"` LevelMin int `json:"levelMin"` LevelMax int `json:"levelMax"` } // NPC represents a non-hostile character living in a town. type NPC struct { ID int64 `json:"id"` TownID int64 `json:"townId"` Name string `json:"name"` Type string `json:"type"` // quest_giver, merchant, healer OffsetX float64 `json:"offsetX"` OffsetY float64 `json:"offsetY"` } // Quest is a template definition offered by a quest-giver NPC. type Quest struct { ID int64 `json:"id"` NPCID int64 `json:"npcId"` Title string `json:"title"` Description string `json:"description"` Type string `json:"type"` // kill_count, visit_town, collect_item TargetCount int `json:"targetCount"` TargetEnemyType *string `json:"targetEnemyType"` // NULL = any enemy TargetTownID *int64 `json:"targetTownId"` // for visit_town quests DropChance float64 `json:"dropChance"` // for collect_item MinLevel int `json:"minLevel"` MaxLevel int `json:"maxLevel"` RewardXP int64 `json:"rewardXp"` RewardGold int64 `json:"rewardGold"` RewardPotions int `json:"rewardPotions"` } // HeroQuest tracks a hero's progress on an accepted quest. type HeroQuest struct { ID int64 `json:"id"` HeroID int64 `json:"heroId"` QuestID int64 `json:"questId"` Status string `json:"status"` // accepted, completed, claimed Progress int `json:"progress"` AcceptedAt time.Time `json:"acceptedAt"` CompletedAt *time.Time `json:"completedAt,omitempty"` ClaimedAt *time.Time `json:"claimedAt,omitempty"` Quest *Quest `json:"quest,omitempty"` // populated on list } // QuestReward holds the rewards granted when a quest is claimed. type QuestReward struct { XP int64 `json:"xp"` Gold int64 `json:"gold"` Potions int `json:"potions"` } // TownWithNPCs is a Town annotated with its NPC residents and computed world positions. type TownWithNPCs struct { ID int64 `json:"id"` Name string `json:"name"` Biome string `json:"biome"` WorldX float64 `json:"worldX"` WorldY float64 `json:"worldY"` Radius float64 `json:"radius"` Size string `json:"size"` // S, M, L derived from radius NPCs []NPCView `json:"npcs"` } // NPCView is the frontend-friendly view of an NPC with absolute world coordinates. type NPCView struct { ID int64 `json:"id"` Name string `json:"name"` Type string `json:"type"` WorldX float64 `json:"worldX"` WorldY float64 `json:"worldY"` } // TownSizeFromRadius derives a size label from the town radius. func TownSizeFromRadius(radius float64) string { switch { case radius >= 17: return "L" case radius >= 14: return "M" default: return "S" } } // NPCInteractAction represents a single action the player can take with an NPC. type NPCInteractAction struct { ActionType string `json:"actionType"` // "quest", "shop_item", "heal" QuestID int64 `json:"questId,omitempty"` // for quest_giver QuestTitle string `json:"questTitle,omitempty"` // for quest_giver ItemName string `json:"itemName,omitempty"` // for merchant ItemCost int64 `json:"itemCost,omitempty"` // for merchant / healer Description string `json:"description,omitempty"` } // NPCInteractResponse is the response for POST /api/v1/hero/npc-interact. type NPCInteractResponse struct { NPCName string `json:"npcName"` NPCType string `json:"npcType"` TownName string `json:"townName"` Actions []NPCInteractAction `json:"actions"` } // NearbyNPCEntry is returned by the nearby-npcs endpoint. type NearbyNPCEntry struct { ID int64 `json:"id"` Name string `json:"name"` Type string `json:"type"` WorldX float64 `json:"worldX"` WorldY float64 `json:"worldY"` InteractionAvailable bool `json:"interactionAvailable"` } // NPCEventResponse is returned when a random NPC event occurs instead of an enemy encounter. type NPCEventResponse struct { Type string `json:"type"` // "npc_event" NPC NPCEventNPC `json:"npc"` Cost int64 `json:"cost"` Reward string `json:"reward"` // e.g. "random_equipment" } // NPCEventNPC describes the wandering NPC in a random event. type NPCEventNPC struct { Name string `json:"name"` Role string `json:"role"` } // AlmsResponse is the response for POST /api/v1/hero/npc-alms. type AlmsResponse struct { Accepted bool `json:"accepted"` GoldSpent int64 `json:"goldSpent,omitempty"` ItemDrop *LootDrop `json:"itemDrop,omitempty"` Hero interface{} `json:"hero,omitempty"` Message string `json:"message"` }