//=============================================================================
// RPG Maker MZ - SailCat's Extended Message UI
//=============================================================================
/*:zh
* @target MZ
* @plugindesc [SEP] 扩展消息界面
* 统合选项列表和数值输入到消息窗口，并极大增强消息窗口的控制能力。
* @author SailCat
* @help SEPUIMessageEx.js
* v 1.0.0 (2026-07-09) 初版
*
* 本插件依赖 SEPUICore.js 1.0.0 以上版本。
*
* 功能概览：
*
* 1. 可将选项列表和数值输入统合到消息窗口内部，统一界面风格。
* 2. 增补支持30余项转义文本指令，用于宏替换游戏数据文字和控制窗口行为。
* a) 角色/队员/敌人的属性值
* b) 职业/技能/物品/武器/防具/状态/敌人/敌群/图块的名称
* c) 任意地图名称（来自地图信息表）或当前地图名称（来自地图名字段）
* d) 属性/武器类别/防具类别/装备类型/技能类型的名称
* e) 公式计算值
* f) 文本用语（TextManager）中的名称
* g) 指针式引用变量值
* h) 支持多种文字格式：上下标、下划线、删除线、制表位、颜色、对齐等。
* 3. 可拓展选项列表支持的最大选项数，最高可至12项。
* 4. 消息窗口可以吸附到说话角色或事件上，显示fuki箭头并自动跟随移动。
* 5. 可以通过插件指令开启或关闭长文章功能，连缀相邻的消息指令形成长文章。
* 6. 支持在消息窗口两侧显示角色立绘。
* 7. 支持根据说话人不同，自动切换窗口皮肤和fuki箭头样式。
* 8. 可以通过插件指令设置消息窗口打字播放音效。
*
* 使用说明：
*
* 1. 首先开启本插件（需要SEP UI核心插件1.0.0以上版本）。
* 2. 完成插件参数配置中的统合模式、最大选项数、颜色和排版相关配置等。
* 3. 使用增补支持的转义文本指令，对文本内容进行宏替换和格式化操作。
* 具体支持的转义文本指令列表，请参考下方文档说明。
* 4. 开启长文章后，相邻的消息指令如果窗口、头像、姓名均一致，则自动连缀。
* 5. 在选择项指令中使用\/拆分子项，并可将选中子项序号存入变量以便后续使用。
*
* 注意事项：
*
* 1. 统合模式下，不再创建选项列表/数值输入子窗口，改为在消息窗中操作。
* 2. 原生模式下，行为与引擎默认一致。
* 受原生模式的窗口尺寸与分辨率限制，最大可见选项数可能受限。
* 3. 当显示角色立绘时，消息窗口会被固定在屏幕底端，吸附及事件调整位置无效。
* 但是，使用\＠[-2]将窗口全屏无边化有效，只是会遮挡立绘。
* 4. 当显示角色立绘时，消息窗口会被缩小到屏幕的一半宽度，但最小可保证显示
* 游戏系统配置中“脸图显示时消息窗口宽度”的文字数。
* 5. 为符合用户习惯，部分转义文本指令在有无参数时行为有别，请正确使用。
* 6. fuki箭头可以单独指令图片文件，若未指令，则会从窗口皮肤中自动检测。
* 窗口皮肤从(120, 36)到(144, 60)的区域若有相关图案，裁切上下两半使用。
* 若仍未检测到，会切割窗口边框四角图案，拼接成fuki箭头图案使用。
* 7. 开启长文章模式时，若连缀了文章，则消息不会再自动收入选择项、数值输入
* 和物品选择，无论是否为统合模式。这是因为消息窗口本身被加高，可能造成
* 显示空间不足或遮挡。若需令选择项与前面的消息同屏显示，请先关闭长文章。
* 8. 被\/拆分的选择项不同子项，在被选中后会进入原本的同一选项的分支，例如：
* 显示选择项：选项1, 选项2a\/选项2b, 选项3, 选项4a\/选项4b\/选项4c
* 选项1的场合
* // 事件指令列表1
* 选项2a\/选项2b的场合
* // 事件指令列表2
* 选项3的场合
* // 事件指令列表3
* 选项4a\/选项4b\/选项4c的场合
* // 事件指令列表4
* 分歧结束
* 在显示选择项时，所有子项会被打散，窗口列出共计7个选项，每条一行：
* 选项1, 选项2a, 选项2b, 选项3, 选项4a, 选项4b, 选项4c
* 若选中选项2a或选项2b，均会进入事件指令列表2。此时，通过存入变量可以
* 判断选中的是2a（值为1）还是2b（值为2）。
* 如果没有指定子项存储的变量，则具体的子项信息会丢失，无法判断。
* 9. 使用插件指令更改窗口皮肤，优先于按照说话人名称映射皮肤。
* 10.按照说话人姓名映射皮肤时，说话人姓名需与插件配置中注册的名称精确一致，
* 包括大小写、空格（含前后空格）、标点等，均需完全一致，否则无效。
* 11.若要关闭打字音效，使用插件指令将SE文件名设置为空即可。
* 快速显示的消息，会直接显示出来，不会触发打字音效。
*
* 【增强版转义文本指令集，含MZ原生指令，适用于所有drawTextEx方法绘制的文字】
*
* 信息替换类：
* 指令 参数示例 说明
* \\ （无参数） 显示反斜杠
* \N[角色ID] \N[1] 显示角色名称
* \N[角色ID.] \N[1.] 显示角色昵称
* \N[角色ID.属性名] \N[1.mhp] 显示角色的指定属性值
* \P[队员序号] \P[1] 显示队员名称
* \P[队员序号.] \P[1.] 显示队员昵称
* \P[队员序号.属性名] \P[1.mhp] 显示队员的指定属性值
* \E[敌人序号] \E[1] 显示敌人名称
* \E[敌人序号.属性名] \E[1.mhp] 显示敌人的指定属性值
* - 在战斗中，敌人序号指敌人在当前敌群中的顺序号，从1开始
* - 在战斗外，敌人序号指敌人自己的数据ID编号
* \V[变量ID] \V[1] 显示变量值
* \V[\V[变量ID]] \V[\V[1]] 显示指针式引用变量值，可多次嵌套
* - 由于\V指令会先于其他所有指令被替换，故可用变量来指定其他指令的参数
* \%[公式] \%[1+2*3] 显示公式计算值
* \%{公式} \%{1+2*3} 同上，支持公式中有方括号的情况
* - 公式中可直接引用以下变量和方法：
* v[变量ID] 变量值
* s[开关ID] 开关值
* ss[独立开关键] 独立开关值
* p 等同于$gameParty
* l 等同于$gamePlayer
* a(角色ID) 等同于$gameActors.actor(角色ID)
* b(敌人ID) 等同于$gameTroop.enemy(敌人ID)
* ev(事件ID) 等同于$gameMap.event(事件ID)
* \G （无参数） 显示货币单位
* \T[文本用语键] \T[attack] 显示文本用语中的指定名称
* \I[图标ID] \I[1] 显示指定图标
* \M[地图ID] \M[1] 显示指定地图名称（来自地图信息表）
* \M （无参数） 显示当前地图名称（来自地图名字段）
* \CL[职业ID] \CL[1] 显示指定职业名称
* \SK[技能ID] \SK[1] 显示指定技能名称（带有图标）
* \IT[物品ID] \IT[1] 显示指定物品名称（带有图标）
* \WE[武器ID] \WE[1] 显示指定武器名称（带有图标）
* \AR[防具ID] \AR[1] 显示指定防具名称（带有图标）
* \SA[状态ID] \SA[1] 显示指定状态名称（带有图标）
* \TR[敌群ID] \TR[1] 显示指定敌群名称
* \TI[图块ID] \TI[1] 显示指定图块名称
* \EL[属性ID] \EL[1] 显示指定属性名称
* \WT[武器类别ID] \WT[1] 显示指定武器类别名称
* \AT[防具类别ID] \AT[1] 显示指定防具类别名称
* \ET[装备类型ID] \ET[1] 显示指定装备类型名称
* \ST[技能类型ID] \ST[1] 显示指定技能类型名称
* \EV[事件ID] \EV[1] 显示指定事件名称
* \ [重复次数] \ [3] 显示指定数量的连续空格
* \,[数字] \,[100403] 显示逗号分隔的数字
* - 在中文、日语、韩文环境下，100403显示为10,0403
* - 在其他语言环境下，100403显示为100,403
* \#[数字] \#[123] 显示指定数字的本地语言化表达
* - 例如，在中文环境下，123显示为一百二十三
*
* 颜色控制类：
* 指令 参数示例 说明
* \C[颜色序号] \C[1] 改变文字颜色，按系统调色板序号
* \C[颜色值] \C[#846DC5] 改变文字颜色，按CSS颜色值
* \C[颜色名] \C[red] 改变文字颜色，按CSS基本颜色名
* \C[rgb(r,g,b)] \C[rgb(0,0,0)]改变文字颜色，按RGB颜色值
* \O[透明度] \O[128] 改变文字透明度，按0~255的数值
* 若启用扩展颜色支持，则还支持：
* \C[hsl(h,s%,l%)] \C[hsl(0,100%,50%)] 改变文字颜色，按HSL颜色值
* \C[扩展颜色名] \C[aliceblue] 改变文字颜色，按CSS扩展颜色名
* 若启用透明颜色支持，则还支持：
* \C[rgba(r,g,b,a)] \C[rgba(0,0,0,0.5)] 改变文字颜色，按RGBA颜色值
* \C[hsla(h,s%,l%,a)] \C[hsla(0,100%,50%,0.5)] 改变文字颜色，按HSLA颜色值
* \C[带透明度的颜色值] \C[#FF808080] 改变文字颜色，按带透明度的HEX颜色值
* \C[transparent] \C[transparent] 将文字色变为透明
*
* 格式控制类：
* 指令 参数示例 说明
* \FF[字体] \FF[Arial] 改变文字字体
* \FS[字号] \FS[24] 改变文字字号
* \{ （无参数） 将文字字号增加12（不超过96）
* \} （无参数） 将文字字号减少12（不低于24)
* \PX[X坐标] \PX[100] 改变下一个字的起始X坐标
* \PY[Y坐标] \PY[100] 改变下一个字的起始Y坐标
* \JX[X坐标增量] \JX[10] 使下一个字的打印位置横向平移
* \JY[Y坐标增量] \JY[10] 使下一个字的打印位置纵向平移
* \J[Tab次数] \J[2] 使下一个字的打印位置跳跃2个Tab空格
* - Tab空格位置由“制表符停靠点”参数配置，未指定或超出时每4个字符停靠一次
* \] （无参数） 本行剩余文字靠另一侧对齐
* - 一般情况为向右对齐，若为从右向左打印的语言，则为向左对齐
* \[ （无参数） 本行剩余文字居中对齐
* \: （无参数） 下一行文字缩进至这个位置开始显示
* \` （无参数） 下一行文字取消缩进，从头开始显示
* \/ （无参数） 手动换行
* \B[粗体文字] \B[强调] 将括号内文字变为粗体
* \I[斜体文字] \I[引用] 将括号内文字变为斜体
* - 斜体文字不能为纯数字，否则会被引擎识别为图标变换
* \BI[粗斜体文字] \BI[着重] 将括号内文字变为粗斜体
* \*或\B （无参数） 切换粗体，使用一次打开，再次关闭
* \_或\I （无参数） 切换斜体，使用一次打开，再次关闭
* \U[下划线文字] \U[关键词] 将括号内文字加上下划线
* \S[删除线文字] \S[删除] 将括号内文字加上删除线
* \U[下划线型] \U[2] 为后续文字加上指定形状的下划线
* - 下划线型参数为0~10，表示不同的下划线样式，其中0为取消下划线：
* 1: 单实线 2: 双实线 3: 粗实线 4: 点虚线 5: 短虚线
* 6: 长虚线 7: 点划线 8: 双点划线 9: 波浪线 10: 着重号
* \S[删除线型] \S[3] 为后续文字加上指定形状的删除线
* - 删除线型参数为0~10，表示不同的删除线样式，其中0为取消删除线：
* 1: 单实线 2: 双实线 3: 粗实线 4: 粗块线 5: 全遮挡
* 6: 示亡框 7: 横阴影 8: 竖阴影 9: 网格影 10: 字加框
* \SP[上标] \SP[2] 将括号内文字以上标式样显示
* \SB[下标] \SB[2] 将括号内文字以下标式样显示
* \~ （无参数） 重置字体样式为默认设置
*
* 【增强版转义控制指令集，含MZ原生指令，仅适用于对话框窗口】
*
* 显示流控制类：
* 指令 参数示例 说明
* \. （无参数） 暂停等待0.25秒
* \; （无参数） 暂停等待0.5秒
* \| （无参数） 暂停等待1秒
* \Z[帧数] \Z[60] 暂停等待指定帧数（1秒=60帧）
* \> （无参数） 立即显示剩余文字
* \< （无参数） 取消立即显示剩余文字
* \^ （无参数） 消息结束后立即关闭窗口
* \^[帧数] \^[60] 消息结束后延迟指定帧数关闭窗口
* \K[速度] \K[4] 改变消息文字的显示速度，越大越慢
* \SE[系统音效编号] \SE[1] 播放指定的系统音效（编号1-24）
* \SE[音效文件名] \SE[Fire1] 播放指定的系统音效（文件名）
*
* 外观控制类：
* 指令 参数示例 说明
* \$ （无参数） 显示金钱窗口
* \W[变量ID] \W[1] 显示指定ID的变量窗口
* \＠[事件ID] \＠[1] 将对话框吸附到指定ID的事件上
* \＠[0] \＠[0] 将对话框吸附到主角上
* \＠[-1] \＠[-1] 取消对话框吸附，恢复默认位置
* \＠[-2] \＠[-2] 将对话框全屏无边化，覆盖整个画面
* \＠[-3] \＠[-3] 将对话框缩小至刚好容纳文字的大小
* \＠[N+角色ID] \＠[N1] 将对话框吸附到指定ID的角色上
* - 如角色在队，吸附到主角队列的对应人物上，如角色不在队或未开启队列行进
* 则吸附到主角上
* \＠[P+队员序号] \＠[P1] 将对话框吸附到指定序号的队员上
* - 如开启队列行进，吸附到对应位置的人物上，若超出队列人数则吸附到主角上
* \＠[E+敌人序号] \＠[E1] 将对话框吸附到指定序号的敌人上
* - 仅限战斗中使用，敌人序号指敌人在当前敌群中的顺序号，从1开始
* - 以上吸附格式均可追加水平和垂直偏移像素值，如 \＠[1,10,-20]
* \＠ （无参数） 对话框智能吸附
* - 智能吸附的检测按照以下优先级进行：
* a) 若当前对话指令有脸图，且与角色对应，则吸附到该角色上
* b) 若当前对话指令有姓名，且与角色对应，则吸附到该角色上
* c) 若当前对话指令有姓名，且与指令所在的事件名称对应，则吸附到该事件上
* d) 战斗中，若当前对话指令有姓名，且与敌人对应，则吸附到该敌人上
* e) 以上均不满足，则吸附到主角上
* - 若打开插件参数的“自动吸附”配置，则智能吸附全时生效，无需显式指令
* - 对话框吸附生效（不是-1或-2的值）时，对话框会缩小到刚好容纳文字的宽高
* 并显示指向吸附对象的fuki箭头，且会始终跟随对象移动
* 若吸附对象在屏幕可视范围外，对话框显示于所在方向的角上，fuki箭头外指
* \L[立绘文件名] \L[Actor1] 显示指定立绘图片在左侧
* \L[角色ID] \L[1] 显示指定角色的立绘图片在左侧
* - 以上格式均可追加水平中心点和垂直偏移像素值，如 \L[Actor1,120,-10]
* \R[立绘文件名] \R[Actor1] 显示指定立绘图片在右侧
* \R[角色ID] \R[1] 显示指定角色的立绘图片在右侧
* - 以上格式均可追加水平中心点和垂直偏移像素值，如 \R[Actor1,120,-10]
* - 若要用角色ID指定立绘，需安装官方插件ActorPictures.js并指定角色立绘
* - 立绘文件需放在 img/pictures/ 目录下
* - 显示立绘时，消息窗口会被固定在屏幕底端，事件指令中的调整和吸附均无效
*
* 【fuki箭头图片素材规格说明】
* fuki箭头图片素材的规格为，宽度建议为12-24像素，高度须为偶数像素。
* 其上部1/2的区域，作为指向上方的fuki箭头；
* 其下部1/2的区域，作为指向下方的fuki箭头。
* 当需要fuki箭头指向左侧或右侧时，会自动将图片旋转90度使用。
*
* 本插件在MIT许可证下发布。
* [url]https://opensource.org/licenses/mit-license.php[/url]
*
* @base SEPUICore
* @orderAfter SEPUICore
*
* @param unifiedMode
* @text 统合模式
* @desc 选项和数值输入的展示方式。
* @type select
* @option 统合到消息窗口
* @value auto
* @option 原生独立窗口
* @value native
* @default auto
*
* @param maxVisibleChoices
* @text 最大可见选项数
* @desc 解放选项列表的最大可见选项数，最高支持12项。
* 项数会受到屏幕高度的限制，非统合模式原始分辨率约为9项。
* @type number
* @min 6
* @max 12
* @default 6
*
* @param allowExtendedColors
* @text 扩展颜色支持
* @desc 是否支持 HSL/HSLA 颜色和 CSS 扩展颜色名。
* @type boolean
* @default true
* @on 启用
* @off 禁用
*
* @param allowTransparentColors
* @text 透明颜色支持
* @desc 是否支持 RGBA/HSLA 颜色和透明关键字。
* @type boolean
* @default true
* @on 启用
* @off 禁用
*
* @param tabStop
* @text 制表符停靠点
* @desc 制表符停靠点的水平位置，单位像素。
* 如果留空，则每4个字符宽度为一个停靠点。
* @type number[]
*
* @param scriptFontSize
* @text 上/下标字体大小
* @desc 上标/下标的字体大小，相对于当前字号的比例值
* @type number
* @decimals 2
* @min 0.2
* @max 0.5
* @default 0.35
*
* @param variableWindowStyle
* @text 变量窗口样式
* @desc 变量窗口的样式配置。
* @type note
* @default "<width: fit>\n<height: 1L>\n<colSpacing:0>\n<maxDigits:8>\n<useDelimiter:false>\n<flashDuration:60>"
*
* @param actorPictureStyle
* @text 角色立绘样式
* @desc 角色立绘的样式配置。
* @type select
* @option 对齐长边
* @value cover
* @option 对齐短边
* @value contain
* @option 原始尺寸
* @value original
* @default cover
*
* @param actorPictureMarginH
* @text 角色立绘水平边距
* @desc 角色立绘的水平边距，单位像素或百分比
* 也可组合使用，如20%+40
* @type string
* @default 0
*
* @param actorPictureMarginV
* @text 角色立绘垂直边距
* @desc 角色立绘的垂直边距，单位像素或百分比
* 也可组合使用，如20%+40
* @type string
* @default 0
*
* @param autoSnap
* @text 自动吸附
* @desc 根据脸图、姓名等自动将对话框吸附到说话角色或事件。
* @type boolean
* @default true
* @on 启用
* @off 禁用
*
* @param windowskinMap
* @text 窗口皮肤映射
* @desc 指定说话人姓名、窗口皮肤、fuki箭头的对应关系
* @type struct<windowskin>[]
* @default []
*
* @param fukiArrowImage
* @text Fuki箭头图片
* @desc fuki箭头的图片文件名，放在 img/system/ 下。
* 留空则从窗口皮肤自动检测。
* @type file
* @dir img/system/
*
* @param choiceExpandVar
* @text 展开选项变量
* @desc 选项含\/拆分时，将选中子项序号（从1开始）存入该变量。
* 设为0则禁用。
* @type number
* @min 0
* @default 0
*
* @command longArticle
* @text 长文章模式
* @desc 连缀相邻的消息指令，形成长文章。
*
* @arg enabled
* @text 启用
* @desc 是否启用长文章模式。
* @type boolean
* @on 启用
* @off 禁用
* @default true
*
* @command longArticleMaxLines
* @text 最大行数
* @desc 设置长文章模式下的最大行数，超过则自动分页。
*
* @arg maxLines
* @text 最大行数
* @desc 长文章最大行数，超过则自动分页，超出屏幕高度也会分页。
* 若设置为0，则只受屏幕高度限制。
* @type number
* @min 0
* @default 0
*
* @command choiceExpandVar
* @text 展开选项变量
* @desc 指定接收\/拆分子项序号（从1开始）的变量。
*
* @arg variableId
* @text 变量ID
* @desc 设为0则禁用存储。
* @type number
* @min 0
* @default 0
*
* @command setTypingSE
* @text 设置打字音效
* @desc 设置当前消息窗口的打字音效。
*
* @arg se
* @text 打字音效
* @desc 打字音效的文件名，放在 audio/se/ 下。
* @type file
* @dir audio/se/
*
* @arg volume
* @text 音量
* @desc 打字音效的音量，0~100。
* @type number
* @min 0
* @max 100
* @default 90
*
* @arg pitch
* @text 音调
* @desc 打字音效的音调，50~150。
* @type number
* @min 50
* @max 150
* @default 100
*
* @arg pan
* @text 声道
* @desc 打字音效的声道，-100~100。
* @type number
* @min -100
* @max 100
* @default 0
*
* @command setMessageWindowskin
* @text 更改消息窗口皮肤
* @desc 更改当前消息窗口的窗口皮肤。
*
* @arg windowskin
* @text 窗口皮肤
* @desc 窗口皮肤的文件名，放在 img/system/ 下。
* @type file
* @dir img/system/
*
* @arg fukiArrow
* @text Fuki箭头
* @desc fuki箭头的图片文件名，放在 img/system/ 下。
* 留空则从窗口皮肤自动检测。
* @type file
* @dir img/system/
*
*/
/*~struct~windowskin:zh
* @param name
* @text 说话人姓名
* @desc 对应的说话人姓名，若留空，则匹配所有说话人。
* 必须严格匹配名称（区分大小写），相应的皮肤才会生效。
* @type string
* @default ""
*
* @param windowskin
* @text 窗口皮肤
* @desc 对应的窗口皮肤文件名，放在 img/system/ 下。
* @type file
* @dir img/system/
* @default ""
*
* @param fukiArrow
* @text Fuki箭头
* @desc 对应的fuki箭头图片文件名，放在 img/system/ 下。
* @type file
* @dir img/system/
* @default ""
*
*/