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

SubViewport

节点继承关系

继承链：Node -> Viewport -> SubViewport

Node

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

定义

SubViewport 是一个"嵌入在游戏画面里的小屏幕"。就像画中画电视一样，你可以在主游戏画面的一个角落里显示另一个独立渲染的画面。

简单说：它是一个可以放在游戏界面里的迷你屏幕，里面可以显示完全不同的内容。

使用频率：★★★ 一般常用

节点用途

• 小地图：在画面角落显示整个地图的缩略图
• 后视镜：赛车游戏中的后视镜效果
• 监控摄像头：安全监控游戏中的多个摄像头画面
• 物品预览：在装备界面中3D旋转预览装备
• 分屏游戏：本地多人分屏游戏

使用场景

场景	说明
小地图	SubViewport 渲染俯瞰视角的地图，放在画面右上角
赛车后视镜	SubViewport 渲染车后视角，显示在后视镜形状的区域内
监控系统	多个 SubViewport 同时显示不同摄像头的画面
物品预览	SubViewport 中渲染3D装备模型，玩家可以旋转查看

常用节点搭配

搭配节点	搭配方式
SubViewportContainer	包裹 SubViewport，将它显示为2D UI元素
Camera2D / Camera3D	放在 SubViewport 内，定义小屏幕看到的内容
World2D / World3D	SubViewport 可以有自己独立的世界

生效必备素材/资源

SubViewport 通常需要配合 SubViewportContainer 使用才能在屏幕上显示。

节点属性与信号

属性

属性	类型	默认值	继承自	说明
size	Vector2i	(512, 512)	SubViewport	小屏幕的分辨率大小（像素）
render_target_update_mode	int	3	SubViewport	更新模式：0=禁用，1=每帧，2=每物理帧，3=可见时更新
transparent_bg	bool	false	SubViewport	背景是否透明
clear_mode	int	0	SubViewport	清除模式：0=总是，1=下一帧，2=从不
scaling_3d_mode	int	0	SubViewport	3D缩放模式
world_2d	World2D	—	Viewport	2D世界资源
world_3d	World3D	—	Viewport	3D世界资源

信号

信号	参数	说明
size_changed	—	小屏幕大小改变时触发

常用方法

方法	参数	返回值	说明
GetTexture()	无	Texture2D	获取当前渲染结果作为纹理（可用于材质）
PushInput(event)	event: InputEvent	void	向 SubViewport 发送输入事件
PushUnhandledInput(event)	event: InputEvent	void	向 SubViewport 发送未处理的输入事件

代码示例

C

// C# - 小地图系统
using Godot;

public partial class MiniMap : SubViewportContainer
{
    private SubViewport _subViewport;
    private Camera2D _miniMapCamera;
    private CharacterBody2D _player;

    public override void _Ready()
    {
        _subViewport = GetNode<SubViewport>("SubViewport");
        _miniMapCamera = _subViewport.GetNode<Camera2D>("MiniMapCamera");
        _player = GetTree().CurrentScene.GetNode<CharacterBody2D>("Player");

        // 设置小地图大小
        _subViewport.Size = new Vector2I(200, 200);

        // 小地图相机跟随玩家
        _miniMapCamera.Position = _player.Position;
    }

    public override void _Process(double delta)
    {
        // 小地图相机实时跟随玩家
        _miniMapCamera.Position = _player.Position;
    }
}

GDScript

# GDScript - 小地图系统
extends SubViewportContainer

@onready var sub_viewport: SubViewport = $SubViewport
@onready var mini_map_camera: Camera2D = $SubViewport/MiniMapCamera
var player: CharacterBody2D

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

    # 设置小地图大小
    sub_viewport.size = Vector2i(200, 200)

    # 小地图相机跟随玩家
    mini_map_camera.position = player.position

func _process(_delta):
    # 小地图相机实时跟随玩家
    mini_map_camera.position = player.position