【python】文字版农场游戏 —— 架构设计文档

🏗️ 文字版农场游戏 —— 架构设计文档

基于《农场文字版策划案.md》的软件架构设计
目标语言：Python 3.10+ | 运行模式：终端 CLI | 存储：JSON 本地持久化

运行游戏

基本集成了土地，播种，浇水，售后，商店等功能，随时间而收获

一、整体架构概览

┌─────────────────────────────────────────────────────┐ │ main.py │ │ (游戏入口 / 主循环) │ └──────────┬──────────────────────────────┬───────────┘ │ │ ┌──────▼──────┐ ┌───────▼──────────┐ │ Game │ │ MenuManager │ │ (游戏核心) │◄────────────►│ (选单导航引擎) │ └──┬──┬──┬──┬─┘ └──────────────────┘ │ │ │ │ ┌────┘ │ │ └──────┐ ▼ ▼ ▼ ▼ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐ │ Land │ │ Crop │ │ Econ │ │ Inventory│ │ System│ │System│ │System│ │(背包/装饰)│ └───────┘ └──────┘ └──────┘ └──────────┘ ┌──────────┐ │ SaveLoad │ │ (数据持久化)│ └──────────┘

二、目录结构

farm_game/ ├── main.py # 程序入口，启动游戏 ├── game.py # Game 类 —— 游戏核心状态与主循环 ├── menu.py # MenuManager —— 选单导航与渲染 │ ├── systems/ │ ├── __init__.py │ ├── land.py # LandSystem —— 地块管理 │ ├── crop.py # CropSystem —— 作物数据与生长逻辑 │ ├── economy.py # EconomySystem —— 金币/经验/等级 │ ├── store.py # StoreSystem —— 商店购买逻辑 │ ├── inventory.py # InventorySystem —— 背包与装饰 │ └── achievement.py # AchievementSystem —— 成就/签到 │ ├── data/ │ └── crops.json # 作物静态数据表 │ ├── save/ │ └── (运行时生成) # save_*.json 存档文件 │ └── utils/ ├── __init__.py ├── display.py # 格式化输出（表格、颜色、图标） └── time_helper.py # 时间工具（倒计时、时间戳转换）

三、核心类设计

1.Game—— 游戏核心

┌─────────────────────────────────────────────┐ │ Game │ ├─────────────────────────────────────────────┤ │ - player_data: dict │ │ - land_system: LandSystem │ │ - crop_system: CropSystem │ │ - economy: EconomySystem │ │ - store: StoreSystem │ │ - inventory: InventorySystem │ │ - achievement: AchievementSystem │ │ - menu: MenuManager │ ├─────────────────────────────────────────────┤ │ + new_game() │ │ + load_game(save_id) │ │ + save_game() │ │ + main_loop() │ │ + tick() # 检查成熟/枯萎状态 │ │ + get_overview() # 主界面概况文本 │ └─────────────────────────────────────────────┘

• Game是唯一的状态持有者，所有子系统通过它访问共享数据。
• main_loop()驱动「显示菜单 → 等待输入 → 分发动作 → 刷新状态」循环。
• tick()在每次操作前调用，检查所有地块的成熟/枯萎状态。

2.LandSystem—— 地块管理

┌─────────────────────────────────────────────┐ │ LandSystem │ ├─────────────────────────────────────────────┤ │ - lands: list[dict] # 地块数组 │ │ # 每块: { id, status, crop_id, │ │ # plant_time, water_count } │ │ - max_lands: int │ ├─────────────────────────────────────────────┤ │ + get_land(land_id) -> dict │ │ + get_lands_by_status(status) -> list │ │ + plant(land_id, crop_id) -> bool │ │ + harvest(land_id) -> dict # 收益 │ │ + water(land_id) -> bool │ │ + fertilize(land_id) -> bool │ │ + till(land_id) -> bool # 翻地 │ │ + unlock_lands(count) -> bool │ │ + update_all(timestamp) # 更新生长状态 │ └─────────────────────────────────────────────┘

地块状态机：

┌──────────┐ 播种 ┌──────────┐ 时间到 ┌──────────┐ │ 空地 │ ──────► │ 生长中 │ ────────► │ 成熟 │ │ (闲置) │ │ (倒计时) │ │ (可收获) │ └──────────┘ └──────────┘ └────┬─────┘ ▲ │ 30min未收 │ 翻地 ▼ │ ┌──────────┐ └────────────────────────────────────── │ 枯萎 │ │ (需翻地) │ └──────────┘

3.CropSystem—— 作物数据

┌─────────────────────────────────────────────┐ │ CropSystem │ ├─────────────────────────────────────────────┤ │ - crops_db: dict[str, CropData] │ │ # crop_id -> { name, price, mature_time, │ │ # sell_price, exp, level_req }│ ├─────────────────────────────────────────────┤ │ + get_crop(crop_id) -> CropData │ │ + get_available_crops(level) -> list │ │ + get_mature_seconds(crop_id, planted_at) │ │ -> int # 剩余秒数 │ │ + load_from_json(path) │ └─────────────────────────────────────────────┘

CropData可定义为dataclass：

@dataclassclassCropData:crop_id:strname:strseed_price:intmature_seconds:int# 成熟所需秒数sell_price:intexp:intlevel_required:int

4.EconomySystem—— 经济与等级

┌─────────────────────────────────────────────┐ │ EconomySystem │ ├─────────────────────────────────────────────┤ │ - gold: int │ │ - exp: int │ │ - level: int │ ├─────────────────────────────────────────────┤ │ + add_gold(amount) │ │ + spend_gold(amount) -> bool │ │ + add_exp(amount) │ │ + get_level() -> int │ │ + get_exp_to_next_level() -> int │ │ - _calculate_level(exp) -> int │ └─────────────────────────────────────────────┘

等级公式（示例）：

下一级所需总经验 = 100 × level²

5.StoreSystem—— 商店

┌─────────────────────────────────────────────┐ │ StoreSystem │ ├─────────────────────────────────────────────┤ │ (依赖 CropSystem 和 EconomySystem) │ ├─────────────────────────────────────────────┤ │ + buy_seed(crop_id) -> bool │ │ + get_store_list(level) -> list │ │ + buy_decoration(item_id) -> bool │ └─────────────────────────────────────────────┘

6.InventorySystem—— 背包与装饰

┌─────────────────────────────────────────────┐ │ InventorySystem │ ├─────────────────────────────────────────────┤ │ - decorations: list[str] # 已购装饰 ID │ │ - seeds: dict[str, int] # 种子库存 │ ├─────────────────────────────────────────────┤ │ + add_seed(crop_id, count) │ │ + use_seed(crop_id) -> bool │ │ + add_decoration(item_id) │ │ + get_active_decoration_text() -> str │ └─────────────────────────────────────────────┘

7.AchievementSystem—— 成就与签到

┌─────────────────────────────────────────────┐ │ AchievementSystem │ ├─────────────────────────────────────────────┤ │ - achievements: dict[str, bool] │ │ - total_harvests: int │ │ - planted_set: set[str] │ │ - sign_in_days: int │ │ - last_sign_in: str / None │ ├─────────────────────────────────────────────┤ │ + check_achievements() -> list[str] # 新成就│ │ + record_harvest(crop_id) │ │ + sign_in() -> dict # 签到奖励 │ │ + get_achievement_list() -> list │ └─────────────────────────────────────────────┘

8.MenuManager—— 选单导航引擎

┌─────────────────────────────────────────────┐ │ MenuManager │ ├─────────────────────────────────────────────┤ │ - game: Game (反向引用) │ ├─────────────────────────────────────────────┤ │ + show_main_menu() │ │ + show_farm_view() │ │ + show_store() │ │ + show_plant_menu() │ │ + show_harvest_menu() │ │ + show_water_menu() │ │ + show_till_menu() │ │ + show_inventory() │ │ + show_achievements() │ │ + show_decoration_shop() │ │ - _get_input(prompt) -> int │ │ - _wait_return() │ └─────────────────────────────────────────────┘

• 每个show_xxx()方法对应策划案中的一个选单界面。
• 方法内部：打印界面 → 读取数字输入 → 调用game对应方法 → 回到主菜单。
• 选单之间不嵌套调用，全部归流到main_loop()。

四、数据存储设计 (JSON Schema)

存档文件save_001.json

{"version":1,"player":{"name":"玩家","gold":520,"exp":350,"level":3},"lands":[{"id":1,"status":"growing","crop_id":"carrot","plant_time":1719715200.0,"water_count":0},{"id":2,"status":"mature","crop_id":"strawberry","plant_time":1719714000.0,"water_count":1}],"inventory":{"seeds":{"carrot":5,"potato":2},"decorations":[]},"achievements":{"first_harvest":true,"total_harvests":12,"planted_crops":["carrot","potato"],"sign_in":{"last_date":"2026-07-01","continuous_days":3}}}

静态作物数据crops.json

[{"crop_id":"carrot","name":"萝卜","seed_price":10,"mature_seconds":120,"sell_price":20,"exp":1,"level_required":1}]

五、主循环流程（伪代码）

function main_loop(): while True: tick() # 刷新所有地块状态 print(main_menu_text()) # 渲染主界面 choice = input("请输入数字选择: ") if choice == 0: # 退出 save_game() break elif choice == 1: menu.show_farm_view() elif choice == 2: menu.show_store() elif choice == 3: menu.show_plant_menu() elif choice == 4: menu.show_harvest_menu() elif choice == 5: menu.show_water_menu() elif choice == 6: menu.show_unlock_land() elif choice == 7: menu.show_till_menu() elif choice == 8: menu.show_inventory() elif choice == 9: menu.show_achievements()

数据流方向：

输入 ──► MenuManager ──► Game ──► SubSystem │ ◄─────────────┘ 返回结果/状态 │ ┌──────────▼──────────┐ │ 自动保存 (每3次操作) │ └─────────────────────┘

六、时间机制

• 使用time.time()记录plant_time（播种时间戳）。
• 每次用户操作时调用tick()：

  剩余时间 = (plant_time + mature_seconds) - now

• 不依赖后台线程 / 定时器，纯被动刷新。
• 浇水效果：mature_seconds -= 60（减少 1 分钟），最少不低于 10 秒。
• 枯萎判定：成熟时间戳 + 1800 秒（30 分钟）→ 标记为withered。

七、浇水/施肥机制

八、依赖关系图

Game / | \ / | \ ▼ ▼ ▼ LandSystem EconomySystem InventorySystem | | | ▼ ▼ | CropSystem StoreSystem | | | ▼ ▼ AchievementSystem (装饰数据)

• 所有子系统之间不直接依赖，仅通过Game协调。
• MenuManager依赖Game（通过它访问所有子系统）。
• StoreSystem依赖CropSystem（读取作物数据）和EconomySystem（扣钱判断）。

九、开发路线（对应策划案 MVP）

github源码下载