关于注解的说明
rmmz 的帮助注释中定义了多种多样的注解。
本章将按项目分别讲解注解的设置内容。
整个插件
与整个插件相关的注解，在制作插件时有很多是必须设置的，请务必记住它们的用法。
| 注解 | 说明 |
|---|---|
@target | 固定填写 MZ。用于与为 RPG Maker MV 制作的插件进行区分，是必需的。 |
@plugindesc | 插件的标题。此处描述的内容会显示在管理画面的一览中。 |
@author | 插件的作者。会显示在管理画面中。 |
@help | 详细说明插件用法的文章。会显示在管理画面中。 |
@url | 插件的发布 URL。会作为链接显示在管理画面中，请指定可访问发布页的 URL。 |
插件参数
插件参数是插件使用者可以自由设定值的功能。
以下是设置示例。
/*~struct~类型名:
*
* @param 参数名
* @text 参数显示名
* @desc 参数的说明
* @default
* @type number
*/
| 注解 | 说明 |
|---|---|
@param | 参数的名称。在插件实现部分获取参数内容时，会用作属性名。定义参数内容的注解中最上方需要写这个。 |
@text | 参数的显示名称。会显示在参数输入画面中。 |
@desc | 参数的详细说明。会显示在参数输入画面中。 |
@default | 插件开启时自动设定的值。注意：这不是参数留空时自动设定的值。 |
@type | 参数的类型信息。根据此处指定的值，输入对话框的 UI 会变化。例如指定 number 就会变成只能输入数值的参数。 |
@parent | 可以指定父级参数。通过设定父子关系，可以将参数做成树形结构。 |
需要最详细说明的可能是 @type。
因为根据 @type 指定的类型，对话框的内容会变化，所以指定合适的类型可以大大提升插件的易用性。
@type 的种类如下。
| 类型 | 说明 | 被设定的值 |
|---|---|---|
string | 通常的字符串输入项，没有特别限制。 | 输入的值 |
multiline_string | 可以输入多行的字符串输入项。 | 输入的值 |
file | 选择图像或音频等的文件对话框。在此选择的文件不会被“未使用素材删除”功能删除。 | 所选文件名（不含扩展名） |
number | 只能输入数值的项目。 | 输入的值 |
boolean | ON/OFF 的单选按钮。 | true / false |
select | 下拉列表。 | 所选项目的 @value 或 @option |
combo | 组合框。 | 所选项目的 @option |
actor | 选择数据库角色的对话框。 | 所选对象的 ID |
class | 选择数据库职业的对话框。 | 所选对象的 ID |
skill | 选择数据库技能的对话框。 | 所选对象的 ID |
item | 选择数据库物品的对话框。 | 所选对象的 ID |
weapon | 选择数据库武器的对话框。 | 所选对象的 ID |
armor | 选择数据库防具的对话框。 | 所选对象的 ID |
enemy | 选择数据库敌人角色的对话框。 | 所选对象的 ID |
troop | 选择数据库敌群的对话框。 | 所选对象的 ID |
state | 选择数据库状态的对话框。 | 所选对象的 ID |
animation | 选择数据库动画的对话框。 | 所选对象的 ID |
tileset | 选择数据库图块组的对话框。 | 所选对象的 ID |
common_event | 选择数据库公共事件的对话框。 | 所选对象的 ID |
map | 选择地图的对话框。 | 所选对象的 ID |
location | 选择地图并指定坐标的对话框。 | {"mapId":"所选地图的ID", "x":"指定的X坐标", "y":"指定的Y坐标"} |
switch | 选择开关的对话框。 | 所选对象的 ID |
variable | 选择变量的对话框。 | 所选对象的 ID |
string[] | 可以输入多个字符串的对话框。即使不是字符串，在后面加上 [] 也会被当作数组处理。 | ["输入值", "输入值"] |
struct<类型名> | 可以汇总输入多个项目的对话框。 | {aaa:"输入值", bbb:"输入值"} |
struct 是将多个参数汇总在一起定义的参数。
类型名请指定不包含符号的任意字符串。
类型的定义像下面的示例一样，在单独的区块中定义。
/*~struct~类型名:
*
* @param 参数名
* @text 参数显示名
* @desc 参数的说明
* @default
* ......
*/
也可以将 struct 进一步设为数组。
具体的实现方法可以参考几个官方插件。
根据指定的 type 不同，有时还需要额外的注解。
| 注解 | 目标 type | 说明 |
|---|---|---|
@max | number | 可输入数值的最大值。 |
@min | number | 可输入数值的最小值。 |
@decimals | number | 小数点后的位数。 |
@dir | file | 指定文件对话框时的目标目录。 |
@on | boolean | 选择 ON 时显示在对话框中的值。 |
@off | boolean | 选择 OFF 时显示在对话框中的值。 |
@option | select / combo | 作为下拉列表的显示项目，显示在对话框中的值。 |
@value | select | 选择下拉列表时实际设定到参数中的值。省略时，@option 的值会被设定到参数中。 |
插件命令
在 rmmz 中，插件命令的规格被更新，命令和参数的定义也可以通过注解来完成。
如果预先定义了命令名称和参数的信息，使用者只需从事件命令中指定即可调用命令。
* @command 命令名
* @text 命令显示名
* @desc 命令说明
*
* @arg 参数名1
* @text 参数显示名
* @desc 参数说明
| 注解 | 说明 |
|---|---|
@command | 插件命令名。在实际调用时用作标识符。定义命令的注解中最上方需要写这个。 |
@arg | 插件命令的参数名。定义参数的注解中最上方需要写这个。 |
对于插件命令及其参数，也可以像参数一样指定相同的注解，来设定显示名、详细说明、默认值和类型名。
插件的依赖关系
在 rmmz 中，新增了用于定义插件之间依赖关系的注解。
通过使用这些新增的注解，可以明确指定基础插件等。
| 注解 | 说明 |
|---|---|
@base | 指定基础插件的名称。如果不放入基础插件而只放入目标插件，会显示警告。 |
@orderAfter | 使用时需要放在上方的插件名称。用于应对冲突等。 |
@orderBefore | 使用时需要放在下方的插件名称。用于应对冲突等。 |
对未使用素材删除功能的支持
如果在插件中直接加载图像，执行部署时勾选了“排除未使用文件”，可能会将需要的图像排除掉。
例如下面的例子：
img/pictures文件夹中的image_1.pngimg/system文件夹中的image_2.pngimg/example文件夹中的image_3.png※
分别是引用以上文件的代码。
let b1 = ImageManager.loadPicture("image_1");
let b2 = ImageManager.loadSystem("image_2");
let b3 = ImageManager.loadBitmap("img/example/", "image_3");
※ 这是通过插件指定了默认不存在的 example 文件夹的例子
但这样下去，图像会被删除。
如果使用的图像文件是固定的，请在 @requiredAssets 后面接着描述所需的文件。
* @requiredAssets img/pictures/image_1
* @requiredAssets img/system/image_2
* @requiredAssets img/example/image_3
| 注解 | 说明 |
|---|---|
@requiredAssets | 指定部署时禁止删除的素材文件路径。 |
如果希望通过插件参数让游戏作者指定的图像不被删除，只要有之前说明过的 @type file 和 @dir 注解即可。
另外，前作 MV 中的注解 @require 已被废除。
将备注中指定的文件排除在“排除未使用文件”之外的注解如下。
* @noteParam sampleImage
* @noteDir img/sample/
* @noteType file
* @noteData items
| 注解 | 说明 |
|---|---|
@noteParam | 指定备注的名称。 |
@noteDir | 指定存放图像的文件夹。 |
@noteType | 固定指定为 file。 |
@noteData | 使用了目标备注的数据库。从以下选项中选择： maps events actors classes skills items weapons armors enemies states tilesets |