Merge pull request #3025 from qiuguohua/master_tiled_plus

Add english documentation

versions/3.8/en/asset/tiledmap.md

@@ -1,29 +1,104 @@
-# TiledMap Assets
+# Tiled Map Resources (TiledMap)
+## Problem
+When using a texture atlas, if a 1-pixel stretch is not applied, adjacent images may blend together, leading to incorrect edge colors, such as the appearance of black edges. Therefore, when creating the texture atlas, it is necessary to stretch each image by one pixel to serve as the edge pixel.
 
-The **TiledMap** asset is a data format exported by [Tiled Editor](https://www.mapeditor.org/).
+The previous implementation of the engine handled this automatically and would indent by 1 pixel. The code implementation was as follows:
+```javascript
+if (spFrame) {
+    grid._name = spFrame.name;
+    const lm = spFrame.unbiasUV[0];
+    const bm = spFrame.rotated ? spFrame.unbiasUV[1] : spFrame.unbiasUV[5];
+    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;
+    grid._rect = new Rect(grid.x, grid.y, grid.width, grid.height);
+}
+```
+
+But there's another problem, it makes the UI design of a good map may look indented, as seen in this [issue](https://github.com/cocos/cocos-engine/issues/17257).
+
+To fix this, in version **3.8.5** we are removing the code that automatically indents by 1 pixel, and will need to require the user to make a texture altas that needs to be set to extend by 1 pixel.
+
+## Creating a Texture Atlas for Tiled Maps
+
+Generally, you'll need to create a texture atlas. You can use the [TexturePacker](https://www.codeandweb.com/texturepacker) tool for this.
+
+- Add the materials to the tool, as shown in the image below:  
+  ![alt text](tiledmap/image.png)
+
+- Arrange the exported atlas layout and set the parameters.  
+  ![alt text](tiledmap/image-14.png)  
+
+  **Note: You need to stretch by 1 pixel here. If you don't stretch by one pixel, the edges of adjacent textures may appear abnormal when used.**
+
+- Export the sprite sheet and then set the save path.  
+  ![alt text](tiledmap/image-2.png)
+![alt text](image.png)
+## Creating and Editing Maps Using Tiled
+
+Tiled map resources are exported in a data format by the [Tiled Editor](https://www.mapeditor.org/).
 
 | Creator Version | Tiled Version |
-| :---------- | :-------- |
-| v3.0 and above | v1.4   |
-| v2.2 and above | v1.2.0 |
-| v2.1 and below | v1.0.0 |
+| :------------- | :----------- |
+| v3.0 and above | v1.4          |
+| v2.2 and above | v1.2.0        |
+| v2.1 and below | v1.0.0        |
+
+- Create map tiles.  
+  ![alt text](tiledmap/image-3.png)
+
+- Set the tile size.  
+  ![alt text](tiledmap/image-4.png)  
+  ![alt text](tiledmap/image-5.png)
+
+- Create a new tileset.  
+  ![alt text](tiledmap/image-6.png)
 
-## Importing Map Assets
+- Select the texture atlas created using TexturePacker.  
+  ![alt text](tiledmap/image-8.png)
 
-The assets required for using a map are:
+  **Set the size to match the original image, i.e., 32x32 pixels. Also, set the margin to 1 (offset the image by 1 pixel on all sides) and set the spacing to 2 (1 pixel on each side, making it 2 pixels total).If you haven't set stretching in TexturePacker, you need to set the margin to 0 and the spacing to 0 here**
+
+- Complete the map, as shown below:  
+  ![alt text](tiledmap/image-12.png)
+
+- Save the `.tmx` file.
+
+## Importing Map Resources
+
+The resources required for the map include:
 
 - `.tmx` map data
-- `.png` atlas textures
-- `.tsx` tileset data configuration file (required for some tmx files)
+- `.png` texture atlas
+- `.tsx` tileset configuration file (required by some `.tmx` files)
 
-    ![tiledmap](tiledmap/import.png)
+  ![tiledmap](tiledmap/import.png)
 
-## Create TiledMap Assets
+## Creating Tiled Map Resources
 
-Drag the map asset from the **Assets** panel into the `Tmx file` property of the created **TiledMap** component.
+Drag the map resources from the **Assets** panel to the Tmx File property of the created TiledMap component:
 
 ![tiledmap](tiledmap/set_asset.png)
 
-## Storage in the Project
+## Organizing in the Project
+
+To improve resource management efficiency, it is recommended to store the imported `.tmx`, `.tsx`, and `.png` files in a separate directory, rather than mixing them with other resources. Make sure to keep the `.tmx` and `.tsx` files in the same directory; otherwise, the resources might not load correctly.
+
+### Notes
+
+1. If the texture is not stretched in the TexturePacker, the result may be an error.
+
+   Without stretching, the effect is as shown below:  
+   ![alt text](tiledmap/image-15.png)
+
+   With stretching, the effect is as shown below:  
+   ![alt text](tiledmap/image-16.png)
+
+2. If you have existing atlases and maps, you can update the atlas without having to recreate it.
+
+   (1) Add a new atlas with new configurations, making sure not to embed it in the map.  
+   ![alt text](tiledmap/image-1.png)
 
-For efficient asset management, it is recommended to store the imported `.tmx`, `.tsx` and `.png` files in a separate directory and not mixed with other assets. Note that it is important to manage the `tmx` file and the `tsx` file in the same directory, otherwise the assets may not be loaded correctly.
+   (2) In the old atlas tab, select and click Replace Tileset, then choose the new atlas created in step (1) to complete the update.  
+   ![alt text](tiledmap/image-7.png)

versions/3.8/zh/asset/tiledmap.md

@@ -1,12 +1,34 @@
 # 瓦片图资源（TiledMap）
-## 制作瓦片贴图需要的素材
+
+## 问题分析
+由于使用图集时，如果没有设置1像素的拉伸，会与相邻的图片发生混合，导致边缘颜色不对，例如出现黑边的问题。
+因此在制作图集时，需要针对每个图片拉伸一像素作为边缘像素。
+
+引擎之前的实现是自动处理这种问题，会缩进1像素，代码：
+```
+if (spFrame) {
+    grid._name = spFrame.name;
+    const lm = spFrame.unbiasUV[0];
+    const bm = spFrame.rotated ? spFrame.unbiasUV[1] : spFrame.unbiasUV[5];
+    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;
+    grid._rect = new Rect(grid.x, grid.y, grid.width, grid.height);
+} 
+```
+但是这样会产生额外的问题，会让UI设计的好地图可能看起来有明显的缩进，类似[issue](https://github.com/cocos/cocos-engine/issues/17257)
+
+为了解决这个问题，在**3.8.5**版本里，我们将移除自动缩进1像素的代码，并且需要需要用户制作图集时，需要设置延伸1像素。
+
+## 制作瓦片贴图的图集
 一般需要制作成图集，可以使用[TexturePacker](https://www.codeandweb.com/texturepacker)工具。
 - 把素材添加到工具中，如下图：
 ![alt text](tiledmap/image.png)
 - 整理导出的图集布局，并设置
 ![alt text](tiledmap/image-14.png)
 **这里需要拉伸1像素，因为相邻的两个纹理如果不拉伸一个像素，使用的时候会出现边缘异常**
-- 发布精灵设置保存路径即可
+- 发布精灵，然后设置保存路径即可
 ![alt text](tiledmap/image-2.png)
 
 ## 使用tiled创建与编辑地图
@@ -35,10 +57,7 @@
 ![alt text](tiledmap/image-8.png)
 
 
-**这里需要设置为要使用原图片的大小，即32X32，并且设置margin为1(图片偏移上下左右1像素)，间距设置为2(左右1像素，就是两个像素，上下也一样)**
-
-- 编辑图集
-![alt text](tiledmap/image-9.png)
+**这里需要设置为要使用原图片的大小，即32X32，并且设置margin为1(图片偏移上下左右1像素)，间距设置为2(左右1像素，就是两个像素，上下也一样)。如果在texturepacker里没设置拉伸，这里就需要设置margin为0，间距设置为0**
 
 - 完成地图，如下图：
 ![alt text](tiledmap/image-12.png)