50 lines
4.6 KiB
Markdown
50 lines
4.6 KiB
Markdown
# Godot 当前最佳实践（4.7 视角，post-cutoff）
|
||
|
||
> **Last verified: 2026-09-12**（源：官方迁移指南 4.5/4.6/4.7 逐条核实 + 4.7 release 页）
|
||
> 用途：训练数据（~4.4）之后的实践差异速查。写码代理在以下事项上**不要**按训练数据默认值行事。
|
||
|
||
## 1. 新建 project.godot 的默认值差异（最易踩坑）
|
||
|
||
| 设置 | 训练数据默认（≤4.4） | 4.7 实际新项目默认 | 生效版本 |
|
||
|---|---|---|---|
|
||
| `display/window/stretch/mode` | `disabled` | `canvas_items` | 4.7（新项目） |
|
||
| `display/window/stretch/aspect` | `keep` | `expand` | 4.7（新项目） |
|
||
| `rendering/rendering_device/driver.windows` | Vulkan（Forward+） | D3D12 | 4.6（新项目） |
|
||
| `physics/3d/physics_engine` | GodotPhysics3D | Jolt | 4.6（新项目；本项目 2D、无 3D 物理，无关） |
|
||
|
||
本项目为 2D 棋盘 UI：stretch mode / aspect 的最终选择归渲染器实现期 ADR，但须知道**引擎新项目默认值已不是训练数据里的那个**——新建工程后检查这三项。
|
||
|
||
## 2. GDScript 4.7 两条语义变化（建议入编码规范）
|
||
|
||
1. **打包数组元素赋值不再触发属性 setter**（4.7，GH-113228）：`my_packed_array[i] = v` 不再调用所在对象的 property setter——依赖 setter 副作用的写法必须改为显式赋回 + 显式调用 setter。D2 schema 类若以 setter 做校验，注意此差异。
|
||
2. **类型化返回的方法覆盖必须显式 `return`**（4.7，GH-115763）：覆盖带返回类型的方法时返回类型自动继承，缺少 return 直接报错（旧版隐式返回 null）——虚方法覆盖一律显式写 return。
|
||
|
||
## 3. 资源与文件
|
||
|
||
- `Resource.duplicate(true)`（4.5 起）：深复制**只覆盖内部子资源**，不再覆盖外部子资源；需旧行为用 `duplicate_deep(DEEP_DUPLICATE_ALL)`。D2 表资源含外部子资源时注意复制语义。
|
||
- `FileAccess.get_as_text()` 的 `skip_cr` 参数已移除（4.6）——换行处理如需自定义须自行实现。
|
||
- TSCN 格式（4.6）：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 会变大（可 Project > Tools > Upgrade Project Files 预升级，减少一次性大 diff）。
|
||
- `ProjectSettings.add_property_info()`（4.5）：对缺失/非法键（含 `usage`）告警；改用 `set_as_basic()` / `set_restart_if_changed()` / `set_as_internal()`。
|
||
|
||
## 4. 2D / UI / 文本
|
||
|
||
- `CanvasItem` 线条绘制**不再自动加抗锯齿羽化**（4.7）——粗线/描边需手动方案（D1 自绘棋盘格边框时注意）。
|
||
- 输入设备 ID：比较输入来源时用 `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` 常量，**不要硬编码 0**（4.7）——D1 输入路由。
|
||
- 字体导入 `hinting` 默认 1 → 3（4.7）；TextServer/Font/CanvasItem 全部 draw 方法新增可选 `oversampling` 参数（4.5）——自绘文字（数字标签）可显式控制过采样。
|
||
- RichTextLabel 图片参数两轮变化：4.5 `size_in_percent` → `width_in_percent`+`height_in_percent`；4.7 → `width_unit`/`height_unit`（bool → `ImageUnit`），常量 `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT`。
|
||
- **Glow 默认值大改**（4.6）：blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排——2D 后处理发光的视觉基底已变，调参以 4.7 默认为起点。
|
||
- `Control.grab_focus` / `has_focus` 新增可选参数（4.6，`hide_focus` / `ignore_hidden_focus`）——焦点可视化管理更细。
|
||
|
||
## 5. 4.7 已核实新特性（本项目可用的增量）
|
||
|
||
- `Tween.tween_await()`：信号等待语法糖——**注意** B1 结算逻辑禁 await 是设计约束（可回放步骤流），该 API 不改变该约束
|
||
- Control `offset_transform_*`：平移/旋转/缩放 Control 不影响容器布局——D1 HUD 局部动效可用
|
||
- CollisionShape2D 单向碰撞方向属性（+ `PhysicsServer2D.body_set_shape_as_one_way_collision` 的 `direction` 参数）——本项目棋盘非物理驱动，暂不依赖
|
||
- conic gradient、AtlasTexture 进 TextureRect——D1 贴图/着色可选
|
||
- DrawableTexture2D、AreaLight3D、HDR 输出、内置 VirtualJoystick、新 Asset Store——本项目暂不依赖
|
||
- `Font.find_variation` 扩展（palette_index / custom_colors）、`TreeItem.select` 扩展——低相关
|
||
|
||
## 6. 本项目不消费的域（相关变更可忽略）
|
||
|
||
3D 渲染与物理（Jolt 行为变化 / SoftBody / WorldBoundary / SpringBone / LookAtModifier）、XR/OpenXR、网络（StreamPeerTCP/TCPServer 方法上移、RPC 更名）、GLTF 导入（int64 字段）、移动端导出（Android 模板结构变化、.NET 9）、编辑器插件 API（ImportFlags / VCS / ExportPlatform）。
|