1. 问题现象
在 Godot 4 编辑器中点击「运行项目」后，游戏窗口默认嵌入编辑器主窗口的面板中，而不是以独立窗口运行。此时试玩窗口的尺寸由编辑器面板的可用区域决定，与 project.godot 中设置的 1280x720 并不完全一致。若在右上角 Window 菜单中选择了「保持宽高比」，窗口四周会出现黑边。
2. 常见误解
很多开发者误以为游戏运行窗口的尺寸由 project.godot 中的 viewport_width 和 viewport_height 直接控制，修改这两个值后嵌入式窗口就会随之变化。实际上，嵌入式运行时游戏视口等于编辑器面板的可用区域，project.godot 中的 viewport 尺寸仅作为逻辑分辨率基准（在 stretch 模式下生效），并不直接等于嵌入式窗口的像素尺寸。
另一个常见误解是认为「保持宽高比」可以铺满窗口。实际上「保持宽高比」（Keep Aspect）会强制按逻辑分辨率比例缩放，当窗口比例与逻辑比例不一致时，四周会留黑边；若要铺满应选择「伸展以适应」（Stretch to Fit），但此时画面比例可能无法保持。
3. 核心概念区分
问题的根源在于混淆了两个不同层面的设置：
- 项目 viewport 设置：定义逻辑分辨率，即游戏内容在逻辑坐标系中的尺寸基准。
- 编辑器嵌入式窗口适配策略：决定逻辑画面如何呈现到实际窗口区域中。
前者管逻辑分辨率，后者管窗口如何呈现逻辑画面，二者不能混为一谈。
4. 嵌入式窗口尺寸选项说明
Godot 4 编辑器右上角 Window 菜单中的「嵌入式窗口尺寸」下拉提供三个选项：
- 固定大小（Fixed Size）：窗口保持固定尺寸，不随面板大小变化。
- 保持宽高比（Keep Aspect）：按逻辑分辨率比例缩放，窗口比例与逻辑比例不一致时四周留黑边。
- 伸展以适应（Stretch to Fit）：拉伸画面铺满整个面板，但画面比例可能失真。
此外还有两个勾选项：「下次运行时嵌入游戏」和「下次运行时浮动游戏工作区」。前者将游戏窗口嵌入编辑器面板，后者则让游戏以独立浮动窗口运行。
5. 如何控制嵌入式窗口尺寸
若希望嵌入式试玩窗口铺满面板，应在 Window 菜单中选择「伸展以适应」；若希望保持画面比例不变，则选择「保持宽高比」，但需接受可能出现的黑边。若希望窗口尺寸与 project.godot 中的设置完全一致，建议取消「下次运行时嵌入游戏」，改用浮动窗口运行。
6. 源码验证
通过实际运行验证，Window 菜单中的两组设置行为如下：
- 下次运行时嵌入游戏：运行后画面嵌入编辑器面板内，视口等于面板可用区域，并随编辑器窗口大小变化。
- 下次运行时浮动游戏工作区：运行后弹出独立浮动窗口，可脱离编辑器自由拉伸或全屏。
「嵌入式窗口尺寸」下拉的三个选项仅在嵌入模式下生效：
- 固定大小：视口保持 project.godot 中的 viewport_width 和 viewport_height，面板变大时画面不跟随，留出空白。
- 保持宽高比：等比缩放填满面板，比例不一致时出现黑边。
- 伸展以适应：拉伸填满面板，无黑边但画面可能变形。
以逻辑分辨率 1280x720 的 Ball 项目为例：选择「伸展以适应」后嵌入式画面铺满面板；选择「保持宽高比」时，在 16:9 面板上显示正常，在更方或更宽的面板上则出现黑边。切换「嵌入式窗口尺寸」即时生效，无需重启编辑器。
结论：嵌入模式下窗口适配属于编辑器 GUI 行为，不会写入 project.godot，代码无法控制。若要完全控制窗口大小，应使用「浮动游戏工作区」，再手动拉伸窗口或全屏。
7. 落地结论与速查
综合以上分析，可以得出以下落地结论：
- 试玩要铺满：在 Window 菜单中选择「伸展以适应」。
- 试玩要原生窗口或全屏：勾选「下次运行时浮动游戏工作区」，运行后拖动窗口边缘或全屏。
- 不要用「保持宽高比」做试玩铺满：它会强制固定比例，四周留黑边。
- 项目代码层面：stretch/mode 决定逻辑分辨率与视口的关系，与嵌入式窗口适配策略相互独立，两者应分开排查。
以上结论适用于 Godot 4 编辑器内的试玩调试。发布后的独立可执行文件或导出包不受此影响，其窗口行为由 project.godot 与操作系统窗口管理共同决定。
8. 速查表
针对不同角色的开发者，这里提供三份速查：
人类开发者速查
- 在编辑器右上角 Window 菜单中查看两组设置。
- 铺满选「伸展以适应」；要独立窗口则勾选「下次运行时浮动游戏工作区」。
- 出现黑边，说明选了「保持宽高比」。
对话式 AI 速查
问法：「Godot 编辑器嵌入式试玩窗口大小不对或有黑边怎么调？」
回答要点：在 Window 菜单的「嵌入式窗口尺寸」中选择「伸展以适应」即可铺满；或勾选「下次运行时浮动游戏工作区」得到独立可拉伸窗口。黑边来自「保持宽高比」。
代码 Agent 速查
- 嵌入式窗口适配是编辑器 GUI 状态，不写入 project.godot，代码 Agent 无法直接修改。
- 如需项目级控制，应提示用户通过 GUI 操作；代码侧只负责 stretch 与响应式逻辑。
6. 总结
嵌入式试玩窗口的尺寸由编辑器面板决定，而非 project.godot 中的 viewport 设置。理解「逻辑分辨率」与「窗口适配策略」的区别，才能正确控制嵌入式窗口的显示效果。根据实际需求选择合适的适配选项，即可获得理想的试玩体验。