很多刚开始用 Godot 做 3D 游戏的朋友都会在某个阶段遇到同一个问题游戏里头场景切换时画面突然卡住或者黑屏几秒钟然后新场景才“哐当”一下出现。如果你只是做了几个小 Demo可能还感觉不明显。但一旦场景里的模型、贴图、材质多起来或者你开始做大地图、多关卡游戏这种卡顿会直接毁掉玩家的沉浸感。这一篇教程就是来解决这个问题的。我们会从 Godot 4.x 的资源异步加载机制讲起带你把“场景切换卡顿”优化成“带进度条的流畅过渡”。你不需要会 C#不需要懂底层线程原理只要跟着步骤走就能在自己的项目里跑通一整套异步加载流程。本文的完整内容包括为什么同步加载会让游戏卡顿它卡在哪个环节Godot 的ResourceLoader异步加载 API 怎么用核心参数是什么如何手写一个带进度条和提示文字的加载过渡界面从写代码到验证效果的完整流程新手最容易踩的坑以及工程上的最佳实践。好了直接开始。1. 这篇文章真正要解决的问题先说结论Godot 的异步资源加载核心并不是“让加载变快”而是“让加载不再堵住主线程”。很多新手容易误解这一点。他们以为用了异步加载场景切换就会变快loading 进度条会刷刷往前走。实际上资源本身的总量没有变硬盘读取的时间也没有变异步加载真正改变的是加载工作不再由游戏主线程一个人扛而是分散到后台线程里执行。这里需要先建立一个基础认知。Godot 的游戏逻辑、渲染、输入处理全都跑在主线程上。如果你在主线程里调用load()或者ResourceLoader.load()加载大资源时主线程就被阻塞住了。表现是什么画面停止刷新、动画卡住、按键没反应看起来就像游戏“死了”几秒钟。这也就是为什么很多游戏在切换场景时必须专门做一个过渡界面。不是因为他们喜欢让玩家看进度条而是必须要有一个放 loading 界面的窗口期让后台把资源准备好。所以这篇文章真正教你的是两件事第一用 Godot 官方的ResourceLoader异步加载接口把资源加载放到后台线程执行 第二在主线程等待过程中用一个“过渡界面”遮住画面并展示真实加载进度让玩家知道游戏还在正常工作。读完本文你能在 Godot 4.x 里独立实现一个完整的异步加载过渡系统并且知道它为什么能解决卡顿、以及哪些情况下它依然不能解决卡顿。2. 基础概念与核心原理2.1 先说清楚什么是异步加载“异步”这个词听起来很高端实际上它描述的是一个非常朴素的场景。同步加载就是“排队办事”。主线程在柜台前排队资源没加载完它不能走。哪怕队列前面还有一堆程序要执行也得等这个资源加载完。同步加载的好处是逻辑简单写完就同步拿到资源对象立刻能用。坏处就是大资源会让游戏冻结。异步加载就是“叫号办事”。主线程把加载任务丢给后台线程然后继续干自己的事。后台线程加载完后给一个“完成”的提醒。主线程收到提醒后再取出资源使用。在 Godot 4.x 中实现异步加载的官方 API 是ResourceLoader的下面三件套ResourceLoader.load_threaded_request(path, type, use_sub_threads) ResourceLoader.load_threaded_get_status(path, progress) ResourceLoader.load_threaded_get(path)你可能也见过ResourceLoader.load()这是同步加载接口本文后面会拿它做对比实验。2.2 三个核心 API 的作用load_threaded_request()是发起加载请求。调用后Godot 会开启后台线程加载指定路径的资源。这个方法会立即返回不阻塞主线程。它的三个参数需要理解清楚path资源路径。注意这里只接受文件路径不接受单个资源的 UID。type资源类型也就是这个路径上的资源“应该是什么类型”。如果你不确定可以让系统直接推断但有时候显式写上 BufferedTexture、PackedScene 之类的类型加载调度会更有针对性。use_sub_threads是否允许这个资源内部再拆分成多个子线程进行加载。这是一个优化项不是必填项但理解它的语义对排查问题有帮助。load_threaded_get_status()用于查询加载状态。它返回一个枚举值常见的有THREAD_LOAD_IN_PROGRESS还在加载中。THREAD_LOAD_LOADED加载完成可以取出资源。THREAD_LOAD_FAILED加载失败通常路径不对或文件损坏。THREAD_LOAD_INVALID_RESOURCE请求时传参有误这个状态需要检查调用方式。它还有一个非常关键的重载形式传入一个progress数组里面会返回每个线程上的加载进度百分比。格式上需要注意它返回的不是一个 Float而是一个数组新手经常在这一步写错。load_threaded_get()是取出资源。只有在状态是THREAD_LOAD_LOADED后调用才能安全拿到资源。取出之后可以像普通load()出来的资源一样使用。2.3 为什么要用过渡界面异步加载把资源加载放到了后台线程但主线程在等待期间游戏画面仍然在正常刷新。这个时候如果不做处理玩家会看到旧场景的画面静止在那里或者看到奇怪的闪烁。于是过渡界面就产生了两个作用第一个作用是遮丑。用一张 UI 界面盖住整个画面玩家的注意力被引导到“加载进度”上不会被半加载状态的场景吓到。第二个作用是提供状态。玩家可以根据进度条判断“还要等多久”减少等待焦虑。如果进度条卡住不动玩家也能尽早发现异常而不是以为游戏崩溃了。所以异步加载和过渡界面是一对组合拳。一个负责后台加载资源一个负责前台等待与展示状态。少了任何一个体验都不完整。3. 环境准备与前置条件在开始写代码之前先确认你的运行环境。3.1 版本要求本教程的代码和 API 以Godot 4.x为准推荐使用 4.2 以上版本。特别提醒一下load_threaded_request()这一组线程加载 API 在 Godot 3.x 中不存在如果你用的是 Godot 3.x请先升级到 Godot 4.x 再继续阅读。版本请以实际项目为准本文重点演示通用思路。3.2 编辑器版本打开 Godot 项目管理器确认你的版本号。只要是大版本为 4 就可以。如果编辑器界面和本文截图不完全一致优先以你自己的版本为准。3.3 语言支持本文全部使用 GDScript。不需要 C#不需要外部插件Godot 自带的编辑器就能完成全部操作。3.4 项目结构约定为了后面演示方便我们先约定一个最简单项目结构你可以在实际项目中替换成你自己的路径res:// ├── scenes/ │ ├── main.tscn │ ├── loading_screen.tscn │ ├── level_2.tscn │ └── level_3.tscn └── scripts/ ├── main.gd └── loading_screen.gd其中main.tscn是入口场景负责启动加载流程并显示过渡界面level_2.tscn和level_3.tscn是我们要测试加载的目标场景。如果你只是为了学习也可以只准备两个简单的 3D 场景目标场景里随便放几个节点就行。关键是路径要一致、脚本挂载正确。4. 同步加载的问题演示在写异步加载之前我建议你先亲手做一次同步加载实验。这不是浪费时间而是为了让你用肉眼看到“卡顿到底卡在哪”。4.1 准备两个测试场景先创建一个 3D 场景保存为level_2.tscn。往里面丢一个CSGBox3D或者一个简单的MeshInstance3D再放一个方向光。这个场景越简单越好只要保证它存在即可。再创建一个level_3.tscn同样放几个节点。为什么要两个场景因为等一下我们会在两个场景之间来回切换你才能对比出异步加载的切换过程有多顺滑。4.2 同步加载的脚本写法接下来创建一个main.gd挂在main.tscn的根节点上。脚本里写一个同步切换场景的方法## 脚本路径scenes/main.gd extends Node3D ## 需要加载的下一个场景路径 export var next_scene_path: String res://scenes/level_2.tscn ## 触发同步切换场景 func _on_switch_pressed() - void: # 同步加载目标场景主线程会被阻塞 var packed_scene: PackedScene load(next_scene_path) get_tree().change_scene_to_packed(packed_scene)在这段脚本里load()就是同步加载。它执行时主线程会一直等资源加载完期间画面不刷新游戏看起来就像卡住了一样。你的项目里肯定已经有一个“切换场景”的按钮或者按键把它连接到这个方法上。点击按钮然后观察游戏画面。如果你准备的目标场景足够大或者资源文件不在缓存中画面上会出现一个明显的停顿这就是同步加载阻塞主线程的表现。如果场景太小、加载太快你看不到明显卡顿也是正常的。这种情况下可以在目标场景里加入一些比较大的资源文件比如大尺寸贴图或者多放几个模型节点让加载时间变长卡顿感就会被放大了。这个实验的目的是让你对“主线程阻塞”有一个直观感受。很多新手一开始写的游戏规模小加载场景不到一秒所以就认为同步加载没毛病。但实际上当项目规模一大或者目标平台从电脑变成中低端手机同样的同步加载代码就会暴露出严重问题。5. 异步加载核心代码实现接下来进入正题把上面的同步加载换成异步加载。5.1 请求加载目标场景异步加载的第一步不是获取资源而是发起加载请求。我们用ResourceLoader.load_threaded_request()把资源路径发给后台线程。这一步立即返回主线程可以继续执行其他逻辑。## 脚本路径scenes/main.gd extends Node3D ## 下一个场景的路径 export var next_scene_path: String res://scenes/level_2.tscn ## 是否已经发起了加载请求 var _load_started: bool false ## 发起异步加载请求 func _on_switch_pressed() - void: if _load_started: return _load_started true # 后台线程开始加载目标场景 ResourceLoader.load_threaded_request( next_scene_path, PackedScene, true )这里需要解释参数的含义。第一个参数是路径就是res://开头的资源路径。第二个参数PackedScene是资源类型。它相当于告诉 Godot我要加载的是一个场景文件请用场景解析器处理它。如果你加载的是贴图这里可以写Texture2D。如果不确定类型也可以传空字符串让 Godot 根据文件扩展名推断。但从工程习惯来说建议尽量显式传类型有助于提前暴露路径写错的低级问题。第三个参数true表示允许使用子线程做内部加载。这是一个经验性的建议值。对于普通 3D 场景开启子线程能更充分地利用多核 CPU。但要注意有些自定义资源或者第三方资源格式并不支持子线程加载遇到加载崩溃时这是排查重点之一。5.2 查询加载状态加载请求发出去之后我们需要在每一帧去检查后台线程的状态直到加载完成。Godot 提供了ResourceLoader.load_threaded_get_status()方法传入路径和进度数组就能拿到当前加载状态。## 每一帧检查加载状态 func _process(_delta: float) - void: if not _load_started: return var progress: Array [] var status ResourceLoader.load_threaded_get_status( next_scene_path, progress ) match status: ResourceLoader.THREAD_LOAD_IN_PROGRESS: # 还在加载可以读取进度 var percent : 0.0 if progress.size() 0: percent float(progress[0]) * 100.0 print(加载进度: %.1f%% % percent) ResourceLoader.THREAD_LOAD_LOADED: # 加载完成可以取出场景 _load_started false _load_and_switch_scene() ResourceLoader.THREAD_LOAD_FAILED: # 加载失败 push_error(异步加载失败: next_scene_path) _load_started false这里有一个新手很容易踩的坑load_threaded_get_status()的第二个参数需要的是一个数组而进度值会写入数组的第一个元素中。很多刚接触的人会直接写var progress : 0.0然后传progress结果报错或者取不到进度。要记住var progress: Array []进度数组里元素的含义是按“线程”排列的。如果你在请求时设置了use_sub_threads true进度数组里可能出现多个元素代表不同线程上的加载进度。实际使用时取第一个元素看整体进度通常就够了。当状态变为THREAD_LOAD_LOADED说明资源已经加载到内存里了下一步就是取出来使用。5.3 取出并切换场景加载完成后用load_threaded_get()取出PackedScene然后像普通场景一样切换。## 加载完成切换场景 func _load_and_switch_scene() - void: var packed_scene: PackedScene ResourceLoader.load_threaded_get( next_scene_path ) if packed_scene: get_tree().change_scene_to_packed(packed_scene) else: push_error(取出的场景为空)这里有个细节load_threaded_get()只有在状态变为THREAD_LOAD_LOADED之后调用才是安全的。如果你在加载中调用会得到一个异常。所以上面的代码里我们是在_process()里确认状态之后才调用取出方法顺序不能反过来。到这里异步加载的最核心最小闭环已经完成了。如果你现在运行项目在场景切换时画面不会因为加载大场景而卡死。你的游戏会在后台加载新场景加载完之后再切换过去。但这个方案还不够完整因为玩家在等待期间看到的还是旧场景的画面。如果加载时间较长玩家会以为游戏出了问题。所以下一步我们给它加一个正式的过渡界面。6. 加载过渡界面设计与进度显示过渡界面听起来复杂本质上就是一套全屏 UI一个背景一个进度条一个进度百分比文字可能再加一行加载提示。它不参与游戏逻辑游戏逻辑在等待期间也不会真的“跑”只是主循环依然在刷新UI 依然能正常显示和更新。6.1 搭建过渡界面场景新建一个场景根节点选择CanvasLayer命名为LoadingScreen保存为loading_screen.tscn。CanvasLayer很关键。它是独立于 3D 世界之外的 UI 层不会受摄像机影响也不会被 3D 场景遮挡。哪怕你在加载新场景的瞬间切换了当前场景CanvasLayer的 UI 依然能正常显示因为它不属于任何具体 3D 场景。在这个根节点下依次添加以下子节点一个ColorRect铺满整个屏幕作为背景遮罩防止旧场景的半加载画面漏出来。一个ProgressBar命名为LoadBar用来展示加载进度min_value设为 0max_value设为 100show_percentage可以关闭因为我们自己写文字显示百分比。一个Label命名为ProgressLabel显示如“加载中 45%”这样的文字。一个Label命名为TipLabel显示一些固定的提示文案比如“正在加载新区域请稍候”。为了让这个 UI 场景能独立运行测试建议在Project - Project Settings - Main Scene中先维持main.tscn作为主场景仅在需要验证 UI 时临时把loading_screen.tscn设为主场景。6.2 在入口场景中动态创建过渡界面不推荐在主场景里放一个隐藏的过渡界面节点然后通过切换可见性来控制因为这样会让主场景的节点树变得混乱。更干净的做法是在需要加载时用代码动态实例化过渡界面用完再释放。下面我们在main.gd中动态创建过渡界面## 脚本路径scenes/main.gd extends Node3D export var next_scene_path: String res://scenes/level_2.tscn ## 过渡界面的场景 export var loading_screen_scene: PackedScene var _load_started: bool false var _loading_screen_instance: CanvasLayer null ## 触发场景切换 func _on_switch_pressed() - void: if _load_started: return _load_started true # 显示过渡界面 _show_loading_screen() # 发起异步加载 ResourceLoader.load_threaded_request( next_scene_path, PackedScene, true ) ## 动态创建并显示过渡界面 func _show_loading_screen() - void: if loading_screen_scene null: return _loading_screen_instance loading_screen_scene.instantiate() add_child(_loading_screen_instance)你需要做的额外操作是在main.tscn中把loading_screen.tscn拖到main.gd的loading_screen_scene导出属性上。这样代码里才能实例化它。6.3 更新进度条然后在_process()里的加载过程中把进度数值同步给过渡界面中的ProgressBar和Label。## 每一帧更新加载状态与 UI func _process(_delta: float) - void: if not _load_started: return var progress: Array [] var status ResourceLoader.load_threaded_get_status( next_scene_path, progress ) match status: ResourceLoader.THREAD_LOAD_IN_PROGRESS: var percent : 0.0 if progress.size() 0: percent float(progress[0]) * 100.0 _update_loading_progress(percent) ResourceLoader.THREAD_LOAD_LOADED: _load_started false _load_and_switch_scene() ResourceLoader.THREAD_LOAD_FAILED: push_error(异步加载失败: next_scene_path) _load_started false ## 更新过渡界面上的进度显示 func _update_loading_progress(percent: float) - void: if _loading_screen_instance null: return var bar: ProgressBar _loading_screen_instance.get_node(LoadBar) var label: Label _loading_screen_instance.get_node(ProgressLabel) bar.value percent label.text 加载中 %d%% % int(percent)这里用get_node()直接按路径获取子节点方便快捷。如果你用的是onready声明变量需要确保过渡界面实例化后再获取否则拿到的节点是空的。6.4 加载完成后回收过渡界面场景切换完成后过渡界面就没有存在意义了。最好是在切换前把它从场景树中移除并释放以免其内容残留在新场景中。修改_load_and_switch_scene()## 加载完成切换场景 func _load_and_switch_scene() - void: var packed_scene: PackedScene ResourceLoader.load_threaded_get( next_scene_path ) if packed_scene: # 先移除过渡界面 if _loading_screen_instance: _loading_screen_instance.queue_free() _loading_screen_instance null get_tree().change_scene_to_packed(packed_scene) else: push_error(取出的场景为空请检查资源路径和类型)到这里一个完整的异步加载 过渡界面流程就通了。运行项目点击切换按钮你应该能看到进度条出现然后当进度达到 100% 时场景平滑切换过去。7. 常见问题与排查思路我用 Godot 做异步加载时遇到过一些非常典型的问题。这里整理成表格方便你直接对照排查。问题现象可能原因排查方式解决方案load_threaded_get_status传入进度变量时报错把进度参数写成了 Float而不是 Array检查progress变量的类型声明var progress: Array []进度一直为 0 或者不更新目标场景很小加载速度极快_process里根本来不及看到进度更新在_process中打印状态给目标场景加一个大资源人为拉长加载时间加载完成后取出的场景为 null路径写错或者资源类型传错打印next_scene_path确认文件确实存在检查res://路径拼写建议在文件系统面板里复制路径设置use_sub_threadstrue后崩溃某些第三方资源或自定义资源不支持子线程加载把use_sub_threads改为false测试对特定资源显式关闭子线程或者换成引擎内置资源格式过渡界面出现后画面仍会闪烁过渡界面的ColorRect没有完全覆盖屏幕或者层级不对检查ColorRect的锚点设置将ColorRect的 anchors 设为全屏拉伸切换场景后过渡界面依然存在过渡界面没有被释放或者它添加到了根节点以外的地方在切换前调用queue_free()确保_load_and_switch_scene()中先释放界面再切换异步加载请求了同一个路径多次按钮可以重复点击触发了多次请求检查_load_started标志位在发起请求前加状态锁防止重复请求场景加载完成时进度条显示 99% 然后跳 100%部分资源的解析发生在最后的load_threaded_get()中这属于正常现象进度只代表资源读取在实际项目中可以取98%封顶或额外展示“进入场景中”文案上面这些问题一半是 API 使用错误一半是并发场景下资源调度的常见现象。建议你遇到问题先看错误日志Godot 的push_error()和输出面板会给出非常明确的指向。8. 最佳实践与工程建议流程跑通之后再从工程角度聊几个长期维护需要注意的点。8.1 用“资源队列”统一管理加载任务在真实项目中你不可能每个场景都单独写一遍异步加载逻辑。更好的做法是抽象出一个“加载管理器”用单例或自动加载节点统一管理一个资源请求队列一个加载状态查询接口一个进度回调接口统一的失败重试策略。这样每个 UI 界面只需调用LoadingManager.load_scene(path, callback)不用关心底层是同步还是异步排查问题也更加集中。8.2 区分“切换场景”和“加载资源”异步加载不只用于场景切换它也可以用于加载单个资源比如贴图、音频、模型。当你在大世界里动态出现新物体时完全可以在物体出现前几秒开始后台加载资源时间到了再实例化物体玩家感知不到任何卡顿。这比全都集中到切换场景时再加载要好得多。8.3 注意 UI 层与场景树的挂载关系过渡界面最好挂在CanvasLayer下而不是挂在当前 3D 场景的某个节点下。原因很简单3D 场景会被切换走过渡界面如果挂在这个场景下切换时会一起销毁你还没来得及显示新场景画面就闪黑了。用CanvasLayer可以保证 UI 独立于任何 3D 场景。进一步地你甚至可以把过渡界面做成全局自动加载节点的一部分永远挂在场景树根部这样无论场景怎么切换加载界面都能稳定工作。8.4 进度条封顶处理异步加载进度并不是完全平滑的最后那个“收尾阶段”常常会有跳变。实际项目中很多团队会把进度条显示值封顶在 98%然后显示“正在进入场景”之类的文字等场景真正切换时再瞬间补满。这个小技巧可以避免玩家在 99% 停留过久而产生焦虑。8.5 加载失败的兜底策略不要只在失败时打一行错误信息。实际项目中你应该提供一个兜底方案比如显示“加载失败点击重试”按钮或者自动回退到上一个安全的场景。游戏发到正式用户那里不可能保证每个用户的机器环境和资源文件都完整。加载失败是会发生的事。提前做好失败处理会让项目整体稳定性上一个台阶。8.6 不要在加载过程中修改正在加载的资源load_threaded_request()启动后如果在同一帧里又对同一个资源做了其他操作可能会引发不可预知的报错。稳妥的做法是在一个加载任务完成后再对资源进行实例化、修改属性、释放引用等操作。9. 总结与后续学习方向这一节的内容其实只讲透了一个点不要在主线程同步加载大资源把加载交给后台线程同时用一个过渡界面把等待过程变得可感知、可接受。你应该已经掌握了同步加载与异步加载对主线程影响的本质区别ResourceLoader.load_threaded_request()、load_threaded_get_status()、load_threaded_get()三个核心 API 的正确用法用CanvasLayer搭建独立过渡界面并动态显示真实加载进度从发起加载、更新进度、取出场景到释放过渡界面的完整闭环。接下来可以继续深挖的方向我建议按顺序来把过渡界面做成可复用的“加载管理器”加入负载策略、失败重试、预加载机制学习ResourceLoader对单个资源的异步加载比如异步加载贴图用于大厅场景的渐进式显示了解 Godot 的change_scene_to_packed()与手动移除实例化节点后add_child()的区别这会影响你如何设计复杂场景切换尝试在异步加载之后加入一个短暂的淡入淡出效果让场景切换更有质感。最后提醒一句在新手阶段异步加载看起来像是“没必要的复杂度”但随着资源量增长你会越来越依赖它。建议现在就把这套过渡界面搭进你的项目里。等哪一天你的场景复杂到切换时不再卡顿你会感谢今天这个决定。
Godot 4异步资源加载实战：解决场景切换卡顿与进度条过渡
很多刚开始用 Godot 做 3D 游戏的朋友都会在某个阶段遇到同一个问题游戏里头场景切换时画面突然卡住或者黑屏几秒钟然后新场景才“哐当”一下出现。如果你只是做了几个小 Demo可能还感觉不明显。但一旦场景里的模型、贴图、材质多起来或者你开始做大地图、多关卡游戏这种卡顿会直接毁掉玩家的沉浸感。这一篇教程就是来解决这个问题的。我们会从 Godot 4.x 的资源异步加载机制讲起带你把“场景切换卡顿”优化成“带进度条的流畅过渡”。你不需要会 C#不需要懂底层线程原理只要跟着步骤走就能在自己的项目里跑通一整套异步加载流程。本文的完整内容包括为什么同步加载会让游戏卡顿它卡在哪个环节Godot 的ResourceLoader异步加载 API 怎么用核心参数是什么如何手写一个带进度条和提示文字的加载过渡界面从写代码到验证效果的完整流程新手最容易踩的坑以及工程上的最佳实践。好了直接开始。1. 这篇文章真正要解决的问题先说结论Godot 的异步资源加载核心并不是“让加载变快”而是“让加载不再堵住主线程”。很多新手容易误解这一点。他们以为用了异步加载场景切换就会变快loading 进度条会刷刷往前走。实际上资源本身的总量没有变硬盘读取的时间也没有变异步加载真正改变的是加载工作不再由游戏主线程一个人扛而是分散到后台线程里执行。这里需要先建立一个基础认知。Godot 的游戏逻辑、渲染、输入处理全都跑在主线程上。如果你在主线程里调用load()或者ResourceLoader.load()加载大资源时主线程就被阻塞住了。表现是什么画面停止刷新、动画卡住、按键没反应看起来就像游戏“死了”几秒钟。这也就是为什么很多游戏在切换场景时必须专门做一个过渡界面。不是因为他们喜欢让玩家看进度条而是必须要有一个放 loading 界面的窗口期让后台把资源准备好。所以这篇文章真正教你的是两件事第一用 Godot 官方的ResourceLoader异步加载接口把资源加载放到后台线程执行 第二在主线程等待过程中用一个“过渡界面”遮住画面并展示真实加载进度让玩家知道游戏还在正常工作。读完本文你能在 Godot 4.x 里独立实现一个完整的异步加载过渡系统并且知道它为什么能解决卡顿、以及哪些情况下它依然不能解决卡顿。2. 基础概念与核心原理2.1 先说清楚什么是异步加载“异步”这个词听起来很高端实际上它描述的是一个非常朴素的场景。同步加载就是“排队办事”。主线程在柜台前排队资源没加载完它不能走。哪怕队列前面还有一堆程序要执行也得等这个资源加载完。同步加载的好处是逻辑简单写完就同步拿到资源对象立刻能用。坏处就是大资源会让游戏冻结。异步加载就是“叫号办事”。主线程把加载任务丢给后台线程然后继续干自己的事。后台线程加载完后给一个“完成”的提醒。主线程收到提醒后再取出资源使用。在 Godot 4.x 中实现异步加载的官方 API 是ResourceLoader的下面三件套ResourceLoader.load_threaded_request(path, type, use_sub_threads) ResourceLoader.load_threaded_get_status(path, progress) ResourceLoader.load_threaded_get(path)你可能也见过ResourceLoader.load()这是同步加载接口本文后面会拿它做对比实验。2.2 三个核心 API 的作用load_threaded_request()是发起加载请求。调用后Godot 会开启后台线程加载指定路径的资源。这个方法会立即返回不阻塞主线程。它的三个参数需要理解清楚path资源路径。注意这里只接受文件路径不接受单个资源的 UID。type资源类型也就是这个路径上的资源“应该是什么类型”。如果你不确定可以让系统直接推断但有时候显式写上 BufferedTexture、PackedScene 之类的类型加载调度会更有针对性。use_sub_threads是否允许这个资源内部再拆分成多个子线程进行加载。这是一个优化项不是必填项但理解它的语义对排查问题有帮助。load_threaded_get_status()用于查询加载状态。它返回一个枚举值常见的有THREAD_LOAD_IN_PROGRESS还在加载中。THREAD_LOAD_LOADED加载完成可以取出资源。THREAD_LOAD_FAILED加载失败通常路径不对或文件损坏。THREAD_LOAD_INVALID_RESOURCE请求时传参有误这个状态需要检查调用方式。它还有一个非常关键的重载形式传入一个progress数组里面会返回每个线程上的加载进度百分比。格式上需要注意它返回的不是一个 Float而是一个数组新手经常在这一步写错。load_threaded_get()是取出资源。只有在状态是THREAD_LOAD_LOADED后调用才能安全拿到资源。取出之后可以像普通load()出来的资源一样使用。2.3 为什么要用过渡界面异步加载把资源加载放到了后台线程但主线程在等待期间游戏画面仍然在正常刷新。这个时候如果不做处理玩家会看到旧场景的画面静止在那里或者看到奇怪的闪烁。于是过渡界面就产生了两个作用第一个作用是遮丑。用一张 UI 界面盖住整个画面玩家的注意力被引导到“加载进度”上不会被半加载状态的场景吓到。第二个作用是提供状态。玩家可以根据进度条判断“还要等多久”减少等待焦虑。如果进度条卡住不动玩家也能尽早发现异常而不是以为游戏崩溃了。所以异步加载和过渡界面是一对组合拳。一个负责后台加载资源一个负责前台等待与展示状态。少了任何一个体验都不完整。3. 环境准备与前置条件在开始写代码之前先确认你的运行环境。3.1 版本要求本教程的代码和 API 以Godot 4.x为准推荐使用 4.2 以上版本。特别提醒一下load_threaded_request()这一组线程加载 API 在 Godot 3.x 中不存在如果你用的是 Godot 3.x请先升级到 Godot 4.x 再继续阅读。版本请以实际项目为准本文重点演示通用思路。3.2 编辑器版本打开 Godot 项目管理器确认你的版本号。只要是大版本为 4 就可以。如果编辑器界面和本文截图不完全一致优先以你自己的版本为准。3.3 语言支持本文全部使用 GDScript。不需要 C#不需要外部插件Godot 自带的编辑器就能完成全部操作。3.4 项目结构约定为了后面演示方便我们先约定一个最简单项目结构你可以在实际项目中替换成你自己的路径res:// ├── scenes/ │ ├── main.tscn │ ├── loading_screen.tscn │ ├── level_2.tscn │ └── level_3.tscn └── scripts/ ├── main.gd └── loading_screen.gd其中main.tscn是入口场景负责启动加载流程并显示过渡界面level_2.tscn和level_3.tscn是我们要测试加载的目标场景。如果你只是为了学习也可以只准备两个简单的 3D 场景目标场景里随便放几个节点就行。关键是路径要一致、脚本挂载正确。4. 同步加载的问题演示在写异步加载之前我建议你先亲手做一次同步加载实验。这不是浪费时间而是为了让你用肉眼看到“卡顿到底卡在哪”。4.1 准备两个测试场景先创建一个 3D 场景保存为level_2.tscn。往里面丢一个CSGBox3D或者一个简单的MeshInstance3D再放一个方向光。这个场景越简单越好只要保证它存在即可。再创建一个level_3.tscn同样放几个节点。为什么要两个场景因为等一下我们会在两个场景之间来回切换你才能对比出异步加载的切换过程有多顺滑。4.2 同步加载的脚本写法接下来创建一个main.gd挂在main.tscn的根节点上。脚本里写一个同步切换场景的方法## 脚本路径scenes/main.gd extends Node3D ## 需要加载的下一个场景路径 export var next_scene_path: String res://scenes/level_2.tscn ## 触发同步切换场景 func _on_switch_pressed() - void: # 同步加载目标场景主线程会被阻塞 var packed_scene: PackedScene load(next_scene_path) get_tree().change_scene_to_packed(packed_scene)在这段脚本里load()就是同步加载。它执行时主线程会一直等资源加载完期间画面不刷新游戏看起来就像卡住了一样。你的项目里肯定已经有一个“切换场景”的按钮或者按键把它连接到这个方法上。点击按钮然后观察游戏画面。如果你准备的目标场景足够大或者资源文件不在缓存中画面上会出现一个明显的停顿这就是同步加载阻塞主线程的表现。如果场景太小、加载太快你看不到明显卡顿也是正常的。这种情况下可以在目标场景里加入一些比较大的资源文件比如大尺寸贴图或者多放几个模型节点让加载时间变长卡顿感就会被放大了。这个实验的目的是让你对“主线程阻塞”有一个直观感受。很多新手一开始写的游戏规模小加载场景不到一秒所以就认为同步加载没毛病。但实际上当项目规模一大或者目标平台从电脑变成中低端手机同样的同步加载代码就会暴露出严重问题。5. 异步加载核心代码实现接下来进入正题把上面的同步加载换成异步加载。5.1 请求加载目标场景异步加载的第一步不是获取资源而是发起加载请求。我们用ResourceLoader.load_threaded_request()把资源路径发给后台线程。这一步立即返回主线程可以继续执行其他逻辑。## 脚本路径scenes/main.gd extends Node3D ## 下一个场景的路径 export var next_scene_path: String res://scenes/level_2.tscn ## 是否已经发起了加载请求 var _load_started: bool false ## 发起异步加载请求 func _on_switch_pressed() - void: if _load_started: return _load_started true # 后台线程开始加载目标场景 ResourceLoader.load_threaded_request( next_scene_path, PackedScene, true )这里需要解释参数的含义。第一个参数是路径就是res://开头的资源路径。第二个参数PackedScene是资源类型。它相当于告诉 Godot我要加载的是一个场景文件请用场景解析器处理它。如果你加载的是贴图这里可以写Texture2D。如果不确定类型也可以传空字符串让 Godot 根据文件扩展名推断。但从工程习惯来说建议尽量显式传类型有助于提前暴露路径写错的低级问题。第三个参数true表示允许使用子线程做内部加载。这是一个经验性的建议值。对于普通 3D 场景开启子线程能更充分地利用多核 CPU。但要注意有些自定义资源或者第三方资源格式并不支持子线程加载遇到加载崩溃时这是排查重点之一。5.2 查询加载状态加载请求发出去之后我们需要在每一帧去检查后台线程的状态直到加载完成。Godot 提供了ResourceLoader.load_threaded_get_status()方法传入路径和进度数组就能拿到当前加载状态。## 每一帧检查加载状态 func _process(_delta: float) - void: if not _load_started: return var progress: Array [] var status ResourceLoader.load_threaded_get_status( next_scene_path, progress ) match status: ResourceLoader.THREAD_LOAD_IN_PROGRESS: # 还在加载可以读取进度 var percent : 0.0 if progress.size() 0: percent float(progress[0]) * 100.0 print(加载进度: %.1f%% % percent) ResourceLoader.THREAD_LOAD_LOADED: # 加载完成可以取出场景 _load_started false _load_and_switch_scene() ResourceLoader.THREAD_LOAD_FAILED: # 加载失败 push_error(异步加载失败: next_scene_path) _load_started false这里有一个新手很容易踩的坑load_threaded_get_status()的第二个参数需要的是一个数组而进度值会写入数组的第一个元素中。很多刚接触的人会直接写var progress : 0.0然后传progress结果报错或者取不到进度。要记住var progress: Array []进度数组里元素的含义是按“线程”排列的。如果你在请求时设置了use_sub_threads true进度数组里可能出现多个元素代表不同线程上的加载进度。实际使用时取第一个元素看整体进度通常就够了。当状态变为THREAD_LOAD_LOADED说明资源已经加载到内存里了下一步就是取出来使用。5.3 取出并切换场景加载完成后用load_threaded_get()取出PackedScene然后像普通场景一样切换。## 加载完成切换场景 func _load_and_switch_scene() - void: var packed_scene: PackedScene ResourceLoader.load_threaded_get( next_scene_path ) if packed_scene: get_tree().change_scene_to_packed(packed_scene) else: push_error(取出的场景为空)这里有个细节load_threaded_get()只有在状态变为THREAD_LOAD_LOADED之后调用才是安全的。如果你在加载中调用会得到一个异常。所以上面的代码里我们是在_process()里确认状态之后才调用取出方法顺序不能反过来。到这里异步加载的最核心最小闭环已经完成了。如果你现在运行项目在场景切换时画面不会因为加载大场景而卡死。你的游戏会在后台加载新场景加载完之后再切换过去。但这个方案还不够完整因为玩家在等待期间看到的还是旧场景的画面。如果加载时间较长玩家会以为游戏出了问题。所以下一步我们给它加一个正式的过渡界面。6. 加载过渡界面设计与进度显示过渡界面听起来复杂本质上就是一套全屏 UI一个背景一个进度条一个进度百分比文字可能再加一行加载提示。它不参与游戏逻辑游戏逻辑在等待期间也不会真的“跑”只是主循环依然在刷新UI 依然能正常显示和更新。6.1 搭建过渡界面场景新建一个场景根节点选择CanvasLayer命名为LoadingScreen保存为loading_screen.tscn。CanvasLayer很关键。它是独立于 3D 世界之外的 UI 层不会受摄像机影响也不会被 3D 场景遮挡。哪怕你在加载新场景的瞬间切换了当前场景CanvasLayer的 UI 依然能正常显示因为它不属于任何具体 3D 场景。在这个根节点下依次添加以下子节点一个ColorRect铺满整个屏幕作为背景遮罩防止旧场景的半加载画面漏出来。一个ProgressBar命名为LoadBar用来展示加载进度min_value设为 0max_value设为 100show_percentage可以关闭因为我们自己写文字显示百分比。一个Label命名为ProgressLabel显示如“加载中 45%”这样的文字。一个Label命名为TipLabel显示一些固定的提示文案比如“正在加载新区域请稍候”。为了让这个 UI 场景能独立运行测试建议在Project - Project Settings - Main Scene中先维持main.tscn作为主场景仅在需要验证 UI 时临时把loading_screen.tscn设为主场景。6.2 在入口场景中动态创建过渡界面不推荐在主场景里放一个隐藏的过渡界面节点然后通过切换可见性来控制因为这样会让主场景的节点树变得混乱。更干净的做法是在需要加载时用代码动态实例化过渡界面用完再释放。下面我们在main.gd中动态创建过渡界面## 脚本路径scenes/main.gd extends Node3D export var next_scene_path: String res://scenes/level_2.tscn ## 过渡界面的场景 export var loading_screen_scene: PackedScene var _load_started: bool false var _loading_screen_instance: CanvasLayer null ## 触发场景切换 func _on_switch_pressed() - void: if _load_started: return _load_started true # 显示过渡界面 _show_loading_screen() # 发起异步加载 ResourceLoader.load_threaded_request( next_scene_path, PackedScene, true ) ## 动态创建并显示过渡界面 func _show_loading_screen() - void: if loading_screen_scene null: return _loading_screen_instance loading_screen_scene.instantiate() add_child(_loading_screen_instance)你需要做的额外操作是在main.tscn中把loading_screen.tscn拖到main.gd的loading_screen_scene导出属性上。这样代码里才能实例化它。6.3 更新进度条然后在_process()里的加载过程中把进度数值同步给过渡界面中的ProgressBar和Label。## 每一帧更新加载状态与 UI func _process(_delta: float) - void: if not _load_started: return var progress: Array [] var status ResourceLoader.load_threaded_get_status( next_scene_path, progress ) match status: ResourceLoader.THREAD_LOAD_IN_PROGRESS: var percent : 0.0 if progress.size() 0: percent float(progress[0]) * 100.0 _update_loading_progress(percent) ResourceLoader.THREAD_LOAD_LOADED: _load_started false _load_and_switch_scene() ResourceLoader.THREAD_LOAD_FAILED: push_error(异步加载失败: next_scene_path) _load_started false ## 更新过渡界面上的进度显示 func _update_loading_progress(percent: float) - void: if _loading_screen_instance null: return var bar: ProgressBar _loading_screen_instance.get_node(LoadBar) var label: Label _loading_screen_instance.get_node(ProgressLabel) bar.value percent label.text 加载中 %d%% % int(percent)这里用get_node()直接按路径获取子节点方便快捷。如果你用的是onready声明变量需要确保过渡界面实例化后再获取否则拿到的节点是空的。6.4 加载完成后回收过渡界面场景切换完成后过渡界面就没有存在意义了。最好是在切换前把它从场景树中移除并释放以免其内容残留在新场景中。修改_load_and_switch_scene()## 加载完成切换场景 func _load_and_switch_scene() - void: var packed_scene: PackedScene ResourceLoader.load_threaded_get( next_scene_path ) if packed_scene: # 先移除过渡界面 if _loading_screen_instance: _loading_screen_instance.queue_free() _loading_screen_instance null get_tree().change_scene_to_packed(packed_scene) else: push_error(取出的场景为空请检查资源路径和类型)到这里一个完整的异步加载 过渡界面流程就通了。运行项目点击切换按钮你应该能看到进度条出现然后当进度达到 100% 时场景平滑切换过去。7. 常见问题与排查思路我用 Godot 做异步加载时遇到过一些非常典型的问题。这里整理成表格方便你直接对照排查。问题现象可能原因排查方式解决方案load_threaded_get_status传入进度变量时报错把进度参数写成了 Float而不是 Array检查progress变量的类型声明var progress: Array []进度一直为 0 或者不更新目标场景很小加载速度极快_process里根本来不及看到进度更新在_process中打印状态给目标场景加一个大资源人为拉长加载时间加载完成后取出的场景为 null路径写错或者资源类型传错打印next_scene_path确认文件确实存在检查res://路径拼写建议在文件系统面板里复制路径设置use_sub_threadstrue后崩溃某些第三方资源或自定义资源不支持子线程加载把use_sub_threads改为false测试对特定资源显式关闭子线程或者换成引擎内置资源格式过渡界面出现后画面仍会闪烁过渡界面的ColorRect没有完全覆盖屏幕或者层级不对检查ColorRect的锚点设置将ColorRect的 anchors 设为全屏拉伸切换场景后过渡界面依然存在过渡界面没有被释放或者它添加到了根节点以外的地方在切换前调用queue_free()确保_load_and_switch_scene()中先释放界面再切换异步加载请求了同一个路径多次按钮可以重复点击触发了多次请求检查_load_started标志位在发起请求前加状态锁防止重复请求场景加载完成时进度条显示 99% 然后跳 100%部分资源的解析发生在最后的load_threaded_get()中这属于正常现象进度只代表资源读取在实际项目中可以取98%封顶或额外展示“进入场景中”文案上面这些问题一半是 API 使用错误一半是并发场景下资源调度的常见现象。建议你遇到问题先看错误日志Godot 的push_error()和输出面板会给出非常明确的指向。8. 最佳实践与工程建议流程跑通之后再从工程角度聊几个长期维护需要注意的点。8.1 用“资源队列”统一管理加载任务在真实项目中你不可能每个场景都单独写一遍异步加载逻辑。更好的做法是抽象出一个“加载管理器”用单例或自动加载节点统一管理一个资源请求队列一个加载状态查询接口一个进度回调接口统一的失败重试策略。这样每个 UI 界面只需调用LoadingManager.load_scene(path, callback)不用关心底层是同步还是异步排查问题也更加集中。8.2 区分“切换场景”和“加载资源”异步加载不只用于场景切换它也可以用于加载单个资源比如贴图、音频、模型。当你在大世界里动态出现新物体时完全可以在物体出现前几秒开始后台加载资源时间到了再实例化物体玩家感知不到任何卡顿。这比全都集中到切换场景时再加载要好得多。8.3 注意 UI 层与场景树的挂载关系过渡界面最好挂在CanvasLayer下而不是挂在当前 3D 场景的某个节点下。原因很简单3D 场景会被切换走过渡界面如果挂在这个场景下切换时会一起销毁你还没来得及显示新场景画面就闪黑了。用CanvasLayer可以保证 UI 独立于任何 3D 场景。进一步地你甚至可以把过渡界面做成全局自动加载节点的一部分永远挂在场景树根部这样无论场景怎么切换加载界面都能稳定工作。8.4 进度条封顶处理异步加载进度并不是完全平滑的最后那个“收尾阶段”常常会有跳变。实际项目中很多团队会把进度条显示值封顶在 98%然后显示“正在进入场景”之类的文字等场景真正切换时再瞬间补满。这个小技巧可以避免玩家在 99% 停留过久而产生焦虑。8.5 加载失败的兜底策略不要只在失败时打一行错误信息。实际项目中你应该提供一个兜底方案比如显示“加载失败点击重试”按钮或者自动回退到上一个安全的场景。游戏发到正式用户那里不可能保证每个用户的机器环境和资源文件都完整。加载失败是会发生的事。提前做好失败处理会让项目整体稳定性上一个台阶。8.6 不要在加载过程中修改正在加载的资源load_threaded_request()启动后如果在同一帧里又对同一个资源做了其他操作可能会引发不可预知的报错。稳妥的做法是在一个加载任务完成后再对资源进行实例化、修改属性、释放引用等操作。9. 总结与后续学习方向这一节的内容其实只讲透了一个点不要在主线程同步加载大资源把加载交给后台线程同时用一个过渡界面把等待过程变得可感知、可接受。你应该已经掌握了同步加载与异步加载对主线程影响的本质区别ResourceLoader.load_threaded_request()、load_threaded_get_status()、load_threaded_get()三个核心 API 的正确用法用CanvasLayer搭建独立过渡界面并动态显示真实加载进度从发起加载、更新进度、取出场景到释放过渡界面的完整闭环。接下来可以继续深挖的方向我建议按顺序来把过渡界面做成可复用的“加载管理器”加入负载策略、失败重试、预加载机制学习ResourceLoader对单个资源的异步加载比如异步加载贴图用于大厅场景的渐进式显示了解 Godot 的change_scene_to_packed()与手动移除实例化节点后add_child()的区别这会影响你如何设计复杂场景切换尝试在异步加载之后加入一个短暂的淡入淡出效果让场景切换更有质感。最后提醒一句在新手阶段异步加载看起来像是“没必要的复杂度”但随着资源量增长你会越来越依赖它。建议现在就把这套过渡界面搭进你的项目里。等哪一天你的场景复杂到切换时不再卡顿你会感谢今天这个决定。
