Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Camera2D

继承: Node2D < CanvasItem < Node < Object

2D 场景的相机节点。

描述

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

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

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

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

教程

属性

AnchorMode

anchor_mode

1

Node

custom_viewport

float

drag_bottom_margin

0.2

bool

drag_horizontal_enabled

false

float

drag_horizontal_offset

0.0

float

drag_left_margin

0.2

float

drag_right_margin

0.2

float

drag_top_margin

0.2

bool

drag_vertical_enabled

false

float

drag_vertical_offset

0.0

bool

editor_draw_drag_margin

false

bool

editor_draw_limits

false

bool

editor_draw_screen

true

bool

enabled

true

bool

ignore_rotation

true

int

limit_bottom

10000000

int

limit_left

-10000000

int

limit_right

10000000

bool

limit_smoothed

false

int

limit_top

-10000000

Vector2

offset

Vector2(0, 0)

bool

position_smoothing_enabled

false

float

position_smoothing_speed

5.0

Camera2DProcessCallback

process_callback

1

bool

rotation_smoothing_enabled

false

float

rotation_smoothing_speed

5.0

Vector2

zoom

Vector2(1, 1)

方法

void

align ( )

void

force_update_scroll ( )

float

get_drag_margin ( Side margin ) const

int

get_limit ( Side margin ) const

Vector2

get_screen_center_position ( ) const

Vector2

get_target_position ( ) const

bool

is_current ( ) const

void

make_current ( )

void

reset_smoothing ( )

void

set_drag_margin ( Side margin, float drag_margin )

void

set_limit ( Side margin, int limit )


枚举

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

Camera2D 的锚点。见 AnchorMode 常量。


Node custom_viewport

  • void set_custom_viewport ( Node value )

  • Node get_custom_viewport ( )

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


float drag_bottom_margin = 0.2

  • void set_drag_margin ( Side margin, float drag_margin )

  • float get_drag_margin ( Side margin ) const

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


bool drag_horizontal_enabled = false

  • void set_drag_horizontal_enabled ( bool value )

  • bool is_drag_horizontal_enabled ( )

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


float drag_horizontal_offset = 0.0

  • void set_drag_horizontal_offset ( float value )

  • float get_drag_horizontal_offset ( )

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

注意:用于设置初始水平拖动偏移量;确定当前偏移量;或强制当前偏移量。当 drag_horizontal_enabledtrue 或更改拖动边距时,它不会自动更新。


float drag_left_margin = 0.2

  • void set_drag_margin ( Side margin, float drag_margin )

  • float get_drag_margin ( Side margin ) const

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


float drag_right_margin = 0.2

  • void set_drag_margin ( Side margin, float drag_margin )

  • float get_drag_margin ( Side margin ) const

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


float drag_top_margin = 0.2

  • void set_drag_margin ( Side margin, float drag_margin )

  • float get_drag_margin ( Side margin ) const

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


bool drag_vertical_enabled = false

  • void set_drag_vertical_enabled ( bool value )

  • bool is_drag_vertical_enabled ( )

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


float drag_vertical_offset = 0.0

  • void set_drag_vertical_offset ( float value )

  • float get_drag_vertical_offset ( )

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

注意:用于设置初始垂直拖动偏移量;确定当前偏移量;或强制当前偏移量。当 drag_vertical_enabledtrue 或更改拖动边距时,它不会自动更新。


bool editor_draw_drag_margin = false

  • void set_margin_drawing_enabled ( bool value )

  • bool is_margin_drawing_enabled ( )

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


bool editor_draw_limits = false

  • void set_limit_drawing_enabled ( bool value )

  • bool is_limit_drawing_enabled ( )

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


bool editor_draw_screen = true

  • void set_screen_drawing_enabled ( bool value )

  • bool is_screen_drawing_enabled ( )

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


bool enabled = true

  • void set_enabled ( bool value )

  • bool is_enabled ( )

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

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


bool ignore_rotation = true

  • void set_ignore_rotation ( bool value )

  • bool is_ignoring_rotation ( )

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


int limit_bottom = 10000000

  • void set_limit ( Side margin, int limit )

  • int get_limit ( Side margin ) const

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


int limit_left = -10000000

  • void set_limit ( Side margin, int limit )

  • int get_limit ( Side margin ) const

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


int limit_right = 10000000

  • void set_limit ( Side margin, int limit )

  • int get_limit ( Side margin ) const

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


bool limit_smoothed = false

  • void set_limit_smoothing_enabled ( bool value )

  • bool is_limit_smoothing_enabled ( )

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

如果 position_smoothing_enabledfalse,则该属性无效。

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


int limit_top = -10000000

  • void set_limit ( Side margin, int limit )

  • int get_limit ( Side margin ) const

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


Vector2 offset = Vector2(0, 0)

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


bool position_smoothing_enabled = false

  • void set_position_smoothing_enabled ( bool value )

  • bool is_position_smoothing_enabled ( )

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


float position_smoothing_speed = 5.0

  • void set_position_smoothing_speed ( float value )

  • float get_position_smoothing_speed ( )

position_smoothing_enabledtrue 时,相机平滑效果的速度,单位为每秒像素。


Camera2DProcessCallback process_callback = 1

该相机的处理回调。见 Camera2DProcessCallback


bool rotation_smoothing_enabled = false

  • void set_rotation_smoothing_enabled ( bool value )

  • bool is_rotation_smoothing_enabled ( )

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

注意:如果 ignore_rotationtrue,则该属性无效。


float rotation_smoothing_speed = 5.0

  • void set_rotation_smoothing_speed ( float value )

  • float get_rotation_smoothing_speed ( )

rotation_smoothing_enabledtrue 时,相机旋转平滑效果的角度渐近速度。


Vector2 zoom = Vector2(1, 1)

相机的缩放。 设置为 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 ( Side margin ) const

返回指定边 Side 的边距。另见 drag_bottom_margindrag_top_margindrag_left_margindrag_right_margin


int get_limit ( Side margin ) const

返回指定边 Side 的相机极限。另见 limit_bottomlimit_toplimit_leftlimit_right


Vector2 get_screen_center_position ( ) const

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

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


Vector2 get_target_position ( ) const

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

注意:返回值与 Node2D.global_position 不同,因为会受到拖动属性的影响。如果 position_smoothing_enabledtrue ,也不等同于当前位置(见 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_enabledfalse 时,本方法无效。


void set_drag_margin ( Side margin, float drag_margin )

设置指定边 Side 的边距。另见 drag_bottom_margindrag_top_margindrag_left_margindrag_right_margin


void set_limit ( Side margin, int limit )

设置指定边 Side 的相机极限。另见 limit_bottomlimit_toplimit_leftlimit_right