chore(release): merge dev into main for v0.2.31

Author: BAKAOLC

.github/actions/ritsulib-build/action.yml

@@ -11,6 +11,14 @@ inputs:
     description: Build artifacts with dev-only package version (9999.0.0-dev.<run>+<sha>).
     required: false
     default: "false"
+  upload-artifact:
+    description: Upload artifacts/github and artifacts/nuget as a GitHub Actions artifact.
+    required: false
+    default: "true"
+  artifact-retention-days:
+    description: Number of days to retain the uploaded Actions artifact.
+    required: false
+    default: "30"
 
 runs:
   using: composite
@@ -41,3 +49,23 @@ runs:
         --repo-root "${{ github.workspace }}"
         --signature-root "${{ inputs.signatures-root }}"
         $extra
+
+    - name: Resolve artifact name
+      if: ${{ inputs.upload-artifact == 'true' }}
+      id: artifact
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      run: |
+        short_sha="$(git rev-parse --short=12 HEAD)"
+        echo "name=ritsulib-${short_sha}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"
+
+    - name: Upload build artifacts
+      if: ${{ inputs.upload-artifact == 'true' }}
+      uses: actions/upload-artifact@v7
+      with:
+        name: ${{ steps.artifact.outputs.name }}
+        path: |
+          artifacts/github/**
+          artifacts/nuget/**
+        if-no-files-found: error
+        retention-days: ${{ inputs.artifact-retention-days }}

.github/labels.yml

@@ -132,3 +132,7 @@
 - name: area/other
   color: ededed
   description: Area is unclear or does not fit existing categories.
+
+- name: ci/build
+  color: 5319e7
+  description: Maintainer-approved one-shot PR build that uploads Actions artifacts.

.github/workflows/build.yml

@@ -0,0 +1,52 @@
+# Controlled CI build: manual ref builds and maintainer-approved PR builds.
+name: Build
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch, tag, or commit SHA to build. Empty uses the selected workflow ref."
+        required: false
+        default: ""
+      use-dev-version:
+        description: "Use unique dev package version 9999.0.0-dev.<run>+<sha>."
+        required: false
+        type: boolean
+        default: true
+  pull_request:
+    branches: [main, dev]
+    types: [labeled]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ritsulib-build-${{ github.event_name }}-${{ github.event.pull_request.number || inputs.ref || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build artifacts
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.label.name == 'ci/build' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+          repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || inputs.ref || github.ref }}
+
+      - name: Checkout API signatures (shallow)
+        uses: actions/checkout@v6
+        with:
+          repository: BAKAOLC/STS2-API-Signatures
+          path: sts2-api-signatures
+          fetch-depth: 1
+          persist-credentials: false
+          token: ${{ github.token }}
+
+      - uses: ./.github/actions/ritsulib-build
+        with:
+          signatures-root: ${{ github.workspace }}/sts2-api-signatures
+          use-dev-version: ${{ github.event_name == 'pull_request' || inputs.use-dev-version }}

Audio/AudioAdaptiveMusicDirector.cs

@@ -4,6 +4,7 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Coordinates adaptive room/combat/victory music playback in response to game lifecycle transitions.
+    ///     根据游戏生命周期转换，协调自适应房间/战斗/胜利音乐播放。
     /// </summary>
     public sealed class AudioAdaptiveMusicDirector : IDisposable
     {
@@ -32,11 +33,13 @@ private AudioAdaptiveMusicDirector()
 
         /// <summary>
         ///     Shared singleton director.
+        ///     共享的单例 director。
         /// </summary>
         public static AudioAdaptiveMusicDirector Shared { get; } = new();
 
         /// <summary>
         ///     Disposes framework lifecycle subscriptions owned by this director.
+        ///     释放此 director 拥有的框架生命周期订阅。
         /// </summary>
         public void Dispose()
         {
@@ -51,6 +54,7 @@ public void Dispose()
 
         /// <summary>
         ///     Starts following the supplied adaptive music plan and returns a handle for later shutdown.
+        ///     开始跟随提供的自适应音乐计划，并返回用于稍后关闭的句柄。
         /// </summary>
         public AudioAdaptiveMusicHandle Attach(AudioAdaptiveMusicPlan plan)
         {
@@ -62,6 +66,7 @@ public AudioAdaptiveMusicHandle Attach(AudioAdaptiveMusicPlan plan)
 
         /// <summary>
         ///     Removes a previously attached adaptive music handle from lifecycle tracking.
+        ///     从生命周期跟踪中移除先前附加的自适应音乐句柄。
         /// </summary>
         public void Detach(AudioAdaptiveMusicHandle handle)
         {

Audio/AudioAdaptiveMusicHandle.cs

@@ -2,6 +2,7 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Represents an active adaptive music binding that can switch tracks and restore vanilla state when stopped.
+    ///     表示一个活动的自适应音乐绑定，可切换曲目，并在停止时恢复原版状态。
     /// </summary>
     public sealed class AudioAdaptiveMusicHandle : IDisposable
     {
@@ -16,6 +17,7 @@ internal AudioAdaptiveMusicHandle(AudioAdaptiveMusicPlan plan)
 
         /// <summary>
         ///     Stops adaptive playback and unregisters this handle from the shared director.
+        ///     停止自适应播放，并从共享 director 注销此句柄。
         /// </summary>
         public void Dispose()
         {
@@ -40,6 +42,7 @@ internal void RefreshVolume(float volume)
 
         /// <summary>
         ///     Stops the current adaptive override and optionally restores vanilla run music.
+        ///     停止当前自适应覆盖，并可选择恢复原版跑局音乐。
         /// </summary>
         public void Stop(bool restoreVanillaMusic = true)
         {

Audio/AudioAdaptiveMusicPlan.cs

@@ -2,51 +2,61 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Declares room/combat/victory music sources that should follow the game's lifecycle transitions.
+    ///     声明应跟随游戏生命周期转换的房间/战斗/胜利音乐源。
     /// </summary>
     public sealed class AudioAdaptiveMusicPlan
     {
         /// <summary>
         ///     Music source to use while the player is in a room outside combat.
+        ///     玩家处于非战斗房间时使用的音乐源。
         /// </summary>
         public AudioSource? RoomSource { get; init; }
 
         /// <summary>
         ///     Music source to use while combat is active.
+        ///     战斗进行时使用的音乐源。
         /// </summary>
         public AudioSource? CombatSource { get; init; }
 
         /// <summary>
         ///     Music source to use after combat victory, when provided.
+        ///     提供后，在战斗胜利后使用的音乐源。
         /// </summary>
         public AudioSource? VictorySource { get; init; }
 
         /// <summary>
         ///     Restores vanilla run music when the adaptive handle is stopped.
+        ///     自适应句柄停止时恢复原版跑局音乐。
         /// </summary>
         public bool RestoreVanillaMusicOnStop { get; init; } = true;
 
         /// <summary>
         ///     Restores vanilla run music after combat ends instead of returning to the room override.
+        ///     战斗结束后恢复原版跑局音乐，而不是返回房间覆盖。
         /// </summary>
         public bool RestoreVanillaMusicOnCombatEnd { get; init; } = true;
 
         /// <summary>
         ///     Refreshes vanilla room track and ambience when entering a room with no room override.
+        ///     进入没有房间覆盖的房间时刷新原版房间曲目和环境音。
         /// </summary>
         public bool RefreshVanillaRoomStateOnRoomEnter { get; init; } = true;
 
         /// <summary>
         ///     Playback options applied when starting room music.
+        ///     启动房间音乐时应用的播放选项。
         /// </summary>
         public AudioPlaybackOptions RoomOptions { get; init; } = new() { Scope = AudioLifecycleScope.Room };
 
         /// <summary>
         ///     Playback options applied when starting combat music.
+        ///     启动战斗音乐时应用的播放选项。
         /// </summary>
         public AudioPlaybackOptions CombatOptions { get; init; } = new() { Scope = AudioLifecycleScope.Combat };
 
         /// <summary>
         ///     Playback options applied when starting victory music.
+        ///     启动胜利音乐时应用的播放选项。
         /// </summary>
         public AudioPlaybackOptions VictoryOptions { get; init; } = new() { Scope = AudioLifecycleScope.Combat };
     }

Audio/AudioAdaptivePlans.cs

@@ -2,11 +2,13 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Convenience builders for common adaptive music override patterns.
+    ///     常见自适应音乐覆盖模式的便捷构建器。
     /// </summary>
     public static class AudioAdaptivePlans
     {
         /// <summary>
         ///     Builds a plan that overrides combat music and optionally room and victory transitions.
+        ///     构建覆盖战斗音乐，并可选择处理房间和胜利转换的计划。
         /// </summary>
         public static AudioAdaptiveMusicPlan CombatOverride(
             AudioSource combatSource,
@@ -30,6 +32,7 @@ public static AudioAdaptiveMusicPlan CombatOverride(
         /// <summary>
         ///     Builds a plan that supplies room and combat overrides for the full run without restoring vanilla music after
         ///     combat.
+        ///     构建在整个跑局中提供房间和战斗覆盖，且战斗后不恢复原版音乐的计划。
         /// </summary>
         public static AudioAdaptiveMusicPlan FullRunOverride(
             AudioSource roomSource,

Audio/AudioChannelMode.cs

@@ -2,16 +2,19 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     How a named channel should behave when new playback arrives.
+    ///     命名通道在新播放到达时应如何处理。
     /// </summary>
     public enum AudioChannelMode
     {
         /// <summary>
         ///     Keep the existing playback and ignore the new request.
+        ///     保留现有播放并忽略新请求。
         /// </summary>
         KeepExisting = 0,
 
         /// <summary>
         ///     Stop the existing playback and replace it with the new one.
+        ///     停止现有播放并用新播放替换。
         /// </summary>
         ReplaceExisting = 1,
     }

Audio/AudioChannelRegistry.cs

@@ -5,6 +5,7 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Tracks named channels and tagged playback groups for higher-level replacement and bulk stop semantics.
+    ///     跟踪命名通道和带标签的播放组，用于更高层的替换和批量停止语义。
     /// </summary>
     public sealed class AudioChannelRegistry
     {
@@ -19,11 +20,13 @@ private AudioChannelRegistry()
 
         /// <summary>
         ///     Shared singleton registry.
+        ///     共享的单例注册表。
         /// </summary>
         public static AudioChannelRegistry Shared { get; } = new();
 
         /// <summary>
         ///     Claims a named channel for a handle, optionally replacing the currently attached playback.
+        ///     为句柄占用命名通道，并可选择替换当前附加的播放。
         /// </summary>
         public bool TryClaimChannel(string channel, IAudioHandle handle, AudioChannelMode mode, bool allowFadeOut)
         {
@@ -52,6 +55,7 @@ public bool TryClaimChannel(string channel, IAudioHandle handle, AudioChannelMod
 
         /// <summary>
         ///     Removes a handle from any named channel it currently owns.
+        ///     从句柄当前拥有的任何命名通道中移除该句柄。
         /// </summary>
         public void ReleaseChannel(IAudioHandle handle)
         {
@@ -62,6 +66,7 @@ public void ReleaseChannel(IAudioHandle handle)
 
         /// <summary>
         ///     Attaches a handle to a tag group for later bulk stop operations.
+        ///     将句柄附加到标签组，以便稍后执行批量停止操作。
         /// </summary>
         public void AttachTag(string tag, IAudioHandle handle)
         {
@@ -71,6 +76,7 @@ public void AttachTag(string tag, IAudioHandle handle)
 
         /// <summary>
         ///     Removes a handle from all tracked channels and tag groups.
+        ///     从所有已跟踪通道和标签组中移除句柄。
         /// </summary>
         public void Detach(IAudioHandle handle)
         {
@@ -81,6 +87,7 @@ public void Detach(IAudioHandle handle)
 
         /// <summary>
         ///     Stops and releases every handle attached to a tag group.
+        ///     停止并释放附加到标签组的每个句柄。
         /// </summary>
         public bool StopTag(string tag, bool allowFadeOut = true)
         {
@@ -101,6 +108,7 @@ public bool StopTag(string tag, bool allowFadeOut = true)
 
         /// <summary>
         ///     Stops and releases the handle currently attached to a named channel.
+        ///     停止并释放当前附加到命名通道的句柄。
         /// </summary>
         public bool StopChannel(string channel, bool allowFadeOut = true)
         {

Audio/AudioEventHandle.cs

@@ -4,11 +4,13 @@ namespace STS2RitsuLib.Audio
 {
     /// <summary>
     ///     Typed handle for FMOD Studio event instances.
+    ///     FMOD Studio 事件实例的类型化句柄。
     /// </summary>
     public sealed class AudioEventHandle : AudioHandleBase
     {
         /// <summary>
         ///     Initializes a typed handle for an FMOD Studio event instance.
+        ///     为 FMOD Studio 事件实例初始化类型化句柄。
         /// </summary>
         public AudioEventHandle(AudioSource source, AudioLifecycleScope scope, GodotObject? rawInstance)
             : base(source, scope, rawInstance)