强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

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_methodforward_plus渲染方法(forward_plus/mobile/gl_compatibility)
rendering/renderer/rendering_method.mobilemobile移动端专用渲染方法
rendering/environment/defaults/default_clear_color#000000场景默认背景色
rendering/anti_aliasing/quality/msaa_2dDisabled2D 多重采样抗锯齿
rendering/anti_aliasing/quality/msaa_3dDisabled3D 多重采样抗锯齿
rendering/textures/canvas_textures/default_texture_filterLinear纹理过滤模式
# 运行时获取渲染设置
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_gravity9802D 重力加速度(像素/秒²)
physics/2d/default_gravity_vector(0, 1)2D 重力方向
physics/3d/default_gravity9.83D 重力加速度
physics/2d/physics_engineDEFAULT2D 物理引擎选择
physics/3d/physics_engineDEFAULT3D 物理引擎选择
physics/common/physics_ticks_per_second60物理帧率
# 自定义物理设置示例
# 在项目设置中修改重力后,在脚本中使用:

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_leftA, ←左摇杆左向左移动
move_rightD, →左摇杆右向右移动
jumpSpace按钮A (Xbox)跳跃
attack鼠标左键按钮X (Xbox)攻击
interactE按钮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_width1152视口宽度
size/viewport_height648视口高度
size/window_width_override0窗口宽度覆盖(0=不覆盖)
size/window_height_override0窗口高度覆盖
stretch/modedisabled拉伸模式
stretch/aspectignore宽高比处理
vsync/vsync_modeEnabled垂直同步
# 运行时窗口操作
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 版本
iOSBundle ID、证书、描述文件
WebHTML 模板、线程支持、导出图标
# 使用命令行导出
# 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.tscnplayer_character.tscn
脚本文件snake_case.gdplayer_controller.gd
资源文件snake_case.tresplayer_stats.tres
类名PascalCasePlayerController
变量名snake_casemove_speed
常量名SCREAMING_SNAKE_CASEMAX_HEALTH
函数名snake_casetake_damage()
信号名snake_casehealth_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行为树 AIAsset Library
Terrain3D3D 地形编辑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 - 编辑器界面与工作流