文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载TileData 是 Godot 4 中承载单个瓦片全部配置的核心资源类从纹理翻转、色调调制、材质与 Z 排序到碰撞多边形、遮挡多边形、导航多边形、自定义数据与地形terrain衔接规则全部由它管理。本文将基于 TileData 类参考文档结合 TileSet 类文档、TileMapLayer 类文档 与 使用 TileSet 教程逐一剖析其全部属性、方法与信号并给出在运行时用_tile_data_runtime_update()动态改写瓦片的可运行 GDScript 示例。读完本文你将能系统掌握瓦片级配置的每一项能力并能在游戏运行时按需修改任意格子上的瓦片数据。TileData 在 TileSet 体系中的定位在 Godot 4 的瓦片系统中资源分为两层TileSet一个瓦片集合负责定义图集atlas、场景集合、物理/导航/遮挡/自定义数据等层的结构与全局参数TileData集合中每一个瓦片的个体配置即设置单个瓦片的一组设定。按官方类文档的定义TileData继承自Object见 class_tiledata.rst是 TileSet 中单个瓦片的设置集合。它通常在瓦片集编辑器TileSet editor中编辑但也可以在运行时通过 TileMapLayer._tile_data_runtime_update() 进行修改。理解这个层次关系非常关键TileSet 决定瓦片有哪些可选类型与层而 TileData 决定这个瓦片具体长什么样、有哪些碰撞、属于哪个地形、携带什么游戏数据。创建图集后每个由编辑器自动生成的瓦片都会附带一个独立的 TileData 实例。属性总览11 项TileData 共有 11 个属性覆盖渲染表现、地形归属与排序三类需求属性类型默认值作用flip_hboolfalse纹理水平翻转flip_vboolfalse纹理垂直翻转materialMaterial—空该瓦片使用的材质modulateColorColor(1, 1, 1, 1)瓦片颜色调制相乘probabilityfloat1.0随机绘制时该瓦片被选中的相对概率terrainint-1该瓦片使用的地形 IDterrain_setint-1该瓦片使用的地形集 IDtexture_originVector2iVector2i(0, 0)瓦片绘制位置偏移transposeboolfalse交换水平/垂直 UV转置显示y_sort_originint0用于 y-sort 排序的垂直基准点z_indexint0相对于 TileMapLayer 的绘制顺序渲染相关属性翻转、转置与绘制偏移flip_h / flip_v分别控制瓦片纹理的水平与垂直翻转。true时纹理沿对应轴镜像。transpose是三者中最容易混淆的一个它为true时瓦片转置显示即交换水平和垂直方向的纹理 UV效果等价于把瓦片旋转 90 度后垂直翻转。因此组合使用这三个开关可以产生各种旋转效果。在 使用 TileSet 教程 中给出了精确的组合结论顺时针旋转 90°开启Flip H Transpose顺时针旋转 180°开启Flip H Flip V顺时针旋转 270°开启Flip V Transpose。在 Godot 4.2 及以后TileMap 编辑器工具栏已提供直接的旋转/翻转按钮无需再为放置阶段创建替代瓦片。texture_origin默认Vector2i(0, 0)以像素为单位偏移瓦片实际绘制的锚点位置可用于让瓦片相对格点浮起或视觉错位。材质与颜色调制material指定该瓦片使用的 Material可以是CanvasItemMaterial使用默认着色器用于调整混合模式等ShaderMaterial为该瓦片定制自定义着色器。这让单个瓦片可以拥有与其他瓦片完全不同的渲染方式适合水面、熔岩、动态装饰等特殊效果。modulate则是一个Color乘数默认白色Color(1, 1, 1, 1)直接与纹理颜色相乘是制作暗色地面、夜晚色调、冻结或高亮瓦片的轻量手段。排序相关属性z_index 与 y_sort_originz_index是瓦片相对所在 TileMapLayer 节点的绘制顺序索引数值越大越靠前渲染用于在同一层内制造前后遮挡关系。y_sort_origin是瓦片用于 y 轴排序的垂直基准点像素。在俯视角top-down游戏中把它调整到瓦片底部可让角色走到瓦片后面时被正确遮挡只有 TileMapLayer 节点在CanvasItem Ordering下开启Y Sort Enabled时它才生效此约束同样记录在 使用 TileSet 教程 的替代瓦片属性一节。probability随机绘制权重probability默认1.0表示当使用随机绘制模式在 TileMap 编辑器中绘制随机瓦片图案时该瓦片被选中的相对概率。数值越大越常被选中通过为同一格位的多个瓦片变体设置不同概率可以营造出自然的草丛、碎石分布效果。地形属性terrain_set 与 terrain地形系统是 Godot 3.x 自动瓦片autotile 的进化形态。与旧版不同地形只是附加在图集瓦片上的若干属性由瓦片级专用绘制模式聪明地挑选合适的瓦片因此任何地形瓦片既可以当地形绘制也可以像普通瓦片一样单独放置。terrain_set是该瓦片所属的地形集 IDterrain是该瓦片在地形集内使用的地形 ID。两者的默认值都是-1含义分别是未分配地形集与未分配地形。在编辑器 Select 模式下展开瓦片属性的Terrains栏即可设置必须先设置Terrain Set ≥ 0才能设置Terrain ≥ 0两者 ID 从0而非1开始计数且相互独立。地形集自身有一个匹配模式 TerrainMode决定了地形之间如何衔接TERRAIN_MODE_MATCH_CORNERS_AND_SIDES0要求四角与四边都与相邻瓦片的地形匹配TERRAIN_MODE_MATCH_CORNERS1只要求四角匹配TERRAIN_MODE_MATCH_SIDES2只要求四边匹配。这三个模式分别对应旧版自动瓦片的 2×2、3×3 与 3×3 minimal 位掩码模式也类似 Tiled 编辑器的功能。Terrain Peering Bits地形衔接的核心机制真正决定哪个瓦片在哪种邻居环境下出现的是地形窥视位Terrain Peering Bits由以下两个方法读写set_terrain_peering_bit(peering_bit, terrain)为给定方向设置该瓦片的地形窥视位get_terrain_peering_bit(peering_bit)读取指定方向的地形窥视位值。peering_bit使用 TileSet.CellNeighbor 枚举它按顺时针顺序定义了以当前格子为中心的 16 个邻接方位从CELL_NEIGHBOR_RIGHT_SIDE 0、CELL_NEIGHBOR_RIGHT_CORNER 1开始依次覆盖右侧、右下、下方、左下、左侧、左上、上方、右上共 8 个方向每个方向都有SIDE边与CORNER角两个位。在调用这两个方法前应先用 is_valid_terrain_peering_bit() 确认该方向对本瓦片有效。窥视位取值规则-1代表该方向是空位而0及以上的整数表示该方向必须与指定地形 ID 匹配。例如一个瓦片所有窥视位都设为0或更大则它只在 8 个邻居全部使用同地形 ID 的瓦片时才会出现用于地形内部填充若上方三个位左上角、上边、右上角都设为-1则它只在上方含斜上方为空时出现——这正是平台边缘、地面顶端的典型配置。下图展示了在 TileSet 编辑器 Select 模式下为单个瓦片配置地形窥视位的情形编辑器中间栏的Terrain Peering Bits区域会随瓦片选择动态显示全部 8 个方向的位值一个完整的地形瓦片表包含角块、边块、内部块即可通过组合窥视位自动衔接大幅减少手工摆放平台边缘的工作量对程序化生成的关卡同样有效。信号changedTileData 只定义一个信号changed()—— 当该瓦片的任一属性被修改时发出。由于 TileData 属于 Resource 体系编辑器中修改瓦片属性会自动触发它在运行时通过 setter 修改属性同样会发出该信号可用于同步自定义逻辑如瓦片状态变化后的表现刷新。方法全解瓦片级碰撞、遮挡、导航与自定义数据TileData 的方法全部围绕按层索引读写多边形/数据展开。Godot 4 的 TileSet 允许一个瓦片拥有多个物理层、多个遮挡层、多个导航层因此绝大多数方法都要求传入layer_id层索引而多边形多边形索引polygon_index从0开始计数一个瓦片在每个层上可以持有多个多边形。1. 碰撞多边形Physics物理层用于为瓦片生成静态碰撞体玩家和物体落到上面时会被阻挡。相关方法成对出现先计数/添加再读写单个多边形add_collision_polygon(layer_id)在指定物理层上添加一个碰撞多边形随后可用 set 系列方法填充顶点get_collision_polygons_count(layer_id) / set_collision_polygons_count(layer_id, polygons_count)查询/设定该物理层上的多边形数量get_collision_polygon_points(layer_id, polygon_index) / set_collision_polygon_points(layer_id, polygon_index, polygon)以PackedVector2Array读写多边形顶点remove_collision_polygon(layer_id, polygon_index)删除指定多边形单向平台支持is_collision_polygon_one_way() / set_collision_polygon_one_way(layer_id, polygon_index, one_way)以及 get_collision_polygon_one_way_margin() / set_collision_polygon_one_way_margin(layer_id, polygon_index, one_way_margin)。开启单向碰撞后角色可从下方穿过、从上方站立one_way_margin控制单向判定生效的边缘距离。物理层的碰撞行为还受 TileSet 全局参数影响每个物理层在 TileSet 上定义了碰撞层与掩码见 TileSet.get_physics_layer_collision_layer() 与 get_physics_layer_collision_mask()瓦片生成的碰撞体按这些层/掩码参与物理世界交互。在编辑器中创建物理层后进入 TileSet 面板的Physics Layer区域即可用 2D 多边形编辑工具绘制碰撞形状快捷键 :kbd:F快速生成矩形对于大量同类碰撞瓦片教程推荐使用 多选批量赋值 或属性绘制模式一次铺开。2. 恒定速度传送带等动态地形两个速度方法特别适合制作传送带、风道等动态地形——注意它们不会移动或旋转瓦片本身而是把速度施加给与瓦片碰撞的物体set_constant_linear_velocity(layer_id, velocity)设置恒定线速度Vector2官方文档明确点出其典型用途就是传送带conveyor belts读取用 get_constant_linear_velocity()set_constant_angular_velocity(layer_id, velocity)设置恒定角速度float弧度/秒读取用 get_constant_angular_velocity()。两者均按物理层layer_id独立配置同一瓦片在不同层上可有不同的速度行为。3. 遮挡多边形Light Occluder遮挡层用于 2D 光照系统为瓦片定义遮挡多边形后DirectionalLight2D、PointLight2D 等光源的光线会被瓦片挡住形成阴影GPUParticles2D 粒子也可以与遮挡体碰撞。相关方法add_occluder_polygon(layer_id) 与 get_occluder_polygons_count(layer_id) / set_occluder_polygons_count(layer_id, polygons_count)管理遮挡层上的多边形数量set_occluder_polygon(layer_id, polygon_index, polygon) / get_occluder_polygon(layer_id, polygon_index, flip_h, flip_v, transpose)读写指定索引的遮挡多边形remove_occluder_polygon(layer_id, polygon_index)删除多边形。注意两个已弃用方法set_occluder()/get_occluder()被标记为Deprecated官方建议改用上述*_occluder_polygon()系列见 class_tiledata.rst。在编辑器里瓦片的遮挡多边形位于图集检视器的Rendering子栏目下展开后才能编辑。翻转参数flip_h / flip_v / transpose多个 getter如get_occluder_polygon、get_navigation_polygon都接受这三个布尔参数允许在不改变瓦片原始多边形数据的前提下返回经过翻转/转置变换后的多边形——非常适合在运行时复用同一份几何数据生成镜像瓦片。4. 导航多边形Navigation为瓦片配置导航多边形后TileMap 可以生成导航网格供 NavigationAgent2D 等角色寻路。相关方法set_navigation_polygon(layer_id, navigation_polygon)为指定导航层设置 NavigationPolygonget_navigation_polygon(layer_id, flip_h, flip_v, transpose)返回指定导航层的导航多边形同样支持三个变换参数。在 使用 TileSet 教程 中创建导航层与绘制碰撞多边形的流程一致同为 2D 多边形编辑只是多边形将用于导航网格生成而非物理碰撞。5. 自定义数据层Custom Data自定义数据层用于在每个瓦片上存储游戏专属数据例如该瓦片每秒造成的伤害、是否可被武器破坏、属于哪片区域等。它与 TileSet 中的自定义数据层定义配合使用set_custom_data(layer_name, value) / get_custom_data(layer_name)按层名读写值类型为Variant任意类型均可set_custom_data_by_layer_id(layer_id, value) / get_custom_data_by_layer_id(layer_id)按层索引读写has_custom_data(layer_name)先判断名为layer_name的层是否存在再读取避免运行时访问不存在的层。在 TileSet 检视器中创建自定义数据层后即可在 Select 模式下为每个瓦片填写数值。下图是教程中配置的两个自定义数据层示例damage_per_second与destructible它们会被存储进每个瓦片各自的 TileData 中自定义数据还有两点实用特性数据与瓦片绑定数据存于 TileSet 中的瓦片定义上所有已放置的该瓦片实例共享同一份数据若需要同图不同数据的变体应创建替代瓦片Alternative Tile并只修改替代瓦片的数据重排安全自定义数据层在 TileSet 中可任意重排编辑器会自动更新既有元数据不会破坏旧数据对应关系。此外TileSet 编辑器的属性绘制模式也支持自定义数据批量赋值方便为大片瓦片区域快速填充数值。运行时修改 TileData_tile_data_runtime_update 实战TileData 通常在编辑器中配置但官方文档明确支持运行时改写。核心入口是 TileMapLayer 的两个虚方法_use_tile_data_runtime_update(coords)返回true表示坐标为coords的格子需要运行时更新。务必只对确有需要的格子返回true否则每个格子都会在运行时被处理造成显著性能损失_tile_data_runtime_update(coords, tile_data)当_use_tile_data_runtime_update对某格子返回true时被调用传入即将被 TileMapLayer 内部使用的 TileData 对象允许就地修改。官方文档的两条重要警告子资源共享传入的tile_data的子资源与 TileSet 中是同一份。直接修改它们可能影响整个 TileSet——例如对get_navigation_polygon()返回的多边形做修改会波及所有使用该瓦片的格子。需要独立副本时务必先duplicate()这些子资源动态更新通知如果 TileData 的属性会随时间变化需要调用 notify_runtime_tile_data_update() 通知 TileMapLayer 重新更新但该调用会触发整层重算开销较大应尽量限制调用频率。可运行示例给特定格子设置自定义数据与翻转下面是一个完整的 GDScript 示例展示如何在运行时为进门后的格子写入自定义数据、翻转瓦片并读取已存数据extends TileMapLayer # 只有被标记的格子才需要运行时更新 func _use_tile_data_runtime_update(coords: Vector2i) - bool: return coords Vector2i(3, 2) or coords Vector2i(4, 2) func _tile_data_runtime_update(coords: Vector2i, tile_data: TileData) - void: # 1) 翻转与色调不会影响 TileSet 中的原瓦片定义 tile_data.flip_h true tile_data.modulate Color(0.6, 0.9, 1.0) # 淡蓝 # 2) 自定义数据前提是 TileSet 中已定义名为 destructible 的层 if tile_data.has_custom_data(destructible): tile_data.set_custom_data(destructible, false) # 按索引读写同样可行 # tile_data.set_custom_data_by_layer_id(0, false) print(destructible , tile_data.get_custom_data(destructible)) # 3) 恒定线速度做成传送带效果需该瓦片已配置物理层 # tile_data.set_constant_linear_velocity(0, Vector2(120, 0)) # 4) 为瓦片动态追加一个三角形碰撞多边形物理层 0 # var idx : tile_data.get_collision_polygons_count(0) # tile_data.add_collision_polygon(0) # tile_data.set_collision_polygon_points(0, idx, PackedVector2Array([ # Vector2(0, 0), Vector2(32, 0), Vector2(0, 32) # ])) # 当上面的修改结果会随时间变化时主动请求一次整层更新 func _on_something_changed() - void: notify_runtime_tile_data_update()要点回顾判断层存在性读写自定义数据前先用has_custom_data(layer_name)检查修改多边形add_collision_polygon(layer_id)会新增一个空多边形并返回其索引位置随后用set_collision_polygon_points()填充顶点坐标为相对瓦片左上角的局部坐标勿直接改共享子资源对导航/遮挡多边形的运行时变换优先使用 getter 自带的flip_h/flip_v/transpose参数返回临时副本而不是原地修改 TileSet 中的共享数据。替代瓦片与 TileData 的关系要创建同一图集图片的不同配置变体如旋转、翻转、不同色调、不同自定义数据官方推荐使用替代瓦片Alternative Tile。替代瓦片在 TileSet 编辑器中位于图集基础瓦片右侧创建后可以像基础瓦片一样修改 TileData 的任意属性但有一个关键区别创建替代瓦片时基础瓦片的任何属性都不会被继承——若希望两者表现一致需要在替代瓦片上重新设置此约束记录于 使用 TileSet 教程 的替代瓦片一节。这意味着每个替代瓦片拥有自己独立、完整的 TileData 实例非常适合同一图片、多种行为的场景例如同一个箱子贴图替代瓦片 A 带碰撞、替代瓦片 B 是可破坏的装饰。小结TileData 的能力全景能力域关键属性 / 方法典型用途渲染表现flip_h、flip_v、transpose、modulate、material、texture_origin镜像、旋转、变色、自定义着色器、绘制偏移排序z_index、y_sort_origin前后遮挡、俯视角高度排序随机绘制probability自然分布的草丛、碎石地形衔接terrain、terrain_set、get/set_terrain_peering_bit、is_valid_terrain_peering_bit自动衔接平台边缘、程序化关卡物理碰撞多边形系列 单向平台 恒定速度系列静态碰撞、单向跳台、传送带光照遮挡多边形系列2D 阴影、粒子碰撞寻路导航多边形系列生成导航网格供角色寻路游戏数据自定义数据系列 has_custom_data伤害值、可破坏性等瓦片级元数据变更通知changed信号属性修改后的逻辑同步运行时改写TileMapLayer 的_use/_tile_data_runtime_updatenotify_runtime_tile_data_update动态地形、状态切换、传送带理解 TileData 就等于理解了 Godot 4 瓦片系统的最后一公里TileSet 负责搭建层与结构TileData 负责在每个瓦片上落地碰撞、光照、导航、地形与游戏数据。需要进一步了解其所在的完整体系可继续阅读 TileSet 类参考、TileMapLayer 类参考以及 使用 TileSet 教程 与 使用 TileMap 教程。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot GridMap 完整指南3D 瓦片地图的 MeshLibrary、碰撞、导航与运行时脚本控制Godot GridMap 完整指南3D 瓦片地图的 MeshLibrary、碰撞、导航与运行时脚本控制 GridMap 是 Godot 中构建 3D 关卡的文档教程游戏开发Godot 3D CPU 粒子系统完全指南CPUParticles3D 属性、发射形状与运行时控制全解析Godot 3D CPU 粒子系统完全指南CPUParticles3D 属性、发射形状与运行时控制全解析 导读 本文以 Godot Engine 官方文档仓文档教程游戏开发Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优 本文围绕 Godot 官方文档仓库中的 Collisi文档教程游戏开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考