文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载导读TileSetAtlasSource是 Godot 4 瓦片地图体系TileMap/TileSet中用于把一张 2D 图集贴图atlas texture切分成可平铺瓦片的核心资源类。本文以 classes/class_tilesetatlassource.rst 为骨架结合 TileSet 教程、TileMap 教程 及同仓库中的 TileSetSource、TileData、TileMapLayer 等类文档系统讲解图集网格布局、瓦片创建、替代瓦片alternative tile、逐帧动画、运行时纹理填充以及变换位标志并给出可直接套用的 GDScript 示例。读完本文你将能独立完成图集型 TileSet 的搭建、属性调优与运行时瓦片操作。一、类概览TileSetAtlasSource 在 TileSet 体系中的位置TileSetAtlasSource继承自TileSetSource进而继承Resource → RefCounted → Object是 Godot 瓦片体系的两种瓦片源之一TileSetAtlasSource 继承自 TileSetSource瓦片源基类 ├── TileSetAtlasSource ← 本文主角从 2D 图集贴图切分瓦片 └── TileSetScenesCollectionSource ← 场景瓦片源以场景为瓦片基类职责TileSetSource 定义了瓦片源的公共接口——瓦片以「坐标 IDVector2i 替代 IDint」两个维度索引并对外暴露get_tiles_count()、get_tile_id()、get_alternative_tiles_count()、get_alternative_tile_id()、has_tile()、has_alternative_tile()等查询方法。基类只提供 getter具体取值约束由子类实现。TileSet 容器TileSet 是瓦片库容器管理一个或多个TileSetSource。每个TileSetAtlasSource对应一张图集贴图图集 IDsource ID用于在 TileSet 中唯一标识该源。消费方TileMapLayerGodot 4.2 的推荐节点旧版TileMap已弃用通过source_id atlas_coords alternative_tile三 ID 组合引用具体瓦片见 set_cell 文档。核心设计思想一个图集是铺在贴图上的瓦片网格。每个网格单元由create_tile()显式暴露为瓦片之后以网格坐标为 ID 索引。瓦片可以跨多个网格单元占据 2×2、1×3 等矩形区域。每个瓦片还能通过create_alternative_tile()派生替代版本替代 ID 为 0 时指向主瓦片网格中的那一张。每个替代瓦片拥有独立的一组属性属性由所属TileSet的属性层物理/导航/遮挡/自定义数据层定义存放在一个TileData对象中通过get_tile_data()读写。值得注意的进阶用法由于TileData属性直接存储在TileSetAtlasSource资源内可以使用TileSetAtlasSource.set(coords_x:coords_y/alternative_id/tile_data_property)这样的路径式字符串直接修改任意瓦片属性例如atlas_source.set(3:4/1/flip_h, true)这在批量脚本化配置时非常方便。二、五个核心属性图集网格的布局参数TileSetAtlasSource的全部属性都在下表中它们是图集如何被切分的直接依据属性类型默认值说明textureTexture2D—图集贴图本身marginsVector2iVector2i(0, 0)网格原点在贴图上的偏移像素用于避开贴图边缘的留白separationVector2iVector2i(0, 0)每个瓦片纹理区域之间的间距像素用于避开图集里的分隔线/引导线texture_region_sizeVector2iVector2i(16, 16)贴图中单个瓦片的基准尺寸像素必须大于或等于 TileSet 的tile_sizeuse_texture_paddingbooltrue是否为每个瓦片生成带 1 像素内边距的内部纹理2.1 属性间的计算关系get_atlas_grid_size()返回图集网格尺寸它由三项决定网格列数 (texture.width - margins.x) / (texture_region_size.x separation.x) 网格行数 (texture.height - margins.y) / (texture_region_size.y separation.y)即贴图尺寸、margins、separation 与 texture_region_size 共同决定能放下多少瓦片。修改其中任意一项都可能导致部分瓦片落在贴图区域之外而被自动删除。2.2 use_texture_padding 与纹理出血use_texture_padding true时Godot 会在内部生成一张为每个瓦片额外包裹 1 像素内边距的ImageTexture避免纹理过滤开启时瓦片之间出现细线纹理出血/bleeding——这是最常见的图集瑕疵。代价是每次修改TileSetAtlasSource资源时都需要额外的内存与处理时间。若关闭该选项虽然能带来少量性能提升但需要自行承担渲染瑕疵风险。官方编辑器默认勾选且推荐保持开启见 Using TileSets 教程。运行时可通过get_runtime_texture()获取实际渲染用的贴图use_texture_padding false时直接返回texture否则返回内部生成的含内边距的ImageTexture。配合get_runtime_tile_texture_region(atlas_coords, frame)可取得瓦片在运行时贴图中的实际区域注意该区域已计入内边距当use_texture_padding false时它与get_tile_texture_region()的返回值相同。三、瓦片创建、删除与移动3.1 创建瓦片create_tile(atlas_coords: Vector2i, size: Vector2i Vector2i(1, 1))在网格坐标atlas_coords处创建尺寸为size的新瓦片。size允许瓦片横跨多个网格单元例如create_tile(Vector2i(2, 1), Vector2i(2, 2))会创建一块 2×2 的大瓦片。限制目标区域必须未被占用且必须能容纳于贴图范围内。在编辑器中自动创建瓦片会根据tile_size与贴图内容批量生成完全透明的区域不会生成瓦片见 教程中的自动创建示例图3.2 删除瓦片remove_tile(atlas_coords: Vector2i)删除指定坐标的瓦片及其全部替代瓦片。3.3 移动瓦片move_tile_in_atlas(atlas_coords: Vector2i, new_atlas_coords: Vector2i Vector2i(-1, -1), new_size: Vector2i Vector2i(-1, -1))将瓦片及其替代版本移动到新坐标并可同时改尺寸new_atlas_coords为Vector2i(-1, -1)时保持原坐标new_size为Vector2i(-1, -1)时保持原尺寸若目标区域已有瓦片则调用失败因此先调用has_room_for_tile()校验再移动是推荐做法。3.4 越界瓦片的检测与清理has_tiles_outside_texture() - bool clear_tiles_outside_texture()has_tiles_outside_texture()检查是否存在部分或完全超出贴图区域的瓦片clear_tiles_outside_texture()移除所有放不下的瓦片。由于该方法会遍历全部瓦片官方文档建议先调用has_tiles_outside_texture()确认有越界瓦片再清理。get_tiles_to_be_removed_on_change(texture, margins, separation, texture_region_size)返回一个PackedVector2Array列出当这四项属性改为指定值时将被自动删除的瓦片坐标 ID。这为修改布局参数前预览数据丢失提供了接口——开发者可以在改动属性前用它做撤销保护。四、替代瓦片Alternative Tile一图多用4.1 创建与删除create_alternative_tile(atlas_coords: Vector2i, alternative_id_override: int -1) - int remove_alternative_tile(atlas_coords: Vector2i, alternative_tile: int) set_alternative_tile_id(atlas_coords: Vector2i, alternative_tile: int, new_id: int)create_alternative_tile为坐标atlas_coords的主瓦片创建替代瓦片。alternative_id_override为-1时自动生成唯一 ID否则使用指定 ID返回新替代 ID若指定 ID 冲突则返回-1。remove_alternative_tile删除指定替代瓦片alternative_tile 0时调用必然失败因为主瓦片base tile的替代版本不可被删除。set_alternative_tile_id把替代瓦片的 ID 从alternative_tile改为new_idnew_id 0时调用失败主瓦片替代不可被搬移。get_next_alternative_tile_id(atlas_coords)返回下一次调用create_alternative_tile()将得到的自动 ID用于预判。为什么需要替代瓦片典型场景是同一张贴图多种配置——同一个瓦片图像可以派生旋转、翻转、调色、不同物理层或不同自定义数据的变体。在 TileSet 教程的替代瓦片章节 中通过右键主瓦片选择Create an Alternative Tile创建随后可在 Select 模式下编辑其属性Flip H/V、Transpose、Texture Origin、Modulate、Material、Z Index、Y Sort Origin 等注意创建替代瓦片时不会继承主瓦片的任何属性需要按需重新设置这一点在官方文档中特别强调。4.2 瓦片数据TileDataget_tile_data(atlas_coords: Vector2i, alternative_tile: int) - TileData返回指定坐标与替代 ID 对应的TileData对象。TileData见 classes/class_tiledata.rst保存单块瓦片的全部可配置状态包括flip_h、flip_v、transpose、modulate、material、texture_origin、probability、z_index、y_sort_origin、terrain/terrain_set以及按层索引的碰撞多边形、遮挡多边形、导航区域与自定义数据。TileData 的层级由TileSet的物理/导航/遮挡/自定义数据层决定因此TileSet中每添加一个层每个替代瓦片的 TileData 就多出一组可写属性。TileData既可在编辑器TileSet 面板中间列修改也可在运行时通过TileMapLayer._tile_data_runtime_update()回调动态改写。五、图集瓦片动画帧、列、间距与速度TileSetAtlasSource原生支持把连续几帧放在图集网格中形成瓦片动画相关方法成对出现getter/setter方法对含义get/set_tile_animation_frames_count瓦片动画总帧数get/set_tile_animation_columns动画帧在网格中的列数设为0表示所有帧排成单行get/set_tile_animation_separation动画帧之间的网格间距以网格单元计get/set_tile_animation_speed动画播放速度get/set_tile_animation_frame_duration指定帧frame_index的时长get/set_tile_animation_mode动画模式见下节枚举另有派生查询get_tile_animation_total_duration(atlas_coords)返回各帧时长的总和实际单次循环时长 帧时长总和 ÷ 动画速度。get_tile_animation_frames_count/get_tile_animation_columns/get_tile_animation_separation/get_tile_animation_speed/get_tile_animation_mode分别读取上述配置。一个典型的4 帧行走动画配置流程伪代码var atlas: TileSetAtlasSource tile_set.get_source(0) var coords : Vector2i(1, 2) atlas.set_tile_animation_frames_count(coords, 4) atlas.set_tile_animation_columns(coords, 4) # 4×1 横向排布 atlas.set_tile_animation_frame_duration(coords, 0, 0.15) atlas.set_tile_animation_frame_duration(coords, 1, 0.15) atlas.set_tile_animation_frame_duration(coords, 2, 0.15) atlas.set_tile_animation_frame_duration(coords, 3, 0.15) atlas.set_tile_animation_speed(coords, 1.0) # 总循环时长 0.6 / 1.0 0.6s5.1 TileAnimationMode 枚举enum TileAnimationMode { TILE_ANIMATION_MODE_DEFAULT 0, # 所有瓦片动画同时启动外观整齐划一 TILE_ANIMATION_MODE_RANDOM_START_TIMES 1, # 各瓦片动画随机起始时间外观更富变化 TILE_ANIMATION_MODE_MAX 2, # 枚举大小占位哨兵值 }TILE_ANIMATION_MODE_RANDOM_START_TIMES适合水面、熔岩、植被等需要错峰观感的自然元素DEFAULT适合需要所有实例严格同步的场合。六、变换位标志在 TileMap 中翻转/旋转瓦片三个常量用于在TileMapLayer/TileMap中表达格子变换通过改写替代 ID 的二进制位实现常量值含义TRANSFORM_FLIP_H4096水平翻转标志TRANSFORM_FLIP_V8192垂直翻转标志TRANSFORM_TRANSPOSE16384转置标志官方文档给出的运行时翻转示例需配合get_cell_alternative_tile()读取当前替代 ID再用|组合标志写回var alternate_id $TileMapLayer.get_cell_alternative_tile(Vector2i(2, 2)) if not alternate_id TileSetAtlasSource.TRANSFORM_FLIP_H: # 若瓦片尚未翻转则水平翻转它 $TileMapLayer.set_cell(Vector2i(2, 2), source_id, atlas_coords, alternate_id | TileSetAtlasSource.TRANSFORM_FLIP_H)这些变换标志可以组合等效实现 0°/90°/180°/270° 旋转enum TileTransform { ROTATE_0 0, ROTATE_90 TileSetAtlasSource.TRANSFORM_TRANSPOSE | TileSetAtlasSource.TRANSFORM_FLIP_H, ROTATE_180 TileSetAtlasSource.TRANSFORM_FLIP_H | TileSetAtlasSource.TRANSFORM_FLIP_V, ROTATE_270 TileSetAtlasSource.TRANSFORM_TRANSPOSE | TileSetAtlasSource.TRANSFORM_FLIP_V, }在 TileMap 教程 的 TileMap 编辑器中可直接使用旋转/翻转按钮无需手工创建替代瓦片Godot 4.2 特性而代码路径下位标志方案依然是运行时变换的标准手段。三 ID 体系说明可参考 TileMap.set_cell 文档source_id定位TileSetSourceatlas_coords定位图集内网格坐标alternative_tile定位替代版本图集源场景下场景 ID 由TileSetScenesCollectionSource使用。七、编辑器中的完整工作流实践篇以下步骤对应 Using TileSets 教程 的实操流程与本类 API 一一对应创建 TileSet 资源在TileMapLayer节点的 Inspector 中新建TileSet资源先设置tile_size例如 64×64——若依赖自动创建瓦片必须在创建图集之前设置好 tile size因为图集切分以它为依据。创建图集源打开底部TileSet面板将 tilesheet 图片拖入面板选择自动创建瓦片。此时后台实际执行的正是create_tile()的批量逻辑完全透明的贴图区域不会生成瓦片。调整图集属性在中间列编辑Margins、Separation、Texture Region Size、Use Texture Padding等对应本类五个属性修改这些参数可能导致越界瓦片被删可通过面板顶部的Create Tiles in Non-Transparent Texture Regions重新生成。官方对参数的建议Margins贴图边缘留白如版权署名区需要跳过的像素数Separation贴图自带分隔线/引导线时需要空开的像素间距Texture Region Size多数情况下应等于 TileSet 的 tile size非强制。创建替代瓦片右键主瓦片 →Create an Alternative Tile替代瓦片在编辑器中显示于主瓦片右侧Select 模式下可改其Alternative ID、Flip H/V、Transpose、Modulate等属性。提示一个 TileSet 可容纳多张图集多个TileSetAtlasSource实例并可通过Atlas Merging Tool合并合并后原 tilesheet 图片保留在文件系统TileSet 内的未合并图集被移除选择Merge (Keep Original Atlases)可保留。八、运行时与脚本化的实用要点遍历所有瓦片基于基类TileSetSource的接口先按get_tiles_count()/get_tile_id()遍历坐标 ID再对每个坐标用get_alternative_tiles_count()/get_alternative_tile_id()遍历替代 ID。对于图集源替代列表至少包含主瓦片ID 0。占用检测has_room_for_tile(atlas_coords, size, animation_columns, animation_separation, frames_count, ignored_tile)用于创建/修改前校验ignored_tile Vector2i(-1, -1)表示忽略某个瓦片修改自身时用避免误判自身占用。区域查询get_tile_at_coords(atlas_coords)返回覆盖该坐标的瓦片左上角坐标即其坐标 ID无瓦片时返回Vector2i(-1, -1)get_tile_size_in_atlas(atlas_coords)返回瓦片在网格坐标系的尺寸get_tile_texture_region(atlas_coords, frame)返回瓦片在原图集贴图中的纹理区域动画瓦片可按frame取各帧。与其他导入器的区别TileSetAtlasSource与 ResourceImporterTextureAtlas 无关——后者是把 PNG 导入为AtlasTexture/ArrayMesh的常规纹理图集导入器不负责处理 TileSetAtlasSource瓦片图集必须通过TileSet编辑器创建。九、小结TileSetAtlasSource是 Godot 4 瓦片系统中承载贴图 → 瓦片转换的核心资源margins/separation/texture_region_size定义网格布局create_tile()暴露瓦片create_alternative_tile()派生变体动画方法组支撑多帧瓦片TRANSFORM_*常量支撑运行时旋转翻转get_tile_data()打通与物理/导航/自定义数据层的对接。它与TileSetSource、TileSet、TileData、TileMapLayer共同构成完整的 2D 瓦片地图解决方案官方文档与教程Using TileSets、Using Tilemaps为其提供了完整的工作流支撑。本文覆盖的属性表、方法签名与代码示例均可在 class_tilesetatlassource.rst 中逐一核对读者可据此在编辑器或脚本层面构建高性能的图集瓦片库。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐folium 瓦片图层完全指南内置瓦片集、自定义 URL 模板与 TileLayer 底层机制folium 瓦片图层完全指南内置瓦片集、自定义 URL 模板与 TileLayer 底层机制 导读 本文是 folium 栅格图层raster layer数据可视化数据分析GISTiled瓦片集切片工具从 sprite sheet 到地图瓦片Tiled瓦片集切片工具从 sprite sheet 到地图瓦片 在游戏开发中你是否曾为如何将一张包含多个角色或场景元素的精灵图Sprite Sheet游戏开发桌面应用开发工具Folium 自定义瓦片Custom Tiles指南无底图、图片瓦片与本地图案底图Folium 自定义瓦片Custom Tiles指南无底图、图片瓦片与本地图案底图 本文围绕 docs/advanced_guide/custom_til数据可视化数据分析GIS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考