DKChan
6c2dbc37c1
- 删除 design/dev/architecture/adr-0001~0007 共 7 份文件（内容留 git 历史可查） - architecture.md：删「ADR 审计」「ADR 立项清单」两节；清除全文 ADR-000X 注记、QQ 表/S 表 ADR 引用；未决表关闭已落定项（QQ-01/02/03），立项清单在途事项转登记 QQ-11~14；补 A1 生成姿态事实、autoload 四件清单、board_generator 性能姿态；文档状态立「事实源地位」条 - CLAUDE.md：恢复 RNG 单点硬性红线（去 ADR-0007 引用）；新增「架构事实唯一源」红线；规范导航架构行标注唯一事实源 - doc-conventions：§5 增「架构事实唯一源」行；§11 活文档清单补架构文档 - registry：architecture.yaml 删 18 处 adr 字段、autoload_set 补 SaveManager/MetaProgression、board_rending 更新为 Node2D 已落地事实；entities.yaml 12 处引用清除 - game/ 代码注释约 60 处清 ADR-000X 引用（事实与日期保留）；豁免标记 ADR-0007-exempt → rng-seed-exempt（main.gd/static_scan.sh/architecture.md/06/iter27 五处同步） - GDD/qa 实现报告/research 卡片/roadmap/tests README 引用全清；死链校验 1206 链接 0 死链、gdd_lint 0 不通过 - 代码中 adr/adr5 等为 adventure_runner 既有局部变量名（非 ADR 引用），未动
116 lines
9.1 KiB
Markdown
116 lines
9.1 KiB
Markdown
# 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
|
||
|
||
- [x] 4.4→4.5 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||
- [x] 4.5→4.6 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||
- [x] 4.6→4.7 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||
- [x] 各版本 deprecated → replacement 对照表（见 `deprecated-apis.md`，2026-09-12）
|
||
- [ ] 4.8 逐条清单（当前仅 dev 快照；稳定版发布后跑 `/setup-engine refresh`）
|
||
- [ ] modules/ 分域参考（按实现期需要建，非阻塞）
|