gplan-2/design/engineering/engine-reference/godot/breaking-changes.md

Godot Breaking Changes（4.4 → 4.7）

Last verified: 2026-09-12（官方迁移指南三份逐条核实——4.5/4.6/4.7 API 级清单已补全，原 2026-09-07"待 refresh"状态解除） 训练数据覆盖至 ~4.4：4.4 及以前的变更视为"已知基线"，4.5+ 为超出截止的增量。 官方迁移指南（升级/写码前必读）：

• 4.5：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.5.html
• 4.6：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.6.html
• 4.7：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html

项目相关性图例：🔵 需要留意（本项目域内）/ ⚪ 本项目不用（3D/XR/网络/移动/GLTF/编辑器插件）。 本项目形态：2D 回合制、GDScript 单语言、Control 重 UI、autoload + .tres、无 3D/物理/网络。

4.5（2025-09-15）

API 级变更

类/方法	变更	GDScript 兼容	项目相关性
Resource.duplicate(true)	深复制不再覆盖外部子资源；旧行为需 duplicate_deep(DEEP_DUPLICATE_ALL)	行为变更	🔵 D2 schema/表资源复制语义注意
Node.set_name	参数 String → StringName	兼容	🔵
JSONRPC.set_scope	更名 set_method	❌	⚪
Node.get_rpc_config	更名 get_node_rpc_config	❌	⚪（RPC 不用）
RenderingServer.instance_reset_physics_interpolation	移除	❌	⚪（3D 插值）
RenderingServer.instance_set_interpolated	移除	❌	⚪
TextServer/Font/CanvasItem/TextLine/TextParagraph 全部 draw 方法	新增可选 oversampling 参数	兼容	🔵 D1 自绘文字
TextServerExtension 四个 draw 虚方法	同上签名变化	❌（全不兼容）	⚪（不实现 TextServer 扩展）
RichTextLabel.add_image/update_image	size_in_percent → width_in_percent + height_in_percent	兼容	🔵（低——富文本用图时）
C# RenderingDevice.Features.Address	更名 BufferDeviceAddress	仅 C#	⚪（C# 不用）
GLTF Accessor/BufferView 十字段	int32 → int64 / 枚举化	仅 C#	⚪（GLTF 不用）

行为变更

• TileMapLayer 物理分块默认开启；get_coords_for_body_rid() 返回值变化；需 4.4 精确行为设 physics_quadrant_size=1 —— 🔵 若棋盘实现走 TileMapLayer（当前设计倾向自绘，未定）
• 3D 模型导入 skeleton 行为修复（新文件新行为；旧文件需改 Import Naming Version）—— ⚪
• Navigation 区域默认异步线程更新；navmesh 合并次序变化 —— ⚪（A2 用自研 BFS，不用 NavigationServer）
• Jolt：areas_detect_static_bodies 设置移除 —— ⚪
• ProjectSettings.add_property_info() 对缺失/非法键（含 usage）告警 —— 🔵（若程序化注册设置项）

4.6（2026-02）

API 级变更

类/方法	变更	GDScript 兼容	项目相关性
FileAccess.get_as_text	skip_cr 参数移除	❌	🔵 文本读取路径
FileAccess.create_temp	mode_flags int → ModeFlags 枚举	兼容性检查变化	🔵
AnimationPlayer assigned_animation/autoplay/current_animation	String → StringName（get_queue()、current_animation_changed 信号参数同步）	❌（类型不兼容）	🔵 B5 期
SpringBoneSimulator3D 三个枚举	移至 SkeletonModifier3D	❌	⚪
StreamPeerTCP / TCPServer	disconnect_from_host/get_status/poll、is_connection_available/is_listening/stop 上移至 StreamPeerSocket/SocketServer 基类	兼容（继承）	⚪（网络不用）
Control.grab_focus/has_focus、LineEdit.edit、SplitContainer.clamp_split_offset、FileDialog.add_filter	新增可选参数	兼容	🔵 D1
EditorFileDialog	add_side_menu 移除；17 方法 / 8 属性 / 4 信号并入 FileDialog 基类	兼容（继承）	⚪（编辑器）
Performance.add_custom_monitor	新增可选 type 参数	兼容	🔵（调试遥测可选）

行为 / 格式变更

• TSCN 格式：load_steps 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 变大（可 Project > Tools > Upgrade Project Files 预升级）—— 🔵
• Glow 默认值大改（blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排）；Mobile 渲染器 glow 重写 —— 🔵 D1/B5 用 2D Glow 时注意视觉基底已变
• AStar2D/AStar3D/AStarGrid2D：from_id 被禁用/固体时返回空路径 —— ⚪（自研 BFS）
• 新项目默认值：Windows 渲染驱动 D3D12；3D 物理引擎 Jolt —— 🔵 创建 project.godot 时须知（本项目 2D、无 3D 物理；渲染驱动已定 = gl_compatibility，2026-09-12）

4.7（2026-06；4.7.2 = 本项目锁定版本）

API 级变更

类/方法	变更	GDScript 兼容	项目相关性
GDScript 语义 ①	打包数组元素赋值不再触发整属性 setter（GH-113228）	语义变化	🔵 全部 .gd 代码
GDScript 语义 ②	覆盖类型化返回方法：返回类型自动继承，必须显式 return（GH-115763）	语义变化	🔵 全部 .gd 代码
Object.is_class()	参数 String → StringName	兼容	🔵
PhysicsServer2D.body_set_shape_as_one_way_collision	新增可选 direction（= CollisionShape2D 单向碰撞方向属性的 server 层）	兼容	🔵（已核实特性的 API 面）
PhysicsServer2DExtension._body_set_shape_as_one_way_collision	新增必填 direction	❌	⚪（不写 PhysicsServer 扩展）
CanvasItem 线条绘制	不再自动加抗锯齿羽化；粗线需手动绘制（GH-105122）	行为变更	🔵 D1 自绘
Input 设备 ID	鼠标/键盘设备 ID 0 → InputEvent.DEVICE_ID_MOUSE / DEVICE_ID_KEYBOARD 常量	行为变更	🔵 D1 输入
Control.accessibility_live	枚举类型 DisplayServer. → AccessibilityServer.AccessibilityLiveMode	仅 C# 不兼容	🔵（低）
RichTextLabel 图片参数	add_image/update_image width/height int→float；width_in_percent/height_in_percent → width_unit/height_unit；常量 UPDATE_WIDTH_IN_PERCENT → UPDATE_WIDTH_UNIT	❌（常量更名）	🔵（低）
Animation.length	元数据 float → double	仅 C# 不兼容	🔵（低，B5 期）
AnimationNodeBlendSpace1D/2D	布尔 sync 属性 → SyncMode 枚举（sync_mode）	行为变更	⚪（3D 动画树）
Font.find_variation / TreeItem.select / ZIPPacker.start_file / Image.save_exr×2	新增可选参数	兼容	⚪/🔵
AudioEffectSpectrumAnalyzer.tap_back_pos	移除	❌	⚪（D4 Alpha 期若用频谱分析注意）
EditorSceneFormatImporter 七常量	并入 ImportFlags 枚举	仅 C# 源不兼容	⚪
EditorVCSInterface._commit	新增 amend 参数	❌	⚪
OptimizedTranslation.generate	返回 void → bool	仅 C# 二进制	⚪
AudioStreamPlayer.area_mask	默认 1 → 0	行为变更	⚪（D4 Alpha 期注意）

行为 / 默认值变更

• LinearToSRGB visual shader 不再 clamp 到 [0,1]（Mobile/Forward+）—— 🔵（若写 shader）
• 新项目默认值：stretch mode disabled → canvas_items、stretch aspect keep → expand —— 🔵 创建 project.godot 时须知（训练数据默认值已过时）
• macOS 最低版本 10.13 → 11 —— ⚪
• LookAtModifier3D.relative 默认 true → false —— ⚪
• ResourceImporterDynamicFont.hinting 默认 1 → 3 —— 🔵（字体导入）
• rendering/reflections/sky_reflections/roughness_layers 默认 7 → 8 —— ⚪（3D）

已知基线（≤4.4，训练数据内，低风险）

• 4.x 系列：Tween 一律经 create_tween() 获取（Tween 节点已废）；信号连接用 Callable 语法；@onready/@export 注解体系；int 恒 64 位（D2 R2 规约依赖此语义，4.x 内稳定）

本项目影响评估（2026-09-12 复核）

变更	影响
4.7 全部已核实特性	均为增量，无破坏 D2/A3 已批准规约的项
4.5–4.7 逐条 API 变更	无一破坏 GDD 已锁架构契约（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）
需入编码规范的项	GDScript 两条新语义（打包数组 setter / 显式 return）→ current-best-practices.md
需项目设置留意的项	新项目默认值已变（stretch mode / aspect / D3D12）→ current-best-practices.md
Resource.duplicate(true) 语义收窄	D2 表资源含外部子资源时的复制语义注意

Pending

• 4.4→4.5 breaking changes 逐条清单（2026-09-12 官方迁移指南）
• 4.5→4.6 breaking changes 逐条清单（2026-09-12 官方迁移指南）
• 4.6→4.7 breaking changes 逐条清单（2026-09-12 官方迁移指南）
• 各版本 deprecated → replacement 对照表（见 deprecated-apis.md，2026-09-12）
• 4.8 逐条清单（当前仅 dev 快照；稳定版发布后跑 /setup-engine refresh）
• modules/ 分域参考（按实现期需要建，非阻塞）