Response Types

기준: OverAnim 0.1.0 Beta · Unreal Engine 5.8
헤더: OverAnimation/Runtime/OverAnimResponseTypes.h

Response는 Signal을 특정 Bone Group과 Module의 시각적 결과로 바꾸는 계약입니다. 모든 route 이름은 같은 UOverAnimMeshDeformer 안에서 해석됩니다.

Core Enum

Enum	값	의미 · 호환성
EOverAnimResponseActivationPolicy	Always	source/activation window와 무관하게 route를 허용합니다.
	AnimNotifyState	RequiredNotifyName과 열린 Activation Channel이 일치해야 합니다.
	ActorTag	Owner Actor에 RequiredActorTag가 있어야 합니다.
	ManualOnly / MotionOnly / AnimNotifyOnly / GameplayEventOnly	각각 FOverAnimSignal::Source가 Manual / MotionAnalyzer / AnimNotify / GameplayEvent일 때만 허용합니다.
EOverAnimResponseMode	Pulse (One Shot (Envelope))	한 번 트리거 후 Attack/Hold/Release envelope를 사용합니다.
	Sustained (Follow Active Motion Stages)	active state 또는 enabled automatic stages를 계속 추적합니다.
EOverAnimResponseTimingDriver	ExplicitEnvelope	Rule의 Envelope를 사용합니다. Notify, gameplay, contact, explicit motion Signal에 맞는 timing입니다.
	AutomaticMotionPhase	Region Motion snapshot의 Six-Stage Motion을 사용합니다. Module이 automatic stage를 지원해야 합니다.
EOverAnimResponseTimingRole	Shape, Volume, Dynamics, Smear	module response의 timing role입니다. 직접 설정하는 Details 필드는 아니며 module class가 정합니다.
EOverAnimMotionPhaseResponseProfile	ModuleDefault, FullCycle, ActionOnly, AnticipationAndAction, RecoveryOnly, Custom	automatic stage coverage를 선택합니다. Custom은 아래 six-stage bool/amount를 사용합니다. Starting Pose는 항상 source pose로 release됩니다.
EOverAnimMotionPhaseAmountMode	AuthoredModuleAmount	module response의 authored peak을 stage amount로 선택합니다.
	ScaleByDetectedMotion	authored stage amount에 analyzer Strength를 추가 곱합니다.
EOverAnimMotionPhaseActionBuildMode	FollowDetectedStroke	검출된 Action stroke 끝에서 authored peak에 도달합니다. build ratio는 1.0입니다.
	EarlyAccent	stroke 절반에서 peak에 도달합니다. build ratio는 0.5입니다.
	Immediate	Action 진입 즉시 peak를 사용합니다. build ratio는 0입니다.
	Custom	CustomActionPeakTiming의 0.05–1.0 값을 build ratio로 사용합니다.
EOverAnimMotionPhaseAnticipationDirection	CounterToAction	Anticipation amount를 Action 반대 방향의 음수 polarity로 해석합니다.
	SameAsAction	Anticipation amount를 Action과 같은 방향의 양수 polarity로 해석합니다.

EOverAnimMotionPhaseContributionResult (C++ 전용)

FOverAnimMotionPhaseResponseSettings::ResolveContribution()의 반환값입니다. BlueprintType이 아닌 C++ enum이며, Automatic Six-Stage Motion 평가가 현재 Response를 어떻게 처리해야 하는지를 나타냅니다.

값	Resolver 상태 변화	출력값 계약
Ignore	이번 Signal은 요청을 만들거나 갱신하지 않습니다. 기존 지속 Response도 이 값만으로 release되지 않습니다.	OutMagnitudeScale은 0, OutPolarity는 1로 초기화된 상태를 사용합니다. Motion Phase가 없거나 유효하지 않음, confidence 미달, Pulse가 trigger stage가 아님 등이 이 결과를 만듭니다.
Contribute	현재 단계의 Response 요청을 생성하거나 갱신합니다.	OutMagnitudeScale은 0 이상 stage amount이고, OutPolarity는 1 또는 -1입니다. Recoil은 음수이고 Anticipation은 AnticipationDirection에 따라 음수 또는 양수입니다.
Release	지속(Sustained) Response의 목표를 source pose 쪽으로 release합니다. 새 시각적 기여는 만들지 않습니다.	magnitude/polarity는 release 판단에 사용되지 않습니다. Stable 단계 또는 활성화되지 않은 단계로 넘어간 경우에 반환될 수 있습니다.

FOverAnimResponseRule

Details UI 이름	C++ 속성명	기본값 · 범위	영향 · 표시 조건
Rule Name	RuleName	None	rule 식별자입니다. 에셋 안에서 고유해야 합니다.
Enabled	bEnabled	true	false이면 route하지 않습니다.
Signal Name	SignalName	None	FOverAnimSignal::SignalName과 일치해야 합니다.
Source Region Filter	SourceRegionFilter	None	None은 모든 source region을 받습니다. 값이 있으면 Signal의 SourceRegionName과 일치해야 합니다.
Bone Group Name	BoneGroupName	None	대상 Region의 GroupName입니다. 유효한 Group 이름이어야 합니다.
Module Name	ModuleName	None	대상 Module의 ModuleName입니다. Group의 enabled Module과 일치해야 합니다.
Response Set Name	ResponseSetName	None	None이면 set 제한이 없습니다. 값이 있으면 존재하고 enabled인 ResponseSet이어야 합니다.
Activation Policy	ActivationPolicy	Always	signal source, notify channel, actor tag 중 어느 조건으로 route를 허용할지 정합니다.
Required Activation Channel	RequiredNotifyName	None	ActivationPolicy == AnimNotifyState일 때만 표시됩니다. 열린 OverAnim Activation Window의 channel과 일치해야 합니다.
Required Actor Tag	RequiredActorTag	None	ActivationPolicy == ActorTag일 때만 표시됩니다.
Slot Name	SlotName	None	response slot의 묶음 이름입니다. 같은 slot의 요청은 resolver가 조정합니다.
Priority	Priority	0	slot conflict 해석 순서입니다. 큰 값이 우선합니다.
Blend Weight	BlendWeight	1, 0..1	route 결과를 slot에 섞는 비율입니다.
Response Input Mapping	Magnitude	아래 구조체 기본값	Signal magnitude 또는 physical feature를 0..1 response amount로 map합니다.
Timing Model	TimingDriver	ExplicitEnvelope	AutomaticMotionPhase일 때만 MotionPhase가 의미 있습니다.
Response Duration	ResponseMode	Pulse	Pulse와 Sustained의 timing/지원 범위를 선택합니다.
Motion Phase	MotionPhase	아래 구조체 기본값	TimingDriver == AutomaticMotionPhase일 때만 표시됩니다.
Envelope	Envelope	0.03 / 0.05 / 0.15 s	ExplicitEnvelope는 값을 그대로 사용합니다. AutomaticMotionPhase는 이 시간을 분석된 Action timing scale로 조정하며, stage contribution이 요청의 기여/해제를 결정합니다.
Module Response at 100%	ModuleParameters	instanced 구조체	선택 Module class와 맞는 response parameter struct여야 합니다. 클래스 불일치는 계약 검증 오류입니다.

FOverAnimResponseMagnitudeSettings

UI 이름	C++ 속성명	기본값 · 범위	영향 · 표시 조건
Input Source	InputSource	SignalMagnitude	Signal magnitude 또는 linear/angular/tip motion feature를 선택합니다.
Motion Feature Projection	MotionFeatureProjection	Magnitude	InputSource != SignalMagnitude일 때만 표시됩니다. signal direction/contact normal을 기준으로 vector를 scalar로 투영합니다.
Measurement Basis	MeasurementBasis	Auto	LinearSpeed, LinearAcceleration, TipSpeed일 때만 표시됩니다. character/region scale로 선형 feature를 정규화합니다.
Input Range	InputMagnitudeRange	(0, 1)	선택 input의 raw range입니다. 단위는 Input Source에 따릅니다.
Output Range	OutputMagnitudeRange	(0, 1)	mapping 결과 response magnitude range입니다.
Clamp Magnitude	bClampMagnitude	true	true면 Input Range 밖을 Output Range 끝 값으로 clamp합니다.

EOverAnimResponseMagnitudeSource 값은 SignalMagnitude, LinearSpeed, LinearAcceleration, AngularSpeed, AngularAcceleration, TipSpeed입니다. EOverAnimMotionFeatureProjection은 Magnitude, Signal Direction의 along/opposite/absolute, Contact Normal의 along/opposite/absolute를 제공합니다. 방향/normal이 없는 Signal에서 해당 projection을 선택하면 usable feature를 만들지 못합니다.

FOverAnimResponseEnvelopeSettings

FOverAnimResponseEnvelopeSettings는 FOverAnimResponseRule::Envelope가 보유하는 시간 envelope입니다. TimingDriver == ExplicitEnvelope에서는 값을 그대로 사용하고, AutomaticMotionPhase에서는 분석된 Action timing scale로 세 시간을 조정한 resolved envelope를 사용합니다.

Details UI 이름	C++ 속성명	기본값 · 단위 · 범위	영향
Attack Time	AttackTime	0.03 s, 0+	Pulse envelope 상승 시간입니다.
Hold Time	HoldTime	0.05 s, 0+	peak 유지 시간입니다.
Release Time	ReleaseTime	0.15 s, 0+	source pose로 돌아가는 시간입니다.

FOverAnimMotionPhaseResponseSettings

Details UI 이름	C++ 속성명	기본값 · 범위	영향 · 표시 조건
Stage Coverage	Profile	ModuleDefault	automatic stage 조합을 선택합니다. Pulse는 One-Shot Trigger Stage만 사용합니다.
Minimum Stage Confidence	MinimumConfidence	0.15, 0..1	이 값보다 불확실한 snapshot은 module에 전달하지 않습니다.
Stage Amount Source	AmountMode	AuthoredModuleAmount	detected motion을 peak amount에 곱할지 결정합니다.
Action Build	ActionBuildMode	FollowDetectedStroke	Sustained Automatic Motion의 Action peak 도달 시점을 선택합니다.
Custom Action Peak Timing	CustomActionPeakTiming	1.0, 0.05..1	ActionBuildMode == Custom일 때만 표시됩니다. detected Action stroke에서 peak에 도달할 비율입니다.
Blend Recovery Stage Changes	bBlendStageAmountChanges	true	non-Action recovery stage amount 전환을 blend합니다.
Recovery Stage Blend Ratio	StageAmountBlendTimeRatio	0.35, 0..1	이전 bool이 true일 때만 표시됩니다. detected Action stroke duration의 비율입니다.
Anticipation / Amount	bEnableAnticipation, AnticipationCounterStrength	true, 0.25 · 0..2	enabled일 때 anticipation shape를 사용합니다. amount는 bool이 true일 때 표시됩니다.
Anticipation Direction	AnticipationDirection	CounterToAction	Anticipation이 Action 반대 방향인지 같은 방향인지 선택합니다.
Action / Amount	bEnableAction, ActionStrength	true, 1 · 0..2	Action peak의 response 비율입니다.
Overshoot / Amount	bEnableOvershoot, OvershootStrength	true, 0.35 · 0..2	Action 뒤 continuation의 response 비율입니다.
Recoil / Amount	bEnableRecoil, RecoilCounterStrength	true, 0.20 · 0..2	Overshoot 뒤의 counter-motion 비율입니다.
Settle Pose / Amount	bEnableSettle, SettleStrength	true, 0.05 · 0..2	source pose 근처에 남길 response 비율입니다.
One-Shot Trigger Stage	PulseTriggerPhase	Action	ResponseMode == Pulse에서만 effect를 시작할 stage입니다. Sustained는 Profile을 사용합니다.
Override Automatic Stage Timing	bOverrideResponseSetTiming	false	true일 때 rule만의 stage delay를 활성화합니다.
Extra Stage Delay	TargetRegionDelay	0 s, 0..0.5 s	위 bool이 true일 때만 표시됩니다.

Public C++ helper contracts

FOverAnimMotionPhaseResponseSettings

C++ 선언	입력 · 반환	전제조건 · 실패/상태 변화
ResolveContribution(const FOverAnimSignal&, EOverAnimResponseMode, float&, float&) const	Signal과 Response mode를 받고 OutMagnitudeScale, OutPolarity를 씁니다. 반환은 EOverAnimMotionPhaseContributionResult입니다.	유효한 MotionPhase snapshot과 IsValid()가 필요합니다. 조건을 충족하지 못하면 Ignore를 반환합니다. 이 함수는 설정을 바꾸지 않습니다. 반환 enum의 resolver 의미는 이 페이지의 EOverAnimMotionPhaseContributionResult 표를 따릅니다.
ApplyProfile(EOverAnimMotionPhaseResponseProfile)	Profile을 받고 반환값은 없습니다.	FullCycle, ActionOnly, AnticipationAndAction, RecoveryOnly는 해당 stage enable flag와 강도를 profile 값으로 덮어씁니다. ModuleDefault와 Custom은 Profile만 바꾸며 기존 stage flag/강도를 보존합니다.
IsPhaseEnabled(EOverAnimMotionPhase) const	Phase를 받아 bool을 반환합니다.	Anticipation, Action, Overshoot, Recoil, Settle은 각각의 bEnable* 값을 반환합니다. Stable은 항상 false입니다.
GetSignedPhaseStrength(EOverAnimMotionPhase) const	Phase를 받아 signed strength를 반환합니다.	enable flag는 검사하지 않습니다. Anticipation은 AnticipationDirection에 따라 양수 또는 음수, Recoil은 음수, Action·Overshoot·Settle은 양수, Stable은 0입니다.
ResolveActionBuildRatio() const	입력 없이 Action build ratio를 반환합니다.	FollowDetectedStroke=1, EarlyAccent=0.5, Immediate=0, Custom=clamp(CustomActionPeakTiming, 0.05, 1)입니다. 상태를 바꾸지 않습니다.
ResolveActionStrength(const FOverAnimMotionPhaseSnapshot& Phase, float ElapsedSeconds, EOverAnimMotionPhase EntryPhase) const	snapshot, Action 경과 시간, 진입 전 stage를 받아 signed Action strength를 반환합니다.	authored stage progress가 있으면 해당 0–1 progress를 우선 사용합니다. 아니면 ActionTempoSeconds × ResolveActionBuildRatio() 동안 진입 strength에서 ActionStrength까지 smooth-step 보간합니다. Immediate는 바로 peak입니다.
ResolveSignedPhaseStrength(const FOverAnimMotionPhaseSnapshot&) const	Motion Phase snapshot을 받아 현재 시점의 signed strength를 반환합니다.	Action은 ResolveActionStrength()를 사용합니다. 다른 stage 전환은 bBlendStageAmountChanges와 이전 Action의 실제 종료 strength를 사용해 recovery blend를 계산합니다. snapshot 유효성은 호출자가 보장해야 합니다.
ResolveDetectedMotionScale(const FOverAnimSignal&) const	Signal을 받아 0..1 motion scale을 반환합니다.	AuthoredModuleAmount이면 항상 1입니다. ScaleByDetectedMotion은 유효한 Motion Phase의 Strength를 clamp해 반환하고, 없거나 유효하지 않으면 0입니다.
ResolveTargetRegionDelay(float ActionTimingScale = 1.0f) const	timing scale을 받아 실제 delay(초)를 반환합니다.	bOverrideResponseSetTiming이 false이거나 scale이 음수/비유한 값이면 0입니다. 그 외에는 TargetRegionDelay × scale을 0..0.5 s로 clamp합니다.
ResolveMaximumTargetRegionDelay(float MaximumActionTimingScale = 1.0f) const	최대 timing scale을 받아 최대 delay(초)를 반환합니다.	ResolveTargetRegionDelay()와 같은 검증 및 clamp를 적용합니다. 이름과 달리 별도의 상태를 읽거나 바꾸지 않습니다.
IsValid() const	반환: bool	MinimumConfidence가 0..1, CustomActionPeakTiming이 0.05..1, TargetRegionDelay가 0..0.5, StageAmountBlendTimeRatio가 0..1, 각 stage strength가 0..2이고 모두 유한할 때만 true입니다.

FOverAnimResponseMagnitudeSettings

C++ 선언	입력 · 반환	전제조건 · 실패/상태 변화
TryResolveInputMagnitude(const FOverAnimSignal&, float&) const	Signal에서 raw input magnitude를 읽어 OutInputMagnitude에 씁니다. 성공 여부를 bool로 반환합니다.	SignalMagnitude는 유한한 Signal.Magnitude가 필요합니다. 다른 source는 bHasMotionFeatures, 선택 feature와 measurement scale, 그리고 projection에 필요한 Signal direction/contact normal이 필요합니다. 충족하지 못하면 false입니다.
TryResolveMagnitude(const FOverAnimSignal&, float&) const	Signal을 받아 mapping된 magnitude를 OutResolvedMagnitude에 쓰고 bool을 반환합니다.	input을 얻지 못하면 출력은 0, 반환은 false입니다. mapping 결과가 비유한 값이면 false이며 출력값은 성공했을 때만 사용해야 합니다.
ResolveMagnitude(float) const	raw input을 받아 mapping된 non-negative float을 반환합니다.	InputMagnitudeRange의 span이 0이면 range 시작점의 output을 사용합니다. bClampMagnitude가 true면 map alpha를 0..1로 clamp합니다. 이 순수 함수는 range의 유한성/의미를 검증하지 않으므로 직접 호출 시 호출자가 이를 보장해야 합니다.

FOverAnimResponseEnvelopeSettings

C++ 선언	입력 · 반환	전제조건 · 상태 변화
GetDuration() const	반환: AttackTime + HoldTime + ReleaseTime(초)	값을 clamp하거나 검증하지 않는 계산 함수입니다. Details 입력은 0 이상으로 제한되지만, C++에서 만든 값은 호출자가 유효성을 보장해야 합니다.

FOverAnimResponseRule

C++ 선언	입력 · 반환	전제조건 · 실패/상태 변화
TryResolveBaseMagnitude(const FOverAnimSignal&, float&) const	Signal을 받아 rule의 base magnitude를 OutMagnitude에 쓰고 bool을 반환합니다.	일반 경로는 Magnitude.TryResolveMagnitude()를 사용합니다. AutomaticMotionPhase + SignalMagnitude + AuthoredModuleAmount 조합은 Signal magnitude를 읽지 않고 정확히 1을 반환합니다. 같은 조합에서 ScaleByDetectedMotion이면 stage strength를 Signal magnitude로 사용해 mapping합니다. mapping 실패 시 false입니다.

Motion feature free function

C++ 선언	입력 · 반환	전제조건 · 실패/상태 변화
TryResolveOverAnimMotionFeatureVector(const FOverAnimMotionFeatureSnapshot&, EOverAnimResponseMagnitudeSource, EOverAnimMotionMeasurementBasis, FVector&)	Motion snapshot, source, basis를 받아 world-space feature vector를 OutFeatureVector에 쓰고 bool을 반환합니다.	MotionFeatures.IsValid()가 필요합니다. LinearSpeed, LinearAcceleration, TipSpeed는 basis의 measurement scale을 해석할 수 있어야 하며, TipSpeed는 bHasTipVelocity도 필요합니다. Angular source는 degree 단위 vector로 변환됩니다. SignalMagnitude는 vector source가 아니므로 false입니다. 함수 시작 시 output을 zero로 초기화하지만, NaN 검출로 실패한 output은 사용하면 안 됩니다.

FOverAnimResponseSet · FOverAnimRequestBudgetSettings

구조체	C++ 속성명	기본값	영향
FOverAnimResponseSet	SetName	None	Rule의 ResponseSetName이 참조합니다.
	bEnabled	true	false인 set의 rule은 route하지 않습니다.
	Intensity	1, 0+	set에 속한 response의 intensity 배율입니다.
	bLogDispatch	false	response dispatch logging을 활성화합니다.
FOverAnimRequestBudgetSettings	MaxPendingSignalsPerFrame	256, 1+	프레임당 pending Signal 상한입니다.
	MaxResolvedRequestsPerFrame	64, 1+	프레임당 해결할 request 상한입니다.
	MaxActiveResponseSlots	32, 1+	동시에 유지할 response slot 상한입니다.
	MinimumSlotLifetime	1/60 s, 0+	slot이 유지되는 최소 시간입니다.
	MaximumSlotLifetime	2 s, 0+	slot이 유지되는 최대 시간입니다.

FOverAnimModuleResponseParameters

FOverAnimModuleResponseParameters는 FOverAnimResponseRule::ModuleParameters가 보관하는 FInstancedStruct의 공용 base struct입니다. 자체 Details 속성이나 함수는 없으며, 에셋 편집기에서는 base type을 직접 선택할 수 없습니다. Route 대상 Module에 맞는 아래의 파생 struct만 유효한 외부 계약입니다.

계약 항목	의미	거부/검증 조건
Base struct	FOverAnimModuleResponseParameters	ModuleParameters의 저장 형식과 파생 response parameter type 식별에만 사용됩니다. base struct만 담으면 module별 시각 파라미터가 없습니다.
Module/type 일치	FOverAnimResponseRule::ModuleName과 ModuleParameters의 파생 struct	선택한 Module이 지원하는 파생 struct여야 합니다. 일치하지 않는 type은 response contract 검증에서 오류입니다.
지원 범위	Signal/Response를 지원하는 module	Joint Volume Corrective는 response parameter struct가 없고 Signal/Response route 대상이 될 수 없습니다.

Module response parameter structs

ModuleParameters에는 route 대상 module과 맞는 구조체만 넣습니다. 대응하지 않는 module/struct 조합은 유효하지 않습니다.

Module · 구조체	속성	기본값 · 범위	영향
Squash & Stretch · FOverAnimSquashStretchResponseParameters	PrimaryScaleAtMax	0.65, 0.05+	full response의 primary-axis scale입니다. 1 미만은 squash, 1 초과는 stretch입니다.
	AnticipationAmount, AnticipationPeakFraction	0, 0.25 · fraction 0.05..0.75	explicit envelope 안의 authored counter-shape와 Attack Time 내 peak 위치입니다. amount가 0이면 timing은 숨겨집니다.
	bEnableRebound, ReboundPrimaryScaleAtMax, ReboundPeakFraction	false, 1.08, 0.35	enabled일 때 explicit envelope recovery overshoot를 추가합니다. Automatic Six-Stage의 Overshoot/Recoil과 동시에 사용하면 둘이 모두 반영됩니다.
Transform Spring · FOverAnimSpringResponseParameters	LinearImpulseScale, MaxLinearImpulse	100 / 1000 cm/s, 0+	one-shot velocity impulse와 누적 상한입니다.
	PhaseTargetOffsetRatio	0.08, 0..0.5	sustained automatic stage를 Region reference length의 offset으로 바꿉니다.
Mesh Bulge · FOverAnimMeshBulgeResponseParameters	IntensityScale, MaxIntensity, DecayRate	1, 3, 8 · 0+	one-shot intensity 배율/상한/지수 decay입니다. sustained stage는 현재 stage strength를 사용합니다.
Contact Dent + Ring Bulge · FOverAnimContactDentBulgeResponseParameters	DentStrengthAtMax, BulgeStrengthAtMax, RadiusScale	모두 1, strength 0..2, radius 0.25..2	full contact response의 dent/ring/radius 배율입니다.
Impact Ripple · FOverAnimImpactRippleResponseParameters	WaveStrengthAtMax, RadiusScale	1, strength 0..2, radius 0.25..2	full contact response의 compression/shear/ripple radius 배율입니다.
Smear · FOverAnimSmearResponseParameters	HistoryStrengthAtMax	1, 0..1	signal-gated response가 노출하는 configured pose history의 비율입니다.
Follow Through · FOverAnimFollowThroughResponseParameters	HistoryStrengthAtMax	1, 0..1	response가 노출하는 authored pose history 비율입니다. chain/safety는 그대로 유지됩니다.
Bone Scaler · FOverAnimBoneScalerResponseParameters	MotionScaleStrengthAtMax	1, 0..1	signal response가 노출하는 velocity-derived scale 비율입니다. axis mask/gain은 module에 남습니다.

지원하지 않는 조합

Joint Volume Corrective는 Signal/Response를 지원하지 않습니다. Contact Dent + Ring Bulge와 Impact Ripple은 Pulse + valid contact input만 지원합니다. Automatic Six-Stage 호환 여부는 각 module page에서 확인해야 합니다.