瓦片地图

类型标识：TILE_MAP

属性

angle

旋转角度（度），顺时针为正。类型 float，默认 0。

collision_enabled

是否参与碰撞检测。类型 bool，默认 False。

collision_offset_x、collision_offset_y

形状相对对象中心的偏移（bbox 不适用）。类型 float，默认 0。

collision_points

polygon 形状的顶点列表。类型 list，默认 []。

collision_type

碰撞形状：'bbox'、'rect'、'ellipse' 或 'polygon'。类型 str，默认 'rect'。

collision_width、collision_height

rect 与 ellipse 形状的尺寸。类型 float，默认为对象尺寸。

color

填充色、文字色或图像着色，取决于对象类型。类型 (r, g, b, a)，默认 (255, 255, 255, 255)。

columns、rows

地图尺寸（以图块为单位）。类型 int，默认 8、6。

layers

图层字典：{'name', 'visible', 'collision', 'tiles'}。类型 list，默认 1 层。地图是在图块集图片上铺出的一片网格，图块编号 -1 表示空；其中一层可以标记为碰撞层——该层中只要放有图块，对应的格子就算作实心。

name

层级面板中显示的名称。运行时只读。类型 str。

physics_angular_damping

角速度阻尼。类型 float，默认 0。

physics_elasticity

弹性系数（0 为完全非弹性，1 为完全弹性）。类型 float，默认 0.2。

physics_enabled

是否启用刚体物理。类型 bool，默认 False。

physics_fixed_rotation

是否固定旋转（碰撞也不会让它转动）。类型 bool，默认 False。

physics_friction

摩擦系数。类型 float，默认 0.6。

physics_gravity_scale

重力缩放（0 表示不受重力影响）。类型 float，默认 1。

physics_linear_damping

线速度阻尼。类型 float，默认 0。

physics_mass

质量。类型 float，默认 1。

physics_shape_height、physics_shape_width

刚体形状 rect、ellipse 的尺寸（0 表示使用对象自身尺寸）。类型 float，默认 0。

physics_shape_offset_x、physics_shape_offset_y

刚体形状相对对象中心的偏移。类型 float，默认 0。

physics_shape_points

刚体形状 polygon 的顶点列表。类型 list，默认 []。

physics_shape_type

刚体形状：'rect'、'ellipse' 或 'polygon'。类型 str，默认 'rect'。

physics_type

刚体类型：'static'、'dynamic' 或 'kinematic'。类型 str，默认 'dynamic'。

pivot

变换基准点模式，可选值见 set_pivot()。类型 str，默认 'center'。

pivot_x、pivot_y

'custom' 基准点的坐标（对象自身的像素网格，原点在对象左上角）。类型 float，默认 0。

pos

即 (x, y)，赋值时会同步更新 x 和 y。类型 (int, int)，默认 (20, 20)。

scale

即 (scale_x, scale_y)。类型 (float, float)，默认 (1, 1)。

scale_x、scale_y

缩放系数（1 为原始大小）。类型 float，默认 1。

script_path

已挂载脚本的路径（相对于工程目录）。类型 str，默认 ''。

size

即 (width, height)。类型 (int, int)。

tile_width、tile_height

单个图块的尺寸（像素）。类型 int，默认 32、32。

tileset_path

图块集图片，相对于工程目录。类型 str，默认 ''。

type

类型标识；瓦片地图为 TILE_MAP。运行时只读。类型 str。

uuid

唯一标识，供 get_object_by_uuid() 使用。运行时只读。类型 str。

visible

隐藏的对象不会绘制，也无法被点击。类型 bool，默认 True。

width、height

像素尺寸。类型 int，默认随对象类型而定。

x、y

相对于父对象的位置。类型 int，默认 20。

方法

clear_tiles(layer=None)

清空一层（等同于 fill_tiles(-1)）。

• layer（int | None）：图层序号；默认使用当前活动图层。

collides_with_object(other)

is_colliding_with_object 的别名。

• other（object）：另一个对象。

collides_with_point(x, y)

点（场景坐标）是否落在碰撞形状内。

• x（int）：点的 x（场景坐标）。
• y（int）：点的 y（场景坐标）。

collides_with_rect(rect)

形状是否与 pygame.Rect 或 (x, y, w, h) 元组重叠。

• rect（pygame.Rect | (int, int, int, int)）：矩形（场景坐标）。

collides_with_world_rect(rect)

某个矩形（场景坐标）与实心格子重叠时为 True。

• rect（pygame.Rect | (int, int, int, int)）：矩形（场景坐标）。

distance_to(x, y)

对象中心到某个点的距离。

• x（int）：点的 x（场景坐标）。
• y（int）：点的 y（场景坐标）。

distance_to_object(other)

两个对象中心之间的距离。

• other（object）：另一个对象。

fill_tiles(tile_id, layer=None)

用同一个图块编号填满整层。

• tile_id（int）：图块编号；-1 表示清空。
• layer（int | None）：图层序号；默认使用当前活动图层。

get_active_layer_index()

编辑器中正在绘制的图层序号。

get_active_layer_tiles()

当前激活图层所有格子的瓦片 id 列表。

get_angle()

旋转角度（度）。

get_center()

对象中心（场景坐标）。

get_collision_center()

碰撞形状的中心（场景坐标）。

get_collision_layer_index()

碰撞层的序号；没有标记碰撞层时为 None。

get_collision_offset()

形状相对对象中心的偏移。

get_collision_polygon()

多边形顶点列表。

get_collision_radius()

椭圆形状的半径（较短边的一半）。

get_collision_rect(x, y, width, height)

与矩形的重叠区域，没有重叠时为 None。

• x（int）：矩形的 x（场景坐标）。
• y（int）：矩形的 y（场景坐标）。
• width（int）：矩形宽度。
• height（int）：矩形高度。

get_collision_rects()

合并后的实心矩形（本地像素坐标，每行中连续的实心格子各一个）。

get_collision_rects_world()

同样这些矩形，但使用场景坐标（地图被旋转时返回 []）。

get_collision_size()

rect 与 ellipse 形状的尺寸。

get_collision_type()

当前碰撞形状。

get_color()

填充、文字或着色颜色 (r, g, b, a)。

get_direction_to(x, y)

从对象指向某点的单位向量 (dx, dy)。

• x（int）：点的 x（场景坐标）。
• y（int）：点的 y（场景坐标）。

get_height()

高度（像素）。

get_layer_count()

图层数量。

get_layer_name(index)

某一层的名称。

• index（int）：图层序号。

get_layer_names()

全部图层的名称。

get_layer_tiles(index)

某一层的图块编号列表。

• index（int）：图层序号。

get_map_pixel_size()

地图的像素尺寸。

get_map_size()

网格尺寸 (列数, 行数)。

get_name()

对象名称。

get_pivot()

变换基准点模式（如 'center'、'top_left'、'custom'）。

get_pivot_point()

基准点解析到对象内容像素后的坐标 (x, y)。

get_pos()

相对父对象的本地坐标 (x, y)。

get_rect()

对象的本地 pygame.Rect。

get_scale()

缩放系数 (scale_x, scale_y)。

get_scale_x()

x 方向缩放系数。

get_scale_y()

y 方向缩放系数。

get_size()

尺寸 (宽, 高)（像素）。

get_tile(column, row, layer=None)

某个格子的图块编号（-1 表示空）；省略 layer 时使用当前活动图层。

• column（int）：格子列号。
• row（int）：格子行号。
• layer（int | None）：图层序号。

get_tile_size()

单个图块的尺寸 (宽, 高)。

get_tileset_dimensions()

图块集图片的 (宽, 高)；未设置时为 (0, 0)。

get_tileset_path()

当前图块集图片路径。

get_tileset_tile_count()

图块集中图块的数量。

get_tileset_tiles()

切分好的图块表面（按行优先、与图块编号顺序一致）。

get_type()

对象类型标识。

get_uuid()

对象 uuid。

get_visible_state()

读取 visible 状态。

get_width()

宽度（像素）。

get_world_pos()

叠加父对象偏移后的场景坐标。

get_world_rect()

场景坐标下的 pygame.Rect。

get_x()

本地坐标的 x 分量。

get_y()

本地坐标的 y 分量。

hide()

隐藏对象，等同于设置 obj.visible = False。

is_cell_solid(column, row)

碰撞层在该格子放有图块时为 True。

• column（int）：格子列号。
• row（int）：格子行号。

is_colliding_with_object(other)

两个对象都开启碰撞且形状重叠时为 True。

• other（object）：另一个对象。

is_colliding_with_rect(x, y, width, height)

形状是否与给定矩形重叠。

• x（int）：矩形的 x（场景坐标）。
• y（int）：矩形的 y（场景坐标）。
• width（int）：矩形宽度。
• height（int）：矩形高度。

is_collision_enabled()

该对象是否开启了碰撞检测。

is_collision_layer(index)

该层是否为碰撞层。

• index（int）：图层序号。

is_hidden()

对象是否被隐藏。

is_layer_visible(index)

该层是否渲染。

• index（int）：图层序号。

is_point_inside(x, y)

轻量检测：点落在对象的外接矩形内即为 True。

• x（int）：点的 x（场景坐标）。
• y（int）：点的 y（场景坐标）。

is_pressed(x, y)

逐像素检测：只有落在非透明像素上才是 True。适合处理点击，不适合每帧调用。

• x（int）：点的 x（场景坐标）。
• y（int）：点的 y（场景坐标）。

is_shown()

同 is_visible()。

is_solid_at(world_x, world_y)

某点（场景坐标）落在实心格子上时为 True（地图被旋转时返回 False）。

• world_x（float）：点的 x（场景坐标）。
• world_y（float）：点的 y（场景坐标）。

is_visible()

对象是否可见。

move(dx, dy)

在当前位置上移动 (dx, dy) 像素。

• dx（int）：水平位移。
• dy（int）：垂直位移。

reset_collision_shape()

把形状字段重置为对象自身尺寸。

set_active_layer_index(index)

设置编辑器中正在绘制的图层（仅编辑器状态）。

• index（int）：图层序号。

set_angle(degrees)

设置旋转角度。

• degrees（float）：角度（度），顺时针为正。

set_center(x, y)

设置对象中心（场景坐标）。

• x（int）：新的中心 x。
• y（int）：新的中心 y。

set_collision_ellipse(radius_x, radius_y)

便捷方法：用两个半径设置椭圆。

• radius_x（float）：水平半径。
• radius_y（float）：垂直半径。

set_collision_enabled(enabled)

开启 / 关闭碰撞检测。关闭时所有 collides_with_* / is_colliding_* 都返回 False。

• enabled（bool）：True / False。

set_collision_offset(x, y)

让形状相对对象中心偏移（会跟随缩放与旋转）。

• x（float）：水平偏移。
• y（float）：垂直偏移。

set_collision_polygon(points)

设置多边形顶点。

• points（list）：顶点列表，例如 [(0, 0), (50, 0), (25, 40)]。

set_collision_size(width, height)

设置 rect 与 ellipse 的尺寸。

• width（int）：形状宽度。
• height（int）：形状高度。

set_collision_type(type)

设置碰撞形状。

• type（str）：'bbox'、'rect'、'ellipse' 或 'polygon'。

set_color(color)

设置颜色。

• color（(r, g, b, a)）：新的颜色元组。

set_height(h)

设置高度。

• h（int）：新的高度（像素）。

set_map_size(columns, rows)

设置网格尺寸（以图块为单位），所有图层都会重新适配。

• columns（int）：新的列数。
• rows（int）：新的行数。

set_pivot(pivot)

设置变换基准点模式。

• pivot（str）：'center'（默认）、'top_left'、'top_center'、'top_right'、'center_left'、'center_right'、'bottom_left'、'bottom_center'、'bottom_right' 或 'custom'。

set_pivot_point(x, y)

把基准点设到对象自身像素网格的任意一点（同时把 pivot 设为 'custom'）。

• x（float）：基准点 x（对象自身像素网格）。
• y（float）：基准点 y。

set_pos(x, y)

设置相对父对象的本地坐标。

• x（int）：新的 x，相对父对象（像素）。
• y（int）：新的 y，相对父对象（像素）。

set_scale(sx, sy)

设置两个缩放系数。

• sx（float）：x 方向缩放系数。
• sy（float）：y 方向缩放系数。

set_scale_x(sx)

设置 x 方向缩放系数。

• sx（float）：x 方向缩放系数。

set_scale_y(sy)

设置 y 方向缩放系数。

• sy（float）：y 方向缩放系数。

set_size(width, height)

设置尺寸（像素）。

• width（int）：新的宽度。
• height（int）：新的高度。

set_tile(column, row, tile_id, layer=None)

设置单个格子。

• column（int）：格子列号。
• row（int）：格子行号。
• tile_id（int）：图块编号；-1 表示清空。
• layer（int | None）：图层序号；默认使用当前活动图层。

set_tile_size(tile_width, tile_height)

设置单个图块的尺寸。

• tile_width（int）：图块宽度（像素）。
• tile_height（int）：图块高度（像素）。

set_tileset_path(tileset_path)

设置图块集图片。

• tileset_path（str）：图片文件（相对于工程目录）。

set_visible_state(visible)

设置 visible 状态。

• visible（bool）：True 显示对象，False 隐藏对象。

set_width(w)

设置宽度。

• w（int）：新的宽度（像素）。

set_world_pos(x, y)

设置场景坐标（已叠加父对象偏移）。

• x（int）：新的 x（场景坐标）。
• y（int）：新的 y（场景坐标）。

set_x(x)

设置本地坐标的 x 分量。

• x（int）：新的 x，相对父对象。

set_y(y)

设置本地坐标的 y 分量。

• y（int）：新的 y，相对父对象。

show()

显示对象，等同于设置 obj.visible = True。

事件

on_clicked()

在该对象上完成一次按下并释放。

on_collision_enter(other)

开始与 other 重叠（双方都需要开启碰撞）。

• other（object）：另一个对象。

on_collision_exit(other)

与 other 的重叠结束。

• other（object）：另一个对象。

on_destroy()

场景被替换、对象被 studio.destroy_object() 移除，或游戏退出时执行。

on_double_clicked()

双击该对象。

on_drag(pos)

拖动过程中鼠标移动。

• pos（(int, int)）：指针位置（场景坐标）。

on_drag_end()

拖动结束。

on_drag_start()

在对象上开始拖动。

on_mouse_enter()

鼠标移入对象。

on_mouse_leave()

鼠标移出对象。

on_pressed()

在该对象上按下鼠标左键。

on_released()

在该对象上按下的按键被释放。

on_right_clicked()

右键点击该对象。

on_start()

场景加载完成后执行一次。

on_update(dt)

每帧执行。

• dt（float）：距上一帧的秒数。

on_visible_changed(visible)

对象被显示或隐藏时。

• visible（bool）：显示为 True，隐藏为 False。