Godot 4 GDScript 教程 / 安装与项目设置
安装与项目设置
正确的安装和项目配置是高效开发的基础。本章详细介绍 Godot 4 的下载安装方式、项目管理器使用、项目设置详解以及版本控制集成。
1. Godot 4 下载方式
1.1 官方下载
| 平台 | 文件格式 | 大小 | 说明 |
|---|
| Windows 64-bit | .zip | ~100MB | 标准版,解压即用 |
| Windows 64-bit (.NET) | .zip | ~130MB | 支持 C# 开发 |
| macOS Universal | .dmg | ~100MB | 支持 Intel/Apple Silicon |
| Linux x86_64 | .AppImage | ~100MB | 无需安装,赋予执行权限即可 |
| Linux x86_64 (.NET) | .zip | ~130MB | 支持 C# 开发 |
# Linux 下载与运行示例
# 1. 下载 AppImage
wget https://github.com/godotengine/godot/releases/download/4.4-stable/Godot_v4.4-stable_linux.x86_64.AppImage
# 2. 赋予执行权限
chmod +x Godot_v4.4-stable_linux.x86_64.AppImage
# 3. 运行
./Godot_v4.4-stable_linux.x86_64.AppImage
# 可选:移动到系统路径
sudo mv Godot_v4.4-stable_linux.x86_64.AppImage /usr/local/bin/godot4
1.2 Steam 安装
| 步骤 | 操作 |
|---|
| 1 | 打开 Steam 客户端 |
| 2 | 搜索 “Godot Engine” |
| 3 | 点击 “安装” (免费) |
| 4 | 从 Steam 库启动 |
💡 提示: Steam 版本功能完全相同,优点是自动更新和 Steam 叠加层支持。
1.3 包管理器安装
# Flatpak (推荐 Linux)
flatpak install flathub org.godotengine.Godot
# Snap
sudo snap install godot-4
# macOS Homebrew
brew install --cask godot
# Windows Scoop
scoop bucket add games
scoop install godot
# Windows Chocolatey
choco install godot
⚠️ 注意: 包管理器版本可能不是最新的稳定版,如需最新版本建议从官网下载。
2. 项目管理器
2.1 界面介绍
启动 Godot 后首先进入项目管理器:
| 区域 | 功能 |
|---|
| 本地项目 | 显示已导入的项目列表 |
| 新建项目 | 创建新的游戏项目 |
| 导入项目 | 导入已有项目文件夹 |
| 资产库 | 浏览官方和社区资源 |
| 设置 | 编辑器全局设置 |
2.2 创建新项目
# 项目创建后,文件系统结构如下:
# MyGame/
# ├── .godot/ # 引擎缓存(自动生成,不纳入版本控制)
# ├── project.godot # 项目配置文件
# ├── icon.svg # 默认图标
# ├── icon.svg.import # 图标导入配置
# └── .gitignore # Git 忽略文件
2.3 项目管理器操作
| 操作 | 方法 |
|---|
| 打开项目 | 双击项目名称 |
| 重命名项目 | 右键 → 重命名 |
| 删除项目 | 右键 → 从列表移除(不删除文件) |
| 项目文件夹 | 右键 → 在文件管理器中打开 |
| 复制项目 | 右键 → 复制项目 |
3. 项目设置详解
通过 项目 → 项目设置 打开配置面板。
3.1 渲染设置
项目设置路径:rendering/
| 设置项 | 默认值 | 说明 |
|---|
| rendering/renderer/rendering_method | forward_plus | 渲染方法(forward_plus/mobile/gl_compatibility) |
| rendering/renderer/rendering_method.mobile | mobile | 移动端专用渲染方法 |
| rendering/environment/defaults/default_clear_color | #000000 | 场景默认背景色 |
| rendering/anti_aliasing/quality/msaa_2d | Disabled | 2D 多重采样抗锯齿 |
| rendering/anti_aliasing/quality/msaa_3d | Disabled | 3D 多重采样抗锯齿 |
| rendering/textures/canvas_textures/default_texture_filter | Linear | 纹理过滤模式 |
# 运行时获取渲染设置
func _ready() -> void:
var method = ProjectSettings.get_setting("rendering/renderer/rendering_method")
print("当前渲染方法: %s" % method)
# 检查是否为移动端
if OS.get_name() in ["Android", "iOS"]:
print("运行在移动平台")
3.2 物理设置
项目设置路径:physics/
| 设置项 | 默认值 | 说明 |
|---|
| physics/2d/default_gravity | 980 | 2D 重力加速度(像素/秒²) |
| physics/2d/default_gravity_vector | (0, 1) | 2D 重力方向 |
| physics/3d/default_gravity | 9.8 | 3D 重力加速度 |
| physics/2d/physics_engine | DEFAULT | 2D 物理引擎选择 |
| physics/3d/physics_engine | DEFAULT | 3D 物理引擎选择 |
| physics/common/physics_ticks_per_second | 60 | 物理帧率 |
# 自定义物理设置示例
# 在项目设置中修改重力后,在脚本中使用:
extends CharacterBody2D
# 获取项目设置中的重力值
var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")
func _physics_process(delta: float) -> void:
if not is_on_floor():
velocity.y += gravity * delta
move_and_slide()
💡 提示: 对于太空游戏,可以将重力设为 0 或很小的值;对于平台跳跃游戏,推荐重力值在 800-1200 之间。
3.3 输入设置
项目设置路径:input/
通过 项目 → 项目设置 → 输入映射 配置输入动作:
| 动作名称 | 键盘映射 | 手柄映射 | 说明 |
|---|
| move_left | A, ← | 左摇杆左 | 向左移动 |
| move_right | D, → | 左摇杆右 | 向右移动 |
| jump | Space | 按钮A (Xbox) | 跳跃 |
| attack | 鼠标左键 | 按钮X (Xbox) | 攻击 |
| interact | E | 按钮Y (Xbox) | 交互 |
# 在代码中添加输入动作
func _ready() -> void:
# 检查动作是否存在
if not InputMap.has_action("dash"):
# 创建新动作
InputMap.add_action("dash")
# 添加键盘映射
var key_event = InputEventKey.new()
key_event.keycode = KEY_SHIFT
InputMap.action_add_event("dash", key_event)
# 添加手柄映射
var joy_event = InputEventJoypadButton.new()
joy_event.button_index = JOY_BUTTON_LEFT_STICK
InputMap.action_add_event("dash", joy_event)
3.4 窗口设置
项目设置路径:display/window/
| 设置项 | 默认值 | 说明 |
|---|
| size/viewport_width | 1152 | 视口宽度 |
| size/viewport_height | 648 | 视口高度 |
| size/window_width_override | 0 | 窗口宽度覆盖(0=不覆盖) |
| size/window_height_override | 0 | 窗口高度覆盖 |
| stretch/mode | disabled | 拉伸模式 |
| stretch/aspect | ignore | 宽高比处理 |
| vsync/vsync_mode | Enabled | 垂直同步 |
# 运行时窗口操作
func _ready() -> void:
# 设置窗口大小
get_window().size = Vector2i(1920, 1080)
# 设置全屏
DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_FULLSCREEN)
# 设置窗口标题
get_window().title = "我的 Godot 游戏"
# 设置最小窗口大小
DisplayServer.window_set_min_size(Vector2i(800, 600))
4. 导出模板管理
4.1 下载导出模板
| 方式 | 操作 |
|---|
| 编辑器内下载 | 编辑器 → 管理导出模板 → 下载 |
| 手动下载 | 从官网下载 .tpz 文件 |
| 安装位置 | ~/.local/share/godot/export_templates/ (Linux) |
# Linux 导出模板路径
~/.local/share/godot/export_templates/4.4.stable/
# Windows 导出模板路径
%APPDATA%\Godot\export_templates\4.4.stable\
# macOS 导出模板路径
~/Library/Application Support/Godot/export_templates/4.4.stable/
4.2 配置导出预设
通过 项目 → 导出 配置导出设置:
| 平台 | 关键配置 |
|---|
| Windows Desktop | 可执行文件名、图标、代码签名 |
| Linux/X11 | 可执行文件权限、嵌入PCK |
| macOS | 签名、公证、DMG 设置 |
| Android | 包名、签名密钥、SDK 版本 |
| iOS | Bundle ID、证书、描述文件 |
| Web | HTML 模板、线程支持、导出图标 |
# 使用命令行导出
# godot --headless --export-release "Windows Desktop" build/game.exe
# godot --headless --export-release "Linux/X11" build/game.x86_64
# godot --headless --export-release "Web" build/game.html
5. 版本控制(Git 集成)
5.1 .gitignore 推荐配置
# Godot 4 .gitignore
# Godot 缓存目录
.godot/
# Godot 项目文件(如果不想跟踪特定设置)
# project.godot
# 导出构建
build/
export/
# 临时文件
*.tmp
*.bak
*.swp
*~
# 系统文件
.DS_Store
Thumbs.db
# IDE 文件
.vscode/
.idea/
*.code-workspace
5.2 推荐纳入版本控制的文件
| 文件/目录 | 是否纳入 | 说明 |
|---|
| project.godot | ✅ 是 | 项目核心配置 |
| *.tscn, *.tres | ✅ 是 | 场景和资源文件 |
| *.gd | ✅ 是 | GDScript 脚本 |
| *.gdshader | ✅ 是 | 着色器文件 |
| assets/ | ✅ 是 | 游戏资源(图片、音频等) |
| .godot/ | ❌ 否 | 自动生成的缓存 |
| export_presets.cfg | ⚠️ 可选 | 包含导出路径等本地设置 |
5.3 Git LFS 配置
# .gitattributes - 大文件使用 Git LFS
# 图片
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.svg filter=lfs diff=lfs merge=lfs -text
*.webp filter=lfs diff=lfs merge=lfs -text
# 音频
*.wav filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
# 3D 模型
*.glb filter=lfs diff=lfs merge=lfs -text
*.gltf filter=lfs diff=lfs merge=lfs -text
*.obj filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
# 字体
*.ttf filter=lfs diff=lfs merge=lfs -text
*.otf filter=lfs diff=lfs merge=lfs -text
6. 项目目录结构规范
6.1 推荐目录结构
my_game/
├── .godot/ # 引擎缓存(自动生成)
├── .git/ # Git 仓库
├── .gitignore # Git 忽略规则
├── .gitattributes # Git LFS 配置
├── project.godot # 项目配置
├── export_presets.cfg # 导出预设
│
├── scenes/ # 场景文件
│ ├── player/
│ │ ├── player.tscn
│ │ └── player.gd
│ ├── enemies/
│ ├── levels/
│ └── ui/
│
├── scripts/ # 纯脚本(无场景)
│ ├── autoload/ # 自动加载单例
│ ├── resources/ # 自定义资源类
│ └── utils/ # 工具函数
│
├── assets/ # 艺术资源
│ ├── sprites/ # 2D 精灵
│ ├── tilesets/ # 瓦片集
│ ├── audio/ # 音频文件
│ │ ├── music/
│ │ └── sfx/
│ ├── fonts/ # 字体
│ └── animations/ # 动画资源
│
├── shaders/ # 着色器文件
├── addons/ # 插件目录
└── builds/ # 构建输出目录
6.2 命名规范
| 类型 | 规范 | 示例 |
|---|
| 场景文件 | snake_case.tscn | player_character.tscn |
| 脚本文件 | snake_case.gd | player_controller.gd |
| 资源文件 | snake_case.tres | player_stats.tres |
| 类名 | PascalCase | PlayerController |
| 变量名 | snake_case | move_speed |
| 常量名 | SCREAMING_SNAKE_CASE | MAX_HEALTH |
| 函数名 | snake_case | take_damage() |
| 信号名 | snake_case | health_changed |
7. 多平台构建配置
7.1 Windows 配置
导出预设:Windows Desktop
├── 可执行文件名称:MyGame
├── 图标:icon.ico
├── 嵌入 PCK:true(单文件发布)
├── 代码签名:配置证书
└── 控制台:false(发布时隐藏控制台)
7.2 Android 配置
导出预设:Android
├── 包名:com.company.mygame
├── 最低 SDK:24 (Android 7.0)
├── 目标 SDK:34 (Android 14)
├── 签名密钥:配置 keystore
├── 图标:adaptive icon 配置
└── 屏幕方向:横屏/竖屏
# 检测平台并应用不同设置
func _ready() -> void:
match OS.get_name():
"Windows":
print("运行在 Windows")
"Linux":
print("运行在 Linux")
"Android":
print("运行在 Android")
# 移动端降低画质
ProjectSettings.set_setting(
"rendering/renderer/rendering_method",
"mobile"
)
"iOS":
print("运行在 iOS")
"Web":
print("运行在 Web")
8. 编辑器设置优化
8.1 编辑器性能设置
| 设置 | 路径 | 推荐值 |
|---|
| 缩略图生成 | 编辑器设置 > 文件系统 | 低配机器关闭 |
| 自动重新导入 | 编辑器设置 > 导入 | 大项目关闭 |
| 脚本自动补全 | 编辑器设置 > 文本编辑器 | 开启 |
| 着色器编辑器 | 编辑器设置 > Shader Editor | 开启语法高亮 |
8.2 快捷键自定义
编辑器设置 > 快捷键
常用自定义:
- 运行项目:F5 (默认)
- 运行场景:F6 (默认)
- 停止运行:F8 (默认)
- 切换脚本:Ctrl+Tab
- 查找文件:Ctrl+P
8.3 插件推荐
| 插件 | 功能 | 安装方式 |
|---|
| Gut | 单元测试框架 | Asset Library |
| Phantom Camera | 高级相机系统 | Asset Library |
| Dialogic | 对话系统 | Asset Library |
| LimboAI | 行为树 AI | Asset Library |
| Terrain3D | 3D 地形编辑 | GitHub |
9. 游戏开发场景
场景:多团队协作项目设置
# scripts/autoload/game_config.gd
extends Node
# 游戏配置单例 - Autoload
# 通过 项目 > 项目设置 > 自动加载 添加
const VERSION: String = "0.1.0"
const CONFIG_PATH: String = "user://settings.cfg"
# 游戏设置
var settings: Dictionary = {
"display": {
"fullscreen": false,
"resolution": Vector2i(1920, 1080),
"vsync": true,
},
"audio": {
"master_volume": 1.0,
"music_volume": 0.8,
"sfx_volume": 1.0,
},
"controls": {
"mouse_sensitivity": 0.3,
"vibration": true,
}
}
func _ready() -> void:
load_settings()
apply_settings()
func load_settings() -> void:
var config = ConfigFile.new()
if config.load(CONFIG_PATH) == OK:
for section in config.get_sections():
for key in config.get_section_keys(section):
settings[section][key] = config.get_value(section, key)
func save_settings() -> void:
var config = ConfigFile.new()
for section in settings:
for key in settings[section]:
config.set_value(section, key, settings[section][key])
config.save(CONFIG_PATH)
func apply_settings() -> void:
# 应用显示设置
if settings.display.fullscreen:
DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_FULLSCREEN)
else:
DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_WINDOWED)
# 应用音频设置
AudioServer.set_bus_volume_db(
AudioServer.get_bus_index("Master"),
linear_to_db(settings.audio.master_volume)
)
⚠️ 注意: user:// 路径在不同平台下指向不同位置,适合存储用户设置和存档。
10. 扩展阅读
上一章: 01 - Godot 4 简介与新特性
下一章: 03 - 编辑器界面与工作流