开发者

Geode 模组开发入门

Geode SDK 模组开发中文指南。环境搭建、创建第一个模组、核心概念介绍。

💡
适合谁？ 本教程适合有 C++ 基础的开发者。如果你不熟悉 C++，建议先学习基础知识再来。

开发环境搭建

Windows

1

安装 Visual Studio

下载并安装 Visual Studio 2022（Community 版免费）。

安装时选择 "使用 C++ 的桌面开发" 工作负载。

2

安装 CMake

下载并安装 CMake（3.20+）。

安装时选择"添加到系统 PATH"。

macOS

1

安装依赖

使用 Homebrew 安装必要工具：

brew install cmake ninja

确保已安装 Xcode Command Line Tools：

xcode-select --install

获取 Geode SDK

克隆 Geode SDK 仓库：

git clone https://github.com/geode-sdk/geode.git
cd geode

设置环境变量：

# Windows (PowerShell)
$env:GEODE_SDK = "path/to/geode"

# macOS/Linux
export GEODE_SDK="path/to/geode"

创建第一个模组

1

使用 CLI 创建项目

Geode 提供了命令行工具来快速创建模组项目：

geode new my-first-mod

这会创建一个包含基本结构的模组项目。

2

了解项目结构

创建的项目结构如下：

my-first-mod/
├── CMakeLists.txt        # CMake 构建配置
├── mod.json              # 模组元数据
└── src/
    └── main.cpp          # 主代码文件
3

编写代码

打开 src/main.cpp，你会看到一个基本的模组模板：

#include <Geode/Geode.hpp>

using namespace geode::prelude;

$on_mod(Loaded) {
    log::info("My first mod loaded!");
}

$on_mod(Loaded) 宏定义了模组加载时执行的代码。 这是最简单的 Hook —— 在模组加载时输出一条日志。

4

编译与测试

使用 CMake 构建项目：

mkdir build && cd build
cmake ..
cmake --build .

编译成功后，将生成的 .geode 文件复制到 GD 的 mods 目录： 

# Windows
%LocalAppData%/GeometryDash/geode/mods/

# macOS
~/Library/Application Support/GeometryDash/geode/mods/

启动 GD，在 Geode 界面中确认你的模组已加载。

mod.json 配置

mod.json 是模组的元数据文件，包含以下必填属性：

属性 说明 示例
geode Geode SDK 版本要求 "4.0.0"
id 模组唯一标识符 "com.example.my-mod"
version 模组版本号 "v1.0.0"
name 模组显示名称 "My First Mod"
developer 开发者名称 "Your Name"
description 模组描述 "A simple example mod"

Hook 机制

Hook 是 Geode 的核心功能，让你可以在游戏函数执行前后插入自定义代码。 使用 $modify 宏来定义 Hook： 

#include <Geode/Geode.hpp>
using namespace geode::prelude;

class $modify(MyPlayerHook, PlayerObject) {
    void playerDestroyed(bool p0) {
        // 在玩家死亡时执行自定义代码
        log::info("Player destroyed!");
        PlayerObject::playerDestroyed(p0);
    }
};

这个例子 Hook 了 PlayerObject::playerDestroyed 函数， 在玩家死亡时输出一条日志。

更多资源