文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载PackedScene 是 Godot 引擎中场景文件.tscn / .scn在内存中的资源化表示它是连接磁盘上的场景模板与运行时节点树实例之间的桥梁。本文基于 classes/class_packedscene.rst 类参考文档系统讲解 PackedScene 的继承体系、加载方式、instantiate()实例化、pack()打包保存以及owner归属机制并结合仓库中的 节点与场景实例教程、场景手动切换教程、存档系统教程 等资料为你提供一套可直接落地的场景资源管理实战方案。PackedScene 在引擎中的定位序列化场景的抽象PackedScene 继承自Resource其完整继承链为Resource RefCounted Object见 class_packedscene.rst本质上是一个序列化场景的抽象An abstraction of a serialized scene为场景文件本身提供了一套简化的操作接口。你可以在不直接触碰节点树的情况下对场景资源执行检查与操作。理解 PackedScene 的关键是要把它与场景实例严格区分开PackedScene 是资源代表磁盘上的模板一个模板可以被反复实例化无数次实例化后的节点树才是运行时对象通过instantiate()产生。正如 tutorials/scripting/resources.rst 中Loading scenes一节所强调的场景也是资源但有一个关键区别——保存到磁盘的场景是PackedScene类型的资源场景被打包在 Resource 内部。要得到节点树的实例就必须调用PackedScene.instantiate()。从磁盘加载一个场景并挂入场景树是 PackedScene 最基础的用法也是后续一切高级应用动态刷怪、切换关卡、存档恢复的起点。加载场景三种途径与各自适用场景GDScriptpreload()与load()在 GDScript 中加载场景有两种原生语法# 编译期加载路径必须在编译时已知加载发生在脚本编译阶段 var scene preload(res://scene.tscn) # 运行时加载路径不必在编译时已知 var scene load(res://scene.tscn)类参考文档给出的标准加载示例class_packedscene.rst如下# 如果路径在编译期未知请用 load() 而不是 preload() var scene preload(res://scene.tscn).instantiate() # 将节点添加为当前脚本所挂载节点的子节点 add_child(scene)C# 没有preload只能通过ResourceLoader.LoadPackedScene()显式加载// C# 没有 preload因此必须始终使用 ResourceLoader.LoadPackedScene() var scene ResourceLoader.LoadPackedScene(res://scene.tscn).Instantiate(); // 将节点添加为当前脚本所挂载节点的子节点 AddChild(scene);两者的取舍在 tutorials/scripting/nodes_and_scene_instances.rst 中有详细说明preload()把加载操作提前到脚本被编译器读取时而非运行时因此玩家在游戏过程中不会体验到加载卡顿但它要求路径在编译期固定无法用于路径动态变化的场景。load()则相反灵活性高代价是运行时才触发磁盘 I/O。异步加载ResourceLoader.load_threaded_request()对于大型关卡或资源较多的场景同步的load()会阻塞当前线程造成游戏短暂无响应。仓库中的 tutorials/io/background_loading.rst 提供了完整的异步方案先用ResourceLoader.load_threaded_request()在后台线程发起加载请求再用load_threaded_get_status()查询进度最后用load_threaded_get()取回资源。const ENEMY_SCENE_PATH : Enemy.tscn func _ready(): # 后台线程发起加载请求 ResourceLoader.load_threaded_request(ENEMY_SCENE_PATH) self.pressed.connect(_on_button_pressed) func _on_button_pressed(): # 按钮被按下 # 在需要时获取资源若尚未加载完成此处会像 load() 一样阻塞 var enemy_scene ResourceLoader.load_threaded_get(ENEMY_SCENE_PATH) var enemy enemy_scene.instantiate() add_child(enemy)值得注意load_threaded_get()在资源尚未加载完时会退化为同步阻塞若要保证绝不阻塞应先在_ready()阶段发起请求、留出加载时间或在取回前先检查load_threaded_get_status()的返回状态。这也是 background_loading.rst 特别提醒的细节。instantiate()从模板到节点树实例方法签名与行为Node instantiate(edit_state: GenEditState 0) constinstantiate()是 PackedScene 最核心的方法负责实例化场景的节点层级。根据 class_packedscene.rst 的方法描述它同时会触发子场景嵌套的 PackedScene 实例的实例化在根节点上触发Node.NOTIFICATION_SCENE_INSTANTIATED通知。NOTIFICATION_SCENE_INSTANTIATED 20这个通知仅由新实例化场景的根节点收到见 classes/class_node.rst 中对应常量的说明。这意味着如果你在某个场景根节点上通过_notification()或NOTIFICATION_SCENE_INSTANTIATED常量监听该通知就可以在这个场景刚被实例化完成这一时刻执行初始化逻辑——例如根据传入参数配置实例而不是依赖_ready()_ready()在节点进入场景树时才触发且无法区分首次实例化与后续复用。两步实例化流程的价值标准做法分两步——先加载得到 PackedScene 资源再调用instantiate()得到节点树var scene load(res://my_scene.tscn) # 1. 加载场景资源 var instance scene.instantiate() # 2. 实例化出节点树 add_child(instance)C# 对应写法var scene GD.LoadPackedScene(res://MyScene.tscn); var instance scene.Instantiate(); AddChild(instance);nodes_and_scene_instances.rst 指出这种两步走的最大优势是**一次加载、多次实例化**你可以让一个 PackedScene 常驻内存然后按需快速生成大量实例。典型场景如 resources.rst 中Loading scenes的子弹示例func _on_shoot(): var bullet preload(res://bullet.tscn).instantiate() add_child(bullet)C# 版本private PackedScene _bulletScene GD.LoadPackedScene(res://Bullet.tscn); private void OnShoot() { Node bullet _bulletScene.Instantiate(); AddChild(bullet); }由于PackedScene.instantiate()本身非常快而图片、网格等底层资源又在所有实例之间共享引用同一份数据所以批量生成子弹、敌人、特效等对象时无需反复从磁盘加载性能开销主要集中在节点树构建本身。GenEditState编辑状态控制枚举instantiate()的唯一可选参数edit_state来自PackedScene.GenEditState枚举它控制实例化时场景状态的可编辑性共有 4 个取值class_packedscene.rst 中的 Enumerations 一节常量值含义GEN_EDIT_STATE_DISABLED0默认值。禁止对场景状态进行编辑适用于所有运行时实例化GEN_EDIT_STATE_INSTANCE1为局部场景提供局部场景资源仅编辑器构建可用GEN_EDIT_STATE_MAIN2提供局部场景资源且只有主场景应接收主编辑状态仅编辑器构建可用GEN_EDIT_STATE_MAIN_INHERITED3与GEN_EDIT_STATE_MAIN类似但用于该场景将被实例化为另一个场景的基底这一继承场景场景仅编辑器构建可用需要特别强调的是GEN_EDIT_STATE_INSTANCE、GEN_EDIT_STATE_MAIN、GEN_EDIT_STATE_MAIN_INHERITED三个值都只在编辑器构建editor builds中可用。游戏运行时实例化场景时始终使用默认的GEN_EDIT_STATE_DISABLED即不传参即可——这也是为什么所有游戏内实例化代码都直接调用scene.instantiate()而从不传edit_state。这些编辑状态与 Godot 编辑器内部的场景编辑机制例如场景继承、实例化后局部覆盖属性深度绑定普通玩家项目不需要也无法在运行时使用。pack() 与 owner 归属机制把节点树保存为场景文件方法签名Error pack(path: Node)pack()将传入的path节点及其所有被其拥有的子节点打包进当前 PackedScene任何已有的数据都会被清除见 class_packedscene.rst 的 Method Descriptions。这一行为由Node.owner属性决定——classes/class_node.rst 对owner的官方定义是The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a PackedScene, all the nodes it owns are also saved with it. 节点的拥有者。拥有者必须是该节点的祖先节点。当把拥有者节点打包进 PackedScene 时它拥有的所有节点也会一并保存。完整打包示例类参考文档给出了一个非常经典的不同 owner 节点打包示例构造了 3 个对象Node2Dnode、RigidBody2Dbody和CollisionShape2Dcollision。层级关系为 collision 是 body 的子节点body 是 node 的子节点但只有 body 被 node 拥有因此pack(node)只会保存 node 和 body 两个节点collision 不会被保存# 创建对象 var node Node2D.new() var body RigidBody2D.new() var collision CollisionShape2D.new() # 构建对象层级 body.add_child(collision) node.add_child(body) # 只把 body 的 owner 设为 node不设置 collision 的 body.owner node var scene PackedScene.new() # 现在只有 node 和 body 被打包 var result scene.pack(node) if result OK: var error ResourceSaver.save(scene, res://path/name.tscn) # 或 user://... if error ! OK: push_error(An error occurred while saving the scene to disk.)C# 对应版本// 创建对象 var node new Node2D(); var body new RigidBody2D(); var collision new CollisionShape2D(); // 构建对象层级 body.AddChild(collision); node.AddChild(body); // 只把 body 的 owner 设为 node不设置 collision 的 body.Owner node; var scene new PackedScene(); // 现在只有 node 和 body 被打包 Error result scene.Pack(node); if (result Error.Ok) { Error error ResourceSaver.Save(scene, res://path/name.tscn); // 或 user://... if (error ! Error.Ok) { GD.PushError(An error occurred while saving the scene to disk.); } }这个示例揭示了 PackedScene 序列化的核心规则打包的是被拥有的节点子集而非单纯的节点树。类参考文档还有两条补充说明节点不需要拥有自己The node doesnt need to own itself——根节点 node 自身总是会被保存保存时该节点及其所有它拥有的节点都会被保存。owner 在编辑器与运行时中的差异class_node.rst 的 Note 进一步补充了实践要点在编辑器中未被场景根节点拥有的节点通常不会显示在 Scene 面板中并且不会被保存。为避免这种情况记得在调用add_child()之后设置 owner。 owner 必须是当前场景根节点。也就是说在编辑器工具脚本中动态add_child()出来的子节点如果不显式设置owner即使层级正确也不会被写入场景文件——这是很多插件开发新手踩过的坑。class_node.rst 在add_child()的说明中也明确提醒如果希望子节点被持久化到 PackedScene必须在调用add_child()之外再设置owner。这通常与工具脚本tool scripts和编辑器插件相关。如果只调用add_child()而不设置owner新添加的节点虽然可见于 2D/3D 视图但不会出现在场景树中。ResourceSaver.save()把 PackedScene 写到磁盘pack()只是把节点树打包进内存中的 PackedScene 对象真正落盘要靠ResourceSaver.save()。其完整签名为classes/class_resourcesaver.rstError save(resource: Resource, path: String , flags: BitField[SaverFlags] 0)path为空时ResourceSaver 会尝试使用Resource.resource_path保存成功返回GlobalScope.OK注意项目运行时生成的 UID 不会被保存因为相关代码只在编辑器模式下执行保存路径可以使用res://path/name.tscn项目内部或user://...用户数据目录后者适合存档类场景文件的写入。can_instantiate() 与 get_state()实例化前的安全检查与场景窥探can_instantiate()bool can_instantiate() const返回true表示该场景文件包含节点见 class_packedscene.rst。这是一个低成本的安全检查如果场景文件是空的例如一个尚未打包任何内容的 PackedScene 对象调用instantiate()就没有意义。典型防御性写法var scene load(res://scene.tscn) if scene.can_instantiate(): add_child(scene.instantiate()) else: push_error(场景文件不包含任何节点无法实例化。)get_state() 与 SceneStateSceneState get_state() constget_state()返回代表场景文件内容的SceneState对象。SceneState无法直接实例化它只能通过PackedScene.get_state()获得见 classes/class_scenestate.rst 的类描述其用途是在不实例化场景的前提下窥探 PackedScene 内部内容。SceneState维护了场景关联的资源、节点、导出与覆盖属性、内建脚本以及信号连接等信息的只读列表并提供了大量只读查询方法节点维度get_node_count()、get_node_name(idx)、get_node_type(idx)、get_node_path(idx)、get_node_owner_path(idx)、get_node_groups(idx)、get_node_property_count(idx)、get_node_property_name(idx, prop_idx)、get_node_property_value(idx, prop_idx)信号连接维度get_connection_count()、get_connection_source(idx)、get_connection_target(idx)、get_connection_signal(idx)、get_connection_method(idx)、get_connection_binds(idx)、get_connection_unbinds(idx)、get_connection_flags(idx)实例与继承维度get_node_instance(idx)返回节点对应分支的 PackedScene若该节点是实例则返回非 null、get_node_instance_placeholder(idx)节点为 InstancePlaceholder 时返回其代表的场景文件路径相关类型见 classes/class_instanceplaceholder.rst、get_base_scene_state()返回当前场景所继承的基场景 SceneState无继承则返回 null、get_path()。例如要统计一个场景里有多少节点而不实例化它var state scene.get_state() print(节点数量: , state.get_node_count()) print(根节点名称: , state.get_node_name(0))这在编辑器插件、资产审查工具或需要根据场景结构动态决策的代码中非常有用——它把读场景与建实例解耦避免为了查一条元数据而付出完整实例化的开销。实战整合从场景管理到存档系统的完整链路场景切换手动实例化与删除策略在运行时手动管理场景切换是 PackedScene 最典型的游戏应用场景。tutorials/scripting/change_scenes_manually.rst 展示了如何把预加载的场景实例手动挂到根节点下实现类似运行时自动加载的效果var simultaneous_scene preload(res://levels/level2.tscn).instantiate() func _add_a_scene_manually(): # 这就像自动加载场景只不过发生在主场景加载完成之后 get_tree().root.add_child(simultaneous_scene)C# 版本public Node simultaneousScene; public MyClass() { simultaneousScene ResourceLoader.LoadPackedScene(res://levels/level2.tscn).Instantiate(); } public void _AddASceneManually() { GetTree().Root.AddChild(simultaneousScene); }而替换旧场景则有三种策略可供权衡详见 change_scenes_manually.rst删除旧场景SceneTree.change_scene_to_file()/change_scene_to_packed()或直接free()主场景根节点——立即卸载内存但回到该场景需重新加载隐藏旧场景CanvasItem.hide()/show()——数据与处理都保留但内存持续占用移动端/网页端需谨慎把旧场景移出场景树remove_child()后保留引用需要时再add_child()挂回——数据处理停止但内存保留且切换成本最低。其中change_scene_to_packed()正是以 PackedScene 为参数的官方场景切换接口与本文主题一脉相承。存档系统动态重建场景实例仓库的 tutorials/io/saving_games.rst 给出了一个值得借鉴的按场景模板存档模式存档时不直接序列化整个节点树而是记录每个可持久化对象的场景文件路径Filename、父节点路径Parent与自定义属性读档时用PackedScene重新实例化并逐属性恢复。其 C# 读档核心逻辑如下// 根据存档中记录的场景路径加载 PackedScene 并实例化 var newObjectScene GD.LoadPackedScene(nodeData[Filename].ToString()); var newObject newObjectScene.InstantiateNode(); GetNode(nodeData[Parent].ToString()).AddChild(newObject); newObject.Set(Node2D.PropertyName.Position, new Vector2((float)nodeData[PosX], (float)nodeData[PosY])); // 再恢复其余自定义变量 foreach (var (key, value) in nodeData) { if (key Filename || key Parent || key PosX || key PosY) { continue; } newObject.Set(key, value); }这个模式与PackedScene.pack()天然互补pack()用于把当前节点树快照成场景文件load() instantiate()用于从场景文件还原节点树二者共同构成场景级序列化的闭环。该教程还特别提醒若存档对象存在嵌套Persist 对象互为父子需要分阶段加载——先加载父对象以便子对象add_child()时有合法的父路径并自行维护父子关联因为此时 NodePath 可能已失效。事件驱动的实例化信号 PackedSceneinstancing_with_signals.rst 展示了 PackedScene 与信号系统的组合用法——把 PackedScene 作为信号参数传递实现发射器负责创建实例、接收方负责复用模板的解耦模式const Bullet preload(res://bullet.tscn) signal shoot(bullet, direction, location) # bullet 参数类型即 PackedScene func _on_player_shoot(bullet, direction, location): var spawned_bullet bullet.instantiate() # ...配置实例C# 侧则用委托与PackedScene字段配合public delegate void ShootEventHandler(PackedScene bullet, float direction, Vector2 location); private PackedScene _bullet GD.LoadPackedScene(res://Bullet.tscn);关键注意事项与最佳实践小结综合类参考文档与仓库教程使用 PackedScene 时有以下几点需要牢记PackedScene 是资源不是节点load()/preload()得到的是资源必须经过instantiate()才能得到可挂入场景树的节点。把 PackedScene 直接add_child()是初学者最常见的错误。owner 决定打包范围pack()只保存根节点与其拥有的子节点。编辑器工具脚本中动态创建的节点若要在保存后保留必须在add_child()之后显式设置owner且 owner 应为场景根节点。此外owner必须是被拥有节点的祖先节点否则非法。编辑状态常量仅限编辑器GEN_EDIT_STATE_INSTANCE/MAIN/MAIN_INHERITED只在编辑器构建中可用运行时统一使用默认的GEN_EDIT_STATE_DISABLED。实例化开销低可反复利用一个 PackedScene 常驻内存即可按需生成大量实例底层资源贴图、网格在所有实例间共享这正是动态刷怪、子弹池等方案的性能基础。大场景优先异步加载同步load()会阻塞主线程大型关卡应使用ResourceLoader.load_threaded_request()后台加载并在取回资源前检查状态以避免意外阻塞参考 background_loading.rst。利用 can_instantiate()/get_state() 做防御与预检实例化前用can_instantiate()确认场景非空需要了解场景结构但不想实例化时通过get_state()获取SceneState做只读查询。存档与场景序列化配合使用运行时快照用pack()ResourceSaver.save()可写入user://目录还原时用load()instantiate()。注意运行时保存不会生成资源 UID且项目重启后 UID 相关内容需重新生成。延伸阅读PackedScene 类参考文档本文核心依据含全部方法签名与枚举定义SceneState 类参考文档get_state()返回的只读场景信息查询接口Node.owner 属性文档理解打包范围的关键ResourceSaver.save() 文档场景落盘接口节点与场景实例教程节点获取、创建与场景实例化的系统讲解手动切换场景教程三种场景替换策略的完整权衡保存游戏教程PackedScene 在存档/读档系统中的应用模式后台加载教程ResourceLoader 异步加载场景的完整示例赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot引擎场景实例化教程从入门到实践Godot引擎场景实例化教程从入门到实践 什么是场景实例化 在Godot引擎中场景实例化 Instancing 是一种强大的设计模式它允许开发者将游戏对象文档教程游戏开发攻克游戏开发痛点Fyrox引擎场景序列化完全指南攻克游戏开发痛点Fyrox引擎场景序列化完全指南 Fyrox是一款用Rust编写的强大3D和2D游戏引擎它提供了全面的场景序列化功能让开发者能够轻松保存和游戏开发图形学3D渲染Godot 引擎 InputMap 单例完全指南输入动作管理与运行时按键重映射Godot 引擎 InputMap 单例完全指南输入动作管理与运行时按键重映射 本篇技术指南以 Godot 官方文档仓库中 classes/class_inp文档教程游戏开发上一篇终极指南KernelSU资源管控全解析——CPU、内存与IO限制实战下一篇TheoremExplainBench数据集详解240个多学科定理的AI解释评估基准创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考