Effect Modules

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

이 인덱스는 Module Stack에 추가할 9개 module의 공개 저작 계약으로 연결됩니다. 각 페이지는 실제 C++ 공개 필드, EditCondition, runtime validation과 Simple knob의 런타임 해석을 기준으로 작성되었습니다. renderer proxy와 shader state는 외부 저작 계약이 아니므로 제외합니다.

Simple과 Details

Asset Editor의 Simple과 Details는 같은 runtime parameter를 서로 다른 수준으로 저작하는 화면입니다. Transform Spring, Follow Through, Mesh Bulge, Smear, Contact Dent + Ring Bulge, Joint Volume Corrective, Impact Ripple, Bone Scaler는 Detailed 속성에 적용되는 Simple* knob를 보유합니다.

Simple knob의 범위는 0.0–5.0, 기본값은 1.0입니다.
1.0은 Detailed에서 작성한 값의 100%, 2.0은 일반적인 비율형 속성에서 200%를 뜻합니다.
Simple knob는 현재 표시 중인 레이아웃과 관계없이 runtime parameter에 항상 적용됩니다. Simple / Details 전환은 화면에 표시할 property만 바꿉니다.
Simple knob는 Detailed 속성에 값을 다시 쓰지 않습니다. runtime instance를 만들 때 Detailed 작성값으로부터 매번 결과를 계산하므로 누적되지 않습니다.
정비율, 역비율, 고정 범위 additive 속성은 해석 방식이 다르며 최종 결과는 각 Detailed 속성의 안전 범위로 제한됩니다. 역비율 속성에서 knob 0은 0.01의 안전 비율을 사용합니다.
Squash & Stretch에는 Simple knob가 없습니다. Simple 화면에서는 Response 저작 UI와 Master Effect Intensity만 사용합니다.

공통 module contract

공통 항목	C++ 속성명	의미
Input Composition	`CompositionMode`	`Additive Offset`은 이전 composed result에 delta를 더하고, `Re-Skinning`은 현재 control-point transform에서 다시 평가합니다. 실행 Phase와 stack order는 이 값으로 정하지 않습니다.
Module identity	`ModuleId`, `ModuleName`, `bEnabled`	Module Stack이 관리하는 식별·이름·활성화 상태입니다. custom Details의 module parameter reference에서는 숨겨집니다. Rule route는 `ModuleName`을 사용합니다.
Phase order	`PhaseOrder`	같은 Phase 안의 composed 순서입니다. `Starting Pose`, `Action` 같은 Automatic Six-Stage Motion의 stage 선택 값이 아닙니다.
Asset intensity	`UOverAnimMeshDeformer::MasterEffectIntensity`	에셋 전체 module authored strength 배율입니다. module safety limit은 개별적으로 유지됩니다.

UOverAnimDeformerModule extension · query contract

UOverAnimDeformerModule은 Abstract, BlueprintType, EditInlineNew, DefaultToInstanced인 공개 base class입니다. 이 클래스 자체는 Module Stack에 실행 가능한 효과를 만들지 않으며, concrete module class가 아래 factory와 query를 override해 자신의 실행·Signal·Response 계약을 선언합니다. 이 항목들은 Blueprint 노드가 아닌 C++ 가상 함수입니다.

Runtime factory · identity

C++ 선언	base 구현 · 반환	extension 계약
`virtual UOverAnimDeformerInstance* CreateInstance(UObject* Outer, UOverAnimDeformerInstanceSettings* Settings, FGuid BoneGroupId, FName BoneGroupName) const`	base class는 `nullptr`를 반환합니다.	실행 가능한 concrete module은 해당 Bone Group의 runtime instance를 만들도록 override합니다. `Outer`, `Settings`, Group ID·이름은 생성 컨텍스트이며 반환 instance의 소유권은 호출 경로가 관리합니다.
`virtual FText GetModuleDisplayName() const`	base class는 `ModuleName`을 `FText`로 반환합니다.	Module Stack에 표시할 이름을 별도 규칙으로 제공할 때 override합니다. 이 반환값은 Response Rule의 `ModuleName` route 자체를 바꾸지 않습니다.
`virtual EOverAnimModulePhase GetPhase() const`	base class 기본값은 `Shape`입니다.	module이 속한 실행 Phase를 반환합니다. `PhaseOrder`는 이 반환값이 같은 module끼리만 순서를 정합니다.
`virtual const UScriptStruct* GetResponseParameterStruct() const`	base class는 `nullptr`를 반환합니다.	Response Rule이 이 module에 전달할 사용자 파라미터 구조체를 반환합니다. `nullptr`이면 module별 Response parameter struct 계약이 없습니다.

Signal · Response · Automatic Motion queries

C++ 선언	base 구현 · 반환	계약
`virtual bool SupportsSignals() const`	`false`	`true`인 module만 Signal에 반응할 수 있습니다. concrete module의 현재 driver/configuration에 따라 반환값이 달라질 수 있습니다.
`virtual bool SupportsResponseMode(EOverAnimResponseMode ResponseMode) const`	`Pulse`일 때만 `true`	해당 Response mode가 module에 허용되는지 질의합니다.
`virtual bool SupportsResponseModeForTimingDriver(EOverAnimResponseMode ResponseMode, EOverAnimResponseTimingDriver TimingDriver) const`	base class는 `TimingDriver`를 구분하지 않고 `SupportsResponseMode(ResponseMode)` 결과를 반환합니다.	timing driver까지 고려해 Response mode를 판정해야 하는 module이 override합니다.
`virtual EOverAnimResponseMode GetPreferredAutomaticMotionPhaseResponseMode() const`	`Sustained`를 지원하면 `Sustained`, 아니면 `Pulse`	Automatic Six-Stage Motion이 module을 대상으로 rule을 만들 때의 선호 Response mode입니다. 실제 허용 여부는 다음 query와 함께 판정됩니다.
`virtual FOverAnimMotionPhaseResponseSettings GetPreferredAutomaticMotionPhaseSettings() const`	기본 생성된 `FOverAnimMotionPhaseResponseSettings`	Automatic Motion rule에 사용할 module 기본 timing/phase settings입니다.
`virtual EOverAnimResponseTimingRole GetAutomaticMotionPhaseTimingRole() const`	`Shape`	Automatic Motion의 timing role입니다. module별 override 값은 Response timing 해석에 사용됩니다.
`virtual bool CanCreateAutomaticMotionPhaseResponse(FText& OutFailureReason) const`	성공 시 `true`와 빈 `OutFailureReason`입니다.	base class는 `bEnabled`, `ModuleName`, `SupportsSignals()`, 선호 mode의 `SupportsResponseModeForTimingDriver(... AutomaticMotionPhase)`를 차례로 검사합니다. 실패하면 `false`와 이유를 반환합니다. concrete module은 필요한 bone·chain·history·contact 조건을 추가로 검사할 수 있습니다.

Editor change classification

이 세 함수는 WITH_EDITOR에서만 존재합니다. 런타임/Blueprint 호출 계약이 아닙니다.

C++ 선언	base 구현 · 상태 변화	extension 계약
`virtual bool IsStructuralProperty(FName PropertyName) const`	`false`	`true`를 반환한 property 또는 member property 변경은 `Structure` asset-change로 분류됩니다.
`virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent)`	Outer가 `UOverAnimMeshDeformer`이면 `bEnabled` 또는 `IsStructuralProperty()`가 가리킨 변경을 `Structure`, 나머지를 `Parameters`로 `NotifyAssetChanged()` 합니다.	Details 변경이 구조 변경인지 module class가 명시할 때 `IsStructuralProperty()`를 override합니다.
`virtual void PostEditUndo()`	Outer가 에셋이면 `Structure` 변경을 알립니다.	module editor state가 Undo 뒤 별도 동기화를 필요로 할 때 override하되 asset-change 분류 계약을 보존합니다.

Module execution enums

EOverAnimModuleTuningSource

현재 built-in module runtime은 UOverAnimMeshDeformer::TuningSource를 읽지 않습니다. 이 enum과 직렬화 필드는 기존 asset 호환을 위해 남아 있지만 Simple / Details 패널 선택이나 runtime parameter 계산을 제어하지 않습니다.

값	의미
`Detailed`	호환성용 직렬화 값입니다. built-in module runtime 동작을 변경하지 않습니다.
`Simple`	호환성용 직렬화 값입니다. Simple knob는 이 값과 관계없이 Detailed 작성값에 적용됩니다.

EOverAnimModulePhase

EOverAnimModulePhase는 module을 실행 구획으로 나눕니다. PhaseOrder는 같은 값의 module끼리만 적용되며, Automatic Six-Stage Motion의 Starting Pose·Action 등의 단계 선택값이 아닙니다.

값 · UI 표시명	의미	OverAnim `0.1.0 Beta` 내장 module
`Dynamics` · `Dynamics`	guide bone의 동적 변형을 담당하는 실행 구획입니다.	`Transform Spring`, `Follow Through`, `Bone Scaler`
`Shape` · `Shape`	surface/volume 형태를 바꾸는 실행 구획입니다.	`Mesh Bulge`, `Squash & Stretch`, `Contact Dent + Ring Bulge`, `Joint Volume Corrective`
`Smear` · `Offset / Smear`	offset 또는 smear 계열 변형을 위한 실행 구획입니다.	`Smear`, `Impact Ripple`
`Presentation` · `Presentation`	최종 표현 계열을 위한 public 실행 구획입니다.	이 릴리스의 9개 내장 module은 이 값을 반환하지 않습니다. concrete extension module은 이 Phase를 반환할 수 있습니다.

EOverAnimModuleCompositionMode

EOverAnimModuleCompositionMode는 Module Details의 Input Composition과 CompositionMode 속성의 값입니다. 기본값은 AdditiveOffset입니다.

값 · UI 표시명	입력/합성 의미	Phase · 순서와의 관계
`AdditiveOffset` · `Additive Offset`	module의 displacement를 현재 composed result에 더합니다.	Phase를 선택하거나 `PhaseOrder`를 변경하지 않습니다.
`ReSkinning` · `Re-Skinning`	현재 control-point transform을 입력으로 module을 다시 평가합니다.	Phase를 선택하거나 `PhaseOrder`를 변경하지 않습니다.

Module index

Phase	Module	Signal · Response	Automatic Six-Stage Motion
`Dynamics`	Transform Spring	Position Spring이 켜진 경우 `Pulse`, automatic `Sustained`	조건부 지원
	Follow Through	Signal-enabled driver에서 `Pulse`, `Sustained`	조건부 지원
`Shape`	Mesh Bulge	signal-enabled driver에서 `Pulse`, `Sustained`	조건부 지원
	Squash & Stretch	`Pulse`, `Sustained`	조건부 지원
	Contact Dent + Ring Bulge	valid contact `Pulse`만	지원하지 않음
	Joint Volume Corrective	지원하지 않음	지원하지 않음
`Offset / Smear`	Smear	signal-enabled driver에서 `Pulse`, `Sustained`	조건부 지원
	Impact Ripple	valid contact `Pulse`만	지원하지 않음
`Dynamics`	Bone Scaler	signal-enabled driver에서 `Pulse`, `Sustained`	조건부 지원

Cross-reference

Signal route, activation policy, envelope, module response parameter struct: Response Types
Signal contact/motion input fields: Signal · Impact Types
Region coverage, mask, LOD, module stack ownership: Bone Group · Region
Runtime Blueprint/C++ signal nodes: UOverAnimComponent: Signal과 Impact Signal

Response 대상의 일치

Response Rule은 Signal Name, Bone Group Name, Module Name, Module의 signal support, Response parameter struct, lifecycle/timing 조건을 모두 통과해야 합니다. 한 조건이라도 불일치하면 Signal이 수락되어도 해당 module response는 만들어지지 않습니다.