Camera2D

继承： Node2D < CanvasItem < Node < Object

2D 场景的相机节点。

描述

用于 2D 场景的相机节点。它强制屏幕（当前层）跟随该节点滚动。与手动改变基于 CanvasItem 节点的坐标相比，这使得对可滚动场景进行编程更加容易和快捷。

相机会在最近的 Viewport（在上层树时）节点中注册自己。每个视口只能激活一个相机。如果树上没有可用的视口，相机将在全局视口中注册。

这个节点旨在成为简单的辅助工具，让事情便捷，但可能需要更多的功能来改变相机的工作方式。要制作自定义相机节点，则从 Node2D 继承，并通过设置 Viewport 中的 Viewport.canvas_transform 来改变画布的变换（你可以通过使用 Node.get_viewport 获得当前的 Viewport）。

请注意，Camera2D 节点的 position 并不代表屏幕的实际位置，这可能会因应用的平滑或限制而有所不同。可以使用 get_screen_center_position 获取真实位置。

教程

• 2D 平台跳跃演示

• 2D 等轴演示

属性

方法

枚举

enum AnchorMode: 🔗

AnchorMode ANCHOR_MODE_FIXED_TOP_LEFT = 0

相机的位置是固定的，所以左上角总是在原点。

AnchorMode ANCHOR_MODE_DRAG_CENTER = 1

相机的位置要考虑垂直/水平偏移和屏幕尺寸。

enum Camera2DProcessCallback: 🔗

Camera2DProcessCallback CAMERA2D_PROCESS_PHYSICS = 0

相机在物理帧期间更新（见 Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS）。

Camera2DProcessCallback CAMERA2D_PROCESS_IDLE = 1

相机在进程帧期间更新（见 Node.NOTIFICATION_INTERNAL_PROCESS）。

属性说明

AnchorMode anchor_mode = 1 🔗

• void set_anchor_mode(value: AnchorMode)

• AnchorMode get_anchor_mode()

Camera2D 的锚点。见 AnchorMode 常量。

Node custom_viewport 🔗

• void set_custom_viewport(value: Node)

• Node get_custom_viewport()

连接到 Camera2D 的自定义 Viewport 节点。如果为 null 或者不是 Viewport，则使用默认的视口。

float drag_bottom_margin = 0.2 🔗

• void set_drag_margin(margin: Side, drag_margin: float)

• float get_drag_margin(margin: Side) const

拖动相机所需的下边距。值为 1 时，相机仅在到达屏幕底部边缘时移动。

bool drag_horizontal_enabled = false 🔗

• void set_drag_horizontal_enabled(value: bool)

• bool is_drag_horizontal_enabled()

如果为 true，相机仅在到达水平（左或右）拖动边距时移动。如果为 false，则相机水平移动时不考虑边距。

float drag_horizontal_offset = 0.0 🔗

• void set_drag_horizontal_offset(value: float)

• float get_drag_horizontal_offset()

相机在右侧（-1）和左侧（1）拖动边距之间的相对水平拖动偏移量。

注意：用于设置初始水平拖动偏移量；确定当前偏移量；或强制当前偏移量。当 drag_horizontal_enabled 为 true 或更改拖动边距时，它不会自动更新。

float drag_left_margin = 0.2 🔗

• void set_drag_margin(margin: Side, drag_margin: float)

• float get_drag_margin(margin: Side) const

拖动相机所需的左边距。值为 1 时，相机仅在到达屏幕左侧边缘时移动。

float drag_right_margin = 0.2 🔗

• void set_drag_margin(margin: Side, drag_margin: float)

• float get_drag_margin(margin: Side) const

拖动相机所需的右边距。值为 1 时，相机仅在到达屏幕右侧边缘时移动。

float drag_top_margin = 0.2 🔗

• void set_drag_margin(margin: Side, drag_margin: float)

• float get_drag_margin(margin: Side) const

拖动相机所需的上边距。值为 1 时，相机仅在到达屏幕顶部边缘时移动。

bool drag_vertical_enabled = false 🔗

• void set_drag_vertical_enabled(value: bool)

• bool is_drag_vertical_enabled()

如果为 true，相机仅在达到垂直（顶部及底部）拖动边距时才移动。如果为 false，相机会垂直移动而不管边距。

float drag_vertical_offset = 0.0 🔗

• void set_drag_vertical_offset(value: float)

• float get_drag_vertical_offset()

相机在底部（-1）和顶部（1）拖动边距之间的相对垂直拖动偏移量。

注意：用于设置初始垂直拖动偏移量；确定当前偏移量；或强制当前偏移量。当 drag_vertical_enabled 为 true 或更改拖动边距时，它不会自动更新。

bool editor_draw_drag_margin = false 🔗

• void set_margin_drawing_enabled(value: bool)

• bool is_margin_drawing_enabled()

如果为 true，在编辑器中绘制相机的拖动边距矩形。

bool editor_draw_limits = false 🔗

• void set_limit_drawing_enabled(value: bool)

• bool is_limit_drawing_enabled()

如果为 true，在编辑器中绘制相机的极限矩形。

bool editor_draw_screen = true 🔗

• void set_screen_drawing_enabled(value: bool)

• bool is_screen_drawing_enabled()

如果为 true，在编辑器中绘制相机的画面矩形。

bool enabled = true 🔗

• void set_enabled(value: bool)

• bool is_enabled()

控制该相机是否可以激活。如果为 true，当该 Camera2D 进入场景树并且当前没有活动的相机时，它将成为主相机（参见 Viewport.get_camera_2d）。

当该相机当前处于活动状态且 enabled 被设置为 false 时，则场景树中下一个启用的 Camera2D 将变为活动状态。

bool ignore_rotation = true 🔗

• void set_ignore_rotation(value: bool)

• bool is_ignoring_rotation()

如果为 true ，相机的渲染视图不会受到其 Node2D.rotation 和 Node2D.global_rotation 的影响。

int limit_bottom = 10000000 🔗

• void set_limit(margin: Side, limit: int)

• int get_limit(margin: Side) const

底部滚动极限，单位为像素。相机会在抵达该值时停止移动，但是 offset 可以把视图推过该极限。

int limit_left = -10000000 🔗

• void set_limit(margin: Side, limit: int)

• int get_limit(margin: Side) const

左侧滚动极限，单位为像素。相机会在抵达该值时停止移动，但是 offset 可以把视图推过该极限。

int limit_right = 10000000 🔗

• void set_limit(margin: Side, limit: int)

• int get_limit(margin: Side) const

右侧滚动极限，单位为像素。相机会在抵达该值时停止移动，但是 offset 可以把视图推过该极限。

bool limit_smoothed = false 🔗

• void set_limit_smoothing_enabled(value: bool)

• bool is_limit_smoothing_enabled()

如果为 true，相机会在达到极限时平滑地停止。

如果 position_smoothing_enabled 为 false，则该属性无效。

注意：要立即将相机的位置更新到限制范围内而不进行平滑，即使启用了该设置，也要调用 reset_smoothing。

int limit_top = -10000000 🔗

• void set_limit(margin: Side, limit: int)

• int get_limit(margin: Side) const

顶部滚动极限，单位为像素。相机会在抵达该值时停止移动，但是 offset 可以把视图推过该极限。

Vector2 offset = Vector2(0, 0) 🔗

• void set_offset(value: Vector2)

• Vector2 get_offset()

相机的相对偏移量。用于环顾四周或相机抖动动画。偏移后的相机可以超过 limit_top、limit_bottom、limit_left 和 limit_right 中定义的限制。

bool position_smoothing_enabled = false 🔗

• void set_position_smoothing_enabled(value: bool)

• bool is_position_smoothing_enabled()

如果为 true，相机的视图会以 position_smoothing_speed 的速度，平滑地移向其目标位置。

float position_smoothing_speed = 5.0 🔗

• void set_position_smoothing_speed(value: float)

• float get_position_smoothing_speed()

当 position_smoothing_enabled 为 true 时，相机平滑效果的速度，单位为每秒像素。

Camera2DProcessCallback process_callback = 1 🔗

• void set_process_callback(value: Camera2DProcessCallback)

• Camera2DProcessCallback get_process_callback()

该相机的处理回调。见 Camera2DProcessCallback。

bool rotation_smoothing_enabled = false 🔗

• void set_rotation_smoothing_enabled(value: bool)

• bool is_rotation_smoothing_enabled()

如果为 true，相机的视图会通过渐近平滑的方式平滑地旋转，以 rotation_smoothing_speed 的速度与其目标旋转对齐。

注意：如果 ignore_rotation 为 true，则该属性无效。

float rotation_smoothing_speed = 5.0 🔗

• void set_rotation_smoothing_speed(value: float)

• float get_rotation_smoothing_speed()

当 rotation_smoothing_enabled 为 true 时，相机旋转平滑效果的角度渐近速度。

Vector2 zoom = Vector2(1, 1) 🔗

• void set_zoom(value: Vector2)

• Vector2 get_zoom()

相机的缩放。 设置为 Vector(2, 2) 的缩放值会使通过视口看到的尺寸翻倍。设置为 Vector(0.5, 0.5)的缩放值会使会使通过视口看到的尺寸减半。

注意：FontFile.oversampling 不会考虑 Camera2D 的缩放值。这意味着放大/缩小将导致位图字体和光栅化（非 MSDF）动态字体看起来模糊或像素化，除非字体是CanvasLayer的一部分从而使其忽略相机缩放。为了确保文本无论如何缩放都保持清晰，你可以通过启用 ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field （仅适用于默认项目字体）来启用 MSDF 字体渲染，或在自定义字体的动态字体导入选项中启用多通道带符号距离场。对于系统字体，可以在检查器中启用 SystemFont.multichannel_signed_distance_field 。

方法说明

void align() 🔗

将相机与跟踪的节点对齐。

void force_update_scroll() 🔗

强制相机立即更新滚动。

float get_drag_margin(margin: Side) const 🔗

返回指定边 Side 的边距。另见 drag_bottom_margin、drag_top_margin、drag_left_margin 和 drag_right_margin。

int get_limit(margin: Side) const 🔗

返回指定边 Side 的相机极限。另见 limit_bottom、limit_top、limit_left 和 limit_right。

Vector2 get_screen_center_position() const 🔗

返回该 Camera2D 视角下的屏幕中心位置，使用全局坐标。

注意：相机实际的目标位置可能与此不同。见 get_target_position。

Vector2 get_target_position() const 🔗

返回该相机的目标位置，使用全局坐标。

注意：返回值与 Node2D.global_position 不同，因为会受到拖动属性的影响。如果 position_smoothing_enabled 为 true ，也不等同于当前位置（见 get_screen_center_position）。

bool is_current() const 🔗

如果该 Camera2D 为活动相机，则返回 true（见 Viewport.get_camera_2d）。

void make_current() 🔗

强制该 Camera2D 成为当前的活动相机。enabled 必须为 true。

void reset_smoothing() 🔗

将相机的位置立即设置为其当前平滑的目标位置。

当 position_smoothing_enabled 为 false 时，本方法无效。

void set_drag_margin(margin: Side, drag_margin: float) 🔗

设置指定边 Side 的边距。另见 drag_bottom_margin、drag_top_margin、drag_left_margin 和 drag_right_margin。

void set_limit(margin: Side, limit: int) 🔗

设置指定边 Side 的相机极限。另见 limit_bottom、limit_top、limit_left 和 limit_right。