ue-mcp 1.2.3 → 1.3.0

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/LevelHandlers_Refresh.cpp

@@ -0,0 +1,723 @@
+// Refresh and inspect actions for state the editor caches (#944, #915, #914).
+//
+// Each of these is a case where the editor is holding a stale answer and there
+// was no way to ask it to recompute, or no way to see the number it was
+// actually using.
+//
+//   #944  A placed Blueprint instance keeps the components and defaults it was
+//         constructed with. Changing the SCS or the construction script does
+//         not touch it. blueprint(run_construction_script) only runs against a
+//         TEMPORARY actor, and Python cannot help because
+//         Actor.rerun_construction_scripts() is missing from the wrapper.
+//   #915  Collision built from mesh data the mesh no longer has produced a
+//         line_trace that reported a MISS through solid geometry. A false
+//         negative is the worst answer a trace can give, because nothing about
+//         it looks wrong.
+//   #914  A UBoxComponent's authored BoxExtent was not readable anywhere, only
+//         its scaled bounds, and there was no way to ask whether two
+//         components actually overlap without a physics query that depends on
+//         the collision state #915 is about.
+
+#include "LevelHandlers.h"
+
+#include "Components/ActorComponent.h"
+#include "Components/BoxComponent.h"
+#include "Components/PrimitiveComponent.h"
+#include "Components/SceneComponent.h"
+#include "Dom/JsonObject.h"
+#include "Dom/JsonValue.h"
+#include "Editor.h"
+#include "Engine/EngineTypes.h"
+#include "Engine/World.h"
+#include "EngineUtils.h"
+#include "GameFramework/Actor.h"
+#include "HandlerRegistry.h"
+#include "HandlerUtils.h"
+
+namespace
+{
+	constexpr int32 MCPRefreshMaxActors = 5000;
+	constexpr int32 MCPRefreshMaxResultRows = 500;
+	constexpr int32 MCPRefreshDefaultMaxComponents = 2000;
+	constexpr int32 MCPRefreshHardMaxComponents = 20000;
+	constexpr int32 MCPRefreshMaxSamples = 25;
+
+	const TCHAR* MCPRefreshCollisionName(ECollisionEnabled::Type Value)
+	{
+		switch (Value)
+		{
+		case ECollisionEnabled::NoCollision:     return TEXT("NoCollision");
+		case ECollisionEnabled::QueryOnly:       return TEXT("QueryOnly");
+		case ECollisionEnabled::PhysicsOnly:     return TEXT("PhysicsOnly");
+		case ECollisionEnabled::QueryAndPhysics: return TEXT("QueryAndPhysics");
+		case ECollisionEnabled::ProbeOnly:       return TEXT("ProbeOnly");
+		case ECollisionEnabled::QueryAndProbe:   return TEXT("QueryAndProbe");
+		default:                                 return TEXT("Unknown");
+		}
+	}
+
+	/** An oriented box in world space, built from a component's LOCAL bounds so
+	 *  it keeps the component's orientation. The world bounds are axis-aligned
+	 *  and would answer a different question. */
+	struct FMCPOrientedBox
+	{
+		FVector Center = FVector::ZeroVector;
+		FVector Axis[3] = { FVector::ForwardVector, FVector::RightVector, FVector::UpVector };
+		FVector Extent = FVector::ZeroVector;
+	};
+
+	FMCPOrientedBox MCPBuildOrientedBox(USceneComponent* Component)
+	{
+		FMCPOrientedBox Box;
+		if (!Component)
+		{
+			return Box;
+		}
+		const FTransform Transform = Component->GetComponentTransform();
+		const FBoxSphereBounds LocalBounds = Component->GetLocalBounds();
+		Box.Center = Transform.TransformPosition(LocalBounds.Origin);
+		const FQuat Rotation = Transform.GetRotation();
+		Box.Axis[0] = Rotation.GetAxisX();
+		Box.Axis[1] = Rotation.GetAxisY();
+		Box.Axis[2] = Rotation.GetAxisZ();
+		const FVector Scale = Transform.GetScale3D();
+		Box.Extent = FVector(
+			LocalBounds.BoxExtent.X * FMath::Abs(Scale.X),
+			LocalBounds.BoxExtent.Y * FMath::Abs(Scale.Y),
+			LocalBounds.BoxExtent.Z * FMath::Abs(Scale.Z));
+		return Box;
+	}
+
+	/** Projected radius of an oriented box onto a unit axis. */
+	double MCPProjectedRadius(const FMCPOrientedBox& Box, const FVector& Axis)
+	{
+		return
+			Box.Extent.X * FMath::Abs(FVector::DotProduct(Box.Axis[0], Axis)) +
+			Box.Extent.Y * FMath::Abs(FVector::DotProduct(Box.Axis[1], Axis)) +
+			Box.Extent.Z * FMath::Abs(FVector::DotProduct(Box.Axis[2], Axis));
+	}
+
+	/**
+	 * Separating axis test between two oriented boxes.
+	 *
+	 * Deliberately geometric rather than a physics overlap query: the whole
+	 * reason #914 was filed alongside #915 is that a physics answer depends on
+	 * collision state, and stale collision state is what produced the wrong
+	 * answer in the first place. This reads the transforms and the bounds and
+	 * nothing else.
+	 *
+	 * Returns true when the boxes intersect. OutSeparation is the largest gap
+	 * found along any tested axis when they do not, and OutPenetration is the
+	 * smallest overlap along any tested axis when they do.
+	 */
+	bool MCPOrientedBoxesOverlap(
+		const FMCPOrientedBox& A,
+		const FMCPOrientedBox& B,
+		double& OutSeparation,
+		double& OutPenetration,
+		FVector& OutAxis)
+	{
+		OutSeparation = 0.0;
+		OutPenetration = TNumericLimits<double>::Max();
+		OutAxis = FVector::ZeroVector;
+
+		TArray<FVector, TInlineAllocator<15>> Axes;
+		for (int32 Index = 0; Index < 3; ++Index) Axes.Add(A.Axis[Index]);
+		for (int32 Index = 0; Index < 3; ++Index) Axes.Add(B.Axis[Index]);
+		for (int32 IndexA = 0; IndexA < 3; ++IndexA)
+		{
+			for (int32 IndexB = 0; IndexB < 3; ++IndexB)
+			{
+				const FVector Cross = FVector::CrossProduct(A.Axis[IndexA], B.Axis[IndexB]);
+				// Parallel edge pairs produce a degenerate axis. The six face
+				// normals already cover that case, so skipping it is correct
+				// rather than an approximation.
+				if (Cross.SizeSquared() > UE_KINDA_SMALL_NUMBER)
+				{
+					Axes.Add(Cross.GetSafeNormal());
+				}
+			}
+		}
+
+		const FVector Delta = B.Center - A.Center;
+		bool bOverlapping = true;
+		for (const FVector& Axis : Axes)
+		{
+			if (Axis.IsNearlyZero())
+			{
+				continue;
+			}
+			const FVector Unit = Axis.GetSafeNormal();
+			const double Distance = FMath::Abs(FVector::DotProduct(Delta, Unit));
+			const double Reach = MCPProjectedRadius(A, Unit) + MCPProjectedRadius(B, Unit);
+			const double Gap = Distance - Reach;
+			if (Gap > 0.0)
+			{
+				bOverlapping = false;
+				if (Gap > OutSeparation)
+				{
+					OutSeparation = Gap;
+					OutAxis = Unit;
+				}
+			}
+			else if (bOverlapping && -Gap < OutPenetration)
+			{
+				OutPenetration = -Gap;
+				OutAxis = Unit;
+			}
+		}
+
+		if (!bOverlapping)
+		{
+			OutPenetration = 0.0;
+		}
+		else if (OutPenetration == TNumericLimits<double>::Max())
+		{
+			// Two zero-extent boxes overlap with every separating axis
+			// degenerate, so no axis ever narrowed the seed. Reporting the seed
+			// would hand the caller 1.79e308 as a penetration depth in
+			// centimetres, which reads as a number rather than as "there was
+			// nothing to measure".
+			OutPenetration = 0.0;
+			OutAxis = FVector::ZeroVector;
+		}
+		return bOverlapping;
+	}
+
+	UActorComponent* MCPRefreshFindComponent(AActor* Actor, const FString& ComponentName)
+	{
+		if (!Actor) return nullptr;
+		for (UActorComponent* Component : Actor->GetComponents())
+		{
+			if (Component && Component->GetName().Equals(ComponentName, ESearchCase::IgnoreCase))
+			{
+				return Component;
+			}
+		}
+		return nullptr;
+	}
+
+	TSharedPtr<FJsonObject> MCPRefreshDescribeBounds(const FBoxSphereBounds& Bounds)
+	{
+		TSharedPtr<FJsonObject> Object = MakeShared<FJsonObject>();
+		Object->SetObjectField(TEXT("origin"), MCPVec3ToJsonObject(Bounds.Origin));
+		Object->SetObjectField(TEXT("boxExtent"), MCPVec3ToJsonObject(Bounds.BoxExtent));
+		Object->SetNumberField(TEXT("sphereRadius"), Bounds.SphereRadius);
+		return Object;
+	}
+
+	/** Everything #914 asked to see about one side of the comparison. */
+	TSharedPtr<FJsonObject> MCPRefreshDescribeComponent(USceneComponent* Component)
+	{
+		TSharedPtr<FJsonObject> Object = MakeShared<FJsonObject>();
+		Object->SetStringField(TEXT("componentName"), Component->GetName());
+		Object->SetStringField(TEXT("componentClass"), Component->GetClass()->GetName());
+
+		const FTransform Transform = Component->GetComponentTransform();
+		TSharedPtr<FJsonObject> TransformObject = MakeShared<FJsonObject>();
+		TransformObject->SetObjectField(TEXT("location"), MCPVec3ToJsonObject(Transform.GetLocation()));
+		TransformObject->SetObjectField(TEXT("rotation"), MCPRotatorToJsonObject(Transform.Rotator()));
+		TransformObject->SetObjectField(TEXT("scale"), MCPVec3ToJsonObject(Transform.GetScale3D()));
+		Object->SetObjectField(TEXT("worldTransform"), TransformObject);
+
+		Object->SetObjectField(TEXT("localBounds"), MCPRefreshDescribeBounds(Component->GetLocalBounds()));
+		Object->SetObjectField(TEXT("worldBounds"), MCPRefreshDescribeBounds(Component->GetBounds()));
+
+		// #914's original ask: the UNSCALED authored extent, which is what the
+		// details panel shows and what no existing read returned.
+		if (const UBoxComponent* BoxComponent = Cast<UBoxComponent>(Component))
+		{
+			Object->SetObjectField(TEXT("boxExtentUnscaled"),
+				MCPVec3ToJsonObject(BoxComponent->GetUnscaledBoxExtent()));
+			Object->SetObjectField(TEXT("boxExtentScaled"),
+				MCPVec3ToJsonObject(BoxComponent->GetScaledBoxExtent()));
+		}
+		return Object;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// rerun_construction_scripts (#944)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::RerunConstruction(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+
+	const FString WorldScope = OptionalString(Params, TEXT("world"), TEXT("editor"));
+	UWorld* World = ResolveWorldFromParams(Params, *WorldScope);
+	if (!World)
+	{
+		return MCPError(FString::Printf(TEXT("World not available for scope '%s'"), *WorldScope));
+	}
+
+	TArray<FString> ActorLabels;
+	{
+		const TArray<TSharedPtr<FJsonValue>>* LabelValues = nullptr;
+		if (Params->TryGetArrayField(TEXT("actorLabels"), LabelValues) && LabelValues)
+		{
+			ActorLabels = JsonArrayToStringList(LabelValues);
+		}
+	}
+	const FString ClassSpec = OptionalString(Params, TEXT("className"));
+	if (ActorLabels.IsEmpty() && ClassSpec.IsEmpty())
+	{
+		// Rerunning every construction script in a map destroys and rebuilds
+		// every generated component in it. That is not a default.
+		return MCPError(TEXT("Pass 'actorLabels' or 'className'. This rebuilds generated components, so it will not run against a whole level implicitly."));
+	}
+
+	UClass* ActorClass = nullptr;
+	FString ClassFallback;
+	if (!ClassSpec.IsEmpty())
+	{
+		ActorClass = MCPResolveClassOfType(ClassSpec, AActor::StaticClass(), true);
+		if (!ActorClass)
+		{
+			ClassFallback = ClassSpec;
+		}
+	}
+	const bool bMatchSubclasses = OptionalBool(Params, TEXT("matchSubclasses"), true);
+
+	TArray<AActor*> Targets;
+	TSet<FString> WantedLabels(ActorLabels);
+	TSet<FString> FoundLabels;
+	for (TActorIterator<AActor> It(World); It; ++It)
+	{
+		AActor* Actor = *It;
+		if (!Actor) continue;
+
+		bool bMatches = false;
+		const FString Label = Actor->GetActorLabel();
+		if (WantedLabels.Contains(Label))
+		{
+			bMatches = true;
+			FoundLabels.Add(Label);
+		}
+		if (!bMatches && ActorClass)
+		{
+			bMatches = bMatchSubclasses ? Actor->IsA(ActorClass) : (Actor->GetClass() == ActorClass);
+		}
+		if (!bMatches && !ClassFallback.IsEmpty())
+		{
+			bMatches = Actor->GetClass()->GetName().Contains(ClassFallback, ESearchCase::IgnoreCase);
+		}
+		if (bMatches)
+		{
+			Targets.Add(Actor);
+		}
+	}
+	if (Targets.Num() > MCPRefreshMaxActors)
+	{
+		return MCPError(FString::Printf(
+			TEXT("Matched %d actors, over the maximum of %d. Narrow the selector."),
+			Targets.Num(), MCPRefreshMaxActors));
+	}
+	Targets.Sort([](const AActor& A, const AActor& B) { return A.GetPathName() < B.GetPathName(); });
+
+	int32 Reran = 0;
+	int32 WithoutScript = 0;
+	TArray<FString> Failed;
+	TArray<FString> Samples;
+
+#if WITH_EDITOR
+	for (AActor* Actor : Targets)
+	{
+		if (!IsValid(Actor))
+		{
+			// Do not call GetName() on the pointer the guard just rejected. A
+			// garbage-but-unfreed UObject happens to answer today, which is
+			// exactly why this would survive testing and then not survive a
+			// real collection.
+			Failed.Add(TEXT("an actor in the selection is pending destruction"));
+			continue;
+		}
+		// An actor with no user construction script still gets its generated
+		// components rebuilt, so this is reported rather than skipped: a
+		// caller expecting a Blueprint change to land needs to know it hit an
+		// actor whose class has no script to run.
+		if (!Actor->HasNonTrivialUserConstructionScript())
+		{
+			++WithoutScript;
+		}
+		Actor->Modify();
+		Actor->RerunConstructionScripts();
+		++Reran;
+		if (Samples.Num() < MCPRefreshMaxSamples)
+		{
+			Samples.Add(FString::Printf(TEXT("%s (%s)"), *Actor->GetActorLabel(), *Actor->GetClass()->GetName()));
+		}
+	}
+#else
+	for (AActor* Actor : Targets)
+	{
+		Failed.Add(FString::Printf(
+			TEXT("%s: RerunConstructionScripts is editor-only"), *Actor->GetActorLabel()));
+	}
+#endif
+
+	TArray<FString> MissingLabels;
+	for (const FString& Label : ActorLabels)
+	{
+		if (!FoundLabels.Contains(Label))
+		{
+			MissingLabels.Add(Label);
+		}
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("success"), Failed.IsEmpty() && MissingLabels.IsEmpty());
+	if (!MissingLabels.IsEmpty())
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d requested actor label(s) matched nothing in this world; see missingLabels."),
+			MissingLabels.Num()));
+	}
+	Result->SetNumberField(TEXT("matched"), Targets.Num());
+	Result->SetNumberField(TEXT("reran"), Reran);
+	Result->SetNumberField(TEXT("actorsWithNoUserConstructionScript"), WithoutScript);
+	Result->SetArrayField(TEXT("failed"), MCPStringListToJson(Failed));
+	Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(MissingLabels));
+	Result->SetArrayField(TEXT("samples"), MCPStringListToJson(Samples));
+	if (Reran > 0)
+	{
+		MCPSetUpdated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("Reconstructed actors leave the level dirty and it is NOT saved. Call level(save) when you are done."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// recreate_physics_state (#915)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::RecreatePhysicsState(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+
+	const FString WorldScope = OptionalString(Params, TEXT("world"), TEXT("editor"));
+	UWorld* World = ResolveWorldFromParams(Params, *WorldScope);
+	if (!World)
+	{
+		return MCPError(FString::Printf(TEXT("World not available for scope '%s'"), *WorldScope));
+	}
+
+	TArray<FString> ActorLabels;
+	{
+		const TArray<TSharedPtr<FJsonValue>>* LabelValues = nullptr;
+		if (Params->TryGetArrayField(TEXT("actorLabels"), LabelValues) && LabelValues)
+		{
+			ActorLabels = JsonArrayToStringList(LabelValues);
+		}
+	}
+	const FString LabelPrefix = OptionalString(Params, TEXT("labelPrefix"));
+	const FString Tag = OptionalString(Params, TEXT("tag"));
+	const FString ActorClassSpec = OptionalString(Params, TEXT("classFilter"));
+	const FString ComponentClassSpec = OptionalString(Params, TEXT("componentClass"));
+	const FString ComponentNameContains = OptionalString(Params, TEXT("componentNameContains"));
+
+	if (ActorLabels.IsEmpty() && LabelPrefix.IsEmpty() && Tag.IsEmpty() &&
+		ActorClassSpec.IsEmpty() && ComponentClassSpec.IsEmpty() && ComponentNameContains.IsEmpty())
+	{
+		// A world-wide physics rebuild is a long, disruptive operation, and the
+		// bug this action exists for is always localised to the meshes that
+		// changed. Refusing an unbounded call is the point.
+		return MCPError(TEXT("Pass at least one bound: actorLabels, labelPrefix, tag, classFilter, componentClass or componentNameContains. This never refreshes a whole world implicitly."));
+	}
+
+	UClass* ActorClass = nullptr;
+	if (!ActorClassSpec.IsEmpty())
+	{
+		ActorClass = MCPResolveClassOfType(ActorClassSpec, AActor::StaticClass(), true);
+		if (!ActorClass)
+		{
+			return MCPClassNotFoundError(ActorClassSpec, TEXT("classFilter"));
+		}
+	}
+	UClass* ComponentClass = nullptr;
+	if (!ComponentClassSpec.IsEmpty())
+	{
+		ComponentClass = MCPResolveClassOfType(ComponentClassSpec, UActorComponent::StaticClass(), true);
+		if (!ComponentClass)
+		{
+			return MCPClassNotFoundError(ComponentClassSpec, TEXT("componentClass"));
+		}
+	}
+
+	// dryRun defaults to TRUE: this is the preflight #915 asked for. Seeing
+	// which components are about to be rebuilt, and what their collision state
+	// is now, is most of the value.
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), true);
+	const int32 MaxComponents = FMath::Clamp(
+		OptionalInt(Params, TEXT("maxComponents"), MCPRefreshDefaultMaxComponents),
+		1, MCPRefreshHardMaxComponents);
+
+	TSet<FString> WantedLabels(ActorLabels);
+	TSet<FString> FoundLabels;
+	TArray<UPrimitiveComponent*> Targets;
+	for (TActorIterator<AActor> It(World); It; ++It)
+	{
+		AActor* Actor = *It;
+		if (!Actor) continue;
+		const FString Label = Actor->GetActorLabel();
+
+		if (!WantedLabels.IsEmpty())
+		{
+			if (!WantedLabels.Contains(Label)) continue;
+			FoundLabels.Add(Label);
+		}
+		if (!LabelPrefix.IsEmpty() && !Label.StartsWith(LabelPrefix, ESearchCase::CaseSensitive)) continue;
+		if (!Tag.IsEmpty() && !Actor->ActorHasTag(FName(*Tag))) continue;
+		if (ActorClass && !Actor->IsA(ActorClass)) continue;
+
+		for (UActorComponent* Component : Actor->GetComponents())
+		{
+			UPrimitiveComponent* Primitive = Cast<UPrimitiveComponent>(Component);
+			if (!Primitive) continue;
+			if (ComponentClass && !Primitive->IsA(ComponentClass)) continue;
+			if (!ComponentNameContains.IsEmpty() &&
+				!Primitive->GetName().Contains(ComponentNameContains, ESearchCase::IgnoreCase))
+			{
+				continue;
+			}
+			Targets.Add(Primitive);
+		}
+	}
+
+	Targets.Sort([](const UPrimitiveComponent& A, const UPrimitiveComponent& B)
+	{
+		return A.GetPathName() < B.GetPathName();
+	});
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetNumberField(TEXT("matchedComponents"), Targets.Num());
+
+	TArray<FString> MissingLabels;
+	for (const FString& Label : ActorLabels)
+	{
+		if (!FoundLabels.Contains(Label)) MissingLabels.Add(Label);
+	}
+	if (!MissingLabels.IsEmpty())
+	{
+		Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(MissingLabels));
+	}
+
+	if (Targets.Num() > MaxComponents)
+	{
+		Result->SetBoolField(TEXT("success"), false);
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("Matched %d components, over maxComponents (%d). Narrow the bounds or raise it deliberately."),
+			Targets.Num(), MaxComponents));
+		return MCPResult(Result);
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Recreated = 0;
+	int32 PhysicsStateAfter = 0;
+	int32 NoCollisionCount = 0;
+	TMap<FString, int32> CollisionSummary;
+
+	for (UPrimitiveComponent* Primitive : Targets)
+	{
+		const ECollisionEnabled::Type Before = Primitive->GetCollisionEnabled();
+		const bool bStateBefore = Primitive->IsPhysicsStateCreated();
+
+		if (!bDryRun)
+		{
+			Primitive->RecreatePhysicsState();
+			++Recreated;
+		}
+
+		const ECollisionEnabled::Type After = Primitive->GetCollisionEnabled();
+		const bool bStateAfter = Primitive->IsPhysicsStateCreated();
+		if (bStateAfter) ++PhysicsStateAfter;
+		if (After == ECollisionEnabled::NoCollision) ++NoCollisionCount;
+		++CollisionSummary.FindOrAdd(MCPRefreshCollisionName(After));
+
+		if (Rows.Num() < MCPRefreshMaxResultRows)
+		{
+			TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+			Row->SetStringField(TEXT("actorLabel"), Primitive->GetOwner() ? Primitive->GetOwner()->GetActorLabel() : FString());
+			Row->SetStringField(TEXT("componentName"), Primitive->GetName());
+			Row->SetStringField(TEXT("componentClass"), Primitive->GetClass()->GetName());
+			Row->SetStringField(TEXT("status"), bDryRun ? TEXT("would_recreate") : TEXT("recreated"));
+			Row->SetStringField(TEXT("collisionEnabledBefore"), MCPRefreshCollisionName(Before));
+			Row->SetStringField(TEXT("collisionEnabledAfter"), MCPRefreshCollisionName(After));
+			Row->SetStringField(TEXT("collisionProfile"), Primitive->GetCollisionProfileName().ToString());
+			Row->SetBoolField(TEXT("physicsStateCreatedBefore"), bStateBefore);
+			Row->SetBoolField(TEXT("physicsStateCreatedAfter"), bStateAfter);
+			Row->SetBoolField(TEXT("registered"), Primitive->IsRegistered());
+			Rows.Add(MakeShared<FJsonValueObject>(Row));
+		}
+	}
+
+	TSharedPtr<FJsonObject> Summary = MakeShared<FJsonObject>();
+	for (const TPair<FString, int32>& Pair : CollisionSummary)
+	{
+		Summary->SetNumberField(Pair.Key, Pair.Value);
+	}
+
+	Result->SetNumberField(bDryRun ? TEXT("wouldRecreate") : TEXT("recreated"),
+		bDryRun ? Targets.Num() : Recreated);
+	Result->SetNumberField(TEXT("physicsStateCreated"), PhysicsStateAfter);
+	Result->SetNumberField(TEXT("componentsWithNoCollision"), NoCollisionCount);
+	Result->SetObjectField(TEXT("collisionSummary"), Summary);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Targets.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (Targets.IsEmpty())
+	{
+		Result->SetStringField(TEXT("zeroMatchNote"),
+			TEXT("Nothing matched. The bounds are AND-ed: an actor selector and a componentClass must both hold. Check with level(query_components, countOnly:true) using the same filters."));
+	}
+	if (bDryRun)
+	{
+		Result->SetStringField(TEXT("dryRunNote"),
+			TEXT("dryRun defaults to TRUE for this action: the preflight shows which components would be rebuilt and their current collision state. Pass dryRun=false to rebuild them."));
+	}
+	else
+	{
+		Result->SetStringField(TEXT("traceNote"),
+			TEXT("Re-run the trace that gave the wrong answer. A false-negative line_trace caused by stale collision looks exactly like a real miss, so the only proof this worked is the trace."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// test_component_overlap (#914)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::TestComponentOverlap(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+
+	const FString WorldScope = OptionalString(Params, TEXT("world"), TEXT("editor"));
+	UWorld* World = ResolveWorldFromParams(Params, *WorldScope);
+	if (!World)
+	{
+		return MCPError(FString::Printf(TEXT("World not available for scope '%s'"), *WorldScope));
+	}
+
+	FString ActorLabelA;
+	if (auto Err = RequireStringAlt(Params, TEXT("actorLabelA"), TEXT("actorPathA"), ActorLabelA)) return Err;
+	FString ActorLabelB;
+	if (auto Err = RequireStringAlt(Params, TEXT("actorLabelB"), TEXT("actorPathB"), ActorLabelB)) return Err;
+	const FString ComponentNameA = OptionalString(Params, TEXT("componentNameA"));
+	const FString ComponentNameB = OptionalString(Params, TEXT("componentNameB"));
+
+	FString Method = OptionalString(Params, TEXT("method"), TEXT("OBB")).ToUpper();
+	if (Method != TEXT("OBB") && Method != TEXT("AABB"))
+	{
+		return MCPError(TEXT("'method' must be either 'OBB' (oriented, default) or 'AABB' (axis-aligned world bounds)"));
+	}
+
+	// #983: each side is selected by its own label / path pair, so an overlap
+	// test between two copy-pasted props refuses rather than answering about
+	// two actors the caller did not name.
+	auto ResolveSide = [&](const TCHAR* LabelKey, const TCHAR* PathKey, const FString& ComponentName,
+		USceneComponent*& OutComponent, AActor*& OutActor, TSharedPtr<FJsonValue>& OutError) -> bool
+	{
+		FMCPActorSelector Selector;
+		Selector.LabelKey = LabelKey;
+		Selector.PathKey = PathKey;
+		AActor* Actor = MCPResolveActor(World, Params, OutError, Selector);
+		if (!Actor) return false;
+		OutActor = Actor;
+		const FString ActorLabel = Actor->GetActorLabel();
+		if (ComponentName.IsEmpty())
+		{
+			OutComponent = Actor->GetRootComponent();
+			if (!OutComponent)
+			{
+				OutError = MCPError(FString::Printf(TEXT("Actor '%s' has no root component"), *ActorLabel));
+				return false;
+			}
+			return true;
+		}
+		UActorComponent* Component = MCPRefreshFindComponent(Actor, ComponentName);
+		OutComponent = Cast<USceneComponent>(Component);
+		if (!OutComponent)
+		{
+			OutError = MCPError(FString::Printf(
+				TEXT("No SceneComponent named '%s' on actor '%s'"), *ComponentName, *ActorLabel));
+			return false;
+		}
+		return true;
+	};
+
+	USceneComponent* ComponentA = nullptr;
+	USceneComponent* ComponentB = nullptr;
+	AActor* ActorA = nullptr;
+	AActor* ActorB = nullptr;
+	TSharedPtr<FJsonValue> ResolveError;
+	if (!ResolveSide(TEXT("actorLabelA"), TEXT("actorPathA"), ComponentNameA, ComponentA, ActorA, ResolveError)) return ResolveError;
+	if (!ResolveSide(TEXT("actorLabelB"), TEXT("actorPathB"), ComponentNameB, ComponentB, ActorB, ResolveError)) return ResolveError;
+	if (ComponentA == ComponentB)
+	{
+		return MCPError(TEXT("Both sides resolved to the same component; an overlap test between a component and itself has no answer"));
+	}
+	ActorLabelA = ActorA->GetActorLabel();
+	ActorLabelB = ActorB->GetActorLabel();
+
+	auto Result = MCPSuccess();
+	Result->SetStringField(TEXT("method"), Method);
+	Result->SetStringField(TEXT("actorLabelA"), ActorLabelA);
+	Result->SetStringField(TEXT("actorPathA"), ActorA->GetPathName());
+	Result->SetStringField(TEXT("actorLabelB"), ActorLabelB);
+	Result->SetStringField(TEXT("actorPathB"), ActorB->GetPathName());
+
+	TSharedPtr<FJsonObject> SideA = MCPRefreshDescribeComponent(ComponentA);
+	SideA->SetStringField(TEXT("actorLabel"), ActorLabelA);
+	SideA->SetStringField(TEXT("actorPath"), ActorA->GetPathName());
+	TSharedPtr<FJsonObject> SideB = MCPRefreshDescribeComponent(ComponentB);
+	SideB->SetStringField(TEXT("actorLabel"), ActorLabelB);
+	SideB->SetStringField(TEXT("actorPath"), ActorB->GetPathName());
+	Result->SetObjectField(TEXT("a"), SideA);
+	Result->SetObjectField(TEXT("b"), SideB);
+
+	bool bOverlap = false;
+	double Separation = 0.0;
+	double Penetration = 0.0;
+	FVector Axis = FVector::ZeroVector;
+
+	if (Method == TEXT("AABB"))
+	{
+		const FBox BoxA = ComponentA->GetBounds().GetBox();
+		const FBox BoxB = ComponentB->GetBounds().GetBox();
+		bOverlap = BoxA.Intersect(BoxB);
+		// Per-axis gap or overlap depth, which is what a caller tuning a
+		// placement actually wants back.
+		FVector PerAxis = FVector::ZeroVector;
+		for (int32 Index = 0; Index < 3; ++Index)
+		{
+			const double Gap = FMath::Max(
+				BoxA.Min[Index] - BoxB.Max[Index],
+				BoxB.Min[Index] - BoxA.Max[Index]);
+			PerAxis[Index] = Gap;
+		}
+		if (bOverlap)
+		{
+			// Every axis gap is negative when they intersect; the shallowest
+			// is the penetration depth.
+			Penetration = -FMath::Max3(PerAxis.X, PerAxis.Y, PerAxis.Z);
+		}
+		else
+		{
+			Separation = FMath::Max3(PerAxis.X, PerAxis.Y, PerAxis.Z);
+		}
+		Result->SetObjectField(TEXT("perAxisGap"), MCPVec3ToJsonObject(PerAxis));
+	}
+	else
+	{
+		const FMCPOrientedBox BoxA = MCPBuildOrientedBox(ComponentA);
+		const FMCPOrientedBox BoxB = MCPBuildOrientedBox(ComponentB);
+		bOverlap = MCPOrientedBoxesOverlap(BoxA, BoxB, Separation, Penetration, Axis);
+		Result->SetObjectField(TEXT("separatingAxis"), MCPVec3ToJsonObject(Axis));
+	}
+
+	Result->SetBoolField(TEXT("overlap"), bOverlap);
+	Result->SetNumberField(TEXT("separation"), bOverlap ? 0.0 : Separation);
+	Result->SetNumberField(TEXT("penetration"), bOverlap ? Penetration : 0.0);
+	Result->SetStringField(TEXT("note"),
+		TEXT("This is a geometric test over the components' bounds and transforms. It deliberately does not run a physics overlap query, because a physics answer depends on collision state and stale collision state is what makes a trace lie. Use level(recreate_physics_state) when you need the physics answer to agree."));
+	return MCPResult(Result);
+}