Bgmap & Fgmap events

docs/event.md

@@ -459,38 +459,6 @@ revisit常常使用在一些商人之类的地方，当用户购买物品后不
 ]
 ```
 
-### hideFloorImg：隐藏贴图
-
-使用`{"type":"hideFloorImg"}`可以隐藏某个楼层的贴图。
-
-有关贴图说明请参见[使用自己的图片作为某层楼的背景/前景素材](personalization#使用自己的图片作为某层楼的背景前景素材)。
-
-``` js
-"x,y": [ // 实际执行的事件列表
-  {"type": "hideFloorImg", "loc": [3,6], "floorId": "MT1"}, // 隐藏[3,6]的贴图
-  {"type": "hideFloorImg", "loc": [3,6]}, // 如果是当前层，则可以省略floorId项
-  {"type": "hideFloorImg", "loc": [[3,6],[2,9],[1,2]]} // 我们也可以同时隐藏多个贴图。
-]
-```
-
-loc为要隐藏的贴图的左上角坐标，可以简单的写[x,y]代表一个点，也可以写个二维数组[[x1,y1],[x2,y2],...]来同时显示多个点。
-
-如果同时存在若干个贴图都是是该坐标为左上角，则这些贴图全部会被隐藏。
-
-floorId为目标点的楼层，如果是当前楼层可以忽略不写。
-
-### showFloorImg：显示贴图
-
-使用`{"type":"showFloorImg"}`可以显示某个楼层的贴图。
-
-其做法和参数，和隐藏贴图是完全一致的。
-
-``` js
-"x,y": [ // 实际执行的事件列表
-  {"type": "showFloorImg", "loc": [3,6], "floorId": "MT1"}, // 显示[3,6]的贴图
-]
-```
-
 ### setBlock：设置某个图块
 
 我们可以采用 `{"type": "setBlock"}` 来改变某个地图块。
@@ -517,6 +485,90 @@ number为**要更改到的数字**，有关“数字”的定义详见参见[素
 
 图块更改往往与[同一个点的多事件处理](#同一个点的多事件处理)相关。
 
+### hideFloorImg：隐藏楼层贴图
+
+使用`{"type":"hideFloorImg"}`可以隐藏某个楼层的贴图。
+
+有关贴图说明请参见[使用自己的图片作为某层楼的背景/前景素材](personalization#使用自己的图片作为某层楼的背景前景素材)。
+
+``` js
+"x,y": [ // 实际执行的事件列表
+  {"type": "hideFloorImg", "loc": [3,6], "floorId": "MT1"}, // 隐藏[3,6]的贴图
+  {"type": "hideFloorImg", "loc": [3,6]}, // 如果是当前层，则可以省略floorId项
+  {"type": "hideFloorImg", "loc": [[3,6],[2,9],[1,2]]} // 我们也可以同时隐藏多个贴图。
+]
+```
+
+loc为要隐藏的贴图的左上角坐标，可以简单的写[x,y]代表一个点，也可以写个二维数组[[x1,y1],[x2,y2],...]来同时显示多个点。
+
+如果同时存在若干个贴图都是是该坐标为左上角，则这些贴图全部会被隐藏。
+
+floorId为目标点的楼层，如果是当前楼层可以忽略不写。
+
+### showFloorImg：显示楼层贴图
+
+使用`{"type":"showFloorImg"}`可以显示某个楼层的贴图。
+
+其做法和参数，和隐藏贴图是完全一致的。
+
+``` js
+"x,y": [ // 实际执行的事件列表
+  {"type": "showFloorImg", "loc": [3,6], "floorId": "MT1"}, // 显示[3,6]的贴图
+]
+```
+
+### hideBgFgMap：隐藏楼层的某些背景或前景图块
+
+使用`{"type":"hideBgFgMap"}`可以隐藏某个楼层的背景或前景图块。
+
+从V2.4.1开始，允许绘制三层图层（背景层，事件层和前景层）。使用`hideBgFgMap`可以隐藏背景或前景层中的图块。
+
+``` js
+"x,y": [ // 实际执行的事件列表
+  {"type": "hideBgFgMap", "name": "bg", "loc": [3,6], "floorId": "MT1"}, // 隐藏MT1层[3,6]的背景层图块
+  {"type": "hideBgFgMap", "name": "bg", "loc": [3,6]}, // 如果是当前层，则可以省略floorId项
+  {"type": "hideBgFgMap", "name": "fg", "loc": [[3,6],[2,9],[1,2]]} // 我们也可以同时隐藏多个贴图。
+]
+```
+
+name为必选的，且只能是`bg`和`fg`之一，分别代表背景图层和前景图层。
+
+loc为要隐藏的贴图的左上角坐标，可以简单的写[x,y]代表一个点，也可以写个二维数组[[x1,y1],[x2,y2],...]来同时显示多个点。
+
+floorId为目标点的楼层，如果是当前楼层可以忽略不写。
+
+### showBgFgMap：显示楼层贴图
+
+使用`{"type":"showFloorImg"}`可以显示某个楼层的贴图。
+
+其做法和参数，和隐藏贴图是完全一致的。
+
+``` js
+"x,y": [ // 实际执行的事件列表
+  {"type": "showBgFgMap", "name": "bg", "loc": [3,6], "floorId": "MT1"}, // 显示MT1层[3,6]的前景层图块
+]
+```
+
+### setBgFgBlock：设置某个背景或前景层图块
+
+我们可以采用 `{"type": "setBgFgBlock"}` 来改变某个背景或前景层地图块。
+
+``` js
+"x,y": [ // 实际执行的事件列表
+    {"type": "setBgFgBlock", "name": "bg", "floorId": "MT1", "loc": [3,3], "number": 233}, // 将MT1层背景层的(3,3)点变成数字233
+    {"type": "setBgFgBlock", "name": "bg", "loc": [2,1], "number": 121}, // 省略floorId则默认为本层
+    {"type": "setBgFgBlock", "name": "fg", "number": 57}, // loc也可省略，默认为当前点
+]
+```
+
+name为必选的，且只能是`bg`和`fg`之一，分别代表背景层和前景层。
+
+floorId为可选的，表示要更改的目标楼层。如果忽略此项，则默认为当前楼层。
+
+loc为可选的，表示要更改地图块的坐标。如果忽略此项，则默认为当前事件点。
+
+图块更改后，其隐藏/显示状态不会发生任何改变，即原来是隐藏还是会不显示。可以使用`showBgFgMap`事件将其显示出来。
+
 ### setHeroIcon：更改角色行走图
 
 使用`{"type": "setHeroIcon"}`可以更改角色行走图。

docs/personalization.md

@@ -44,6 +44,16 @@ HTML5魔塔是使用画布（canvas）来绘制，存在若干个图层，它们
 
 如果你需要某个素材已经存在，则可以直接将其覆盖images目录下的同名文件，就能看到效果。
 
+### 背景和前景图层
+
+从V2.4.1开始，样板允许多个图层叠加，最多支持背景层、事件层和前景层三个图层。
+
+在地图编辑器中绘图时，下拉框选中“背景层”或“前景层”即可在对应的图层上绘图。
+
+其中背景层和前景层仅为静态绘图（不支持动画），但可以使用自动元件（autotile）。
+
+可以使用`showBgFgMap`, `hideBgFgMap`, `setBgFgBlock`等事件对背景和前景图层进行操作。
+
 ### 使用自己的图片作为某层楼的背景/前景素材
 
 由于HTML5功能（素材）有限，导致了对很多比较复杂的素材（比如房子内）等无法有着较好的绘图方式。