【插件】协程

GameMaker 开发者之家2021/12/5插件教程

协程是由@jujuadams为GameMaker Studio 2.3.6及以上版本设计的一套在GML中异步执行代码的语法扩展

适用GM版本 : 2.3.6+

适用目标平台 ：除HTML5之外的一切平台。

下载连接：Githubopen in new window

常见问题解答

协程在哪些平台上有效？

除了HTML5之外的所有平台。我目前只在Windows上进行了测试。由于它是纯原生GML，所以应该可以直接使用。在我不经常测试的平台上，你可能会遇到一些边缘情况；如果你发现任何bug，请报告open in new window。

这个代码库的许可证是什么？我可以将它用于商业项目吗？

这个库是基于MIT许可证发布的open in new window。这意味着你可以将它用于任何目的，包括商业项目。如果你能在你的游戏中提到我的名字（Juju Adams）和/或表示感谢，那对我来说意义重大，但你没有义务这么做。

我认为你缺少了一个有用的功能，希望你能实现它！

太好了！请提交一个功能请求open in new window。功能请求使协程更加有趣，也给了我在公共交通上无聊时的思考素材。

我发现了一个bug，它既让我害怕又略微烦恼。解决这个问题的最佳方法是什么？

请提交一个bug报告open in new window。Juju每天都会检查GitHub，通常几天后就会发布bug修复。你也可以在Discord服务器open in new window上找到我，但这不能代替清晰的bug报告。

救命！我在编译时遇到了关于异步事件的错误。

由于GMS2.3.6更改了一些与异步事件相关的常量名称，GameMaker v2.3.6之前的版本将无法编译此库。你可以通过查找GM文档中的旧名称并替换它们来自己解决这个问题。

协程与 GMLiveopen in new window兼容吗？

我还没有测试过。请让我知道你的发现。

说到 YellowAfterlifeopen in new window，他也通过GMEdit实现了协程open in new window。这个库有何不同？

Vadim在GameMaker Studio 2.3引入匿名函数之前就实现了他的协程。它是一个非常聪明的技术解决方案，解决了旧版本GM中许多缺失的功能。幸运的是，现在GameMaker更加灵活，这个库充分利用了新功能来实现协程。

谁编写了代码？

这个库是由@jujuadamsopen in new window构建和维护的，他长期以来一直在研究GameMaker的内部机制。Juju参与了许多商业GameMaker游戏open in new window的开发。

许多宏的想法基于Katsaiiopen in new window在她著名（臭名昭著？）的宏黑客文章open in new window中提出的想法。shdwcatopen in new window也在库的公共发布前提供了一些建议，帮助指导了库的发展方向，她从编写自己的协程系统中学到了一些东西。

我可以向你捐款吗？你会开始一个Patreon吗？

感谢你愿意表示感谢——这对我个人来说意义重大——但我很幸运能从游戏开发中获得稳定的收入。我目前没有打算作为创作者加入Patreon。如果你想支持我的工作，可以在你的游戏中提到我，和/或在你选择的社交媒体平台上给我一个喊话。

协程简介

本节是一个关于协程如何帮助你制作游戏的高级描述。如果你想了解更技术性的描述，请参见 [[协程是如何执行的？]] 和 [[我们如何扩展GML？]]

当你编写代码并运行你的游戏时，你编写的代码是按顺序执行的，每个命令在前一个命令完成后立即执行。我们将代码存储在函数中，意图是程序将从一个函数移动到下一个函数，使游戏工作。当程序进入一个函数时，它必须完成整个函数（或至少到达一个 return 命令）后才能退出该函数并运行其他代码。这被称为“同步执行”，这是GameMaker的工作方式——代码是同步运行的，一行接一行，每帧数千行代码分布在数百个函数中。

异步函数的操作方式不同。异步函数不需要在程序离开该函数并做其他事情之前完全完成所有代码，更重要的是，异步函数可以从暂停的地方继续执行。这意味着你可以编写一些代码，在执行过程中允许整个程序去做其他事情，然后稍后再回到该函数继续执行。

此库允许你在GameMaker中编写可暂停的函数。这些可暂停的函数称为“协程”：一段可以在执行过程中暂停并在稍后继续的代码块。

许多语言原生支持编写异步代码，无论是作为核心语言特性，还是作为支持异步执行的库。GML属于后者。因此，有必要开发我们自己的系统来模拟支持异步函数的语言的特性和行为。从纯函数构建协程是笨拙且难以理解的，因此此库扩展了GML的语法，以便我们能够以更优雅的方式描述协程。

一个示例

让我们来看一个简单的例子：过场动画。

制作过场动画是一场噩梦，多年来人们花费了大量精力设计和构建不同的解决方案来解决过场动画问题。最常见的解决方案是使用一个大的 switch...case 语句来控制哪个实例在什么时候做什么。构建这些系统非常耗时，而且它们总是最终变得丑陋且难以管理。实际上，我们想要的过场动画函数是一个异步函数——一个可暂停的函数，它可以向游戏传递指令以动画化对象和显示文本，而不会阻止游戏的其余部分运行。

这里是一个过场动画的示例。稍后我们会详细解释发生了什么，但这应该会让你了解使用协程可以实现的功能：

function CutsceneFindMyFroggy()
{
	return CO_BEGIN
		// 防止玩家使用正常的控制移动
		oPlayer.inCutscene = true;
		
		// 让玩家走进房间
		WHILE (oPlayer.x != 55) THEN
			oPlayer.x = min(oPlayer.x + 2, 55);
			YIELD THEN
		END
		
		// 显示一些对话
		oTextbox.text = "我的青蛙在哪里？";
		oTextbox.expression = sPlayerSad;
		AWAIT keyboard_check_pressed(vk_space) THEN
		
		oTextbox.text = "...";
		
		// 为了喜剧效果暂停片刻
		DELAY 350 THEN // 毫秒
		
		oTextbox.text = "呱呱！";
		oTextbox.expression = sFrog;
		audio_play_sound(sndLonelyRibbit, 1, false);
		
		// 让青蛙跳进玩家的怀里
		WHILE (oFrog.x != 55) THEN
			oFrog.x = max(oFrog.x - 2, 55);
			YIELD THEN
		END
		
		oTextbox.text = "啊，她在这儿！谁是我的美丽两栖动物？";
		oTextbox.expression = sPlayerHappy;
		AWAIT keyboard_check_pressed(vk_space) THEN
		
		oTextbox.text = "呱呱！ :)";
		oTextbox.expression = sFrog;
		audio_play_sound(sndHappyRibbit, 1, false);
		AWAIT keyboard_check_pressed(vk_space) THEN
		
		// 清空文本框然后释放玩家
		oTextbox.text = "";
		player.inCutscene = false;
	CO_END
}

这种语法与普通的GML有些不同。特别值得注意的是使用了一些新的流程控制关键字。你可能以前见过 WHILE（虽然是小写的 while 循环命令），但很多其他全大写的命令是新的或不熟悉的。

CO_BEGIN 和 CO_END 定义了协程的起点和终点。这两个标记之间的所有内容构成了协程的代码。在整个协程中可以使用普通的GML，例如修改其他实例中的变量，但为了启用协程特定的行为，必须使用特殊的协程语法。THEN 和 END 是结构命令，它们的用法类似于打开 { 和关闭 } 大括号。

AWAIT 和 DELAY 是为方便提供的命令。AWAIT 会在那行代码暂停协程，直到条件返回 true。在上面的示例中，我们正在等待用户按下空格键，然后再将过场动画推进到后续指令。DELAY 会等待一段时间（以毫秒为单位）再继续。

最后，我们有一个不寻常的命令 YIELD。这个函数是协程的核心。当协程遇到 YIELD 命令时，它会立即跳出协程并允许你的游戏执行其他指令。在下一步中，协程将从 YIELD 命令处继续执行代码。

简化过场动画处理只是一个开始：协程还可以用于UI动画、复杂的网络协议、REST API和OAuth流程、多阶段视觉效果、异步保存/加载（主机开发所需）等。它们非常有用，现在它们已经在GameMaker中实现了。

协程是如何执行的？

本文档解释了协程执行的基本原理，以及如何使用函数调用生成协程。如果你想了解GML语法扩展的内部工作原理，请参见[我们如何扩展GML]

执行

此库中的协程执行围绕“协程根结构”进行，这是一个数据容器，既管理协程的执行又存储协程状态（协程执行时读写的变量）。每当你为协程编写代码时，它会自动作用于协程的范围内。这意味着你可以编写代码而不必担心是否意外访问了其他地方的数据——从某种意义上说，协程中的每个变量都是局部的。根结构也是执行协程方法open in new window的目标范围。

当创建一个协程时，它会在每帧处理的全局协程列表中注册。因此，协程会自动执行，无需额外的代码来运行它们。当然，你可以在任何时候使用相关方法取消open in new window或暂停open in new window协程。当一个协程完成open in new window时，它会从全局列表中移除，这意味着分配给它的内存将被垃圾回收，前提是你的代码没有引用它。

如上所述，协程每帧自动执行。不幸的是，GameMaker没有使这变得容易，我们实际上需要在某个实例的Step事件中挂钩，以便协程能够执行。这就是CoroutineEventHook()open in new window函数的目的。请注意，此函数还包含处理异步事件的代码——同样的问题，我们需要一个实例来执行事件钩子函数，以便协程接收到任何异步事件。

生成

当定义一个协程时，根结构会被赋予一系列需要执行的指令。指令可以简单地是“运行这段GML代码”，也可以是流程控制（循环和分支），或者是需要根结构等待进一步输入的行为。指令通过函数调用添加到根结构中，如下所示：

__CoroutineFunction(function() // 指令1
{
    i = 0;
});

__CoroutineWhile(function() // 指令2
{
    return (i < 6);
});

__CoroutineFunction(function() // 指令3
{
    show_debug_message("六条消息！");
    show_debug_message("(i=" + string(i) + ")");
});

__CoroutineYield(function() // 指令4
{
    return i;
});

__CoroutineEndLoop(); // 指令5

__CoroutineFunction(function() // 指令6
{
    show_debug_message("完成！");
});

我们称一系列添加指令到协程的函数调用为“生成器函数”。注意协程生成器函数需要一个步骤来启动while循环__CoroutineWhile()，并需要另一个指令来结束循环__CoroutineEndLoop()。这个生成器函数等价于以下标准的GML代码：

var i = 0;
while (i < 6)
{
    show_debug_message("六条消息！");
    show_debug_message("(i=" + string(i) + ")");
    //YIELD...THEN没有等价物！
}
show_debug_message("完成！");

通过比较生成器函数和它的标准GML等价代码，很明显标准GML更简洁！我们通过扩展GML中的语法解决了这个问题——有关更多信息，请参见[我们如何扩展GML]。

无论如何，协程是通过这些生成器函数调用构建的。这些函数所做的只是将数据推入一个指令数组，或更改将数据推入哪个指令数组。我们首先将数据写入协程的根结构，但当进入while循环时，我们开始将数据推入while循环中。在结束while循环后，我们返回将指令推入根结构的数组。

我们可以通过将其写成嵌套数组来进行可视化（为简单起见，我在这里简化了函数调用）：

根 : [
    i = 0,                        指令1
    while (i < 6) : [             指令2
        "六条消息！",              指令3
        "(i=" + string(i) + ")",
        YIELD i,                  指令4
    ],                            指令5
    "完成!"                       指令6
]

通过将指令分解为这些嵌套数组，我们可以将我们的协程解释为一个遍历其指令数组直到执行完所有指令的机器。数组中的每个指令本身都是一个机器。无论那个内部机器需要做什么，它必须完成其任务，然后外部机器才能继续遍历其指令数组。考虑到根结构在完成其指令时会完全停止，但while循环可能执行其循环数百次，因此显然存在多种类型的机器。

这些机器并不真实，毕竟它们是虚拟机open in new window，这是你可能听说过的一个术语。这里描述的是一种非常简单的VM，但它仍然是一个VM。

实际上，每个[命令]都有一个对应的机器。如果你感兴趣，可以通过查看库代码中的System文件夹来探究控制每种机器的代码。要使用这个库，理解所有细节并不是必需的，但我认为这仍然很有趣。

协程的主要特征（不仅仅是这个库）是它们可以暂停和恢复执行。回到我们的机器比喻，每台机器都有记忆：1）是否已完成，如果没有，2）协程暂停前它在做什么。这比听起来要简单。每个协程都有一个根结构，包含所有变量，因此它会保留，而每个机器可以存储其自己的状态跟踪变量。例如，我们示例中的while循环有一个变量跟踪它在指令数组中的位置。当协程恢复时，整个协程会找到哪个内部机器仍有工作要做，并使用该机器的状态变量恢复执行。

这解释了指令如何组织和执行，但具体的代码行呢？通常，对于虚拟机，每一行代码都会被处理。这实际上就是GameMaker的虚拟机工作方式open in new window，每一行代码都会被分解成一系列指令。这个库并没有做这么多的工作，因为我们可以让GameMaker为我们完成！我们可以利用GMS2.3的匿名函数特性（function() {}）来准备任意代码，以便在协程需要时执行。

我们如何扩展GML？

乍一看，向GML添加新语言特性似乎像是魔法。在编写库或者任何可互换代码时，我们通常优先考虑通过函数与系统交互。一些库鼓励你直接编辑变量，其他则使用着色器或表面来实现所需效果，许多库使用宏和枚举来表示该库特有的常量。

宏非常强大。宏实际上会直接将其值插入到代码中。通常，我们会将宏设置为一个字符串或数字，偶尔会将宏用作我们希望在多个地方使用的表达式。例如：

#macro ON_DIRECTX  ((os_type == os_windows) or (os_type == os_xboxone) or (os_type == os_xboxseriesxs) or (os_type == os_uwp))

然后，我们可以在代码库的其他地方使用ON_DIRECTX，根据游戏是否在DirectX平台上运行来执行不同的行为（这对于修复UV坐标的问题非常有用）。在这里，宏被用作封闭表达式——它是完全自包含的，可以在需要的地方插入而无需进一步考虑。

这个库使用了许多宏，但大多数这些宏不是自包含的。库中的宏会将不完整的表达式插入到代码中。为了生成有效的、完整的表达式，这些宏必须一起使用。乍一看这似乎是个问题，但它允许我们创建一种可以表达复杂结构的语法。

让我们来看看CO_BEGIN和CO_END是如何工作的。这两个宏在概念上是最复杂的，但理解它们的工作原理可以解释其他自定义语法宏如何配合在一起。

#macro CO_BEGIN  ((function(){__CoroutineBegin(function(){
#macro CO_END    });return __CoroutineEnd();})());

这是非常复杂的代码，使用了很多嵌套，难以阅读，所以让我们在上下文中使用它来使事情变得更容易理解。

function Example()
{
    return CO_BEGIN
        show_debug_message("What an incredible function.");
    CO_END
}

这段代码展开为：

function Example()
{
    // CO_BEGIN
    return ((function(){__CoroutineBegin(function(){
    
    //我们在协程中放置的单行代码
    show_debug_message("What an incredible function.");
    
    //CO_END
    });return __CoroutineEnd();})());
}

你可以看到，我们使用宏在协程的内容周围插入合法的GML。让我们进一步拆解实际进行的操作。我将重写一些内容，以便更容易看出生成函数如何返回新的协程根结构体。

function Example()
{
    var _generatorFunction = function()
    {
        //将一些代码添加到全局协程根结构体 (global.__coroutineNext) 中执行
        //在启动时创建一个全局空协程根结构体，并始终可用
        //在这个生成函数的末尾生成一个新的结构体，以便在下一个协程中使用
        __CoroutineBegin(function()
        {
            show_debug_message("What an incredible function.");
        });
        
        //返回我们刚刚添加代码的协程结构体
        return __CoroutineEnd();
    };
    
    //运行生成函数并返回其值（协程根结构体）
    return _generatorFunction();
}

这样，通过宏扩展，我们可以在GML中定义和使用协程。

宏的强大功能

使用宏的确可以做很多事情。仅通过两个简单的语句 CO_BEGIN 和 CO_END，我们就能在一个函数内部展开整个协程的功能！你会注意到，CO_BEGIN 以 __CoroutineFunction(function() { 结尾，而 CO_END 以 }); 开始。这使得这两个宏能够用于将代码封装在一个函数内部。这是这个库中宏的一个重复模式：一个宏要么是开启一个新函数，要么是关闭一个函数。

让我们通过引入另外三个宏来使我们的示例更加复杂。

#macro REPEAT  });__CoroutineRepeat(function(){return 
#macro THEN    });__CoroutineThen(function(){
#macro END     });__CoroutineEndLoop(function(){

接下来是协程本身的示例：

请注意，在这里使用 REPEAT 5 THEN ... END 是完全不必要的，repeat(5) {} 就足够了。REPEAT（以及 WHILE / IF / FOREACH）只有在循环中包含 YIELD 命令时才是必需的。我们在这里使用协程版本的循环仅作为示例。

function Example()
{
    return CO_BEGIN
        show_debug_message("What an incredible function.");
        REPEAT 5 THEN
            show_debug_message("Wow!");
        END
    CO_END
}

这段代码展开为以下的生成函数：

function Example()
{
    // CO_BEGIN
    var _generatorFunction = function()
    {
        __CoroutineBegin(function()
        {
            // 第一行代码
            show_debug_message("What an incredible function.");
        
            // REPEAT
        });
        __CoroutineRepeat(function()
        {
            return 5; // 5 来自 REPEAT 和 THEN 之间的数字
        
            // THEN
        });
        __CoroutineThen(function()
        {
            // 第二行代码
            show_debug_message("Wow!");
        
            // END
        });
        __CoroutineEndLoop(function()
        {
        
            // CO_END
        });
        
        // 返回我们刚刚添加代码的协程结构体
        return __CoroutineEnd();
    };
    
    // 运行生成函数并返回其值（协程根结构体）
    return _generatorFunction();
}

注意最后一个函数是空的。这个宏系统的一个特性就是这种情况很常见！

现在，应该可以清楚地看到这些宏如何作为不完整的表达式链接在一起以生成有效的GML。实际上，这些宏并没有做比其他库中的函数调用更多的事情。它们的强大之处在于如何隐藏功能组件的细节，从而使编写代码时不被屏幕上的函数调用混淆。

宏示例总结

宏的使用实际上是为了隐藏复杂的函数调用，使得代码更加简洁。下面是宏展开的代码：

function Example()
{
    // CO_BEGIN
    var _generatorFunction = function()
    {
        __CoroutineBegin(function()
        {
            show_debug_message("What an incredible function.");
        });
        __CoroutineRepeat(function()
        {
            return 5; // 5 是 REPEAT 和 THEN 之间的数字
        });
        __CoroutineThen(function()
        {
            show_debug_message("Wow!");
        });
        __CoroutineEndLoop(function()
        {
        });
        return __CoroutineEnd();
    };
    
    return _generatorFunction();
}

通过宏，我们可以在GML中实现复杂的协程行为，而不必显式地处理大量的底层函数调用和管理代码。宏的设计使得复杂的功能变得易于使用，帮助开发者集中精力在实际的逻辑和功能实现上。