DKChan
f406002766
- git mv 15 件本体；13 个引用文件 34 处路径同步＋熵增闸 DESIGN_SUBDIRS 白名单同批改判 - 白名单漏改时熵增闸当场真红（子目录越界拦截能力实录验证），同步后全绿 - game/tests 三件套注释按用户特别授权批后主区直改（不入本批）；reports/research 暂存档按吸收即死原则不改 - 文档域闸全绿：gdd_lint/doc_link/doc_term/流水线闸/熵增闸
4.6 KiB
4.6 KiB
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 已定（canvas_items + expand，2026-09-12），但须知道引擎新项目默认值已不是训练数据里的那个——新建工程后检查这三项。
2. GDScript 4.7 两条语义变化（建议入编码规范）
- 打包数组元素赋值不再触发属性 setter（4.7，GH-113228）：
my_packed_array[i] = v不再调用所在对象的 property setter——依赖 setter 副作用的写法必须改为显式赋回 + 显式调用 setter。D2 schema 类若以 setter 做校验，注意此差异。 - 类型化返回的方法覆盖必须显式
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）。