From ee4adac4d1bd364e4cd75e4f7cf671c41add15bf Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 14:43:04 +0800
Subject: [PATCH 01/14] feat(animation): migrate sound binding back to onPlay

---
 spx-gui/src/models/spx/animation.test.ts | 30 ++++++++++++++++++------
 spx-gui/src/models/spx/animation.ts      |  4 +---
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/spx-gui/src/models/spx/animation.test.ts b/spx-gui/src/models/spx/animation.test.ts
index d1f80c052..eae97017d 100644
--- a/spx-gui/src/models/spx/animation.test.ts
+++ b/spx-gui/src/models/spx/animation.test.ts
@@ -1,7 +1,7 @@
 import { nextTick } from 'vue'
 import { describe, expect, it, vi } from 'vitest'
 import { delayFile } from '@/utils/test'
-import { fromText, type Files } from '../common/file'
+import { fromText, toConfig, type Files } from '../common/file'
 import { SpxProject } from './project'
 import { Sprite } from './sprite'
 import { Costume } from './costume'
@@ -130,8 +130,7 @@ describe('Animation', () => {
     expect(exportedId).toBeUndefined()
   })
 
-  // Temporary skip until goplus/spx#1574 is fixed and animation export switches back from onStart to onPlay.
-  it.skip('should export sound binding using onPlay', () => {
+  it('should export sound binding using onPlay', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
@@ -142,8 +141,7 @@ describe('Animation', () => {
     expect(config.onStart).toBeUndefined()
   })
 
-  // Temporary skip until goplus/spx#1574 is fixed and animation export switches back from onStart to onPlay.
-  it.skip('should export loop: true in onPlay when soundLoop is true', () => {
+  it('should export loop: true in onPlay when soundLoop is true', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
@@ -154,8 +152,7 @@ describe('Animation', () => {
     expect(config.onPlay).toEqual({ play: project.sounds[0].name, loop: true })
   })
 
-  // Temporary skip until goplus/spx#1574 is fixed and animation export switches back from onStart to onPlay.
-  it.skip('should load soundLoop from onPlay.loop', () => {
+  it('should load soundLoop from onPlay.loop', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const costumes = sprite.costumes
@@ -194,6 +191,25 @@ describe('Animation', () => {
     expect(animation.soundLoop).toBe(false)
   })
 
+  it('should preserve non-loop sound binding through project export and load', async () => {
+    const project = makeProject()
+    const animation = project.sprites[0].animations[0]
+    animation.setSound(project.sounds[0].id)
+    animation.setSoundLoop(false)
+
+    const { metadata, files } = await project.export()
+    const spriteConfig = (await toConfig(files['assets/sprites/MySprite/index.json']!)) as {
+      fAnimations: Record<string, { onPlay?: unknown; onStart?: unknown }>
+    }
+    expect(spriteConfig.fAnimations.default.onPlay).toEqual({ play: project.sounds[0].name, loop: false })
+    expect(spriteConfig.fAnimations.default.onStart).toBeUndefined()
+
+    const newProject = new SpxProject()
+    await newProject.load({ metadata, files })
+    expect(newProject.sprites[0].animations[0].sound).toBe(newProject.sounds[0].id)
+    expect(newProject.sprites[0].animations[0].soundLoop).toBe(false)
+  })
+
   it('should load sound binding from legacy onStart for backward compatibility', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index a29968456..3a51da3c3 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -230,9 +230,7 @@ export class Animation extends Disposable {
     }
     const soundName = sounds.find((s) => s.id === this.sound)?.name
     if (soundName != null) {
-      // Revert to legacy onStart temporarily. For details, see https://github.com/goplus/builder/issues/3172
-      // TODO: Use `onPlay` instead of `onStart` and pass loop after goplus/spx#1574 resolved and spx updated.
-      config.onStart = { play: soundName }
+      config.onPlay = { play: soundName, loop: this.soundLoop }
     }
     if (includeId) config.builder_id = this.id
     return [config, costumeConfigs, files]

From 198d6c767c02b1f69faa7cf4ef9e17b1aceff189 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 15:54:58 +0800
Subject: [PATCH 02/14] docs(animation): clarify sound loop default

---
 spx-gui/src/models/spx/animation.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index 3a51da3c3..2728383b6 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -11,7 +11,7 @@ import type { Sound } from './sound'
 type ActionConfig = {
   /** Sound name to play */
   play?: string
-  /** Whether to loop the sound; for onStart defaults to false, for onPlay defaults to true */
+  /** Whether to loop the sound; defaults to false */
   loop?: boolean
   // not supported by builder:
   costumes?: unknown

From b2ed272954ae7567607320cf078971324d8ba7ae Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 16:01:20 +0800
Subject: [PATCH 03/14] Revert "docs(animation): clarify sound loop default"

This reverts commit 6fdacde5e085e2d7b52036ee3fc7f75b98adb1fd.
---
 spx-gui/src/models/spx/animation.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index 2728383b6..3a51da3c3 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -11,7 +11,7 @@ import type { Sound } from './sound'
 type ActionConfig = {
   /** Sound name to play */
   play?: string
-  /** Whether to loop the sound; defaults to false */
+  /** Whether to loop the sound; for onStart defaults to false, for onPlay defaults to true */
   loop?: boolean
   // not supported by builder:
   costumes?: unknown

From e63ed2504fb2a0a7b6b9f48958fc69c2800b9115 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 17:28:54 +0800
Subject: [PATCH 04/14] feat(animation): choose sound playback mode

---
 .../editor/sprite/animation/SoundEditor.vue   | 40 +++++++++--
 spx-gui/src/models/spx/animation.test.ts      | 71 +++++++++----------
 spx-gui/src/models/spx/animation.ts           | 44 +++++++-----
 3 files changed, 94 insertions(+), 61 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index c140bbdcb..015e7a193 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -42,13 +42,30 @@
         </UIMenu>
       </UIDropdown>
     </ul>
+    <UIRadioGroup v-if="selected != null" v-model:value="selectedMode" class="mt-4 flex-col items-start gap-3">
+      <UIRadio :value="AnimationSoundMode.Complete">
+        {{ $t({ en: 'Play once', zh: '完整播放一次' }) }}
+      </UIRadio>
+      <UIRadio :value="AnimationSoundMode.FollowAnimation">
+        {{ $t({ en: 'Follow animation', zh: '跟随动画播放' }) }}
+      </UIRadio>
+    </UIRadioGroup>
   </UIDropdownForm>
 </template>
 
 <script setup lang="ts">
 import { ref } from 'vue'
-import type { Animation } from '@/models/spx/animation'
-import { UIDropdownForm, UIDropdown, UIMenu, UIMenuItem, UIBlockItem, UIIcon } from '@/components/ui'
+import { AnimationSoundMode, type Animation } from '@/models/spx/animation'
+import {
+  UIDropdownForm,
+  UIDropdown,
+  UIMenu,
+  UIMenuItem,
+  UIBlockItem,
+  UIIcon,
+  UIRadioGroup,
+  UIRadio
+} from '@/components/ui'
 import { useEditorCtx } from '@/components/editor/EditorContextProvider.vue'
 import SoundItem from '@/components/editor/stage/sound/SoundItem.vue'
 import { useAddAssetFromLibrary, useAddSoundFromLocalFile, useAddSoundByRecording } from '@/components/asset'
@@ -67,15 +84,21 @@ const editorCtx = useEditorCtx()
 
 const actionName = { en: 'Select sound', zh: '选择声音' }
 const selected = ref(props.animation.sound)
+const selectedMode = ref(props.animation.soundMode)
+function selectSound(sound: string) {
+  if (selected.value == null) selectedMode.value = AnimationSoundMode.Complete
+  selected.value = sound
+}
 async function handleSoundClick(sound: string) {
-  selected.value = selected.value === sound ? null : sound
+  if (selected.value === sound) selected.value = null
+  else selectSound(sound)
 }
 
 const addFromLocalFile = useAddSoundFromLocalFile()
 const handleAddFromLocalFile = useMessageHandle(
   async () => {
     const sound = await addFromLocalFile(editorCtx.project)
-    selected.value = sound.id
+    selectSound(sound.id)
   },
   {
     en: 'Failed to add sound from local file',
@@ -87,7 +110,7 @@ const addAssetFromLibrary = useAddAssetFromLibrary()
 const handleAddFromAssetLibrary = useMessageHandle(
   async () => {
     const sounds = await addAssetFromLibrary(editorCtx.project, AssetType.Sound)
-    selected.value = sounds[0].id
+    selectSound(sounds[0].id)
   },
   { en: 'Failed to add sound from asset library', zh: '从素材库添加失败' }
 ).fn
@@ -96,13 +119,16 @@ const addSoundFromRecording = useAddSoundByRecording()
 const handleRecord = useMessageHandle(
   async () => {
     const sound = await addSoundFromRecording(editorCtx.project)
-    selected.value = sound.id
+    selectSound(sound.id)
   },
   { en: 'Failed to record sound', zh: '录音失败' }
 ).fn
 
 async function handleConfirm() {
-  await editorCtx.state.history.doAction({ name: actionName }, () => props.animation.setSound(selected.value))
+  await editorCtx.state.history.doAction({ name: actionName }, () => {
+    props.animation.setSound(selected.value)
+    props.animation.setSoundMode(selectedMode.value)
+  })
   emit('close')
 }
 </script>
diff --git a/spx-gui/src/models/spx/animation.test.ts b/spx-gui/src/models/spx/animation.test.ts
index eae97017d..b26e8f360 100644
--- a/spx-gui/src/models/spx/animation.test.ts
+++ b/spx-gui/src/models/spx/animation.test.ts
@@ -6,7 +6,7 @@ import { SpxProject } from './project'
 import { Sprite } from './sprite'
 import { Costume } from './costume'
 import { Sound } from './sound'
-import { Animation } from './animation'
+import { Animation, AnimationSoundMode } from './animation'
 
 vi.mock('@/apis/aigc', async (importOriginal) => ({
   ...(await importOriginal<typeof import('@/apis/aigc')>()),
@@ -130,29 +130,30 @@ describe('Animation', () => {
     expect(exportedId).toBeUndefined()
   })
 
-  it('should export sound binding using onPlay', () => {
+  it('should export complete sound binding using onStart', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
     animation.setSound(project.sounds[0].id)
 
     const [config] = animation.export('', { sounds: project.sounds })
-    expect(config.onPlay).toEqual({ play: project.sounds[0].name, loop: false })
-    expect(config.onStart).toBeUndefined()
+    expect(config.onStart).toEqual({ play: project.sounds[0].name })
+    expect(config.onPlay).toBeUndefined()
   })
 
-  it('should export loop: true in onPlay when soundLoop is true', () => {
+  it('should export follow-animation sound binding using onPlay', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
     animation.setSound(project.sounds[0].id)
-    animation.setSoundLoop(true)
+    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
 
     const [config] = animation.export('', { sounds: project.sounds })
-    expect(config.onPlay).toEqual({ play: project.sounds[0].name, loop: true })
+    expect(config.onPlay).toEqual({ play: project.sounds[0].name })
+    expect(config.onStart).toBeUndefined()
   })
 
-  it('should load soundLoop from onPlay.loop', () => {
+  it('should load follow-animation sound mode from onPlay', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const costumes = sprite.costumes
@@ -163,16 +164,16 @@ describe('Animation', () => {
       {
         frameFrom: costumes[0].name,
         frameTo: costumes[0].name,
-        onPlay: { play: sounds[0].name, loop: true }
+        onPlay: { play: sounds[0].name }
       },
       costumes,
       { sounds }
     )
     expect(animation.sound).toBe(sounds[0].id)
-    expect(animation.soundLoop).toBe(true)
+    expect(animation.soundMode).toBe(AnimationSoundMode.FollowAnimation)
   })
 
-  it('should default soundLoop to false when loop field is absent', () => {
+  it('should load complete sound mode from onStart', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const costumes = sprite.costumes
@@ -183,64 +184,62 @@ describe('Animation', () => {
       {
         frameFrom: costumes[0].name,
         frameTo: costumes[0].name,
-        onPlay: { play: sounds[0].name }
+        onStart: { play: sounds[0].name }
       },
       costumes,
       { sounds }
     )
-    expect(animation.soundLoop).toBe(false)
+    expect(animation.soundMode).toBe(AnimationSoundMode.Complete)
   })
 
-  it('should preserve non-loop sound binding through project export and load', async () => {
+  it('should preserve complete sound binding through project export and load', async () => {
     const project = makeProject()
     const animation = project.sprites[0].animations[0]
     animation.setSound(project.sounds[0].id)
-    animation.setSoundLoop(false)
 
     const { metadata, files } = await project.export()
     const spriteConfig = (await toConfig(files['assets/sprites/MySprite/index.json']!)) as {
       fAnimations: Record<string, { onPlay?: unknown; onStart?: unknown }>
     }
-    expect(spriteConfig.fAnimations.default.onPlay).toEqual({ play: project.sounds[0].name, loop: false })
-    expect(spriteConfig.fAnimations.default.onStart).toBeUndefined()
+    expect(spriteConfig.fAnimations.default.onStart).toEqual({ play: project.sounds[0].name })
+    expect(spriteConfig.fAnimations.default.onPlay).toBeUndefined()
 
     const newProject = new SpxProject()
     await newProject.load({ metadata, files })
     expect(newProject.sprites[0].animations[0].sound).toBe(newProject.sounds[0].id)
-    expect(newProject.sprites[0].animations[0].soundLoop).toBe(false)
+    expect(newProject.sprites[0].animations[0].soundMode).toBe(AnimationSoundMode.Complete)
   })
 
-  it('should load sound binding from legacy onStart for backward compatibility', () => {
+  it('should preserve follow-animation sound binding through project export and load', async () => {
     const project = makeProject()
-    const sprite = project.sprites[0]
-    const costumes = sprite.costumes
-    const sounds = project.sounds
+    const animation = project.sprites[0].animations[0]
+    animation.setSound(project.sounds[0].id)
+    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
 
-    const [animation] = Animation.load(
-      'default',
-      {
-        frameFrom: costumes[0].name,
-        frameTo: costumes[0].name,
-        onStart: { play: sounds[0].name }
-      },
-      costumes,
-      { sounds }
-    )
-    expect(animation.sound).toBe(sounds[0].id)
-    expect(animation.soundLoop).toBe(false)
+    const { metadata, files } = await project.export()
+    const spriteConfig = (await toConfig(files['assets/sprites/MySprite/index.json']!)) as {
+      fAnimations: Record<string, { onPlay?: unknown; onStart?: unknown }>
+    }
+    expect(spriteConfig.fAnimations.default.onPlay).toEqual({ play: project.sounds[0].name })
+    expect(spriteConfig.fAnimations.default.onStart).toBeUndefined()
+
+    const newProject = new SpxProject()
+    await newProject.load({ metadata, files })
+    expect(newProject.sprites[0].animations[0].sound).toBe(newProject.sounds[0].id)
+    expect(newProject.sprites[0].animations[0].soundMode).toBe(AnimationSoundMode.FollowAnimation)
   })
 
   it('should clone well', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
-    animation.setSoundLoop(true)
+    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
     const clonedAnimation = animation.clone()
     expect(clonedAnimation.id).not.toBe(animation.id)
     expect(clonedAnimation.name).toBe(animation.name)
     expect(clonedAnimation.duration).toBe(animation.duration)
     expect(clonedAnimation.sound).toBe(animation.sound)
-    expect(clonedAnimation.soundLoop).toBe(animation.soundLoop)
+    expect(clonedAnimation.soundMode).toBe(animation.soundMode)
     expect(clonedAnimation.costumes.length).toBe(animation.costumes.length)
     for (let i = 0; i < clonedAnimation.costumes.length; i++) {
       expect(clonedAnimation.costumes[i].id).not.toBe(animation.costumes[i].id)
diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index 3a51da3c3..5bc09fdfa 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -1,11 +1,11 @@
 import { reactive } from 'vue'
+import { nanoid } from 'nanoid'
 
 import { Disposable } from '@/utils/disposable'
 import { ensureValidCostumeName, getAnimationName, validateAnimationName } from './common/asset-name'
 import type { Files } from '../common/file'
 import type { Costume, RawCostumeConfig, Pivot as CostumePivot } from './costume'
 import type { Sprite } from './sprite'
-import { nanoid } from 'nanoid'
 import type { Sound } from './sound'
 
 type ActionConfig = {
@@ -19,13 +19,17 @@ type ActionConfig = {
 
 export const defaultFps = 10
 
+export enum AnimationSoundMode {
+  Complete = 'complete',
+  FollowAnimation = 'followAnimation'
+}
+
 export type AnimationInits = {
   id?: string
   /** Duration (in seconds) for animation to be played once */
   duration?: number
   sound?: string
-  /** Whether to loop the sound; defaults to false */
-  soundLoop?: boolean
+  soundMode?: AnimationSoundMode
 }
 
 export type RawAnimationConfig = {
@@ -108,10 +112,9 @@ export class Animation extends Disposable {
     this.sound = soundId
   }
 
-  /** Whether to loop the sound when played; defaults to false */
-  soundLoop: boolean
-  setSoundLoop(loop: boolean) {
-    this.soundLoop = loop
+  soundMode: AnimationSoundMode
+  setSoundMode(mode: AnimationSoundMode) {
+    this.soundMode = mode
   }
 
   constructor(name: string, inits?: AnimationInits) {
@@ -120,7 +123,7 @@ export class Animation extends Disposable {
     this.costumes = []
     this.duration = inits?.duration ?? 0
     this.sound = inits?.sound ?? null
-    this.soundLoop = inits?.soundLoop ?? false
+    this.soundMode = inits?.soundMode ?? AnimationSoundMode.Complete
     this.id = inits?.id ?? nanoid()
 
     return reactive(this) as this
@@ -131,7 +134,7 @@ export class Animation extends Disposable {
       id: preserveId ? this.id : undefined,
       duration: this.duration,
       sound: this.sound ?? undefined,
-      soundLoop: this.soundLoop
+      soundMode: this.soundMode
     })
     const costumes = this.costumes.map((c) => c.clone(preserveId))
     animation.setCostumes(costumes)
@@ -180,22 +183,26 @@ export class Animation extends Disposable {
     if (isLoop != null) console.warn(`unsupported field: isLoop for animation ${name}`)
     if (anitype != null) console.warn(`unsupported field: anitype for animation ${name}`)
     let soundId: string | undefined = undefined
-    let soundLoop = false
-    // onPlay is the current API; onStart is legacy for backward compatibility
-    const soundName = onPlay?.play ?? onStart?.play
-    if (soundName != null) {
-      const sound = sounds.find((s) => s.name === soundName)
-      if (sound == null) console.warn(`Sound ${soundName} not found when creating animation ${name}`)
+    let soundMode = AnimationSoundMode.Complete
+    const soundBinding =
+      onPlay?.play != null
+        ? { soundName: onPlay.play, mode: AnimationSoundMode.FollowAnimation }
+        : onStart?.play != null
+          ? { soundName: onStart.play, mode: AnimationSoundMode.Complete }
+          : null
+    if (soundBinding != null) {
+      const sound = sounds.find((s) => s.name === soundBinding.soundName)
+      if (sound == null) console.warn(`Sound ${soundBinding.soundName} not found when creating animation ${name}`)
       else {
         soundId = sound.id
-        soundLoop = onPlay?.loop ?? false
+        soundMode = soundBinding.mode
       }
     }
     const animation = new Animation(name, {
       id: includeId ? id : undefined,
       duration,
       sound: soundId,
-      soundLoop
+      soundMode
     })
     const animationCostumeNames = animationCostumes.map((c) => c.name)
     for (const costume of animationCostumes) {
@@ -230,7 +237,8 @@ export class Animation extends Disposable {
     }
     const soundName = sounds.find((s) => s.id === this.sound)?.name
     if (soundName != null) {
-      config.onPlay = { play: soundName, loop: this.soundLoop }
+      if (this.soundMode === AnimationSoundMode.FollowAnimation) config.onPlay = { play: soundName }
+      else config.onStart = { play: soundName }
     }
     if (includeId) config.builder_id = this.id
     return [config, costumeConfigs, files]

From 08f1e4c397fddfe1cc6b1a893ed2dabcbfd0ffe7 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 17:51:55 +0800
Subject: [PATCH 05/14] refactor(animation): address sound mode review

---
 .../editor/sprite/animation/SoundEditor.vue   | 51 +++++++++++++++----
 spx-gui/src/models/spx/animation.ts           | 23 ++++-----
 2 files changed, 52 insertions(+), 22 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 015e7a193..71261b4ec 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -42,14 +42,44 @@
         </UIMenu>
       </UIDropdown>
     </ul>
-    <UIRadioGroup v-if="selected != null" v-model:value="selectedMode" class="mt-4 flex-col items-start gap-3">
-      <UIRadio :value="AnimationSoundMode.Complete">
-        {{ $t({ en: 'Play once', zh: '完整播放一次' }) }}
-      </UIRadio>
-      <UIRadio :value="AnimationSoundMode.FollowAnimation">
-        {{ $t({ en: 'Follow animation', zh: '跟随动画播放' }) }}
-      </UIRadio>
-    </UIRadioGroup>
+    <UIButtonGroup
+      v-if="selected != null"
+      v-radar="{
+        name: 'Animation sound playback mode control',
+        desc: 'Control to choose animation sound playback mode'
+      }"
+      type="text"
+      class="mt-4"
+      :value="selectedMode"
+      @update:value="(mode) => (selectedMode = mode as AnimationSoundMode)"
+    >
+      <UITooltip>
+        {{
+          $t({
+            en: 'Play the sound once and let it complete independently of the animation',
+            zh: '声音播放一次，并独立于动画完整播放'
+          })
+        }}
+        <template #trigger>
+          <UIButtonGroupItem :value="AnimationSoundMode.Complete">
+            {{ $t({ en: 'Play once', zh: '播放一次' }) }}
+          </UIButtonGroupItem>
+        </template>
+      </UITooltip>
+      <UITooltip>
+        {{
+          $t({
+            en: 'Play the sound with the animation and stop it when the animation stops',
+            zh: '声音跟随动画播放，并在动画停止时停止'
+          })
+        }}
+        <template #trigger>
+          <UIButtonGroupItem :value="AnimationSoundMode.FollowAnimation">
+            {{ $t({ en: 'Follow animation', zh: '跟随动画' }) }}
+          </UIButtonGroupItem>
+        </template>
+      </UITooltip>
+    </UIButtonGroup>
   </UIDropdownForm>
 </template>
 
@@ -63,8 +93,9 @@ import {
   UIMenuItem,
   UIBlockItem,
   UIIcon,
-  UIRadioGroup,
-  UIRadio
+  UIButtonGroup,
+  UIButtonGroupItem,
+  UITooltip
 } from '@/components/ui'
 import { useEditorCtx } from '@/components/editor/EditorContextProvider.vue'
 import SoundItem from '@/components/editor/stage/sound/SoundItem.vue'
diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index 5bc09fdfa..838bae034 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -11,8 +11,6 @@ import type { Sound } from './sound'
 type ActionConfig = {
   /** Sound name to play */
   play?: string
-  /** Whether to loop the sound; for onStart defaults to false, for onPlay defaults to true */
-  loop?: boolean
   // not supported by builder:
   costumes?: unknown
 }
@@ -184,18 +182,19 @@ export class Animation extends Disposable {
     if (anitype != null) console.warn(`unsupported field: anitype for animation ${name}`)
     let soundId: string | undefined = undefined
     let soundMode = AnimationSoundMode.Complete
-    const soundBinding =
-      onPlay?.play != null
-        ? { soundName: onPlay.play, mode: AnimationSoundMode.FollowAnimation }
-        : onStart?.play != null
-          ? { soundName: onStart.play, mode: AnimationSoundMode.Complete }
-          : null
-    if (soundBinding != null) {
-      const sound = sounds.find((s) => s.name === soundBinding.soundName)
-      if (sound == null) console.warn(`Sound ${soundBinding.soundName} not found when creating animation ${name}`)
+    let soundName: string | undefined = undefined
+    if (onPlay?.play != null) {
+      soundName = onPlay.play
+      soundMode = AnimationSoundMode.FollowAnimation
+    } else if (onStart?.play != null) {
+      soundName = onStart.play
+      soundMode = AnimationSoundMode.Complete
+    }
+    if (soundName != null) {
+      const sound = sounds.find((s) => s.name === soundName)
+      if (sound == null) console.warn(`Sound ${soundName} not found when creating animation ${name}`)
       else {
         soundId = sound.id
-        soundMode = soundBinding.mode
       }
     }
     const animation = new Animation(name, {

From ff7f8942b113b277314a60d8f765041c3c3757d3 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 19:47:54 +0800
Subject: [PATCH 06/14] style(animation): clarify sound behavior control

---
 .../editor/sprite/animation/SoundEditor.vue   | 79 ++++++++++---------
 1 file changed, 41 insertions(+), 38 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 71261b4ec..21eb0ec6b 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -42,44 +42,47 @@
         </UIMenu>
       </UIDropdown>
     </ul>
-    <UIButtonGroup
-      v-if="selected != null"
-      v-radar="{
-        name: 'Animation sound playback mode control',
-        desc: 'Control to choose animation sound playback mode'
-      }"
-      type="text"
-      class="mt-4"
-      :value="selectedMode"
-      @update:value="(mode) => (selectedMode = mode as AnimationSoundMode)"
-    >
-      <UITooltip>
-        {{
-          $t({
-            en: 'Play the sound once and let it complete independently of the animation',
-            zh: '声音播放一次，并独立于动画完整播放'
-          })
-        }}
-        <template #trigger>
-          <UIButtonGroupItem :value="AnimationSoundMode.Complete">
-            {{ $t({ en: 'Play once', zh: '播放一次' }) }}
-          </UIButtonGroupItem>
-        </template>
-      </UITooltip>
-      <UITooltip>
-        {{
-          $t({
-            en: 'Play the sound with the animation and stop it when the animation stops',
-            zh: '声音跟随动画播放，并在动画停止时停止'
-          })
-        }}
-        <template #trigger>
-          <UIButtonGroupItem :value="AnimationSoundMode.FollowAnimation">
-            {{ $t({ en: 'Follow animation', zh: '跟随动画' }) }}
-          </UIButtonGroupItem>
-        </template>
-      </UITooltip>
-    </UIButtonGroup>
+    <div v-if="selected != null" class="mt-4 flex items-center justify-between gap-3 border-t border-grey-400 pt-3">
+      <span class="flex-none text-xs font-medium text-grey-800">
+        {{ $t({ en: 'Sound behavior', zh: '声音方式' }) }}
+      </span>
+      <UIButtonGroup
+        v-radar="{
+          name: 'Animation sound playback mode control',
+          desc: 'Control to choose animation sound playback mode'
+        }"
+        type="text"
+        :value="selectedMode"
+        @update:value="(mode) => (selectedMode = mode as AnimationSoundMode)"
+      >
+        <UITooltip>
+          {{
+            $t({
+              en: 'Play the sound once and let it complete independently of the animation',
+              zh: '声音播放一次，并独立于动画完整播放'
+            })
+          }}
+          <template #trigger>
+            <UIButtonGroupItem :value="AnimationSoundMode.Complete">
+              {{ $t({ en: 'Play once', zh: '播放一次' }) }}
+            </UIButtonGroupItem>
+          </template>
+        </UITooltip>
+        <UITooltip>
+          {{
+            $t({
+              en: 'Play the sound with the animation and stop it when the animation stops',
+              zh: '声音跟随动画播放，并在动画停止时停止'
+            })
+          }}
+          <template #trigger>
+            <UIButtonGroupItem :value="AnimationSoundMode.FollowAnimation">
+              {{ $t({ en: 'Follow animation', zh: '跟随动画' }) }}
+            </UIButtonGroupItem>
+          </template>
+        </UITooltip>
+      </UIButtonGroup>
+    </div>
   </UIDropdownForm>
 </template>
 

From de8fc2b6032faf0e1bd89a10b84790b6e2d131b6 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Mon, 25 May 2026 19:53:45 +0800
Subject: [PATCH 07/14] style(animation): keep sound behavior control stable

---
 spx-gui/src/components/editor/sprite/animation/SoundEditor.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 21eb0ec6b..1a8320900 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -42,7 +42,7 @@
         </UIMenu>
       </UIDropdown>
     </ul>
-    <div v-if="selected != null" class="mt-4 flex items-center justify-between gap-3 border-t border-grey-400 pt-3">
+    <div class="mt-4 flex items-center justify-between gap-3 border-t border-grey-400 pt-3">
       <span class="flex-none text-xs font-medium text-grey-800">
         {{ $t({ en: 'Sound behavior', zh: '声音方式' }) }}
       </span>

From 80c1f4931dc453a1b397432dc14cbfce2693219f Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Tue, 26 May 2026 08:49:53 +0800
Subject: [PATCH 08/14] copy(animation): clarify looping sound behavior

---
 .../src/components/editor/sprite/animation/SoundEditor.vue  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 1a8320900..365cc5907 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -71,13 +71,13 @@
         <UITooltip>
           {{
             $t({
-              en: 'Play the sound with the animation and stop it when the animation stops',
-              zh: '声音跟随动画播放，并在动画停止时停止'
+              en: 'Loop the sound during each animation playback and stop it when the animation stops',
+              zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
             })
           }}
           <template #trigger>
             <UIButtonGroupItem :value="AnimationSoundMode.FollowAnimation">
-              {{ $t({ en: 'Follow animation', zh: '跟随动画' }) }}
+              {{ $t({ en: 'Loop with animation', zh: '随动画循环' }) }}
             </UIButtonGroupItem>
           </template>
         </UITooltip>

From 3e816f3113a99f70eb50fd303e1deab0aaed0c5f Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 11:25:48 +0800
Subject: [PATCH 09/14] style(animation): match sound playback selector UI

---
 .../editor/sprite/animation/SoundEditor.vue   | 90 ++++++++++---------
 spx-gui/src/components/ui/UIDropdownForm.vue  | 35 ++++----
 2 files changed, 68 insertions(+), 57 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 365cc5907..c2ea1b0c9 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -2,11 +2,11 @@
   <UIDropdownForm
     v-radar="{ name: 'Sound editor dropdown form', desc: 'Dropdown form for selecting animation sound' }"
     :title="$t(actionName)"
-    style="width: 320px; max-height: 400px"
+    style="width: 408px; max-height: 400px"
     @cancel="emit('close')"
     @confirm="handleConfirm"
   >
-    <ul class="flex-[1_1_0] flex flex-wrap content-start gap-3">
+    <ul class="flex-[1_1_0] flex flex-wrap content-start gap-2">
       <SoundItem
         v-for="sound in editorCtx.project.sounds"
         :key="sound.id"
@@ -42,52 +42,40 @@
         </UIMenu>
       </UIDropdown>
     </ul>
-    <div class="mt-4 flex items-center justify-between gap-3 border-t border-grey-400 pt-3">
-      <span class="flex-none text-xs font-medium text-grey-800">
-        {{ $t({ en: 'Sound behavior', zh: '声音方式' }) }}
-      </span>
-      <UIButtonGroup
-        v-radar="{
-          name: 'Animation sound playback mode control',
-          desc: 'Control to choose animation sound playback mode'
-        }"
-        type="text"
-        :value="selectedMode"
-        @update:value="(mode) => (selectedMode = mode as AnimationSoundMode)"
-      >
+    <template #footer-left>
+      <div class="flex h-8 items-center gap-2">
+        <span class="text-base text-grey-900">
+          {{ $t({ en: 'Playback', zh: '播放' }) }}
+        </span>
         <UITooltip>
-          {{
-            $t({
-              en: 'Play the sound once and let it complete independently of the animation',
-              zh: '声音播放一次，并独立于动画完整播放'
-            })
-          }}
+          {{ $t(playbackTooltip) }}
           <template #trigger>
-            <UIButtonGroupItem :value="AnimationSoundMode.Complete">
-              {{ $t({ en: 'Play once', zh: '播放一次' }) }}
-            </UIButtonGroupItem>
+            <UISelect
+              v-radar="{
+                name: 'Animation sound playback selector',
+                desc: 'Select how the selected sound plays with the animation'
+              }"
+              :value="selectedMode"
+              :disabled="selected == null"
+              class="min-w-[80px]"
+              @update:value="handlePlaybackUpdate"
+            >
+              <UISelectOption :value="AnimationSoundMode.Complete">
+                {{ $t({ en: 'One', zh: '一次' }) }}
+              </UISelectOption>
+              <UISelectOption :value="AnimationSoundMode.FollowAnimation">
+                {{ $t({ en: 'Loop', zh: '循环' }) }}
+              </UISelectOption>
+            </UISelect>
           </template>
         </UITooltip>
-        <UITooltip>
-          {{
-            $t({
-              en: 'Loop the sound during each animation playback and stop it when the animation stops',
-              zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
-            })
-          }}
-          <template #trigger>
-            <UIButtonGroupItem :value="AnimationSoundMode.FollowAnimation">
-              {{ $t({ en: 'Loop with animation', zh: '随动画循环' }) }}
-            </UIButtonGroupItem>
-          </template>
-        </UITooltip>
-      </UIButtonGroup>
-    </div>
+      </div>
+    </template>
   </UIDropdownForm>
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { AnimationSoundMode, type Animation } from '@/models/spx/animation'
 import {
   UIDropdownForm,
@@ -96,8 +84,8 @@ import {
   UIMenuItem,
   UIBlockItem,
   UIIcon,
-  UIButtonGroup,
-  UIButtonGroupItem,
+  UISelect,
+  UISelectOption,
   UITooltip
 } from '@/components/ui'
 import { useEditorCtx } from '@/components/editor/EditorContextProvider.vue'
@@ -119,10 +107,28 @@ const editorCtx = useEditorCtx()
 const actionName = { en: 'Select sound', zh: '选择声音' }
 const selected = ref(props.animation.sound)
 const selectedMode = ref(props.animation.soundMode)
+const playbackTooltip = computed(() =>
+  selectedMode.value === AnimationSoundMode.FollowAnimation
+    ? {
+        en: 'Loop the sound during each animation playback and stop it when the animation stops',
+        zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
+      }
+    : {
+        en: 'Play the sound once and let it complete independently of the animation',
+        zh: '声音播放一次，并独立于动画完整播放'
+      }
+)
+
 function selectSound(sound: string) {
   if (selected.value == null) selectedMode.value = AnimationSoundMode.Complete
   selected.value = sound
 }
+
+function handlePlaybackUpdate(mode: string | null) {
+  if (mode !== AnimationSoundMode.Complete && mode !== AnimationSoundMode.FollowAnimation) return
+  selectedMode.value = mode
+}
+
 async function handleSoundClick(sound: string) {
   if (selected.value === sound) selected.value = null
   else selectSound(sound)
diff --git a/spx-gui/src/components/ui/UIDropdownForm.vue b/spx-gui/src/components/ui/UIDropdownForm.vue
index f2273a4c9..11b9c8238 100644
--- a/spx-gui/src/components/ui/UIDropdownForm.vue
+++ b/spx-gui/src/components/ui/UIDropdownForm.vue
@@ -14,21 +14,26 @@
     <main class="flex-auto min-h-0 overflow-y-auto px-4 py-3">
       <slot></slot>
     </main>
-    <footer class="flex-none flex justify-end gap-3 p-4">
-      <UIButton
-        v-radar="{ name: 'Cancel button', desc: 'Click to cancel the operation in dropdown' }"
-        type="neutral"
-        @click="emit('cancel')"
-      >
-        {{ $t({ en: 'Cancel', zh: '取消' }) }}
-      </UIButton>
-      <UIButton
-        v-radar="{ name: 'Confirm button', desc: 'Click to submit the dropdown' }"
-        type="primary"
-        html-type="submit"
-      >
-        {{ $t({ en: 'Confirm', zh: '确认' }) }}
-      </UIButton>
+    <footer class="flex-none flex items-center justify-between gap-3 p-4">
+      <div class="min-w-0 flex items-center">
+        <slot name="footer-left"></slot>
+      </div>
+      <div class="flex justify-end gap-3">
+        <UIButton
+          v-radar="{ name: 'Cancel button', desc: 'Click to cancel the operation in dropdown' }"
+          type="neutral"
+          @click="emit('cancel')"
+        >
+          {{ $t({ en: 'Cancel', zh: '取消' }) }}
+        </UIButton>
+        <UIButton
+          v-radar="{ name: 'Confirm button', desc: 'Click to submit the dropdown' }"
+          type="primary"
+          html-type="submit"
+        >
+          {{ $t({ en: 'Confirm', zh: '确认' }) }}
+        </UIButton>
+      </div>
     </footer>
   </form>
 </template>

From c97a5fe9e541d722e1f34d3abfb51968ea26236c Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 11:36:32 +0800
Subject: [PATCH 10/14] copy(animation): refine playback selector text

---
 .../editor/sprite/animation/SoundEditor.vue   | 29 ++++++++++---------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index c2ea1b0c9..7d47ef812 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -48,7 +48,19 @@
           {{ $t({ en: 'Playback', zh: '播放' }) }}
         </span>
         <UITooltip>
-          {{ $t(playbackTooltip) }}
+          {{
+            $t(
+              selectedMode === AnimationSoundMode.FollowAnimation
+                ? {
+                    en: 'Loop the sound during each animation playback and stop it when the animation stops',
+                    zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
+                  }
+                : {
+                    en: 'Play the sound once and let it complete independently of the animation',
+                    zh: '声音播放一次，并独立于动画完整播放'
+                  }
+            )
+          }}
           <template #trigger>
             <UISelect
               v-radar="{
@@ -61,7 +73,7 @@
               @update:value="handlePlaybackUpdate"
             >
               <UISelectOption :value="AnimationSoundMode.Complete">
-                {{ $t({ en: 'One', zh: '一次' }) }}
+                {{ $t({ en: 'Once', zh: '一次' }) }}
               </UISelectOption>
               <UISelectOption :value="AnimationSoundMode.FollowAnimation">
                 {{ $t({ en: 'Loop', zh: '循环' }) }}
@@ -75,7 +87,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import { AnimationSoundMode, type Animation } from '@/models/spx/animation'
 import {
   UIDropdownForm,
@@ -107,17 +119,6 @@ const editorCtx = useEditorCtx()
 const actionName = { en: 'Select sound', zh: '选择声音' }
 const selected = ref(props.animation.sound)
 const selectedMode = ref(props.animation.soundMode)
-const playbackTooltip = computed(() =>
-  selectedMode.value === AnimationSoundMode.FollowAnimation
-    ? {
-        en: 'Loop the sound during each animation playback and stop it when the animation stops',
-        zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
-      }
-    : {
-        en: 'Play the sound once and let it complete independently of the animation',
-        zh: '声音播放一次，并独立于动画完整播放'
-      }
-)
 
 function selectSound(sound: string) {
   if (selected.value == null) selectedMode.value = AnimationSoundMode.Complete

From 88cb735697079c2646bce55cfb564c17456ea244 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 11:45:19 +0800
Subject: [PATCH 11/14] refactor(animation): rename sound playback model

---
 .../editor/sprite/animation/SoundEditor.vue   | 22 +++++++-------
 spx-gui/src/models/spx/animation.test.ts      | 30 +++++++++----------
 spx-gui/src/models/spx/animation.ts           | 30 ++++++++++---------
 3 files changed, 42 insertions(+), 40 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 7d47ef812..1da52ad1d 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -50,7 +50,7 @@
         <UITooltip>
           {{
             $t(
-              selectedMode === AnimationSoundMode.FollowAnimation
+              selectedPlayback === AnimationSoundPlayback.Loop
                 ? {
                     en: 'Loop the sound during each animation playback and stop it when the animation stops',
                     zh: '声音在动画的单次播放周期内循环播放，并在动画停止时停止'
@@ -67,15 +67,15 @@
                 name: 'Animation sound playback selector',
                 desc: 'Select how the selected sound plays with the animation'
               }"
-              :value="selectedMode"
+              :value="selectedPlayback"
               :disabled="selected == null"
               class="min-w-[80px]"
               @update:value="handlePlaybackUpdate"
             >
-              <UISelectOption :value="AnimationSoundMode.Complete">
+              <UISelectOption :value="AnimationSoundPlayback.Once">
                 {{ $t({ en: 'Once', zh: '一次' }) }}
               </UISelectOption>
-              <UISelectOption :value="AnimationSoundMode.FollowAnimation">
+              <UISelectOption :value="AnimationSoundPlayback.Loop">
                 {{ $t({ en: 'Loop', zh: '循环' }) }}
               </UISelectOption>
             </UISelect>
@@ -88,7 +88,7 @@
 
 <script setup lang="ts">
 import { ref } from 'vue'
-import { AnimationSoundMode, type Animation } from '@/models/spx/animation'
+import { AnimationSoundPlayback, type Animation } from '@/models/spx/animation'
 import {
   UIDropdownForm,
   UIDropdown,
@@ -118,16 +118,16 @@ const editorCtx = useEditorCtx()
 
 const actionName = { en: 'Select sound', zh: '选择声音' }
 const selected = ref(props.animation.sound)
-const selectedMode = ref(props.animation.soundMode)
+const selectedPlayback = ref(props.animation.soundPlayback)
 
 function selectSound(sound: string) {
-  if (selected.value == null) selectedMode.value = AnimationSoundMode.Complete
+  if (selected.value == null) selectedPlayback.value = AnimationSoundPlayback.Once
   selected.value = sound
 }
 
-function handlePlaybackUpdate(mode: string | null) {
-  if (mode !== AnimationSoundMode.Complete && mode !== AnimationSoundMode.FollowAnimation) return
-  selectedMode.value = mode
+function handlePlaybackUpdate(playback: string | null) {
+  if (playback !== AnimationSoundPlayback.Once && playback !== AnimationSoundPlayback.Loop) return
+  selectedPlayback.value = playback
 }
 
 async function handleSoundClick(sound: string) {
@@ -168,7 +168,7 @@ const handleRecord = useMessageHandle(
 async function handleConfirm() {
   await editorCtx.state.history.doAction({ name: actionName }, () => {
     props.animation.setSound(selected.value)
-    props.animation.setSoundMode(selectedMode.value)
+    props.animation.setSoundPlayback(selectedPlayback.value)
   })
   emit('close')
 }
diff --git a/spx-gui/src/models/spx/animation.test.ts b/spx-gui/src/models/spx/animation.test.ts
index b26e8f360..1b6339009 100644
--- a/spx-gui/src/models/spx/animation.test.ts
+++ b/spx-gui/src/models/spx/animation.test.ts
@@ -6,7 +6,7 @@ import { SpxProject } from './project'
 import { Sprite } from './sprite'
 import { Costume } from './costume'
 import { Sound } from './sound'
-import { Animation, AnimationSoundMode } from './animation'
+import { Animation, AnimationSoundPlayback } from './animation'
 
 vi.mock('@/apis/aigc', async (importOriginal) => ({
   ...(await importOriginal<typeof import('@/apis/aigc')>()),
@@ -130,7 +130,7 @@ describe('Animation', () => {
     expect(exportedId).toBeUndefined()
   })
 
-  it('should export complete sound binding using onStart', () => {
+  it('should export once sound playback using onStart', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
@@ -141,19 +141,19 @@ describe('Animation', () => {
     expect(config.onPlay).toBeUndefined()
   })
 
-  it('should export follow-animation sound binding using onPlay', () => {
+  it('should export loop sound playback using onPlay', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
     animation.setSound(project.sounds[0].id)
-    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
+    animation.setSoundPlayback(AnimationSoundPlayback.Loop)
 
     const [config] = animation.export('', { sounds: project.sounds })
     expect(config.onPlay).toEqual({ play: project.sounds[0].name })
     expect(config.onStart).toBeUndefined()
   })
 
-  it('should load follow-animation sound mode from onPlay', () => {
+  it('should load loop sound playback from onPlay', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const costumes = sprite.costumes
@@ -170,10 +170,10 @@ describe('Animation', () => {
       { sounds }
     )
     expect(animation.sound).toBe(sounds[0].id)
-    expect(animation.soundMode).toBe(AnimationSoundMode.FollowAnimation)
+    expect(animation.soundPlayback).toBe(AnimationSoundPlayback.Loop)
   })
 
-  it('should load complete sound mode from onStart', () => {
+  it('should load once sound playback from onStart', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const costumes = sprite.costumes
@@ -189,10 +189,10 @@ describe('Animation', () => {
       costumes,
       { sounds }
     )
-    expect(animation.soundMode).toBe(AnimationSoundMode.Complete)
+    expect(animation.soundPlayback).toBe(AnimationSoundPlayback.Once)
   })
 
-  it('should preserve complete sound binding through project export and load', async () => {
+  it('should preserve once sound playback through project export and load', async () => {
     const project = makeProject()
     const animation = project.sprites[0].animations[0]
     animation.setSound(project.sounds[0].id)
@@ -207,14 +207,14 @@ describe('Animation', () => {
     const newProject = new SpxProject()
     await newProject.load({ metadata, files })
     expect(newProject.sprites[0].animations[0].sound).toBe(newProject.sounds[0].id)
-    expect(newProject.sprites[0].animations[0].soundMode).toBe(AnimationSoundMode.Complete)
+    expect(newProject.sprites[0].animations[0].soundPlayback).toBe(AnimationSoundPlayback.Once)
   })
 
-  it('should preserve follow-animation sound binding through project export and load', async () => {
+  it('should preserve loop sound playback through project export and load', async () => {
     const project = makeProject()
     const animation = project.sprites[0].animations[0]
     animation.setSound(project.sounds[0].id)
-    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
+    animation.setSoundPlayback(AnimationSoundPlayback.Loop)
 
     const { metadata, files } = await project.export()
     const spriteConfig = (await toConfig(files['assets/sprites/MySprite/index.json']!)) as {
@@ -226,20 +226,20 @@ describe('Animation', () => {
     const newProject = new SpxProject()
     await newProject.load({ metadata, files })
     expect(newProject.sprites[0].animations[0].sound).toBe(newProject.sounds[0].id)
-    expect(newProject.sprites[0].animations[0].soundMode).toBe(AnimationSoundMode.FollowAnimation)
+    expect(newProject.sprites[0].animations[0].soundPlayback).toBe(AnimationSoundPlayback.Loop)
   })
 
   it('should clone well', () => {
     const project = makeProject()
     const sprite = project.sprites[0]
     const animation = sprite.animations[0]
-    animation.setSoundMode(AnimationSoundMode.FollowAnimation)
+    animation.setSoundPlayback(AnimationSoundPlayback.Loop)
     const clonedAnimation = animation.clone()
     expect(clonedAnimation.id).not.toBe(animation.id)
     expect(clonedAnimation.name).toBe(animation.name)
     expect(clonedAnimation.duration).toBe(animation.duration)
     expect(clonedAnimation.sound).toBe(animation.sound)
-    expect(clonedAnimation.soundMode).toBe(animation.soundMode)
+    expect(clonedAnimation.soundPlayback).toBe(animation.soundPlayback)
     expect(clonedAnimation.costumes.length).toBe(animation.costumes.length)
     for (let i = 0; i < clonedAnimation.costumes.length; i++) {
       expect(clonedAnimation.costumes[i].id).not.toBe(animation.costumes[i].id)
diff --git a/spx-gui/src/models/spx/animation.ts b/spx-gui/src/models/spx/animation.ts
index 838bae034..1b3abadc7 100644
--- a/spx-gui/src/models/spx/animation.ts
+++ b/spx-gui/src/models/spx/animation.ts
@@ -17,9 +17,11 @@ type ActionConfig = {
 
 export const defaultFps = 10
 
-export enum AnimationSoundMode {
-  Complete = 'complete',
-  FollowAnimation = 'followAnimation'
+export enum AnimationSoundPlayback {
+  /** Play once and let the sound complete independently of the animation. */
+  Once = 'once',
+  /** Loop during each animation playback and stop when the animation stops. */
+  Loop = 'loop'
 }
 
 export type AnimationInits = {
@@ -27,7 +29,7 @@ export type AnimationInits = {
   /** Duration (in seconds) for animation to be played once */
   duration?: number
   sound?: string
-  soundMode?: AnimationSoundMode
+  soundPlayback?: AnimationSoundPlayback
 }
 
 export type RawAnimationConfig = {
@@ -110,9 +112,9 @@ export class Animation extends Disposable {
     this.sound = soundId
   }
 
-  soundMode: AnimationSoundMode
-  setSoundMode(mode: AnimationSoundMode) {
-    this.soundMode = mode
+  soundPlayback: AnimationSoundPlayback
+  setSoundPlayback(playback: AnimationSoundPlayback) {
+    this.soundPlayback = playback
   }
 
   constructor(name: string, inits?: AnimationInits) {
@@ -121,7 +123,7 @@ export class Animation extends Disposable {
     this.costumes = []
     this.duration = inits?.duration ?? 0
     this.sound = inits?.sound ?? null
-    this.soundMode = inits?.soundMode ?? AnimationSoundMode.Complete
+    this.soundPlayback = inits?.soundPlayback ?? AnimationSoundPlayback.Once
     this.id = inits?.id ?? nanoid()
 
     return reactive(this) as this
@@ -132,7 +134,7 @@ export class Animation extends Disposable {
       id: preserveId ? this.id : undefined,
       duration: this.duration,
       sound: this.sound ?? undefined,
-      soundMode: this.soundMode
+      soundPlayback: this.soundPlayback
     })
     const costumes = this.costumes.map((c) => c.clone(preserveId))
     animation.setCostumes(costumes)
@@ -181,14 +183,14 @@ export class Animation extends Disposable {
     if (isLoop != null) console.warn(`unsupported field: isLoop for animation ${name}`)
     if (anitype != null) console.warn(`unsupported field: anitype for animation ${name}`)
     let soundId: string | undefined = undefined
-    let soundMode = AnimationSoundMode.Complete
+    let soundPlayback = AnimationSoundPlayback.Once
     let soundName: string | undefined = undefined
     if (onPlay?.play != null) {
       soundName = onPlay.play
-      soundMode = AnimationSoundMode.FollowAnimation
+      soundPlayback = AnimationSoundPlayback.Loop
     } else if (onStart?.play != null) {
       soundName = onStart.play
-      soundMode = AnimationSoundMode.Complete
+      soundPlayback = AnimationSoundPlayback.Once
     }
     if (soundName != null) {
       const sound = sounds.find((s) => s.name === soundName)
@@ -201,7 +203,7 @@ export class Animation extends Disposable {
       id: includeId ? id : undefined,
       duration,
       sound: soundId,
-      soundMode
+      soundPlayback
     })
     const animationCostumeNames = animationCostumes.map((c) => c.name)
     for (const costume of animationCostumes) {
@@ -236,7 +238,7 @@ export class Animation extends Disposable {
     }
     const soundName = sounds.find((s) => s.id === this.sound)?.name
     if (soundName != null) {
-      if (this.soundMode === AnimationSoundMode.FollowAnimation) config.onPlay = { play: soundName }
+      if (this.soundPlayback === AnimationSoundPlayback.Loop) config.onPlay = { play: soundName }
       else config.onStart = { play: soundName }
     }
     if (includeId) config.builder_id = this.id

From 60fc41164ae0d1c108218d46b4e558ef06e9a450 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 11:56:23 +0800
Subject: [PATCH 12/14] refactor(animation): simplify sound selection state

---
 .../editor/sprite/animation/SoundEditor.vue         | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 1da52ad1d..8f6b0805c 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -120,11 +120,6 @@ const actionName = { en: 'Select sound', zh: '选择声音' }
 const selected = ref(props.animation.sound)
 const selectedPlayback = ref(props.animation.soundPlayback)
 
-function selectSound(sound: string) {
-  if (selected.value == null) selectedPlayback.value = AnimationSoundPlayback.Once
-  selected.value = sound
-}
-
 function handlePlaybackUpdate(playback: string | null) {
   if (playback !== AnimationSoundPlayback.Once && playback !== AnimationSoundPlayback.Loop) return
   selectedPlayback.value = playback
@@ -132,14 +127,14 @@ function handlePlaybackUpdate(playback: string | null) {
 
 async function handleSoundClick(sound: string) {
   if (selected.value === sound) selected.value = null
-  else selectSound(sound)
+  else selected.value = sound
 }
 
 const addFromLocalFile = useAddSoundFromLocalFile()
 const handleAddFromLocalFile = useMessageHandle(
   async () => {
     const sound = await addFromLocalFile(editorCtx.project)
-    selectSound(sound.id)
+    selected.value = sound.id
   },
   {
     en: 'Failed to add sound from local file',
@@ -151,7 +146,7 @@ const addAssetFromLibrary = useAddAssetFromLibrary()
 const handleAddFromAssetLibrary = useMessageHandle(
   async () => {
     const sounds = await addAssetFromLibrary(editorCtx.project, AssetType.Sound)
-    selectSound(sounds[0].id)
+    selected.value = sounds[0].id
   },
   { en: 'Failed to add sound from asset library', zh: '从素材库添加失败' }
 ).fn
@@ -160,7 +155,7 @@ const addSoundFromRecording = useAddSoundByRecording()
 const handleRecord = useMessageHandle(
   async () => {
     const sound = await addSoundFromRecording(editorCtx.project)
-    selectSound(sound.id)
+    selected.value = sound.id
   },
   { en: 'Failed to record sound', zh: '录音失败' }
 ).fn

From c2cf1bf8ece18a35ed043e1b2edd208220e5224c Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 12:25:54 +0800
Subject: [PATCH 13/14] style(animation): hide playback selector without sound

---
 spx-gui/src/components/editor/sprite/animation/SoundEditor.vue | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
index 8f6b0805c..cd6addfae 100644
--- a/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
+++ b/spx-gui/src/components/editor/sprite/animation/SoundEditor.vue
@@ -43,7 +43,7 @@
       </UIDropdown>
     </ul>
     <template #footer-left>
-      <div class="flex h-8 items-center gap-2">
+      <div v-if="selected != null" class="flex h-8 items-center gap-2">
         <span class="text-base text-grey-900">
           {{ $t({ en: 'Playback', zh: '播放' }) }}
         </span>
@@ -68,7 +68,6 @@
                 desc: 'Select how the selected sound plays with the animation'
               }"
               :value="selectedPlayback"
-              :disabled="selected == null"
               class="min-w-[80px]"
               @update:value="handlePlaybackUpdate"
             >

From d8e43b422c688ce6cafda9e793003e6b205e6653 Mon Sep 17 00:00:00 2001
From: nighca <nighca@live.cn>
Date: Thu, 28 May 2026 15:31:44 +0800
Subject: [PATCH 14/14] feat(animation): add sound playback options to
 AnimationPlayer

---
 .../editor/sprite/AnimationDetail.vue         |   1 +
 .../sprite/animation/AnimationPlayer.vue      | 112 ++++++++++++++----
 2 files changed, 87 insertions(+), 26 deletions(-)

diff --git a/spx-gui/src/components/editor/sprite/AnimationDetail.vue b/spx-gui/src/components/editor/sprite/AnimationDetail.vue
index 628d5cd3e..e4a81a65c 100644
--- a/spx-gui/src/components/editor/sprite/AnimationDetail.vue
+++ b/spx-gui/src/components/editor/sprite/AnimationDetail.vue
@@ -3,6 +3,7 @@
     <AnimationPlayer
       :costumes="animation.costumes"
       :sound="sound"
+      :sound-playback="animation.soundPlayback"
       :duration="animation.duration"
       class="w-full flex-[1_1_0]"
     />
diff --git a/spx-gui/src/components/editor/sprite/animation/AnimationPlayer.vue b/spx-gui/src/components/editor/sprite/animation/AnimationPlayer.vue
index e439126c4..22fd41ed4 100644
--- a/spx-gui/src/components/editor/sprite/animation/AnimationPlayer.vue
+++ b/spx-gui/src/components/editor/sprite/animation/AnimationPlayer.vue
@@ -14,6 +14,7 @@ import { onUnmounted, ref, watchEffect } from 'vue'
 import { registerPlayer as registerAudioPlayer } from '@/utils/player-registry'
 import { useActivated } from '@/utils/utils'
 import { Cancelled, capture } from '@/utils/exception'
+import { AnimationSoundPlayback } from '@/models/spx/animation'
 import type { Costume } from '@/models/spx/costume'
 import type { Sound } from '@/models/spx/sound'
 import { UILoading } from '@/components/ui'
@@ -21,19 +22,27 @@ import CostumesPlayer from '@/components/common/CostumesPlayer.vue'
 import CheckerboardBackground from '../CheckerboardBackground.vue'
 import MuteSwitch from './MuteSwitch.vue'
 
-const props = defineProps<{
-  costumes: Costume[]
-  sound: Sound | null
-  duration: number
-}>()
+const props = withDefaults(
+  defineProps<{
+    costumes: Costume[]
+    sound: Sound | null
+    soundPlayback?: AnimationSoundPlayback
+    duration: number
+  }>(),
+  {
+    soundPlayback: AnimationSoundPlayback.Once
+  }
+)
 
 const registered = registerAudioPlayer(() => setMuted(true))
-const audioRef = ref<HTMLAudioElement | null>(null)
+const audios = new Set<HTMLAudioElement>()
 const mutedRef = ref(true)
 function setMuted(muted: boolean) {
   mutedRef.value = muted
-  if (audioRef.value != null) {
-    audioRef.value.muted = muted
+  for (const audio of audios) {
+    audio.muted = muted
+  }
+  if (props.sound != null) {
     if (muted) registered.onStopped()
     else registered.onStart()
   }
@@ -50,25 +59,70 @@ async function loadAudio(sound: Sound, signal: AbortSignal) {
   return audio
 }
 
-function playAudio(audio: HTMLAudioElement, duration: number, signal: AbortSignal) {
-  audio.muted = mutedRef.value
-  audioRef.value = audio
-  const playFromStart = () => {
-    try {
-      audio.currentTime = 0
-      audio.play()
-    } catch {
-      // We can get an error from `play()` if the sound is not loaded yet
-      // or if the sound is not allowed to play
-    }
+// Limit the number of concurrently playing audio instances to prevent overwhelming the browser and causing performance issues or crashes.
+const concurrentAudioLimit = 10
+
+/**
+ * Play the audio with `playback: AnimationSoundPlayback.Once`.
+ * The sound is triggered once per animation cycle (duration).
+ * If the previous sound is still playing when the next cycle starts, it will keep playing.
+ * In that case, multiple sound instances can overlap.
+ */
+function playAudioWithPlaybackOnce(audio: HTMLAudioElement, duration: number, signal: AbortSignal) {
+  function playOnce() {
+    // Create a new audio element to play the sound so it plays independently
+    const newAudio = new Audio(audio.src)
+    newAudio.muted = mutedRef.value
+    audios.add(newAudio)
+    newAudio.addEventListener('ended', () => audios.delete(newAudio), { once: true })
+    signal.addEventListener(
+      'abort',
+      () => {
+        newAudio.pause()
+        audios.delete(newAudio)
+      },
+      { once: true }
+    )
+    setTimeout(
+      () => {
+        // Stop the newAudio after some time to prevent too many overlapping audios
+        newAudio.pause()
+        audios.delete(newAudio)
+      },
+      duration * 1000 * concurrentAudioLimit
+    )
+    newAudio.play()
   }
+  playOnce()
+  const timer = setInterval(playOnce, duration * 1000)
+  signal.addEventListener('abort', () => clearInterval(timer), { once: true })
+}
+
+/**
+ * Play the audio with `playback: AnimationSoundPlayback.Loop`.
+ * The sound loops continuously within each animation cycle.
+ * When a new cycle starts, playback is reset to the beginning.
+ * This prevents overlapping between cycles.
+ */
+function playAudioWithPlaybackLoop(audio: HTMLAudioElement, duration: number, signal: AbortSignal) {
+  function playFromStart() {
+    audio.currentTime = 0
+    audio.play()
+  }
+  audio.loop = true
+  audio.muted = mutedRef.value
+  audios.add(audio)
+  signal.addEventListener(
+    'abort',
+    () => {
+      audio.pause()
+      audios.delete(audio)
+    },
+    { once: true }
+  )
   playFromStart()
   const timer = setInterval(playFromStart, duration * 1000)
-  signal.addEventListener('abort', async () => {
-    clearInterval(timer)
-    audio.pause()
-    audioRef.value = null
-  })
+  signal.addEventListener('abort', () => clearInterval(timer), { once: true })
 }
 
 const activatedRef = useActivated()
@@ -93,7 +147,7 @@ watchEffect(async () => {
   if (costumesPlayer == null) return
   try {
     const signal = ctrl.signal
-    const { costumes, sound, duration } = props
+    const { costumes, sound, soundPlayback, duration } = props
     const [, audio] = await Promise.all([
       costumesPlayer.load(costumes, duration, signal),
       sound != null ? loadAudio(sound, signal) : null
@@ -101,7 +155,13 @@ watchEffect(async () => {
     signal.throwIfAborted()
 
     costumesPlayer.play(signal)
-    if (audio != null) playAudio(audio, duration, signal)
+    if (audio != null) {
+      if (soundPlayback === AnimationSoundPlayback.Once) {
+        playAudioWithPlaybackOnce(audio, duration, signal)
+      } else if (soundPlayback === AnimationSoundPlayback.Loop) {
+        playAudioWithPlaybackLoop(audio, duration, signal)
+      }
+    }
   } catch (e) {
     ctrl.abort(e)
     capture(e, 'load and play animation failed')