jutland-add-plane

name	jutland-add-plane
description	Add aircraft to the Jutland game from supplied drawings, reference images, or historical specifications. Use when creating or updating entries in configs/planes.json5, producing transparent top-view plane PNGs, completing gun/bomb/torpedo/rocket references, assigning aircraft to carriers, or validating the resulting resource chain.

Jutland 添加飞机

核心规则

• 在仓库根目录工作。先阅读 AGENTS.md 并执行 git status --short，保留所有无关用户改动。
• 所有项目路径以仓库根目录为基准；脚本不得写死机器绝对路径，外部输入和输出路径由调用者显式传入。
• 先检查同阵营、同任务类型的现有飞机，再按现有命名、数值和素材风格做最小修改。
• 保持配置引用链完整：弹药 -> 机炮/释放器/火箭发射器 -> 飞机 -> 舰船编组。
• 保持飞机 name、PNG 文件名和舰船编组引用完全一致。
• 不替换、压缩或清理用户未要求处理的现有素材。
• 历史资料存在冲突时，说明采用的型号、数据口径和游戏近似；不要伪造精确值。

目标文件

• 飞机配置：configs/planes.json5
• 机炮：configs/guns.json5，弹药：configs/bullets.json5
• 炸弹/鱼雷释放器：configs/releasers.json5
• 航空火箭：configs/plane_rocket_launchers.json5
• 舰载机编组：configs/ships.json5
• 舰船图鉴：configs/references.json5
• 顶视图素材：resources/images/planes/<type>/<name>.png
• 图片加载器：pkg/resources/images/plane/plane.go
• 飞机类型和行为：pkg/mission/object/unit/plane.go
• 字段说明：configs/Readme.md 的飞机配置章节

脚本

• scripts/extract_plane_top_view.py：从用户提供的原图裁剪飞机顶视图，执行裁剪、旋转、白底透明化、保留最大连通飞机区域、裁去透明边界和可选缩放。该脚本只做确定性处理，不重绘、不补线、不改结构、不重新配色。
• 使用示例：

  python .codex/skills/jutland-add-plane/scripts/extract_plane_top_view.py \
    --input "raw/source.jpg" \
    --output resources/images/planes/fighter/A6M2.png \
    --crop 285,35,1015,780 \
    --rotate -45 \
    --target-height 270
  

• 角度说明：脚本沿用 Pillow 角度，正数为逆时针，顺时针 45 度写 --rotate -45。
• 尺寸说明：原始 PNG 的机头到机尾垂直高度必须等于 configs/planes.json5 中该飞机 length * 30 像素；宽度按裁剪后原图比例自动确定，不强制压缩到配置 width。优先使用 --target-height，例如 length: 9 时传 --target-height 270。
• 该脚本输出后必须再用 view_image 预览。若方向、裁剪、白边或残片有问题，只调整 --crop、--rotate、阈值或目标高度；不要在脚本外重绘飞机结构。

工作流程

用户图片处理经验

• 用户明确提供某张图片作为素材来源时，必须从这张图片裁剪处理；不要擅自改用仓库里已有的相似素材、清线图合集、网络图或生成图，除非用户明确批准。
• “风格统一”不等于重绘。默认只允许裁剪、旋转、透明化、边缘清理、轻微去噪和缩放；不得为了统一线宽、配色或视觉风格而臆造结构、补画面板线、重画座舱、改变翼型/尾翼/发动机/螺旋桨形状。
• 如果用户要求“清线图化”，先确认其含义。默认应理解为在原图基础上清理白底、白边、噪点和残片，尽量保留原图线稿；只有用户明确要求重新生成、重绘或接受艺术化加工时，才可生成新美术。
• 多图/拼图来源中若存在不同风格版本，先优先处理用户当轮指定图片中的对应飞机。不要因为另一个来源更清晰而自动替换来源；如确需换源，先说明原因并等待确认。
• 旋转角度以用户反馈为准。例如用户说“原图顺时针旋转 45 度”，就按该角度执行；不要继续凭目测反复试错。工具角度方向要换算清楚，Pillow 中顺时针 45 度是 rotate(-45)。
• 裁剪和旋转后必须用 view_image 预览；发现机头方向、尾翼完整性、相邻图块残片、文字/色块误入、白边或透明漏选问题时，先修这些确定性问题，不要改画风格。
• 若用户批评“结构臆想”“不尊重原图”“艺术化加工”，立即停止生成/重绘路线，回退到原图裁剪处理路线，并明确只保留确定性处理。

1. 确认输入与型号。

   • 从用户资料中确定内部名、展示名、国家、具体改型、任务类型和武器挂载。
   • 用户只给常用名时，结合仓库命名习惯选择简洁型号名，例如 A7M2；高风险歧义先询问。
   • 区分原型机、计划编组和实战型号，不把设计图展示数量默认当成完整载机量，除非用户要求按图配置。

2. 选择游戏类型。

   • 当前仅支持 fighter、dive_bomber、torpedo_bomber。
   • fighter 只选择飞机目标；其余两类只选择舰船目标，并使用对应移动/返航逻辑。
   • 侦察机、攻击机等缺少专用行为时，选择最接近的现有类型，在 description 和最终说明中明确近似。
   • 只有用户明确要求独立玩法，且现有类型无法表达时，才扩展 Go 枚举、目标选择、移动策略、资源目录和相关判断。

3. 生成顶视图素材。

   • 先检查现有同国飞机 PNG：透明 RGBA、机头朝上。
   • 原始 PNG 的垂直高度（机头到机尾）必须按 planes.json5 的 length * 30 像素生成；宽度由原素材比例决定，不为匹配配置宽度做非等比压缩。
   • 用户提供组合图时，优先裁取无遮挡、结构完整的同型机实例；若飞机互相遮挡，换用另一实例，不猜测被遮挡轮廓。
   • 仅做裁剪、旋转、透明化、边缘清理、轻微去噪和按真实尺寸缩放，不重绘用户素材，除非用户明确要求生成新美术。
   • 不要为了匹配其他飞机素材而重建线稿、重绘机翼/机身/尾翼、补画结构线或重新设计涂装。历史线稿即使不完美，也应优先保留。
   • 不要把“从另一张清线合集裁一架相似飞机”当作处理用户图片；这会破坏素材来源约束。
   • 如果需要调整清晰度，优先保留更高原始分辨率，或做轻微对比/锐化；避免阈值化导致线条断裂、黑点噪声或细节丢失。
   • 颜色掩膜不能只保留高饱和机身。逐项检查黑色发动机整流罩、螺旋桨、座舱、轮廓线、尾翼和武器等低饱和部件。
   • 去除甲板线、网格、升降机边框和相邻飞机残片。预览透明 PNG，并在黑底或棋盘格上检查白边、断裂和漏选。
   • 按类型保存：fighter、dive_bomber 或 torpedo_bomber；文件名必须是 <name>.png。

4. 添加飞机配置。

   • 从 1-3 架同阵营、同年代、同任务飞机推导 HP、减伤、加速度、转向、费用和建造时间。
   • maxSpeed 使用 km/h，range 使用 km，length/width 使用米，tonnage 使用吨；初始化阶段会转换速度和航程。
   • year 使用服役年份（整数），用于年代匹配和排序。
   • 描述列出角色、国家和游戏中实际配置的武器，不写入未配置挂载。
   • 战斗机配置前向机炮；俯冲轰炸机配置炸弹；鱼雷轰炸机配置鱼雷。多用途机若同时配置炸弹和鱼雷，会在当前开火循环中都尝试释放，必须先确认这种行为符合需求。
   • 新武器只能引用已存在名称。缺少释放器但已有弹药时，补充最小释放器条目；缺少弹药或机炮时继续补齐整条引用链。

5. 接入舰船和图鉴。

   • 用户要求可实际出击或任务上下文指向某艘航母时，更新该舰 aircraft.groups。
   • 同目标类型的多个编组按数组顺序消耗；据此安排战斗机、侦察机和不同攻击机的顺序。
   • 同步更新对应 references.json5 舰载机名称与数量。不要改动无关舰船或任务。

6. 验证。

   • 用 git diff --check 检查文本问题，用 file 或 sips 确认 PNG 为 RGBA 且尺寸合理。
   • 对每张新增或更新的飞机 PNG，确认像素高度等于 planes.json5 中该飞机 length * 30；宽度只检查是否保持等比和视觉比例正常。
   • 搜索每个新飞机名，确认配置、资源和所有舰船引用一致且没有重复定义。
   • 搜索每个机炮、炸弹、鱼雷和火箭名称，确认上游配置存在。
   • 逐张使用 view_image 检查完整轮廓、朝向、透明边缘及发动机/螺旋桨等深色部件。
   • 对用户提供图片生成的素材，最终说明必须写清楚素材来源、执行的旋转角度、是否只做确定性处理，以及是否发生过换源或重绘；若没有用户明确授权，不得声称重绘/生成版本是最终结果。
   • 运行 go build ./pkg/...。修改 Go 行为时再运行相关单元测试和 gofmt。
   • 最终说明新增型号、类型近似、舰船编组变化、素材来源处理和实际执行的验证。