✨ Add Texture Slot keyframes and Variant stacks

- Variant keyframes apply several Variants in order; old keyframes migrate in 1.11.0
- Texture Slot keyframes switch slots during an animation, on 1.21.4+ only
- Animate mode previews each bone from the animation's start state, leaving Edit mode alone
- Each frame's effects export to one function, shared by baked, storage, and loop paths
- Plugin JSON exports Variants and `variant` keyframes instead of flattening them
- Keyframe panel edits are undoable and mark the project unsaved
- Fix Variant keyframes never applying with storage animations
- Fix last-frame Variant and function keyframes skipped in loops without a moving Locator

Author: SnaveSutit

schemas/plugin-blueprint.schema.json

@@ -36,6 +36,15 @@
 				}
 			}
 		},
+		"variants": {
+			"type": "object",
+			"default": {},
+			"patternProperties": {
+				"^[a-z0-9_]+$": {
+					"$ref": "#/definitions/variant"
+				}
+			}
+		},
 		"nodes": {
 			"type": "object",
 			"default": {},
@@ -149,6 +158,41 @@
 				}
 			}
 		},
+		"variant": {
+			"type": "object",
+			"description": "A named set of changes to the rig. Applying a Variant changes every node it doesn't exclude.",
+			"required": ["texture_slots", "excluded_nodes", "entity_properties"],
+			"properties": {
+				"is_default": {
+					"type": "boolean",
+					"default": false,
+					"description": "Whether this is the default Variant. Exactly one Variant is the default."
+				},
+				"texture_slots": {
+					"$ref": "#/definitions/texture_slot_changes",
+					"description": "The texture each slot switches to, on nodes this Variant doesn't exclude. Slots not listed are unchanged. The default Variant lists every slot with its default texture."
+				},
+				"excluded_nodes": {
+					"type": "array",
+					"default": [],
+					"description": "Keys from the 'nodes' section this Variant leaves unchanged, including their texture slots.",
+					"items": {
+						"type": "string",
+						"pattern": "^[a-z0-9_]+$"
+					}
+				},
+				"entity_properties": {
+					"type": "object",
+					"default": {},
+					"description": "Entity properties this Variant merges onto nodes, by key from the 'nodes' section. Each value has the same shape as that node's 'entity_properties'. For the default Variant, these are the nodes' default properties.",
+					"patternProperties": {
+						"^[a-z0-9_]+$": {
+							"type": "object"
+						}
+					}
+				}
+			}
+		},
 		"node": {
 			"type": "object",
 			"required": ["type"],
@@ -674,14 +718,25 @@
 				"global_keyframes": {
 					"type": "object",
 					"default": {},
+					"description": "Keyframes that aren't tied to a node. When a 'variant' and a 'texture_slot' keyframe share a timestamp, the Variants apply first.",
 					"properties": {
+						"variant": {
+							"type": "object",
+							"default": {},
+							"description": "A collection of variant keyframes, identified by a floating-point timestamp.",
+							"patternProperties": {
+								"^\\d+\\.\\d+$": {
+									"$ref": "#/definitions/variant_keyframe"
+								}
+							}
+						},
 						"texture_slot": {
 							"type": "object",
 							"default": {},
-							"description": "A collection of texture slot keyframes, identified by a floating-point timestamp.",
+							"description": "A collection of texture slot keyframes, identified by a floating-point timestamp. Each one changes every node with faces in the listed slots, regardless of Variant exclusions.",
 							"patternProperties": {
 								"^\\d+\\.\\d+$": {
-									"$ref": "#/definitions/texture_slot_keyframe"
+									"$ref": "#/definitions/texture_slot_changes"
 								}
 							}
 						},
@@ -751,10 +806,19 @@
 			"minItems": 3,
 			"maxItems": 3
 		},
-		"texture_slot_keyframe": {
+		"variant_keyframe": {
+			"type": "array",
+			"description": "Keys from the 'variants' section, applied in order. Later Variants override earlier ones on the nodes they change.",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z0-9_]+$"
+			}
+		},
+		"texture_slot_changes": {
 			"type": "object",
 			"default": {},
-			"description": "Maps keys from the 'texture_slots' section to the texture each slot switches to. Slots not listed are unchanged.",
+			"description": "Maps keys from the 'texture_slots' section to the key of the texture each slot switches to. Slots not listed are unchanged.",
 			"patternProperties": {
 				"^[a-z0-9_]+$": {
 					"type": "string",

src/animationPreview.ts

@@ -0,0 +1,161 @@
+import { EFFECT_ANIMATOR_CHANNELS } from './mods/customKeyframes'
+import { VanillaBlockDisplay } from './outliner/vanillaBlockDisplay'
+import { VanillaItemDisplay } from './outliner/vanillaItemDisplay'
+import { getSlotDefaultTexture, getSlotPreviewTexture, getSlotTextures } from './textureSlots'
+import { Variant } from './variants'
+
+/**
+ * What an animation has applied to the rig at the previewed time. Only exists in Animate mode with
+ * an animation selected. Otherwise the editor shows the Variant selected in the Variants panel.
+ */
+interface AnimationPreviewState {
+	/** Every Variant applied so far, in order. */
+	variants: Variant[]
+	/** Bone UUID -> slot UUID -> texture UUID. Slots left out show their default texture. */
+	boneSlots: Map<string, Map<string, string>>
+}
+
+type PreviewEvent =
+	| { time: number; variants: Variant[] }
+	| { time: number; textureSlots: Record<string, string> }
+
+let state: AnimationPreviewState | undefined
+let stateKey = ''
+
+/**
+ * The Variant whose display entity config `node` shows: the last applied Variant that changes it.
+ */
+export function getPreviewVariant(node: OutlinerNode): Variant | undefined {
+	if (!state) return Variant.selected
+	for (let i = state.variants.length - 1; i >= 0; i--) {
+		const variant = state.variants[i]
+		if (variant.excludedNodes.has(node.uuid)) continue
+		const configs = (node as { configs?: { variants?: Record<string, unknown> } }).configs
+		if (variant.isDefault || configs?.variants?.[variant.uuid] !== undefined) return variant
+	}
+	return Variant.getDefault()
+}
+
+/**
+ * The texture a slot shows on faces of `bone`.
+ */
+export function getPreviewSlotTexture(slot: Texture, bone: OutlinerNode | undefined) {
+	if (!state) {
+		// The selected Variant leaves the slots it sets on excluded bones at their default.
+		const variant = Variant.selected
+		const excluded =
+			bone && variant?.excludedNodes.has(bone.uuid) && variant.slotTextures.has(slot.uuid)
+		return excluded ? getSlotDefaultTexture(slot) : getSlotPreviewTexture(slot)
+	}
+	const uuid = bone && state.boneSlots.get(bone.uuid)?.get(slot.uuid)
+	const textures = getSlotTextures(slot)
+	return textures.find(t => t.uuid === uuid) ?? textures[0]
+}
+
+function getAnimationStartVariants(animation: _Animation): Variant[] {
+	const variants = (animation.preview_variants ?? [])
+		.map(uuid => Variant.getByUUID(uuid))
+		.filter((v): v is Variant => !!v)
+	return variants.length ? variants : [Variant.getDefault()]
+}
+
+function getPreviewEvents(animation: _Animation, time: number): PreviewEvent[] {
+	const effects = animation.animators.effects as unknown as EffectAnimator | undefined
+	const events: PreviewEvent[] = []
+	if (effects && !effects.muted[EFFECT_ANIMATOR_CHANNELS.VARIANT]) {
+		for (const kf of effects[EFFECT_ANIMATOR_CHANNELS.VARIANT] as _Keyframe[]) {
+			if (kf.time <= time) events.push({ time: kf.time, variants: kf.variants ?? [] })
+		}
+	}
+	if (effects && !effects.muted[EFFECT_ANIMATOR_CHANNELS.TEXTURE_SLOT]) {
+		for (const kf of effects[EFFECT_ANIMATOR_CHANNELS.TEXTURE_SLOT] as _Keyframe[]) {
+			if (kf.time <= time)
+				events.push({ time: kf.time, textureSlots: kf.texture_slots ?? {} })
+		}
+	}
+	// Variants apply before texture slots on the same frame, like in-game.
+	return events.sort(
+		(a, b) => a.time - b.time || Number('textureSlots' in a) - Number('textureSlots' in b)
+	)
+}
+
+/**
+ * Replays what `animation` applies to the rig, from its start state up to `time`.
+ */
+export function computeAnimationPreviewState(
+	animation: _Animation,
+	time: number
+): AnimationPreviewState {
+	const result: AnimationPreviewState = { variants: [], boneSlots: new Map() }
+	const bones = Group.all
+
+	const applyVariant = (variant: Variant) => {
+		result.variants.push(variant)
+		for (const bone of bones) {
+			if (variant.excludedNodes.has(bone.uuid)) continue
+			if (variant.isDefault) {
+				result.boneSlots.delete(bone.uuid)
+				continue
+			}
+			for (const [slotUuid, textureUuid] of variant.slotTextures) {
+				setBoneSlot(bone.uuid, slotUuid, textureUuid)
+			}
+		}
+	}
+	const applyTextureSlots = (textureSlots: Record<string, string>) => {
+		for (const [slotUuid, textureUuid] of Object.entries(textureSlots)) {
+			for (const bone of bones) setBoneSlot(bone.uuid, slotUuid, textureUuid)
+		}
+	}
+	const setBoneSlot = (boneUuid: string, slotUuid: string, textureUuid: string) => {
+		let slots = result.boneSlots.get(boneUuid)
+		if (!slots) result.boneSlots.set(boneUuid, (slots = new Map()))
+		slots.set(slotUuid, textureUuid)
+	}
+
+	for (const variant of getAnimationStartVariants(animation)) applyVariant(variant)
+	applyTextureSlots(animation.preview_texture_slots ?? {})
+	for (const event of getPreviewEvents(animation, time)) {
+		if ('variants' in event) event.variants.forEach(applyVariant)
+		else applyTextureSlots(event.textureSlots)
+	}
+	return result
+}
+
+function getStateKey(previewState: AnimationPreviewState | undefined) {
+	if (!previewState) return ''
+	const slots = [...previewState.boneSlots].map(([bone, map]) => [bone, [...map]])
+	return JSON.stringify([previewState.variants.map(v => v.uuid), slots])
+}
+
+/**
+ * Forgets the previewed animation, so the next update starts fresh. Used when switching projects.
+ */
+export function resetAnimationPreview() {
+	state = undefined
+	stateKey = ''
+}
+
+/**
+ * Re-renders everything that depends on which Variant or slot texture is shown.
+ */
+export function refreshVariantPreview() {
+	Canvas.updateAllFaces()
+	VanillaBlockDisplay.forceUpdateAll()
+	VanillaItemDisplay.forceUpdateAll()
+}
+
+/**
+ * Previews the selected animation's Variants and texture slots in Animate mode, or the Variants
+ * panel's selection everywhere else. Only re-renders when what's shown changes.
+ */
+export function updateAnimationPreview() {
+	const animation = Modes.animate ? Blockbench.Animation.selected : undefined
+	const next = animation ? computeAnimationPreviewState(animation, animation.time) : undefined
+	const nextKey = getStateKey(next)
+	const wasActive = !!state
+	state = next
+	if (nextKey === stateKey && wasActive === !!next) return
+	stateKey = nextKey
+	refreshVariantPreview()
+}

src/dialogs/animationProperties/animationProperties.svelte

@@ -9,20 +9,26 @@
 <script lang="ts">
 	import Collection from '../../svelteComponents/dialogItems/collection.svelte'
 	import Select from '../../svelteComponents/dialogItems/select.svelte'
+	import SlotTexturesEditor from '../../svelteComponents/slotTexturesEditor.svelte'
+	import VariantStackEditor from '../../svelteComponents/variantStackEditor.svelte'
 	import { getAvailableNodes } from '../../util/excludedNodes'
 
 	interface Props {
 		animationName: Observable<string>
 		loopMode: Observable<string>
 		loopDelay: Observable<number>
 		excludedNodes: Observable<Array<{ name: string; value: string }>>
+		previewVariants: Observable<string[]>
+		previewTextureSlots: Observable<Record<string, string>>
 	}
 
 	let {
 		animationName = $bindable(),
 		loopMode = $bindable(),
 		loopDelay = $bindable(),
 		excludedNodes = $bindable(),
+		previewVariants,
+		previewTextureSlots,
 	}: Props = $props()
 
 	const AVAILABLE_BONES = getAvailableNodes(excludedNodes.get())
@@ -92,7 +98,27 @@
 		availableItems={AVAILABLE_BONES}
 		bind:includedItems={excludedNodes}
 	/>
+
+	<VariantStackEditor
+		title={translate('dialog.animation_properties.preview_variants.title')}
+		description={translate('dialog.animation_properties.preview_variants.description')}
+		emptyText={translate('dialog.animation_properties.preview_variants.empty')}
+		value={$previewVariants}
+		onchange={value => previewVariants.set(value)}
+	/>
+
+	<SlotTexturesEditor
+		title={translate('dialog.animation_properties.preview_texture_slots.title')}
+		description={translate('dialog.animation_properties.preview_texture_slots.description')}
+		emptyText={translate('dialog.animation_properties.preview_texture_slots.empty')}
+		value={$previewTextureSlots}
+		onchange={value => previewTextureSlots.set(value)}
+	/>
 </div>
 
 <style>
+	div {
+		overflow-y: auto;
+		max-height: 75vh;
+	}
 </style>

src/dialogs/animationProperties/animationProperties.ts

@@ -11,6 +11,8 @@ export function openAnimationPropertiesDialog(animation: _Animation) {
 	const loopMode = observable(animation.loop as string)
 	const loopDelay = observable(Number(animation.loop_delay) || 0)
 	const excludedNodes = observable(animation.excluded_nodes)
+	const previewVariants = observable([...animation.preview_variants])
+	const previewTextureSlots = observable({ ...animation.preview_texture_slots })
 
 	new SvelteDialog({
 		id: DIALOG_ID,
@@ -22,6 +24,8 @@ export function openAnimationPropertiesDialog(animation: _Animation) {
 			loopMode,
 			loopDelay,
 			excludedNodes,
+			previewVariants,
+			previewTextureSlots,
 		},
 		disableKeybinds: true,
 		onConfirm() {
@@ -30,6 +34,9 @@ export function openAnimationPropertiesDialog(animation: _Animation) {
 			animation.loop = loopMode.get() as any
 			animation.loop_delay = loopDelay.get().toString()
 			animation.excluded_nodes = excludedNodes.get()
+			animation.preview_variants = previewVariants.get()
+			animation.preview_texture_slots = previewTextureSlots.get()
+			Animator.preview()
 
 			Project!.saved = false
 		},