9.1 KiB
9.1 KiB
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 物理，渲染驱动选择归实现期 ADR）
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 期注意） |
行为 / 默认值变更
LinearToSRGBvisual shader 不再 clamp 到 [0,1]（Mobile/Forward+）—— 🔵（若写 shader）- 新项目默认值：stretch mode
disabled→canvas_items、stretch aspectkeep→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/ 分域参考（按实现期需要建，非阻塞）