diff --git a/cocos/tiledmap/tiled-map.ts b/cocos/tiledmap/tiled-map.ts index 80b8445aa4c..766669edcd9 100644 --- a/cocos/tiledmap/tiled-map.ts +++ b/cocos/tiledmap/tiled-map.ts @@ -33,7 +33,7 @@ import { TiledLayer } from './tiled-layer'; import { TiledObjectGroup } from './tiled-object-group'; import { TiledMapAsset } from './tiled-map-asset'; import { Sprite } from '../2d/components/sprite'; -import { fillTextureGrids } from './tiled-utils'; +import { fillTextureGrids, enableTexelOffsetUtils } from './tiled-utils'; import { Size, Vec2, logID, Color, sys, warnID } from '../core'; import { SpriteFrame } from '../2d/assets'; import { NodeEventType } from '../scene-graph/node-event'; @@ -303,6 +303,22 @@ export class TiledMap extends Component { return this._tileProperties.get(gid); } + /** + * @en Enables or disables texel offset correction to fix rendering issues like grid edge artifacts. + * This function adjusts the texture coordinates of each grid in the tilemap by applying + * a 0.5-pixel offset, ensuring that grid edges do not show black lines or artifacts caused by + * texture sampling inaccuracies. This is especially useful for tile-based rendering systems. + * @zh 启用或禁用像素偏移修正,用于修复网格边缘的渲染问题(如黑线)。此函数通过对每个 tilemap 网格的纹理坐标应用 0.5 像素 + * 的偏移来调整,确保网格边缘不会出现因纹理采样不准确导致的黑线或其他伪影问题。对基于图块的渲染系统特别有用。 + * + * @param enable + * @en Whether to enable (true) or disable (false) the texel offset correction. + * @zh 是否启用 (true) 或禁用 (false) 像素偏移修正。 + */ + enableTexelOffset (enable: boolean): void { + enableTexelOffsetUtils(enable); + } + __preload (): void { if (!this._tmxFile) { return; diff --git a/cocos/tiledmap/tiled-utils.ts b/cocos/tiledmap/tiled-utils.ts index 8dc0cbbae6d..852137ec3ac 100644 --- a/cocos/tiledmap/tiled-utils.ts +++ b/cocos/tiledmap/tiled-utils.ts @@ -27,6 +27,12 @@ import { Texture2D } from '../asset/assets'; import { Rect } from '../core'; import { GID, TiledGrid, TiledTextureGrids, TMXTilesetInfo } from './tiled-types'; +let _enableTexelOffset = false; + +export function enableTexelOffsetUtils (enable: boolean): void { + _enableTexelOffset = enable; +} + export function fillTextureGrids (tileset: TMXTilesetInfo, texGrids: TiledTextureGrids, spFrame?: SpriteFrame): void { const spf: SpriteFrame = spFrame || tileset.sourceImage!; const tex: Texture2D = spf.texture as Texture2D; @@ -100,10 +106,19 @@ export function fillTextureGrids (tileset: TMXTilesetInfo, texGrids: TiledTextur grid._name = spFrame.name; const lm = spFrame.unbiasUV[0]; const bm = spFrame.rotated ? spFrame.unbiasUV[1] : spFrame.unbiasUV[5]; - grid.l = lm + (grid.x) / texWidth; - grid.t = bm + (grid.y) / texHeight; - grid.r = lm + (grid.x + grid.width) / texWidth; - grid.b = bm + (grid.y + grid.height) / texHeight; + + if (_enableTexelOffset) { + grid.l = lm + (grid.x + 0.5) / texWidth; + grid.t = bm + (grid.y + 0.5) / texHeight; + grid.r = lm + (grid.x + grid.width - 0.5) / texWidth; + grid.b = bm + (grid.y + grid.height - 0.5) / texHeight; + } else { + grid.l = lm + (grid.x) / texWidth; + grid.t = bm + (grid.y) / texHeight; + grid.r = lm + (grid.x + grid.width) / texWidth; + grid.b = bm + (grid.y + grid.height) / texHeight; + } + grid._rect = new Rect(grid.x, grid.y, grid.width, grid.height); } else { grid.l = grid.x / texWidth;