• 文档
• 教程
• 游戏开发

本篇指南围绕 Godot 官方文档中ResourceImporterBitMap类参考展开，系统讲解 BitMap（二维布尔值数组）资源的导入机制、create_from与threshold两个核心导入参数的工作原理，以及如何将图片导入为 BitMap 后作为TextureButton/TouchScreenButton的点击遮罩使用。读完本文，你将掌握在编辑器 Import 面板中配置 BitMap 导入、在脚本中查询与生成位图数据，以及结合BitMap类方法完成形态学处理与多边形提取的完整实战方案。

一、ResourceImporterBitMap 在 Godot 资源管线中的定位

Godot 引擎在导入外部素材时，会把各类资源统一交给对应的导入器（Importer）处理，BitMap 资源的导入器即ResourceImporterBitMap。从类继承关系看（见 class_resourceimporterbitmap.rst）：

ResourceImporterBitMap < ResourceImporter < RefCounted < Object

其基类ResourceImporter是 Godot 全部资源导入器的基类，继承它的导入器还包括ResourceImporterImage、ResourceImporterTexture、ResourceImporterScene、ResourceImporterWAV等十余种（见 class_resourceimporter.rst）。官方文档对ResourceImporterBitMap的作用定义非常明确：

Imports aBitMapresource (2D array of boolean values).

也就是说，它的职责是把一张普通图片转换为BitMap资源——一个每个元素只占 1 bit 的二维布尔矩阵，用于高效存储二进制掩码数据（见 class_bitmap.rst）。

需要特别强调的是，BitMap 与 Texture2D 有本质区别：

• Texture2D存储在显存中，用于 2D/3D 节点上的直接渲染显示；
• BitMap是一种 1-bit 单色资源，无法直接显示在任何 2D 或 3D 节点上，但像素值可以通过脚本使用get_bit()查询（见 tutorials/assets_pipeline/importing_images.rst 中 "Changing import type" 一节）。

BitMap 的典型用途

ResourceImporterBitMap生成的BitMap资源最典型的应用场景是作为点击遮罩（click mask）：

• TextureButton.texture_click_mask：纯黑白的BitMap图像，用于点击检测。遮罩上白色像素代表按钮的可点击区域，可借此制作任意曲线/异形形状的按钮（见 class_texturebutton.rst 中texture_click_mask属性）；
• TouchScreenButton.bitmask：触屏按钮的位图遮罩，用法相同（见 class_touchscreenbutton.rst 中bitmask属性）。

这意味着，对于圆形、星形、不规则图案等非矩形交互区域，通过 BitMap 遮罩可以做到"所见即所点"，让点击判定精确到像素级别。

二、两个核心导入属性：create_from 与 threshold

ResourceImporterBitMap的全部导入选项由以下两个属性构成，它们共同决定了"图片如何被转成布尔位图"：

create_from：选择数据来源

create_from决定以图像的哪部分信息作为生成位图的依据，共有两种模式（属性描述原文见 class_resourceimporterbitmap.rst）：

Black & White（黑与白）模式像素的 HSV 值大于threshold时，该位视为 "enabled"（true）；HSV 值小于或等于threshold时，该位视为 "disabled"（false）。

Alpha（Alpha 通道）模式像素的 Alpha 值大于threshold时，该位视为 "enabled"（true）；Alpha 值小于或等于threshold时，该位视为 "disabled"（false）。

从属性表默认值0及属性描述的枚举顺序可以推断，0对应Black & White模式，1对应Alpha模式。两种模式的选择取决于你的源图片形态：

• 源图片本身就是纯黑白轮廓图（如 logo、字形、剪影），适合Black & White，直接把亮度转化为布尔值；
• 源图片带 Alpha 通道（如半透明 PNG、带抗锯齿边缘的贴图），适合Alpha，直接把透明度转化为布尔值，可以精确保留抗锯齿边缘的轮廓信息。

threshold：阈值判定

threshold是一个0.0 ~ 1.0之间的浮点值（默认0.5），用于确定哪些位应被判定为 enabled 或 disabled：

• 阈值越高，被判定为true（enabled）的区域越小，遮罩越"苛刻"；
• 阈值越低，被判定为true的区域越大，遮罩越"宽松"。

例如在Alpha模式下，若源图某像素 Alpha = 0.6，则当threshold = 0.5时该位为true；若把threshold提高到0.7，则该位变为false。调整阈值时建议边调边在导入预览中观察效果，找到恰好能覆盖交互区域又不过度外扩的取值。

与运行时 API 的对应关系

值得一提的是，ResourceImporterBitMap的两个参数与BitMap类的运行时方法create_from_image_alpha()在语义上高度一致（见 class_bitmap.rst）：

create_from_image_alpha(image: Image, threshold: float = 0.1)

该方法"根据给定图像的尺寸创建位图，若图像在该位置的 Alpha 值等于或小于threshold则对应位设为false，否则为true"——与导入器的Alpha模式判定规则完全同源。也就是说，你既可以在编辑器里通过导入器静态生成位图，也可以在运行时用代码对任意Image实时生成位图，判定逻辑一致。注意运行时方法的默认阈值是0.1，与导入器默认值0.5不同，混用时需留意。

三、编辑器实操：把图片导入为 BitMap 资源

导入流程与文件存放

Godot 的导入流程遵循统一规则：把图片文件（PNG、JPG、WebP、SVG 等）直接放入项目文件夹，或从系统文件管理器拖拽到编辑器的 FileSystem 停靠面板，Godot 便会自动导入资源，并将导入产物隐藏在res://.godot/imported/目录中（见 tutorials/assets_pipeline/import_process.rst）。

注意：访问导入资源必须通过ResourceLoader（即load()），它会自动解析内部文件的存放位置；直接用FileAccess读取在编辑器里能工作，但在导出的项目中会失败。

切换导入类型为 BitMap

默认情况下图片会被导入为 Texture2D。要改为 BitMap 类型，在 FileSystem 停靠面板选中图片后，打开Import面板，将导入类型切换为BitMap（对应 tutorials/assets_pipeline/importing_images.rst 中 "Changing import type" 一节列出的可选导入类型之一）。切换到 BitMap 后，面板中会出现create_from与threshold两个参数供调整。

此时即可根据上节内容设置数据来源与阈值。设置完成后点击Reimport按钮应用更改：

• 切换导入类型或修改参数后，必须先点击 Reimport；若在点击前选中了 FileSystem 面板中的其他文件，本次修改会被丢弃；
• Reimport 后的参数只对该素材及后续的重复导入生效；
• 若需要批量修改，可在 FileSystem 中同时选中多个素材，Import 面板中每个参数左侧会出现勾选框，勾选后统一修改并点击重新导入，所有被选中素材只会应用勾选参数的变化（见 tutorials/assets_pipeline/import_process.rst）；
• 当源文件的 MD5 校验和发生变化时，Godot 会自动重新导入该素材，并使用为其配置的预设参数。

导入完成后，在脚本中即可通过load()拿到BitMap资源并使用。

配置示例：制作一个圆形按钮的点击遮罩

以典型的"圆形按钮精确点击"为例，完整的配置与使用步骤如下：

1. 准备一张圆形图案的 PNG（白色圆形、透明或黑色背景均可）；
2. 放入项目目录，在 FileSystem 中选中它，Import 面板中将导入类型切换为BitMap；
3. 若图片本身是"白色图形 + 黑色背景"，选择create_from = 0（Black & White），threshold保持在0.5附近；
4. 若图片依赖 Alpha 通道表达形状（例如带抗锯齿边缘的半透明贴图），选择create_from = 1（Alpha），再按需微调threshold；
5. 点击Reimport生成 BitMap 资源；
6. 在场景中把生成的 BitMap 拖到TextureButton的texture_click_mask属性（或TouchScreenButton的bitmask属性）上。

之后，当玩家点击按钮矩形范围内、但落在圆形遮罩之外的透明角落时，按钮将不会响应点击。

四、脚本侧的读取与动态生成

导入的 BitMap 资源既可以直接挂在控件上使用，也可以在脚本中查询和操纵其数据。以下代码展示了核心读写方式（方法签名均出自 class_bitmap.rst）：

# 加载导入的 BitMap 资源 var mask: BitMap = load("res://icon_bitmap.png") # 实际路径以导入后的资源路径为准 # 查询某一位的值（笛卡尔坐标） var enabled: bool = mask.get_bit(10, 20) # 等价于 get_bitv(Vector2i(10, 20)) # 获取尺寸与 true 位数 var size: Vector2i = mask.get_size() var true_count: int = mask.get_true_bit_count() # 运行时从任意 Image 的 Alpha 通道生成位图 var bitmap := BitMap.new() bitmap.create_from_image_alpha(some_image, 0.5)

常用方法速查

其中grow_mask()可用于修正遮罩边缘误差（例如对遮罩膨胀 1~2 像素避免边缘漏点），opaque_to_polygons()则可以把遮罩轮廓转化为多边形顶点集，用于碰撞体或判定区域的生成——注意 RDP 算法的epsilon越小，生成的多边形点数越多、贴合越精确（要覆盖整个位图，可传入Rect2(Vector2(), get_size())）。

五、类参考速览

ResourceImporterBitMap不提供任何可调用方法，全部接口仅为两个导入属性（完整参考见 class_resourceimporterbitmap.rst）：

Properties int create_from = 0 float threshold = 0.5

其继承链ResourceImporterBitMap < ResourceImporter < RefCounted < Object意味着它同样受ResourceImporter基类框架约束（如ImportOrder枚举：默认导入顺序为 0，场景导入顺序为 100，自定义导入器一般应低于 100 以避免依赖问题，详见 class_resourceimporter.rst），但在日常使用中，你只需关心create_from与threshold两个参数。

六、总结

ResourceImporterBitMap是 Godot 将图片转换为 1-bit 布尔矩阵的核心入口，仅凭create_from（数据来源：亮度或 Alpha）与threshold（判定阈值）两个参数即可完成全部配置。它的实际价值体现在与TextureButton.texture_click_mask、TouchScreenButton.bitmask的组合使用上，让异形按钮的像素级点击判定变得简单可靠；同时，BitMap类在运行时提供了与导入参数语义一致的方法族（create_from_image_alpha、get_bit、grow_mask、opaque_to_polygons等），支持静态导入与动态生成两种工作流。掌握"编辑器导入配置 + 脚本运行时读取"这套组合，即可应对各类需要精确遮罩与掩码判定的 2D 交互场景。

• 文档
• 教程
• 游戏开发