最后同步日期：2026-04-15 | Godot 官方原文 — InstancePlaceholder

InstancePlaceholder

节点继承关系

继承链：Node -> InstancePlaceholder

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

InstancePlaceholder 是一个"占位符"节点。当你在编辑器中使用场景实例化（Instance）功能时，如果不想在游戏启动时就加载某个场景，可以把它替换为 InstancePlaceholder。游戏运行后，你可以在需要的时候再手动加载真正的场景替换这个占位符。

打个比方：就像快递柜的格子——平时是空的（占位），你需要的时候才把包裹放进去（替换为真正的场景）。

简单说：它是一个"空壳占位符"，等你需要的时候再加载真正的场景替换它。

使用频率：★ 基本用不到

节点用途

• 延迟加载：大场景不一次性全部加载，等玩家走到附近再加载
• 内存优化：把暂时不需要的场景设为占位符，节省内存
• 动态替换：运行时根据条件替换不同的场景（如随机关卡）

使用场景

场景	说明
开放世界	远处的建筑物用占位符，走近时再加载详细模型
关卡生成	运行时随机选择关卡场景替换占位符
内存优化	大型场景中暂时不需要的区域用占位符代替

常用节点搭配

搭配节点	搭配方式
任意场景	通过 CreateInstance() 方法替换为真正的场景

生效必备素材/资源

需要设置 scene 属性，指向要加载的场景文件（.tscn）。

节点属性与信号

属性

属性	类型	默认值	继承自	说明
scene	PackedScene	null	InstancePlaceholder	要加载的场景资源
placeholder_index	int	0	InstancePlaceholder	实例占位符的索引

信号

InstancePlaceholder 没有自己的特有信号。

常用方法

方法	参数	返回值	说明
CreateInstance(replace, customizableSceneInstance)	replace: bool = true	Node	用真正的场景替换占位符，返回新创建的节点
GetInstance()	无	Node	获取占位符对应的实例（如果已创建）

代码示例

C

// C# - 延迟加载场景（走近时才加载）
using Godot;

public partial class LazyLoader : Node
{
    private CharacterBody3D _player;
    private InstancePlaceholder[] _placeholders;

    public override void _Ready()
    {
        _player = GetTree().CurrentScene.GetNode<CharacterBody3D>("Player");

        // 获取所有占位符
        _placeholders = FindChildren("*", "InstancePlaceholder")
            .Cast<InstancePlaceholder>()
            .ToArray();
    }

    public override void _Process(double delta)
    {
        foreach (var placeholder in _placeholders)
        {
            if (placeholder == null) continue;

            // 如果玩家距离占位符小于50个单位，就加载真正的场景
            float distance = _player.GlobalPosition.DistanceTo(placeholder.GlobalPosition);
            if (distance < 50f)
            {
                placeholder.CreateInstance(true);
                GD.Print($"已加载场景: {placeholder.Scene.ResourcePath}");
            }
        }
    }
}

GDScript

# GDScript - 延迟加载场景（走近时才加载）
extends Node

var player: CharacterBody3D
var placeholders: Array[InstancePlaceholder] = []

func _ready():
    player = get_tree().current_scene.get_node("Player")

    # 获取所有占位符
    for child in get_children():
        if child is InstancePlaceholder:
            placeholders.append(child)

func _process(_delta):
    for placeholder in placeholders:
        if placeholder == null:
            continue

        # 如果玩家距离占位符小于50个单位，就加载真正的场景
        var distance = player.global_position.distance_to(placeholder.global_position)
        if distance < 50.0:
            placeholder.create_instance(true)
            print("已加载场景: %s" % placeholder.scene.resource_path)