Bird Watching — Changelog

2.0.0 — July 21, 2026

This update is a comprehensive overhaul of the mod’s content, ecosystem, and underlying systems, built on the foundation of version 1.0.0. The number of bird species has increased from 5 to 10, while the photo storage, flight navigation, natural spawning, and server configuration systems have all been reworked.

New Bird Species

• Added Cockatiels, Macaws, Long-tailed Tits, Crows, and Seagulls.

• Every new bird has its own model, textures, animations, spawning environment, diet, and spawn egg.

• The field guide now includes all 10 bird species: Black-crowned Night Heron, Sparrow, Long-tailed Tit, Cockatiel, Macaw, Budgerigar, Spotted Dove, Pigeon, Crow, and Seagull.

• Bird proportions have been recalibrated based on representative real-world body weights and actual model dimensions, while preserving individual size variation. The Long-tailed Tit has also been adjusted to appear visually similar in size to the Sparrow.

New Ecology and Interactions

• Tamed birds now support four command modes: Free, Follow, Stay, and Return Home. Owners can switch modes by sneaking and interacting with an empty hand. The selected mode is saved with the world, although birds will still prioritize escaping from danger.

• Seagulls can observe players and steal ordinary food items from a configurable safety whitelist. After stealing food, they will fly away and eat it. This behavior includes per-player cooldowns and concurrency limits.

• Crows can collect food and shiny objects, then carry their treasures back to a claimed nest. Named items, items with NBT data, containers, and rare items are protected by default.

• Flocks are now strictly limited to birds of the same species. Different parrots, Sparrows, and Long-tailed Tits will no longer form mixed-species flocks.

• Spotted Doves and Pigeons can sense approaching rain or severe weather and search for more suitable shelter or perching locations.

• Cockatiel crests now change according to mood and behavioral state.

• Each bird species now has its own food tag and toxic food checks. The Black-crowned Night Heron also has a separate list of aquatic prey.

• Natural sleep schedules have been added for the Black-crowned Night Heron, Budgerigar, Cockatiel, Macaw, Crow, and Seagull, all of which have dedicated sleeping animations. They will sleep at suitable times and in suitable environments, and will wake up when attacked or startled by loud noises.

Nest Gameplay

• Added naturally generating Crow nests, along with a crafting recipe made entirely from sticks.

• Each nest can hold up to 3 chicken eggs and store treasures brought back by Crows.

• Players can open the nest search interface to rummage through and retrieve discovered collectibles.

• Configuration options are available for natural nest generation, generation rate, Crow claiming behavior, nest search distance, and the maximum number of treasures stored in each nest.

Bird Droppings Gameplay

• Added 4 types of bird droppings, throwable projectiles, ground stains, and attached effects. Bird droppings can also be fired from dispensers.

• Bird droppings can be composted or used to probabilistically accelerate crop growth around farmland.

• Food hit by bird droppings, or used in certain crafting recipes, can be turned into prank food with special names, tooltips, and negative effects.

• Hitting players, villagers, iron golems, cakes, and various creatures with bird droppings can trigger different reactions and advancements.

• When bird droppings hit a pressure plate, they generate a single redstone pulse with a configurable duration. The pressure plate automatically resets after the pulse ends.

• Added nearby bird dropping limits and automatic cleanup to prevent ground stains from accumulating indefinitely.

“Feathers of the Wild” and Configuration Interface

• The original birdwatching field guide has been renamed “Feathers of the Wild” and now features a new icon and redesigned interface layout.

• Each bird entry now includes an introduction, activity period, diet, habitat, behavior tags, and selectable observation animations.

• A new Bird Watching Settings entry has been added to the guide, allowing players to open the configuration screen without memorizing commands.

• Added global, current-world, and server configuration scopes. Players and server administrators can independently adjust spawning, group size, sounds, flocking, food scanning, threat scanning, and other settings for each bird species.

• Added April Fools’ Mode. All birds become significantly larger, Sparrows grow to approximately player height, and birds no longer fear players.

• Configuration saving now uses temporary files and atomic replacement. Failed writes will no longer be reported as successful, and corrupted configuration files are automatically backed up as .broken-timestamp files.

Photo System Overhaul

• Photos no longer store 65,536 pixels inside item NBT or transfer the entire image through a single oversized network packet.

• Screenshots are now encoded as JPEG files with a maximum size of 96 KiB and uploaded in chunks of up to 24 KiB. The server validates file size, chunk structure, SHA-256 hashes, JPEG format, and actual image resolution.

• Photo files are stored in data/guaniao/photos inside the world directory. Photo items and framed photos now store only lightweight metadata.

• Added upload cooldowns, per-minute traffic limits, per-player session limits, timeout cleanup, and server-wide download budgets.

• JPEG decoding, hashing, and disk I/O have been moved to bounded background threads. Client downloads and texture uploads are also processed asynchronously with strict limits.

• The client-side compressed image cache has been increased to 192 entries, while the GPU texture cache has been increased to 96 entries. Resources are now properly released when evicted or when leaving a world.

• Added per-player and per-world photo count and storage quotas, as well as a recycle bin, restoration tools, integrity verification, and orphaned photo cleanup.

• Legacy pixel-based photos are migrated to JPEG when loaded. Old data is preserved as a backup until migration succeeds, after which the pixel array is removed from the item.

Flight and Spawning Improvements

• Flight destination selection now checks for a continuous, collision-free path between the bird and its target, reducing collisions with walls, doorway obstructions, and repeated flight loops inside caves.

• Stuck detection now checks whether the bird is actually moving closer to its target. After repeated failures, the bird will search for a visible upward or reverse escape route.

• Outdoor birds must now be able to see the sky when naturally spawning, reducing underground and cave spawns.

• All birds can pass through leaves by default. This behavior can be disabled in the configuration.

• Habitat checks for colony spawning now use a bounded regional cache, reducing block scan pressure during multiplayer gameplay and new chunk generation.

• Flyover events, bird population statistics, and AI perception now use regional counters, caching, and scan budgets. Their stored state is cleared when players leave or worlds unload.

Sounds, Models, and Items

• Added or expanded realistic calls for the Spotted Dove, Seagull, Crow, Macaw, Cockatiel, and Long-tailed Tit.

• Bird calls are now rate-limited within the same area, reducing noise and performance issues when many birds vocalize at once.

• Fixed scale and texture display issues on several bird models and updated the Black-crowned Night Heron animations.

• Added unique textures for every bird spawn egg.

• Added missing localization for the breadcrumb block.

• Added crafting recipes for small, medium, and large bird cages. Bird cages remain decorative blocks and cannot currently contain birds.

• Added the appropriate mining tool tags for wooden, stone, and iron blocks.

Advancements and Administration Tools

• Added 16 advancements covering taming, species collection, flock observation, Seagull food theft, Crow observation, bird dropping interactions, and other gameplay systems.

• Added the /guaniao photo administration command for viewing statistics, listing photos, deleting photos, restoring photos, verifying integrity, and cleaning up stored photo data.

• Added the /guaniao stress stress-testing command, which can spawn marked test birds in batches, measure tick time, and automatically clean them up.

• Added the /guaniao perf diagnostics command for viewing and resetting bird scan budget statistics.

• Test-only nest commands are no longer registered in production environments.

Security, Performance, and Compatibility

• Fixed an issue where camera packets sent from the client to the server could bypass cooldowns, spoof data lengths, and generate duplicate film items.

• Photo uploads now include strict length rejection, content validation, storage quotas, and administrator tracking tools.

• Dynamic photo textures now have cache limits, asynchronous decoding, per-frame upload budgets, and proper resource release paths.

• Natural spawn population checks now use incremental regional statistics instead of repeatedly scanning large numbers of entities.

• Pressure plate compatibility logic now uses a single event trigger, and the related Mixin can fall back gracefully if it cannot be applied.

• Bird baths are no longer rendered while off-screen, and their long-distance rendering range has been limited.

• Build artifacts no longer include build timestamps, and now use deterministic file ordering and reproducible ZIP timestamps.

• Dependency ranges have been restricted to Minecraft 1.20.1, Forge 47.2.x, and GeckoLib 4.4.x.

• The network protocol has been upgraded to version 10. Older clients cannot connect to a 2.0.0 server, and 2.0.0 clients cannot connect to older servers.

Upgrade Notes

• Before upgrading from 1.0.0, a complete world backup is strongly recommended. Make sure the backup includes data/guaniao/photos inside the world directory.

• Both the client and server must be running version 2.0.0.

• Legacy photos are migrated gradually when players interact with photo items or load framed photos. The first load may take slightly longer than usual.

• Version 2.0.0 is available exclusively for Minecraft Forge 1.20.1. The 1.21.1 branch in the repository is currently only a starting point for future porting work and does not indicate compatibility with Minecraft 1.21.1.

• # 《Bird Watching / 观鸟》更新日志

  
  

  ## 2.0.0 — 2026-07-21

  
  

  本次更新以 1.0.0 为基线，是一次内容、生态与底层系统的全面升级。鸟类数量由 5 种增加到 10 种，并重构了照片存储、飞行导航、自然生成和服务器配置系统。

  
  

  ### 新增鸟类

  
  

  - 新增玄凤鹦鹉、金刚鹦鹉、北长尾山雀、乌鸦和海鸥。

  - 所有新鸟均拥有独立模型、纹理、动画、生成环境、食性与刷怪蛋。

  - 图鉴现已收录全部 10 种鸟：夜鹭、麻雀、北长尾山雀、玄凤鹦鹉、金刚鹦鹉、虎皮鹦鹉、珠颈斑鸠、鸽子、乌鸦和海鸥。

  - 按现实中的代表体重和模型实际尺寸重新校准鸟类比例，并保留个体体型差异；北长尾山雀调整为与麻雀接近的视觉大小。

  
  

  ### 新增生态与互动

  
  

  - 驯服鸟新增“自由、跟随、停留、归巢”四种指令模式。主人潜行并空手互动即可切换，状态会随存档保存；遭遇危险时鸟仍会优先逃生。

  - 海鸥会观察玩家并抢走安全白名单内的普通食物，叼走后飞离并进食；该行为带有玩家冷却和并发限制。

  - 乌鸦会收集食物或亮闪闪的物品，并将宝物带回已认领的鸟窝；命名物品、带 NBT 的物品、容器及稀有物品默认受到保护。

  - 鸟群现在严格按相同物种组成，不同鹦鹉、麻雀和北长尾山雀不再混群。

  - 珠颈斑鸠和鸽子会感知即将到来的降雨或恶劣天气，并寻找更合适的避雨、停栖位置。

  - 玄凤鹦鹉的冠羽会根据情绪和行为状态变化。

  - 每种鸟拥有独立食物标签和有毒食物判断；夜鹭拥有单独的水生猎物范围。

  - 为具备睡姿动画的夜鹭、虎皮鹦鹉、玄凤鹦鹉、金刚鹦鹉、乌鸦和海鸥接入自然作息。它们会在适合的时间和环境睡觉，并在受击或听见巨大声响时惊醒。

  
  

  ### 鸟窝玩法

  
  

  - 新增可自然生成的乌鸦鸟窝，并加入纯木棍合成配方。

  - 鸟窝最多可放置 3 枚鸡蛋，并可保存乌鸦带回的宝物。

  - 玩家可以打开鸟窝搜索界面，翻找并取出已经发现的收藏。

  - 支持控制自然生成、生成倍率、乌鸦认领、寻巢距离及单巢宝物数量。

  
  

  ### 鸟粪玩法

  
  

  - 新增 4 种鸟粪、投掷物、地面污渍和附着效果；鸟粪也可由发射器发射。

  - 鸟粪可用于堆肥，或对农田周围的作物进行概率催熟。

  - 鸟粪击中食物或参与合成后可制作恶作剧食物，并会产生特殊名称、提示与负面效果。

  - 击中玩家、村民、铁傀儡、蛋糕及多种生物时会触发不同反应和进度。

  - 鸟粪砸中压力板时只产生一次可配置时长的红石脉冲，结束后压力板会自动回弹。

  - 新增附近鸟粪数量限制和自然清理，避免地面痕迹无限堆积。

  
  

  ### “林野飞羽录”与配置界面

  
  

  - 原观鸟图鉴更名为“林野飞羽录”，更新图标和界面布局。

  - 每种鸟均提供简介、活动时间、食性、栖息环境、行为标签及可切换的观察动作。

  - 图鉴内新增“观鸟配置”入口，无需记忆指令即可打开设置。

  - 新增全局、当前存档和服务器配置范围，并支持单独调整每种鸟的生成、群体大小、声音、鸟群、食物扫描和威胁扫描等参数。

  - 新增“愚人节模式”：所有鸟类会明显放大，麻雀接近玩家高度，同时不再惧怕玩家。

  - 配置保存改为临时文件加原子替换；写入失败不会假装保存成功，损坏配置会自动备份为 `.broken-时间戳` 文件。

  
  

  ### 照片系统重构

  
  

  - 照片不再把 65,536 个像素写入物品 NBT，也不再通过单个超大网络包传输。

  - 截图改为最高 96 KiB 的 JPEG，按最高 24 KiB 的分片上传；服务端会校验大小、分片、SHA-256、JPEG 格式和实际分辨率。

  - 照片文件保存在世界目录的 `data/guaniao/photos` 中，照片物品和挂画只保存轻量元数据。

  - 增加上传冷却、每分钟流量限制、单玩家会话限制、超时清理以及服务器级下载预算。

  - JPEG 解码、哈希和磁盘读写移至有界后台线程；客户端下载和纹理上传也改为限量、异步处理。

  - 客户端压缩图片缓存提升至 192 项，GPU 纹理缓存提升至 96 项，并在淘汰或退出世界时正确释放资源。

  - 新增每玩家和每世界的照片数量、容量配额，以及回收站、恢复、校验和孤儿照片清理机制。

  - 旧版像素照片会在加载时迁移为 JPEG；迁移成功前保留旧数据备份，成功后再移除物品中的像素数组。

  
  

  ### 飞行与生成改进

  
  

  - 飞行选点加入鸟到目标之间的连续无碰撞通道检测，减少撞墙、卡门口和在洞窟内循环飞行。

  - 卡住判断改为检查是否真正接近目标；连续失败后会寻找可见的爬升或反向出口。

  - 户外鸟自然生成时必须能够看见天空，减少鸟类从洞窟中生成。

  - 所有鸟类默认可以穿过树叶，相关功能可在配置中关闭。

  - 聚居模式的栖息地判断加入有上限的区域缓存，降低多人和新区块生成时的方块扫描压力。

  - 飞越事件、鸟类数量统计和 AI 感知加入区域计数、缓存及扫描预算，并在玩家退出或世界卸载时清理状态。

  
  

  ### 声音、模型与物品

  
  

  - 为珠颈斑鸠、海鸥、乌鸦、金刚鹦鹉、玄凤鹦鹉和北长尾山雀新增或扩充真实叫声。

  - 同一区域内的鸟叫加入限流，降低大量鸟同时鸣叫造成的噪声和性能压力。

  - 修复部分鸟模型比例和材质显示异常，并更新夜鹭动画。

  - 为所有鸟类刷怪蛋换用独立贴图。

  - 补齐面包屑方块本地化。

  - 为小型、中型和大型鸟笼补充合成配方；鸟笼目前仍为装饰方块，不能收纳鸟类。

  - 补充木制、石制和铁制方块对应的工具挖掘标签。

  
  

  ### 进度与管理工具

  
  

  - 新增 16 项进度，覆盖驯服、物种收集、鸟群观察、海鸥抢食、乌鸦观察、鸟粪互动等玩法。

  - 新增 `/guaniao photo` 管理命令，可查看统计、列出、删除、恢复、校验和清理照片。

  - 新增 `/guaniao stress` 压测命令，可分批生成带标记的测试鸟、统计 tick 耗时并自动清理。

  - 新增 `/guaniao perf` 诊断命令，用于查看和重置鸟类扫描预算统计。

  - 测试用鸟窝指令在正式生产环境中不再注册。

  
  

  ### 安全、性能与兼容性

  
  

  - 修复相机客户端到服务端数据包可绕过冷却、伪造长度和重复生成胶卷的问题。

  - 照片上传新增严格长度拒绝、内容验证、配额和管理员追踪能力。

  - 动态照片纹理增加缓存上限、异步解码、逐帧上传预算和释放路径。

  - 自然生成数量检查改用增量区域统计，避免反复扫描大范围实体。

  - 压力板兼容逻辑改为单次事件触发，并将 Mixin 调整为可降级加载。

  - 鸟浴盆不再离屏渲染，并限制远距离渲染范围。

  - 构建产物移除构建时间戳，启用固定文件顺序和可复现 ZIP 时间。

  - 依赖范围收紧为 Minecraft `1.20.1`、Forge `47.2.x` 和 GeckoLib `4.4.x`。

  - 网络协议升级至 10，旧版客户端与 2.0.0 服务器不能混合连接。

  
  

  ### 升级须知

  
  

  - 从 1.0.0 升级前建议完整备份世界；备份时请包含世界目录下的 `data/guaniao/photos`。

  - 客户端和服务器必须同时安装 2.0.0。

  - 旧照片会在玩家接触物品或加载照片挂画时逐步迁移，首次加载可能稍有延迟。

  - 2.0.0 仅面向 Minecraft Forge 1.20.1；仓库中的 `1.21.1` 分支目前只是后续移植起点，不代表已经兼容 1.21.1。