mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-23 03:04:29 +08:00
5d8fec2acd
- 修正 basic/01-environment.md 中的 C# 项目初始化图片路径 - 修正 basic/02-project-setup.md 中的 C# 支持初始化图片路径 - 修正 basic/02-project-setup.md 中的 NuGet 包管理图片路径 - 修正 basic/02-project-setup.md 中的全局类创建图片路径 - 修正 basic/03-counter-basic.md 中的计数器界面图片路径 - 修正 basic/03-counter-basic.md 中的运行效果图片路径 - 修正 basic/04-model-refactor.md 中的运行效果图片路径 - 修正 basic/06-utility-system.md 中的阈值提示图片路径 - 统一所有图片路径从 ../assets/basic-tutorial/ 指向 ../assets/basic/
353 lines
7.9 KiB
Markdown
353 lines
7.9 KiB
Markdown
---
|
||
prev:
|
||
text: '教程首页'
|
||
link: './index'
|
||
next:
|
||
text: '项目创建与初始化'
|
||
link: './02-project-setup'
|
||
---
|
||
|
||
# 第 1 章：环境准备
|
||
|
||
在开始使用 GFramework 之前，我们需要配置好开发环境。本章将指导你完成所有必要工具的安装和验证。
|
||
|
||
## 系统要求
|
||
|
||
### 操作系统
|
||
|
||
- **Windows**：Windows 10 或更高版本（推荐 Windows 11）
|
||
- **macOS**：macOS 10.15 Catalina 或更高版本
|
||
- **Linux**：主流发行版（Ubuntu 20.04+, Fedora 35+, Arch Linux 等）
|
||
|
||
### 硬件要求
|
||
|
||
- **CPU**：双核或更高（推荐四核）
|
||
- **内存**：8 GB RAM（推荐 16 GB）
|
||
- **存储**：至少 5 GB 可用空间
|
||
- **显卡**：支持 OpenGL 3.3 或更高
|
||
|
||
## 安装 .NET SDK
|
||
|
||
GFramework 基于 .NET 6.0+，需要先安装 .NET SDK。
|
||
|
||
### Windows
|
||
|
||
1. 访问 [.NET 官方下载页](https://dotnet.microsoft.com/download)
|
||
2. 下载 **.NET 6.0 SDK** 或更高版本
|
||
3. 运行安装程序，按照提示完成安装
|
||
4. 安装完成后，打开命令提示符或 PowerShell
|
||
|
||
### macOS
|
||
|
||
**方式一：使用官方安装包**
|
||
|
||
```bash
|
||
# 访问官网下载 .pkg 安装包
|
||
# https://dotnet.microsoft.com/download
|
||
```
|
||
|
||
**方式二：使用 Homebrew**
|
||
|
||
```bash
|
||
brew install --cask dotnet-sdk
|
||
```
|
||
|
||
### Linux
|
||
|
||
**Ubuntu/Debian**
|
||
|
||
```bash
|
||
# 添加 Microsoft 包仓库
|
||
wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
|
||
sudo dpkg -i packages-microsoft-prod.deb
|
||
rm packages-microsoft-prod.deb
|
||
|
||
# 安装 .NET SDK
|
||
sudo apt-get update
|
||
sudo apt-get install -y dotnet-sdk-6.0
|
||
```
|
||
|
||
**Fedora**
|
||
|
||
```bash
|
||
sudo dnf install dotnet-sdk-6.0
|
||
```
|
||
|
||
**Arch Linux**
|
||
|
||
```bash
|
||
sudo pacman -S dotnet-sdk
|
||
```
|
||
|
||
### 验证 .NET 安装
|
||
|
||
打开终端或命令提示符，运行：
|
||
|
||
```bash
|
||
dotnet --version
|
||
```
|
||
|
||
你应该看到类似以下输出：
|
||
|
||
```
|
||
6.0.428
|
||
```
|
||
|
||
或更高版本（如 7.0.x, 8.0.x）。
|
||
|
||
::: tip 提示
|
||
建议安装最新的 LTS（长期支持）版本。本教程兼容 .NET 6.0 及以上所有版本。
|
||
:::
|
||
|
||
## 安装 Godot 引擎
|
||
|
||
GFramework 的 Godot 集成需要 **Godot 4.5.1** 或更高版本，并且必须是 **.NET 版本**（不是标准版）。
|
||
|
||
### 下载 Godot
|
||
|
||
1. 访问 [Godot 官方下载页](https://godotengine.org/download)
|
||
2. 选择 **Godot 4.5.x - .NET** 版本
|
||
- **Windows**: 下载 `Godot_v4.5.x-stable_mono_win64.zip`
|
||
- **macOS**: 下载 `Godot_v4.5.x-stable_mono_macos.universal.zip`
|
||
- **Linux**: 下载 `Godot_v4.5.x-stable_mono_linux_x86_64.zip`
|
||
|
||
### 安装 Godot
|
||
|
||
**Windows**
|
||
|
||
1. 解压下载的 ZIP 文件
|
||
2. 将文件夹移动到合适的位置（如 `C:\Godot\`）
|
||
3. 双击 `Godot_v4.5.x-stable_mono_win64.exe` 启动
|
||
|
||
**macOS**
|
||
|
||
1. 解压下载的 ZIP 文件
|
||
2. 将 `Godot.app` 拖动到 `应用程序` 文件夹
|
||
3. 首次运行时，右键点击 → 打开（绕过安全检查）
|
||
|
||
**Linux**
|
||
|
||
1. 解压下载的 ZIP 文件
|
||
2. 添加可执行权限：
|
||
|
||
```bash
|
||
chmod +x Godot_v4.5.x-stable_mono_linux.x86_64
|
||
```
|
||
|
||
3. 运行：
|
||
|
||
```bash
|
||
./Godot_v4.5.x-stable_mono_linux.x86_64
|
||
```
|
||
|
||
### 配置 Godot .NET 支持
|
||
|
||
首次启动 Godot 时，编辑器会自动检测 .NET SDK。
|
||
|
||
1. 打开 Godot 编辑器
|
||
2. 点击菜单 **编辑器 → 编辑器设置**
|
||
3. 在左侧导航中找到 **Mono → Builds**
|
||
4. 确认 **Build Tool** 设置为 `dotnet CLI`
|
||
|
||
如果 Godot 提示找不到 .NET SDK，确保：
|
||
|
||
- .NET SDK 已正确安装
|
||
- 终端中能运行 `dotnet --version`
|
||
- 重启 Godot 编辑器
|
||
|
||
::: warning 注意
|
||
必须下载 **.NET (Mono) 版本** 的 Godot，标准版不支持 C# 开发。文件名中应包含 `mono` 字样。
|
||
:::
|
||
|
||
## 安装 IDE（可选但推荐）
|
||
|
||
虽然可以使用任何文本编辑器，但专业的 IDE 能大幅提升开发效率。
|
||
|
||
### Visual Studio 2022（推荐 Windows 用户）
|
||
|
||
1. 下载 [Visual Studio 2022 Community](https://visualstudio.microsoft.com/downloads/)（免费）
|
||
2. 安装时选择以下工作负载：
|
||
- **.NET 桌面开发**
|
||
- **游戏开发 → 使用 Unity 的游戏开发**（可选，提供更好的游戏开发工具）
|
||
3. 确保勾选 **.NET 6.0 SDK**
|
||
|
||
### JetBrains Rider（推荐跨平台用户）
|
||
|
||
1. 下载 [JetBrains Rider](https://www.jetbrains.com/rider/)
|
||
2. 安装并激活（提供 30 天试用，或使用社区许可证）
|
||
3. 首次启动时，Rider 会自动检测 .NET SDK
|
||
|
||
**优势**：
|
||
|
||
- 跨平台支持（Windows, macOS, Linux）
|
||
- 出色的代码补全和重构工具
|
||
- 原生支持 Godot 项目
|
||
|
||
### Visual Studio Code
|
||
|
||
1. 下载 [Visual Studio Code](https://code.visualstudio.com/)
|
||
2. 安装以下扩展：
|
||
- **C# (Microsoft)**
|
||
- **C# Dev Kit**
|
||
- **godot-tools**
|
||
|
||
::: tip IDE 选择建议
|
||
|
||
- **Windows 用户**：Visual Studio 2022 或 Rider
|
||
- **macOS/Linux 用户**：Rider 或 VS Code
|
||
- **轻量级需求**：VS Code
|
||
:::
|
||
|
||
## 环境验证
|
||
|
||
完成所有安装后，让我们创建一个测试项目来验证环境。
|
||
|
||
### 1. 创建测试控制台项目
|
||
|
||
打开终端，运行：
|
||
|
||
```bash
|
||
# 创建新的控制台项目
|
||
dotnet new console -n GFrameworkTest
|
||
cd GFrameworkTest
|
||
|
||
# 添加 GFramework 核心包
|
||
dotnet add package GeWuYou.GFramework.Core
|
||
|
||
# 编译测试
|
||
dotnet build
|
||
```
|
||
|
||
如果编译成功，说明 .NET 环境配置正确。
|
||
|
||
### 2. 创建测试 Godot 项目
|
||
|
||
1. 打开 Godot 编辑器
|
||
2. 点击 **新建项目**
|
||
3. 选择项目路径，命名为 `GodotTest`
|
||
4. **渲染器** 选择 **Forward+** 或 **Mobile**
|
||
5. 点击 **创建并编辑**
|
||
|
||
项目创建后，Godot 会提示初始化 C# 项目：
|
||
|
||
|
||
|
||
点击 **创建 C# 解决方案**，Godot 会自动生成 `.csproj` 文件。
|
||
|
||
### 3. 验证 Godot C# 支持
|
||
|
||
在 Godot 编辑器中：
|
||
|
||
1. 右键点击 **文件系统** 面板的根目录
|
||
2. 选择 **创建新脚本**
|
||
3. **语言** 选择 **C#**
|
||
4. 脚本名称输入 `TestScript.cs`
|
||
5. 点击 **创建**
|
||
|
||
如果脚本成功创建并打开外部编辑器，说明 Godot 和 .NET 集成正常。
|
||
|
||
### 4. 完整验证脚本
|
||
|
||
将以下代码粘贴到 `TestScript.cs`：
|
||
|
||
```csharp
|
||
using Godot;
|
||
using System;
|
||
|
||
public partial class TestScript : Node
|
||
{
|
||
public override void _Ready()
|
||
{
|
||
GD.Print("✅ Godot + .NET 环境配置成功！");
|
||
GD.Print($"✅ .NET 版本: {Environment.Version}");
|
||
GD.Print("✅ 准备开始使用 GFramework！");
|
||
}
|
||
}
|
||
```
|
||
|
||
在场景中添加一个 Node 节点，附加这个脚本，然后点击 **运行场景**（F6）。
|
||
|
||
如果在输出面板看到：
|
||
|
||
```
|
||
✅ Godot + .NET 环境配置成功！
|
||
✅ .NET 版本: 6.0.x
|
||
✅ 准备开始使用 GFramework！
|
||
```
|
||
|
||
恭喜！你的环境已经完全配置好了！
|
||
|
||
## 常见问题排查
|
||
|
||
### Godot 找不到 .NET SDK
|
||
|
||
**症状**：Godot 提示"无法找到 .NET SDK"
|
||
|
||
**解决方案**：
|
||
|
||
1. 确认终端中能运行 `dotnet --version`
|
||
2. 重启 Godot 编辑器
|
||
3. 检查 **编辑器设置 → Mono → Builds** 中的 .NET 路径
|
||
4. 尝试手动指定 .NET SDK 路径
|
||
|
||
### MSBuild 错误
|
||
|
||
**症状**：编译时提示 MSBuild 相关错误
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 清理并重新生成项目
|
||
dotnet clean
|
||
dotnet build
|
||
```
|
||
|
||
### macOS 安全限制
|
||
|
||
**症状**：macOS 阻止 Godot 运行
|
||
|
||
**解决方案**：
|
||
|
||
1. 右键点击 `Godot.app`
|
||
2. 选择 **打开**（不是双击）
|
||
3. 在弹出的对话框中点击 **打开**
|
||
4. 后续可以正常双击启动
|
||
|
||
### Linux 缺少依赖
|
||
|
||
**症状**：Linux 下 Godot 无法启动
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt-get install libxcursor1 libxinerama1 libxi6 libxrandr2 libgl1
|
||
|
||
# Fedora
|
||
sudo dnf install libXcursor libXinerama libXi libXrandr mesa-libGL
|
||
```
|
||
|
||
## 下一步
|
||
|
||
环境配置完成！现在你已经准备好开始使用 GFramework 了。
|
||
|
||
在下一章中，我们将：
|
||
|
||
- 创建一个新的 Godot 项目
|
||
- 引入 GFramework NuGet 包
|
||
- 搭建基础的项目架构
|
||
- 创建游戏入口点
|
||
|
||
👉 [第 2 章：项目创建与初始化](./02-project-setup.md)
|
||
|
||
---
|
||
|
||
::: details 本章检查清单
|
||
|
||
- [ ] .NET SDK 已安装并可以运行 `dotnet --version`
|
||
- [ ] Godot 4.5.1+ .NET 版本已安装
|
||
- [ ] IDE 已安装（Visual Studio / Rider / VS Code）
|
||
- [ ] 测试项目成功编译
|
||
- [ ] Godot 能够创建和运行 C# 脚本
|
||
:::
|