更新UserScripts

README.md

@@ -5,3 +5,4 @@ Documents of Open-Source Arcaea Chart Making & Previewing Tool Project 「Arcade
 Contents:
 
 - [Special System](Specials/README.md "Arcade-Chan Special System Developing Document")
+- [User Scripts(用户脚本)](UserScripts/README.md "Arcade-Chan User Scripts Developing Document")

Specials/README.md

@@ -9,6 +9,14 @@ Caution: We will use placeholder `%varName%` to replace the corresponding value
 
 Updated on: 1.2.0 (5.17.2022)
 
+##### New Location Support in 2.4.5 (4.1.2023)
+Now you can use 3 locations to show the text: `top`, `center` and `bottom`.  
+Their corresponding id is `topText`, `text` and `bottomText`.  
+For exmaple:  
+```cs
+special(%time%, topText, in, %textId%);  
+```
+
 This statement can dynamically show/hide tutorial text on the top-center of the window.
 
 Usage:
@@ -163,6 +171,9 @@ special(%time%, uiedit, <type>, <value>);
 
 * `1`: Difficulty Rating ("rating10"(means "10")/"rating9plus"(means "9+"))
 * `2`: Full Difficulty String ("Beyond_rating12"(means "Beyond 12")/"Future_rating9plus"(means "Future 9+"))
+* `3`: Difficulty Indicator Sprite ("level0"/"level1"/"level2"/"level3", corresponding to Past/Present/Future/Beyond)
+* `4`: Song Title (The id of the title text in ``spStrTable.json`` (same as the file in **Section 1**.)) [Added in v2.5.0]
+* `5`: Song Artist (The id of the artist text in ``spStrTable.json`` (same as the file in **Section 1**.)) [Added in v2.5.0]
 
 ``value``(string): The value of the UI component.
 
@@ -208,5 +219,5 @@ special(%time%, uiedit, 1, R); // This is not start with a number, so we don't n
 
 ---
 
-Last Update: Sunday, December 25, 2022  
-Corresponding Arcade-Chan Version: 2.1.0 LTS (Updated on 12.25.2022)
+Last Update: Friday, April 7th, 2023
+Corresponding Arcade-Chan Version: 2.5.0 LTS (Updated on 4.7.2023(Pending))

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArc.md

@@ -0,0 +1,56 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting
+# ScriptArc 类
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+表示一个用于Lua脚本的脚本音符Arc。
+
+```csharp
+[MoonSharpUserData]
+public sealed class ScriptArc : ScriptNote<Arcade.Gameplay.Chart.ArcArc, Arcade.Aff.RawAffArc>
+```
+
+继承 [Object](https://learn.microsoft.com/zh-cn/dotnet/api/system.object?view=latest) -> [ScriptObject](ScriptObject.md) -> [ScriptEvent](ScriptEvent.md) -> [ScriptEvent&lt;TEvent, TRawEvent&gt;](ScriptEvent`2.md) -> [ScriptNote&lt;TNote, TRawNote&gt;](ScriptNote`2.md) -> **ScriptArc**
+
+## 注解
+该类用于在脚本层表示Arcaea谱面中的Arc音符。
+
+## 属性
+| 属性名 | 类型 | 说明 |
+| -- | -- | -- |
+| ``Timing`` | int | 该音符的起始时间。 |
+| ``TimingGroupIdx`` | int | 该音符所属的时间组(TimingGroup)的索引下标。对应时间组必须已经存在于谱面中。 |
+| ``EndTiming`` | int | 该音符的结束时间。 |
+| ``Color`` | int | 该音符的颜色。0=蓝，1=红，2=绿，3=灰/白(持续时间0ms的3号颜色Arc会视为可变长度的ArcTap处理)。 |
+| ``XStart`` | float | 该音符的起始X坐标。 |
+| ``XEnd`` | float | 该音符的结束X坐标。 |
+| ``YStart`` | float | 该音符的起始Y坐标。 |
+| ``YEnd`` | float | 该音符的结束Y坐标。 |
+| ``LineType`` | Arcade.Gameplay.ArcLineType | 该Arc音符的音弧缓动(曲线)形态。<br />可选 ``S/B/Si/So/SiSi/SiSo/SoSi/SoSo``中任意一值。 |
+| ``VoidType`` | Arcade.Aff.VoidType | 该Arc音符的音轨状态类型。<br />可选 ``Solid/Void/VoidDesignant``中任意一值。 |
+| ``Effect`` | string | 其上的ArcTap音符的特殊音效(Sfx)参数。<br />若值不为none，其上所有的ArcTap都会表示为SfxArcTap的样式，并且单击判定成功时播放Effect所指的音效wav文件，而非正常的点击音效(hitsound)。<br />(文件名中"."用"_"代替, 例如"kick_wav"表示音效是项目文件夹下的kick.wav) |
+| ``ArcTaps`` | [ObservableCollection&lt;ScriptArcTap&gt;](https://docs.microsoft.com/zh-cn/dotnet/api/system.collections.objectmodel.observablecollection-1?view=latest) | 该Arc音符上的所有ArcTap音符。<br />只要存在附属ArcTap，若 ``VoidType`` 的值为 ``VoidType.Solid``，该Arc音符也会被视为音轨(Trace/Vold)处理【即视 ``VoidType`` 为 ``VoidType.Void``】。 |
+
+## 方法
+| 方法名 | 说明 |
+| -- | -- |
+| [Create(int, int, int, float, float, float, float, ArcLineType, ArcVoidType, string, int, DynValue)](ScriptArc_Create.md) | 创建一个新的Arc(音弧)脚本音符，并初始化其绑定的对象事件。 |
+| [AddArcTap(int)](ScriptArc_AddArcTap.md) | 添加一个脚本音符ArcTap到该脚本音符Arc上。 |
+| [RemoveArcTap(int)](ScriptArc_RemoveArcTap.md#Overload_int) | 从该脚本音符Arc上移除一个指定判定时间的ArcTap。 |
+| [RemoveArcTap(ScriptArcTap)](ScriptArc_RemoveArcTap.md#Overload_ScriptArcTap) | 从该脚本音符Arc上移除一个ArcTap。 |
+| [RemoveArcTaps(Predicate&lt;ScriptArcTap&gt;)](ScriptArc_RemoveArcTaps.md) | 从该脚本音符Arc上移除所有满足条件的ArcTap。 |
+
+## 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |
+
+## 另请参阅
+- [ScriptArcTap](ScriptArcTap.md)
+- [ScriptChart](ScriptChart.md)

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArcTap.md

@@ -0,0 +1,43 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting
+# ScriptArcTap 类
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+表示一个用于Lua脚本的脚本音符ArcTap。  
+该音符无法单独存在，其必须属于且仅属于一个音轨状态的Arc音符。  
+(若其属于了一个音弧状态的Arc音符，则对应Arc音符会直接视为音轨状态处理)
+
+```csharp
+[MoonSharpUserData]
+public sealed class ScriptArcTap : ScriptEvent
+```
+
+继承 [Object](https://learn.microsoft.com/zh-cn/dotnet/api/system.object) -> [ScriptObject](ScriptObject.md) -> [ScriptEvent](ScriptEvent.md) -> **ScriptArcTap**
+
+## 注解
+该类用于在脚本层表示Arcaea谱面中的ArcTap音符。
+
+## 属性
+| 属性名 | 类型 | 说明 |
+| -- | -- | -- |
+| ``Timing`` | int | 该音符的判定时间。 |
+
+## 方法
+| 方法名 | 说明 |
+| -- | -- |
+| [Create(ScriptArc, int)](ScriptArcTap_Create.md) | 使用指定的父脚本音符Arc和判定时间创建一个新的ArcTap脚本音符。 |
+
+## 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |
+
+## 另请参阅
+- [ScriptArc](ScriptArc.md)
+- [ScriptChart](ScriptChart.md)

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArcTap_Create.md

@@ -0,0 +1,36 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting / ScriptArcTap / 方法 /
+# ScriptArcTap.Create(ScriptArc, int) 方法
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+使用指定的父脚本音符Arc和判定时间创建一个新的ArcTap脚本音符。  
+**ArcTap所属的时间组将与其父Arc所属的时间组一致。**  
+
+```csharp
+public static ScriptArcTap Create(ScriptArc arc, int timing);
+```
+
+## 参数
+- ``arc`` [ScriptArc](ScriptArc.md)  
+  ArcTap所属的父脚本音符Arc。
+- ``timing`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  ArcTap的判定时间。
+
+## 返回
+[ScriptArcTap](ScriptArcTap.md)  
+  创建的ArcTap脚本音符。
+
+## 注解
+该方法创建的 [ScriptArcTap](ScriptArcTap.md) 对象无法添加到父Arc中。  
+如需添加到父Arc中请直接使用 [ScriptArc.AddArcTap(int)](ScriptArc_AddArcTap.md) 方法。
+
+## 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArc_AddArcTap.md

@@ -0,0 +1,33 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting / ScriptArc / 方法 /
+# ScriptArc.AddArcTap(int) 方法
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+添加一个脚本音符ArcTap到该脚本音符Arc上。
+
+```csharp
+public ScriptArcTap AddArcTap(int timing);
+```
+
+## 参数
+- ``timing`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  ArcTap的判定时间。
+
+## 返回
+[ScriptArcTap](ScriptArcTap.md)  
+  创建的ArcTap脚本音符。
+
+## 异常
+[InvalidOperationException](https://docs.microsoft.com/zh-cn/dotnet/api/system.invalidoperationexception)  
+  在当前Arc可判定(不属于启用NoInput的时间组)的情况下，新ArcTap的判定时间与既有至少一个ArcTap的判定时间重叠(TimeOverlap)——这在谱面制作规范中是不被允许的。
+
+## 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArc_Create.md

@@ -0,0 +1,58 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting / ScriptArc / 方法 /
+# ScriptArc.Create(int, int, int, float, float, float, float, ArcLineType, ArcVoidType, string, int, DynValue) 方法
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+创建一个新的Arc(音弧)脚本音符，并初始化其绑定的对象事件。
+
+```csharp
+public static ScriptArc Create(int timing, int endtiming, int color, float xStart, float xEnd, float yStart, float yEnd, ArcLineType lineType, ArcVoidType voidType, string effect = "none", int timingGroup = 0, DynValue arctaps = null);
+```
+
+## 参数
+- ``timing`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  Arc的起始时间。
+- ``endtiming`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  Arc的结束时间。
+- ``color`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  Arc的颜色。可选值为0=蓝，1=红，2=绿，3=灰/白(持续时间0ms的3号颜色Arc会视为可变长度的ArcTap处理)。
+- ``xStart`` [float](https://docs.microsoft.com/zh-cn/dotnet/api/system.single)  
+  Arc的起始X坐标。
+- ``xEnd`` [float](https://docs.microsoft.com/zh-cn/dotnet/api/system.single)  
+  Arc的结束X坐标。
+- ``yStart`` [float](https://docs.microsoft.com/zh-cn/dotnet/api/system.single)  
+  Arc的起始Y坐标。
+- ``yEnd`` [float](https://docs.microsoft.com/zh-cn/dotnet/api/system.single)  
+  Arc的结束Y坐标。
+- ``lineType`` ArcLineType  
+  Arc的音弧缓动(曲线)形态。可选值为【基础】S/B/Si/So和【高级】SiSi/SiSo/SoSi/SoSo八种缓动形态之一。
+- ``voidType`` ArcVoidType  
+  Arc音符的音轨状态类型。可选值为Solid/Void和VoidDesignant三种状态之一。
+- ``effect`` [string](https://docs.microsoft.com/zh-cn/dotnet/api/system.string)  
+  其上的ArcTap音符的特殊音效(Sfx)参数。默认为"none"(即无特殊音效)。
+- ``timingGroup`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  Arc所属的时间组(TimingGroup)的索引下标。默认为0(默认时间组)。
+- ``arctaps`` DynValue (Lua层为``Table``，列表形态，元素为[ScriptArcTap](ScriptArcTap.md))  
+  其上的所有ArcTap音符。可选参数。默认为空列表(即该Arc音符不存在任何附属ArcTap)。
+
+## 返回
+[ScriptArc](ScriptArc.md)  
+  创建的Arc(音弧)脚本音符。
+
+## 异常
+[ArgumentOutOfRangeException](https://docs.microsoft.com/zh-cn/dotnet/api/system.argumentoutofrangeexception)  
+  时间组索引下标超出现有时间组列表的范围。
+
+## 注解
+该方法创建的 [ScriptArc](ScriptArc.md) 对象并不会自动添加并应用到谱面中，如需添加到谱面中请参考 [ScriptChart.AddArc(ScriptArc)](ScriptChart_AddArc.md) 方法。
+
+## 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArc_RemoveArcTap.md

@@ -0,0 +1,67 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting / ScriptArc / 方法 /
+# ScriptArc.RemoveArcTap 方法
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+## 重载
+| 方法名 | 说明 |
+| -- | -- |
+| [RemoveArcTap(int)](#Overload_int) | 从该脚本音符Arc上移除一个指定判定时间的ArcTap。 |
+| [RemoveArcTap(ScriptArcTap)](#Overload_ScriptArcTap) | 从该脚本音符Arc上移除一个ArcTap。 |
+
+
+## ScriptArc.RemoveArcTap(int)
+<a name="Overload_int"></a>
+从该脚本音符Arc上移除一个指定判定时间的ArcTap。
+
+```csharp
+public bool RemoveArcTap(int timing);
+```
+
+### 参数
+- ``timing`` [int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  要移除的ArcTap的判定时间。
+
+### 返回
+[bool](https://docs.microsoft.com/zh-cn/dotnet/api/system.boolean)  
+  如果找到并成功移除了指定判定时间的ArcTap，则返回``true``；否则返回``false``。
+
+### 适用于
+<details>
+	<summary>Arcade-Chan 3.3.0+</summary>
+	<table>
+		<tr><th><strong>产品</strong></th><th><strong>版本</strong></th></tr>
+		<tr><td><strong>Arcade-Chan</strong></td><td>3.3.0+</td></tr>
+	</table>
+</details>
+
+## ScriptArc.RemoveArcTap(ScriptArcTap)
+<a name="Overload_ScriptArcTap"></a>
+从该脚本音符Arc上移除一个ArcTap。
+
+```csharp
+public bool RemoveArcTap(ScriptArcTap arcTap);
+```
+
+### 参数
+- ``arcTap`` [ScriptArcTap](ScriptArcTap.md)  
+  要移除的ArcTap。
+
+### 返回
+[bool](https://docs.microsoft.com/zh-cn/dotnet/api/system.boolean)  
+  如果找到并成功移除了指定的ArcTap，则返回``true``；否则返回``false``。
+
+### 适用于
+<details>
+	<summary>Arcade-Chan 3.3.0+</summary>
+	<table>
+		<tr><th><strong>产品</strong></th><th><strong>版本</strong></th></tr>
+		<tr><td><strong>Arcade-Chan</strong></td><td>3.3.0+</td></tr>
+	</table>
+</details>

UserScripts/Data/Arcade.Scripting.Apis/Aff/ScriptArc_RemoveArcTaps.md

@@ -0,0 +1,29 @@
+Arcade-Chan 用户脚本 / 开发手册 / Arcade.Scripting / ScriptArc / 方法 /
+# ScriptArc.RemoveArcTaps(Predicate<ScriptArcTap>) 方法
+参考
+
+## 定义
+<div style="font-size: 90%;">
+命名空间: <a href="README.md">Arcade.Scripting.Apis.Aff</a><br />
+Lua层级: &lt;Global&gt;<br />
+程序集: Arcade.Scripting.dll
+</div><br />
+
+从该脚本音符Arc上移除所有满足条件的ArcTap。
+
+```csharp
+public int RemoveArcTaps(Predicate<ScriptArcTap> match);
+```
+
+### 参数
+- ``match`` [Predicate&lt;ScriptArcTap&gt;](https://docs.microsoft.com/zh-cn/dotnet/api/system.predicate-1)  
+  要移除的ArcTap的条件。
+
+### 返回
+[int](https://docs.microsoft.com/zh-cn/dotnet/api/system.int32)  
+  成功移除的ArcTap的数量。若移除操作灾难性失败(Failed Fatally)，则返回0 (不存在成功移除的ArcTap)。
+
+### 适用于
+| 产品 | 版本 |
+|:----|:----|
+| **Arcade-Chan** | 3.3.0+ |