Merge pull request #256 from EmbarrassingMoment/v.1.2.0

V.1.2.0

Author: EmbarrassingMoment

CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [Unreleased]
+
+## [1.2.0] - 2026-05-03
+
+### Added
+
+**Built-in Effects (+1, total 26)**
+- **Diamond Band Wipe** — A dynamic transition where a diamond-shaped band expands from the center, splitting apart to reveal the underlying scene.
+
+**Sequence System**
+- `UTransitionSequence` data asset for chaining multiple transitions back-to-back.
+- `PlaySequence` / `StopSequence` / `IsSequencePlaying` / `GetCurrentSequenceStep` API on `UTransitionManagerSubsystem`.
+- `PlaySequenceAndWait` latent Blueprint node.
+- `OnSequenceCompleted` and `OnSequenceStepChanged` delegates.
+
+### Fixed
+
+- Fixed a one-frame background flash between sequence steps caused by the previous step's PostProcessVolume being destroyed before the next step's effect was initialized. During a sequence, the effect now hot-swaps across steps and is only torn down when the full sequence completes.
+- Fixed an issue where an incorrect material instance was set for DA_FadeToBlack.
+- Refactoring to a more efficient node configuration for M_Transition_Diamond.
+
+---
+
 ## [1.1.0] - 2026-04-09
 
 ### Added

CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Setup
+
+This is an Unreal Engine 5.5 plugin project. There are no CLI build scripts — all compilation happens through the UE editor or Visual Studio 2022.
+
+**Setup steps:**
+1. Right-click `TransitionFX_Dev.uproject` → **Generate Visual Studio project files**
+2. Open `TransitionFX_Dev.uproject` in UE 5.5; click **Yes** to rebuild missing modules
+3. First launch compiles shaders (several minutes)
+
+**Requirements:** Visual Studio 2022 (C++ Game Development workload), UE 5.5+, Windows with DX12/SM6 GPU.
+
+**Testing:** No automated test suite. Test manually using:
+- The `L_ShowCase` level (showcases all 26 transition effects)
+- The in-editor **Transition Preview Panel** (real-time playback with easing/duration controls)
+
+## Architecture
+
+TransitionFX is a **data-driven, GameInstance-scoped** transition system built on two C++ modules:
+
+### Module Boundaries
+
+| Module | Path | Role |
+|--------|------|------|
+| `TransitionFX` (Runtime) | `Plugins/TransitionFX/Source/TransitionFX/` | Core state machine, effect rendering, Blueprint API |
+| `TransitionFXEditor` (Editor) | `Plugins/TransitionFX/Source/TransitionFXEditor/` | Preview panel, GIF exporter, asset type actions |
+
+### Data Flow
+
+```
+Blueprint / C++ call
+        ↓
+UTransitionBlueprintLibrary  (latent actions — PlayTransitionAndWait, OpenLevelWithTransition)
+        ↓
+UTransitionManagerSubsystem  (GameInstance subsystem — state machine, pooling, event broadcasting)
+        ↓
+ITransitionEffect / UPostProcessTransitionEffect  (PostProcess volume + dynamic material instance)
+        ↓
+Material parameter "Progress" [0.0→1.0] drives SDF shader on screen
+```
+
+### Core Classes
+
+| Class | File | Role |
+|-------|------|------|
+| `UTransitionManagerSubsystem` | `Public/TransitionManagerSubsystem.h` | Central tick-driven state machine; manages effect pool, audio, input blocking, level transitions, and sequences |
+| `UTransitionPreset` | `Public/TransitionPreset.h` | Data Asset holding all config: effect class, material, duration, easing, audio, input blocking |
+| `ITransitionEffect` | `Public/ITransitionEffect.h` | Interface for effect implementations (`Initialize`, `UpdateProgress`, `Cleanup`, `SetInvert`) |
+| `UPostProcessTransitionEffect` | `Public/PostProcessTransitionEffect.h` | Concrete implementation: creates a PostProcess volume + dynamic material instance |
+| `UTransitionBlueprintLibrary` | `Public/TransitionBlueprintLibrary.h` | Blueprint-callable latent actions and helper nodes |
+| `UTransitionSequence` | `Public/TransitionSequence.h` | Data Asset for chaining multiple transitions; each `FTransitionSequenceEntry` holds preset, mode, duration override, delay |
+| `UTransitionFXConfig` | `Public/TransitionFXConfig.h` | Compile-time constants: material parameter names (`Progress`, `Invert`, `TransitionColor`), default asset path |
+
+### Effect Pool
+
+`UTransitionManagerSubsystem` maintains a `TMap<UClass*, FTransitionEffectPool>` capped at **3 instances per class**. Always return effects to the pool via `CleanupAndPoolCurrentEffect()` — never destroy them directly.
+
+### Easing
+
+Easing is applied in the subsystem's `Tick()` using `ETransitionEasing` (12+ built-in curves + `UCurveFloat` custom). The raw `[0,1]` progress is eased before being written to the material's `Progress` parameter.
+
+### Level Transition Pattern
+
+`OpenLevelWithTransition()` uses a two-step delegate chain:
+1. Fade-out completes → `OnLevelTransitionFadeOutFinished()` opens the level
+2. `OnPostLoadMapWithWorld()` fires → auto-reverse fade-in plays
+
+`PrepareAutoReverseTransition()` stores state so it survives level unload.
+
+### Sequence System (Phase 1, unreleased v1.2.0)
+
+Sequence logic lives inline in `UTransitionManagerSubsystem` with a comment marking it for extraction into a `UTransitionSequencePlayer` in Phase 2. The `bIsDispatchingSequenceStep` flag prevents external `StartTransition()` calls from interrupting internal sequence steps.
+
+## Key Files
+
+```
+Plugins/TransitionFX/
+├── Source/TransitionFX/
+│   ├── Public/
+│   │   ├── TransitionManagerSubsystem.h   ← all public API + delegates
+│   │   ├── TransitionPreset.h             ← data asset schema
+│   │   ├── ITransitionEffect.h            ← effect interface
+│   │   ├── TransitionBlueprintLibrary.h   ← Blueprint nodes
+│   │   ├── TransitionSequence.h           ← sequence data asset
+│   │   └── TransitionFXConfig.h           ← material param name constants
+│   └── Private/
+│       ├── TransitionManagerSubsystem.cpp ← ~1,000 LOC, core tick loop
+│       └── TransitionBlueprintLibrary.cpp ← latent action implementations
+├── Source/TransitionFXEditor/
+│   ├── Public/TransitionPreviewPanel.h    ← editor preview UI
+│   └── Private/
+│       ├── STransitionPreviewPanel.cpp    ← preview panel (800+ LOC)
+│       └── GifEncoder.cpp                ← GIF89a encoder for docs
+└── Content/
+    ├── Data/          ← 26 DA_*.uasset transition presets
+    ├── Materials/     ← M_Transition_*.uasset master materials + instances
+    └── MaterialFunctions/  ← 9 reusable SDF helper functions
+```
+
+## Conventions
+
+- **PCH**: `PCHUsage = UseExplicitOrSharedPCHs` — always include the module's own header explicitly.
+- **UPROPERTY Transient**: All runtime state (pool, current effect, audio component) uses `UPROPERTY(Transient)` to avoid serialization.
+- **Weak pointers for cache**: `TWeakObjectPtr` for `CachedPlayerController` to handle destruction safely.
+- **Category**: All `UFUNCTION`/`UPROPERTY` use `Category = "TransitionFX"` or `"TransitionFX|Sequence"`.
+- **No Blueprint-only builds assumption**: The plugin must work for both Blueprint-only and C++ projects; keep all required logic in the Runtime module.
+
+## Platform & Compatibility Notes
+
+- **Win64 only** (DX12 SM6). Console and mobile are untested — SDF effects are GPU-bound.
+- **Not compatible with UEFN** (Unreal Editor for Fortnite).
+- **PostProcess limitation**: Transitions do not cover UMG/Slate UI layers.
+- **Single active transition**: One subsystem per GameInstance; no simultaneous transitions.
+- **No multiplayer replication**: Operates locally per client.
+
+## CI/CD
+
+`.github/workflows/release.yml` triggers on version tags (`v*`) to build a distribution ZIP (excluding binaries/intermediates), parse CHANGELOG.md, and publish a GitHub release.

Content/SampleLevel/L_ShowCase.umap

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d5020cbd4c2ff9c727b3ead625180a79ed02cf69bc99ac01ca16001fc06ee48f
-size 116343
+oid sha256:b9a6f18b6f744d80dada5355d3041c7950da5d8a4f6d6e5e70b882ea8d267a0f
+size 116495

Plugins/TransitionFX/Content/Data/DA_DiamondWipe.uasset

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a0ad4dd189c61e83f55bad8c69ebeae1c1d9438326139ff1a42b1ab8b01ccf5
+size 1834

Plugins/TransitionFX/Content/Data/DA_FadeToBlack.uasset

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3c3e6df04cac4355017c6b460f9191367ee7bba3cbbfa868e779a62c57665e5f
+oid sha256:0866cf0701d1d7b732e174fb3e009c284c1b9e5a9e5988261b74ca5f3997e596
 size 1820

Plugins/TransitionFX/Content/Materials/Instances/MI_Transition_DiamondWipe.uasset

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f51112d4b979001030eba9850b5e37e82423146af8b4740836edb9a43cf9fa51
+size 5413

Plugins/TransitionFX/Content/Materials/M_Transition_Diamond.uasset

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:569f6f3b20fc878b3adf235e3064eb5c3dbfb5ba69d0c94a79866c28a6dfebd0
-size 28694
+oid sha256:8c6aeb05b2aae4b5087b1818fd0bf493573cb5c61885fe74c654f7bb8c9afde0
+size 32347

Plugins/TransitionFX/Content/Materials/M_Transition_DiamondWipe.uasset

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aa0c024b920b087cb545c89255dd5155a0406d6756c8cf039de18d85b24992b1
+size 38355

Plugins/TransitionFX/Source/TransitionFX/Private/TransitionBlueprintLibrary.cpp

@@ -6,6 +6,7 @@
 #include "LatentActions.h"
 #include "TransitionFXConfig.h"
 #include "TransitionManagerSubsystem.h"
+#include "TransitionSequence.h"
 #include "Engine/Engine.h"
 #include "Engine/World.h"
 #include "Kismet/GameplayStatics.h"
@@ -127,6 +128,46 @@ class FOpenLevelTransitionLatentAction : public FPendingLatentAction
 #endif
 };
 
+/**
+ * Latent action that polls the transition manager and completes when the
+ * currently playing sequence finishes or the manager becomes invalid.
+ */
+class FTransitionSequenceLatentAction : public FPendingLatentAction
+{
+public:
+	FLatentActionInfo ExecutionFunction;
+	int32 OutputLink;
+	FWeakObjectPtr CallbackTarget;
+	TWeakObjectPtr<UTransitionManagerSubsystem> Manager;
+
+	FTransitionSequenceLatentAction(const FLatentActionInfo& InLatentInfo, UTransitionManagerSubsystem* InManager)
+		: ExecutionFunction(InLatentInfo)
+		, OutputLink(InLatentInfo.Linkage)
+		, CallbackTarget(InLatentInfo.CallbackTarget)
+		, Manager(InManager)
+	{
+	}
+
+	virtual void UpdateOperation(FLatentResponse& Response) override
+	{
+		bool bFinished = true;
+
+		if (Manager.IsValid())
+		{
+			bFinished = !Manager->IsSequencePlaying();
+		}
+
+		Response.FinishAndTriggerIf(bFinished, ExecutionFunction.ExecutionFunction, OutputLink, CallbackTarget);
+	}
+
+#if WITH_EDITOR
+	virtual FString GetDescription() const override
+	{
+		return TEXT("Waiting for transition sequence...");
+	}
+#endif
+};
+
 /** Starts a transition and registers a latent action that completes when the transition finishes. */
 void UTransitionBlueprintLibrary::PlayTransitionAndWait(const UObject* WorldContextObject, UTransitionPreset* Preset, ETransitionMode Mode, float PlaySpeed, bool bInvert, FTransitionParameters OverrideParams, struct FLatentActionInfo LatentInfo)
 {
@@ -387,6 +428,45 @@ void UTransitionBlueprintLibrary::OpenLevelWithTransitionAndWait(const UObject*
 	}
 }
 
+/**
+ * Starts a transition sequence and registers a latent action that completes
+ * when the sequence finishes. If Sequence is null or has no entries, the
+ * latent action finishes on the next poll to avoid hanging Blueprints.
+ */
+void UTransitionBlueprintLibrary::PlaySequenceAndWait(const UObject* WorldContextObject, UTransitionSequence* Sequence, struct FLatentActionInfo LatentInfo)
+{
+	UWorld* World = GEngine ? GEngine->GetWorldFromContextObject(WorldContextObject, EGetWorldErrorMode::LogAndReturnNull) : nullptr;
+	if (!World)
+	{
+		return;
+	}
+
+	FLatentActionManager& LatentActionManager = World->GetLatentActionManager();
+	if (LatentActionManager.FindExistingAction<FTransitionSequenceLatentAction>(LatentInfo.CallbackTarget, LatentInfo.UUID) != nullptr)
+	{
+		return;
+	}
+
+	UTransitionManagerSubsystem* Manager = World->GetGameInstance() ? World->GetGameInstance()->GetSubsystem<UTransitionManagerSubsystem>() : nullptr;
+
+	if (!Sequence || Sequence->Entries.Num() == 0)
+	{
+		UE_LOG(LogTransitionFX, Warning, TEXT("PlaySequenceAndWait: Sequence is null or empty. Finishing immediately."));
+		// Passing nullptr causes FTransitionSequenceLatentAction::UpdateOperation to return true on first poll.
+		LatentActionManager.AddNewAction(LatentInfo.CallbackTarget, LatentInfo.UUID, new FTransitionSequenceLatentAction(LatentInfo, nullptr));
+		return;
+	}
+
+	if (!Manager)
+	{
+		LatentActionManager.AddNewAction(LatentInfo.CallbackTarget, LatentInfo.UUID, new FTransitionSequenceLatentAction(LatentInfo, nullptr));
+		return;
+	}
+
+	Manager->PlaySequence(Sequence);
+	LatentActionManager.AddNewAction(LatentInfo.CallbackTarget, LatentInfo.UUID, new FTransitionSequenceLatentAction(LatentInfo, Manager));
+}
+
 /** Converts duration to play speed, starts the transition, and registers a latent action for completion. */
 void UTransitionBlueprintLibrary::PlayTransitionAndWaitWithDuration(const UObject* WorldContextObject, UTransitionPreset* Preset, ETransitionMode Mode, float Duration, bool bInvert, FTransitionParameters OverrideParams, struct FLatentActionInfo LatentInfo)
 {