ue-mcp 1.2.4 → 1.3.0

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

@@ -20,6 +20,29 @@
 
 namespace
 {
+	/**
+	 * #933: the world a trace runs in, taken from the request's own `world`
+	 * (editor|pie|game|auto) plus `pieInstance`, through ResolveWorldFromParams -
+	 * the one resolver every other world-scoped action in this category already
+	 * goes through. Written once here because all three trace actions need it and
+	 * a second copy of the resolution is how the two would drift apart again.
+	 *
+	 * On failure OutError carries the response to return, so the caller does not
+	 * restate the message and the three actions cannot disagree about it.
+	 */
+	static UWorld* ResolveTraceWorld(const TSharedPtr<FJsonObject>& Params, TSharedPtr<FJsonValue>& OutError)
+	{
+		const FString Scope = OptionalString(Params, TEXT("world"), TEXT("editor"));
+		UWorld* World = ResolveWorldFromParams(Params, *Scope);
+		if (!World)
+		{
+			OutError = MCPError(FString::Printf(
+				TEXT("World not available for scope '%s'. world='pie' needs a running PIE session; see editor(list_pie_instances)."),
+				*Scope));
+		}
+		return World;
+	}
+
 	/**
 	 * Channel display names come from the project's collision settings, so a project
 	 * that renamed GameTraceChannel1 to "Weapon" can be traced by that name. The
@@ -90,6 +113,20 @@ namespace
 		return FString::Join(Names, TEXT(", "));
 	}
 
+	/** Which world answered: "editor", "pie", "game" or "other". */
+	static FString DescribeTracedWorld(const UWorld* World)
+	{
+		if (!World) return TEXT("none");
+		switch (World->WorldType)
+		{
+			case EWorldType::Editor:        return TEXT("editor");
+			case EWorldType::EditorPreview: return TEXT("editorPreview");
+			case EWorldType::PIE:           return TEXT("pie");
+			case EWorldType::Game:          return TEXT("game");
+			default:                        return TEXT("other");
+		}
+	}
+
 	static void EmitHitFields(TSharedPtr<FJsonObject> Result, const FHitResult& Hit)
 	{
 		AActor* HitActor = Hit.GetActor();
@@ -97,6 +134,9 @@ namespace
 		if (HitActor)
 		{
 			Result->SetStringField(TEXT("actorLabel"), HitActor->GetActorLabel());
+			// #983: a trace hit is exactly where a caller needs the precise
+			// selector, since it did not choose the actor at all.
+			Result->SetStringField(TEXT("actorPath"), HitActor->GetPathName());
 			Result->SetStringField(TEXT("actorClass"), HitActor->GetClass()->GetName());
 		}
 		if (HitComp)
@@ -115,92 +155,170 @@ namespace
 		if (Hit.BoneName != NAME_None) Result->SetStringField(TEXT("boneName"), Hit.BoneName.ToString());
 		if (Hit.PhysMaterial.IsValid()) Result->SetStringField(TEXT("physicalMaterial"), Hit.PhysMaterial->GetPathName());
 	}
+
+	/** One line_trace. Shared by the single-item handler and bulk_line_trace. */
+	static TSharedPtr<FJsonValue> ExecuteLineTrace(UWorld* World, const TSharedPtr<FJsonObject>& Params)
+	{
+		if (!Params->HasField(TEXT("start")))
+		{
+			return MCPError(TEXT("Missing 'start' vector"));
+		}
+		const FVector Start = OptionalVec3(Params, TEXT("start"));
+		FVector End;
+		if (Params->HasField(TEXT("end")))
+		{
+			End = OptionalVec3(Params, TEXT("end"));
+		}
+		else if (Params->HasField(TEXT("direction")))
+		{
+			FVector Dir = OptionalVec3(Params, TEXT("direction"));
+			if (!Dir.Normalize())
+			{
+				return MCPError(TEXT("'direction' must be a non-zero vector"));
+			}
+			const double Distance = OptionalNumber(Params, TEXT("distance"), 200000.0);
+			End = Start + Dir * Distance;
+		}
+		else
+		{
+			return MCPError(TEXT("Pass either 'end' (Vec3) or 'direction' (Vec3) + 'distance?'"));
+		}
+
+		// Gameplay traces run against simple collision unless they ask otherwise, so a
+		// trace taken here to verify in-game behaviour has to do the same by default.
+		// Complex geometry and its simple hull can be far apart, and a per-triangle hit
+		// the running game never produces reads as a confirmed impact point.
+		const bool bTraceComplex = OptionalBool(Params, TEXT("traceComplex"), false);
+
+		// Visibility is the editor picking channel. A gameplay trace usually runs on
+		// another one, and blocking differs per channel, so the channel has to be
+		// selectable for the result to mean anything about the game.
+		ECollisionChannel Channel = ECC_Visibility;
+		FString ChannelName = TEXT("Visibility");
+		const FString RequestedChannel = OptionalString(Params, TEXT("channel"));
+		if (!RequestedChannel.IsEmpty() && !ResolveTraceChannel(RequestedChannel, Channel, ChannelName))
+		{
+			return MCPError(FString::Printf(
+				TEXT("Unknown collision channel '%s'. Available channels: %s"),
+				*RequestedChannel, *DescribeTraceChannels()));
+		}
+
+		FCollisionQueryParams Query(SCENE_QUERY_STAT(MCPLineTrace), bTraceComplex);
+		Query.bReturnPhysicalMaterial = true;
+		Query.bReturnFaceIndex = bTraceComplex;
+
+		const TArray<TSharedPtr<FJsonValue>>* IgnoreArr = nullptr;
+		if (Params->TryGetArrayField(TEXT("ignoreActors"), IgnoreArr) && IgnoreArr)
+		{
+			for (const TSharedPtr<FJsonValue>& V : *IgnoreArr)
+			{
+				FString Label;
+				if (!V->TryGetString(Label)) continue;
+				// #983: an ignore list is the plural case. A label naming
+				// three actors ignores all three, which is what the caller
+				// meant and what ignoring one of them silently was not.
+				TArray<AActor*> Matches;
+				MCPCollectActorsByToken(World, Label, EMCPActorMatch::LabelNameOrPath, Matches);
+				for (AActor* A : Matches) Query.AddIgnoredActor(A);
+			}
+		}
+
+		FHitResult Hit;
+		const bool bHit = World->LineTraceSingleByChannel(Hit, Start, End, Channel, Query);
+
+		auto Result = MCPSuccess();
+		Result->SetBoolField(TEXT("hit"), bHit);
+		Result->SetObjectField(TEXT("start"), MCPVec3ToJsonObject(Start));
+		Result->SetObjectField(TEXT("end"), MCPVec3ToJsonObject(End));
+		// Report the collision semantics the result was produced under, so a caller
+		// comparing against the game can see which one it got.
+		Result->SetBoolField(TEXT("traceComplex"), bTraceComplex);
+		Result->SetStringField(TEXT("channel"), ChannelName);
+		// #933: name the world that actually answered. A caller comparing a PIE
+		// trace against an editor trace has no other way to tell them apart, and
+		// silently answering from the wrong one is the bug this closes.
+		Result->SetStringField(TEXT("world"), DescribeTracedWorld(World));
+		if (bHit) EmitHitFields(Result, Hit);
+		return MCPResult(Result);
+	}
 }
 
 
+// #933: `world` selects the world the trace runs against, the same way every
+// other PIE-aware action in this category does. REQUIRE_EDITOR_WORLD ignored the
+// parameter, so a trace asked for during PIE answered from the editor world and
+// reported the pre-play geometry as though it were the running game's. That is
+// the worst shape of wrong answer: nothing about it looks wrong.
 TSharedPtr<FJsonValue> FLevelHandlers::LineTrace(const TSharedPtr<FJsonObject>& Params)
 {
-	REQUIRE_EDITOR_WORLD(World);
+	TSharedPtr<FJsonValue> WorldError;
+	UWorld* World = ResolveTraceWorld(Params, WorldError);
+	if (!World) return WorldError;
+	return ExecuteLineTrace(World, Params);
+}
 
-	const FVector Start = OptionalVec3(Params, TEXT("start"));
-	FVector End;
-	if (Params->HasField(TEXT("end")))
-	{
-		End = OptionalVec3(Params, TEXT("end"));
-	}
-	else if (Params->HasField(TEXT("direction")))
+
+TSharedPtr<FJsonValue> FLevelHandlers::BulkLineTrace(const TSharedPtr<FJsonObject>& Params)
+{
+	// #933: one world for the whole batch, chosen by the top-level `world`. A
+	// per-item scope would let one batch straddle two worlds and report the
+	// results in one array as though they were comparable.
+	TSharedPtr<FJsonValue> WorldError;
+	UWorld* World = ResolveTraceWorld(Params, WorldError);
+	if (!World) return WorldError;
+
+	constexpr int32 MaxBulkLineTraces = 256;
+	const TArray<TSharedPtr<FJsonValue>>* Traces = nullptr;
+	if (!Params->TryGetArrayField(TEXT("traces"), Traces) || !Traces)
 	{
-		FVector Dir = OptionalVec3(Params, TEXT("direction"));
-		if (!Dir.Normalize())
-		{
-			return MCPError(TEXT("'direction' must be a non-zero vector"));
-		}
-		const double Distance = OptionalNumber(Params, TEXT("distance"), 200000.0);
-		End = Start + Dir * Distance;
+		return MCPError(TEXT("Missing 'traces' array"));
 	}
-	else
+	if (Traces->Num() == 0)
 	{
-		return MCPError(TEXT("Pass either 'end' (Vec3) or 'direction' (Vec3) + 'distance?'"));
+		return MCPError(TEXT("'traces' must contain at least one line trace"));
 	}
-
-	// Gameplay traces run against simple collision unless they ask otherwise, so a
-	// trace taken here to verify in-game behaviour has to do the same by default.
-	// Complex geometry and its simple hull can be far apart, and a per-triangle hit
-	// the running game never produces reads as a confirmed impact point.
-	const bool bTraceComplex = OptionalBool(Params, TEXT("traceComplex"), false);
-
-	// Visibility is the editor picking channel. A gameplay trace usually runs on
-	// another one, and blocking differs per channel, so the channel has to be
-	// selectable for the result to mean anything about the game.
-	ECollisionChannel Channel = ECC_Visibility;
-	FString ChannelName = TEXT("Visibility");
-	const FString RequestedChannel = OptionalString(Params, TEXT("channel"));
-	if (!RequestedChannel.IsEmpty() && !ResolveTraceChannel(RequestedChannel, Channel, ChannelName))
+	if (Traces->Num() > MaxBulkLineTraces)
 	{
 		return MCPError(FString::Printf(
-			TEXT("Unknown collision channel '%s'. Available channels: %s"),
-			*RequestedChannel, *DescribeTraceChannels()));
+			TEXT("'traces' exceeds the maximum batch size of %d (received %d)"),
+			MaxBulkLineTraces, Traces->Num()));
 	}
 
-	FCollisionQueryParams Query(SCENE_QUERY_STAT(MCPLineTrace), bTraceComplex);
-	Query.bReturnPhysicalMaterial = true;
-	Query.bReturnFaceIndex = bTraceComplex;
-
-	const TArray<TSharedPtr<FJsonValue>>* IgnoreArr = nullptr;
-	if (Params->TryGetArrayField(TEXT("ignoreActors"), IgnoreArr) && IgnoreArr)
+	TArray<TSharedPtr<FJsonValue>> Results;
+	Results.Reserve(Traces->Num());
+	for (int32 Index = 0; Index < Traces->Num(); ++Index)
 	{
-		for (const TSharedPtr<FJsonValue>& V : *IgnoreArr)
+		const TSharedPtr<FJsonValue>& Entry = (*Traces)[Index];
+		const TSharedPtr<FJsonObject> Item = Entry.IsValid() ? Entry->AsObject() : nullptr;
+		if (!Item.IsValid())
 		{
-			FString Label;
-			if (!V->TryGetString(Label)) continue;
-			if (AActor* A = FindActorByLabel(World, Label)) Query.AddIgnoredActor(A);
+			Results.Add(MCPError(FString::Printf(TEXT("traces[%d] must be an object"), Index)));
+			continue;
 		}
+		Results.Add(ExecuteLineTrace(World, Item));
 	}
 
-	FHitResult Hit;
-	const bool bHit = World->LineTraceSingleByChannel(Hit, Start, End, Channel, Query);
-
 	auto Result = MCPSuccess();
-	Result->SetBoolField(TEXT("hit"), bHit);
-	Result->SetObjectField(TEXT("start"), MCPVec3ToJsonObject(Start));
-	Result->SetObjectField(TEXT("end"), MCPVec3ToJsonObject(End));
-	// Report the collision semantics the result was produced under, so a caller
-	// comparing against the game can see which one it got.
-	Result->SetBoolField(TEXT("traceComplex"), bTraceComplex);
-	Result->SetStringField(TEXT("channel"), ChannelName);
-	if (bHit) EmitHitFields(Result, Hit);
+	Result->SetArrayField(TEXT("results"), Results);
+	Result->SetNumberField(TEXT("count"), Results.Num());
 	return MCPResult(Result);
 }
 
 
 TSharedPtr<FJsonValue> FLevelHandlers::SnapActorToFloor(const TSharedPtr<FJsonObject>& Params)
 {
-	REQUIRE_EDITOR_WORLD(World);
+	// #933: same defect as line_trace. The actor is looked up in this world and
+	// the downward trace runs in it, so both halves have to agree on which one.
+	TSharedPtr<FJsonValue> WorldError;
+	UWorld* World = ResolveTraceWorld(Params, WorldError);
+	if (!World) return WorldError;
 	FString ActorLabel;
-	if (auto Err = RequireString(Params, TEXT("actorLabel"), ActorLabel)) return Err;
+	if (auto Err = RequireStringAlt(Params, TEXT("actorLabel"), TEXT("actorPath"), ActorLabel)) return Err;
 
-	AActor* Actor = FindActorByLabel(World, ActorLabel);
-	if (!Actor) return MCPError(FString::Printf(TEXT("Actor not found: %s"), *ActorLabel));
+	TSharedPtr<FJsonValue> ActorErr;
+	AActor* Actor = MCPResolveActor(World, Params, ActorErr);
+	if (!Actor) return ActorErr;
+	ActorLabel = Actor->GetActorLabel();
 
 	const double Offset = OptionalNumber(Params, TEXT("floorOffset"), 0.0);
 	const double MaxDistance = OptionalNumber(Params, TEXT("maxDistance"), 100000.0);
@@ -231,6 +349,7 @@ TSharedPtr<FJsonValue> FLevelHandlers::SnapActorToFloor(const TSharedPtr<FJsonOb
 	auto Result = MCPSuccess();
 	MCPSetUpdated(Result);
 	Result->SetStringField(TEXT("actorLabel"), ActorLabel);
+	Result->SetStringField(TEXT("actorPath"), Actor->GetPathName());
 	Result->SetObjectField(TEXT("from"), MCPVec3ToJsonObject(PrevLoc));
 	Result->SetObjectField(TEXT("to"), MCPVec3ToJsonObject(NewLoc));
 	Result->SetObjectField(TEXT("impactPoint"), MCPVec3ToJsonObject(Hit.ImpactPoint));
@@ -239,6 +358,7 @@ TSharedPtr<FJsonValue> FLevelHandlers::SnapActorToFloor(const TSharedPtr<FJsonOb
 
 	TSharedPtr<FJsonObject> Payload = MakeShared<FJsonObject>();
 	Payload->SetStringField(TEXT("actorLabel"), ActorLabel);
+	Payload->SetStringField(TEXT("actorPath"), Actor->GetPathName());
 	TSharedPtr<FJsonObject> Loc = MakeShared<FJsonObject>();
 	Loc->SetNumberField(TEXT("x"), PrevLoc.X);
 	Loc->SetNumberField(TEXT("y"), PrevLoc.Y);

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

@@ -0,0 +1,337 @@
+// Transient verification actors (#956).
+//
+// Verifying anything that only exists on a live actor (a GAS attribute set, a
+// component's runtime state) needs a subject, and there was no way to make one
+// without leaving it behind. Spawning a normal actor to check something and
+// then forgetting to delete it is #966's exact shape: a capture action left a
+// SceneCapture2D in the map and it got committed.
+//
+// So these actors are transient by construction rather than by discipline:
+//
+//   RF_Transient means the package serializer skips them, so a save cannot
+//   write one into the map even if the caller never destroys it.
+//   bTemporaryEditorActor marks the actor as an editor preview actor, which
+//   keeps it out of the level's persistent actor list.
+//   bCreateActorPackage is off, so a World Partition map does not mint an
+//   external actor package for it, which is the artefact that would actually
+//   reach source control.
+//   The label is set with bMarkDirty=false, because SetActorLabel dirties the
+//   map by default and a verification spawn that dirties the map has already
+//   failed at its one job.
+//
+// Every one of them also carries a marker tag, so they can be listed and so
+// destroy refuses anything it did not create.
+
+#include "LevelHandlers.h"
+
+#include "Components/ActorComponent.h"
+#include "Dom/JsonObject.h"
+#include "Dom/JsonValue.h"
+#include "Editor.h"
+#include "Engine/World.h"
+#include "EngineUtils.h"
+#include "GameFramework/Actor.h"
+#include "HandlerEditorState.h"
+#include "HandlerRegistry.h"
+#include "HandlerUtils.h"
+
+namespace
+{
+	/** The marker every actor spawned by this action carries. Listing and
+	 *  destruction both key on it, so nothing else can be destroyed by
+	 *  accident and nothing spawned here can be missed. */
+	const TCHAR* const MCPTransientActorTag = TEXT("UEMCP_TransientVerification");
+
+	constexpr int32 MCPTransientMaxListed = 500;
+
+	TSharedPtr<FJsonObject> MCPDescribeTransientActor(AActor* Actor)
+	{
+		TSharedPtr<FJsonObject> Object = MakeShared<FJsonObject>();
+		Object->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+		Object->SetStringField(TEXT("actorName"), Actor->GetName());
+		Object->SetStringField(TEXT("actorPath"), Actor->GetPathName());
+		Object->SetStringField(TEXT("actorClass"), Actor->GetClass()->GetPathName());
+		Object->SetBoolField(TEXT("transient"), Actor->HasAnyFlags(RF_Transient));
+		Object->SetObjectField(TEXT("location"), MCPVec3ToJsonObject(Actor->GetActorLocation()));
+		return Object;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// spawn_transient_actor (#956)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::SpawnTransientActor(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 ActorClassSpec;
+	if (auto Err = RequireString(Params, TEXT("actorClass"), ActorClassSpec)) return Err;
+	UClass* ActorClass = MCPResolveClassOfType(ActorClassSpec, AActor::StaticClass(), true);
+	if (!ActorClass)
+	{
+		return MCPClassNotFoundError(ActorClassSpec, TEXT("actorClass"));
+	}
+	if (auto Err = MCPCheckClassUsable(ActorClassSpec, ActorClass, AActor::StaticClass()))
+	{
+		return Err;
+	}
+
+	const FVector Location = OptionalVec3(Params, TEXT("location"), FVector::ZeroVector);
+	const FRotator Rotation = OptionalRotator(Params, TEXT("rotation"), FRotator::ZeroRotator);
+	const FVector Scale = OptionalVec3(Params, TEXT("scale"), FVector::OneVector);
+	const FString Label = OptionalString(Params, TEXT("label"));
+	const bool bHideFromOutliner = OptionalBool(Params, TEXT("hideFromOutliner"), false);
+
+	// How far to take the actor towards a running state. The editor world has
+	// not begun play, so a spawned actor gets neither InitializeComponent nor
+	// BeginPlay, and anything that does its setup there (a GAS ability system
+	// component's default subobject scan, for instance) is not ready to be
+	// read. Each level is opt-in because each does more to the editor world.
+	const FString Initialize = OptionalString(Params, TEXT("initialize"), TEXT("construction")).ToLower();
+	if (Initialize != TEXT("none") && Initialize != TEXT("construction") && Initialize != TEXT("beginplay"))
+	{
+		return MCPError(TEXT("'initialize' must be 'none', 'construction' (default) or 'beginPlay'"));
+	}
+
+	TArray<FString> DirtyBefore;
+	MCPEditorState::CollectDirtyEditorPackageNames(DirtyBefore);
+
+	FActorSpawnParameters SpawnParameters;
+	SpawnParameters.SpawnCollisionHandlingOverride = ESpawnActorCollisionHandlingMethod::AlwaysSpawn;
+	// The transiency contract, stated three ways so no single engine path can
+	// quietly persist this actor.
+	SpawnParameters.ObjectFlags |= RF_Transient;
+#if WITH_EDITOR
+	SpawnParameters.bTemporaryEditorActor = true;
+	SpawnParameters.bHideFromSceneOutliner = bHideFromOutliner;
+	SpawnParameters.bCreateActorPackage = false;
+#endif
+
+	AActor* Actor = World->SpawnActor<AActor>(
+		ActorClass, FTransform(Rotation, Location, Scale), SpawnParameters);
+	if (!Actor)
+	{
+		return MCPError(FString::Printf(
+			TEXT("Failed to spawn a transient %s"), *ActorClass->GetName()));
+	}
+
+	// Belt and braces: SpawnActor does not always propagate ObjectFlags to
+	// every path, and the transiency claim in the response has to be true.
+	Actor->SetFlags(RF_Transient);
+	Actor->Tags.AddUnique(FName(MCPTransientActorTag));
+	if (!Label.IsEmpty())
+	{
+		// bMarkDirty=false. The default marks the map package dirty, and a
+		// verification spawn that dirties the map has failed at its one job.
+		Actor->SetActorLabel(Label, /*bMarkDirty*/ false);
+	}
+
+	FString InitializeNote;
+#if WITH_EDITOR
+	if (Initialize == TEXT("construction"))
+	{
+		Actor->RerunConstructionScripts();
+		InitializeNote = TEXT("Construction scripts ran. Components exist and their editable defaults are applied, but InitializeComponent and BeginPlay have NOT run, because the editor world has not begun play.");
+	}
+	else if (Initialize == TEXT("beginplay"))
+	{
+		Actor->RerunConstructionScripts();
+		Actor->RegisterAllComponents();
+		Actor->DispatchBeginPlay();
+		InitializeNote = TEXT("Components were registered and the begin-play cycle was dispatched on this actor, so InitializeComponent and BeginPlay ran. This is what a component that does its setup in BeginPlay needs before it can be read. It runs on this actor only, in a world that has not begun play, so anything depending on other actors or on world subsystems may still be absent.");
+	}
+	else
+	{
+		InitializeNote = TEXT("initialize='none': the actor exists with its default subobjects and nothing else has been run on it.");
+	}
+#else
+	InitializeNote = TEXT("Non-editor build: no construction or begin-play cycle was run.");
+#endif
+
+	TArray<TSharedPtr<FJsonValue>> Components;
+	for (UActorComponent* Component : Actor->GetComponents())
+	{
+		if (!Component) continue;
+		TSharedPtr<FJsonObject> ComponentObject = MakeShared<FJsonObject>();
+		ComponentObject->SetStringField(TEXT("name"), Component->GetName());
+		ComponentObject->SetStringField(TEXT("class"), Component->GetClass()->GetName());
+		ComponentObject->SetBoolField(TEXT("registered"), Component->IsRegistered());
+		// The read side of #956 needs this: a component whose setup happens in
+		// InitializeComponent is not ready until this is true.
+		ComponentObject->SetBoolField(TEXT("initialized"), Component->HasBeenInitialized());
+		Components.Add(MakeShared<FJsonValueObject>(ComponentObject));
+	}
+
+	auto Result = MCPSuccess();
+	MCPSetCreated(Result);
+	Result->SetObjectField(TEXT("actor"), MCPDescribeTransientActor(Actor));
+	Result->SetStringField(TEXT("initialize"), Initialize);
+	Result->SetStringField(TEXT("initializeNote"), InitializeNote);
+	Result->SetArrayField(TEXT("components"), Components);
+	Result->SetStringField(TEXT("cleanupNote"), FString::Printf(
+		TEXT("Destroy this with level(destroy_transient_actor, actorPath:'%s') when you are done. It is RF_Transient and a save cannot write it into the map, but it stays in the open world until it is destroyed or the map is reloaded."),
+		*Actor->GetPathName()));
+
+	// The #966-shaped guarantee, asserted rather than promised: if spawning
+	// this dirtied anything, the caller is told which package.
+	TArray<FString> DirtyAfter;
+	MCPEditorState::CollectDirtyEditorPackageNames(DirtyAfter);
+	for (const FString& Already : DirtyBefore)
+	{
+		DirtyAfter.Remove(Already);
+	}
+	Result->SetBoolField(TEXT("dirtiedPackages"), DirtyAfter.Num() > 0);
+	if (DirtyAfter.Num() > 0)
+	{
+		Result->SetArrayField(TEXT("dirtyPackages"), MCPStringListToJson(DirtyAfter));
+		Result->SetStringField(TEXT("dirtyWarning"),
+			TEXT("This spawn dirtied a package, which it is not supposed to do. Destroy the actor and do not save until you have checked what changed."));
+	}
+
+	TSharedPtr<FJsonObject> Rollback = MakeShared<FJsonObject>();
+	Rollback->SetStringField(TEXT("actorPath"), Actor->GetPathName());
+	MCPSetRollback(Result, TEXT("destroy_transient_actor"), Rollback);
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// destroy_transient_actor (#956)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::DestroyTransientActor(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));
+	}
+
+	const FString ActorPath = OptionalString(Params, TEXT("actorPath"));
+	const FString ActorLabel = OptionalString(Params, TEXT("actorLabel"));
+	const bool bAll = OptionalBool(Params, TEXT("all"), false);
+	if (ActorPath.IsEmpty() && ActorLabel.IsEmpty() && !bAll)
+	{
+		return MCPError(TEXT("Pass 'actorPath', 'actorLabel', or all=true to destroy every transient verification actor in this world"));
+	}
+
+	const FName MarkerTag(MCPTransientActorTag);
+	TArray<AActor*> Targets;
+	TArray<FString> RefusedNonTransient;
+
+	for (TActorIterator<AActor> It(World); It; ++It)
+	{
+		AActor* Actor = *It;
+		if (!Actor) continue;
+
+		bool bSelected = bAll;
+		if (!bSelected && !ActorPath.IsEmpty()) bSelected = Actor->GetPathName() == ActorPath;
+		if (!bSelected && !ActorLabel.IsEmpty()) bSelected = Actor->GetActorLabel() == ActorLabel;
+		if (!bSelected) continue;
+
+		// The guardrail. This action destroys things, and a label or a path is
+		// easy to get wrong, so it will only destroy an actor it created. A
+		// normal placed actor selected by mistake is refused by name rather
+		// than deleted.
+		if (!Actor->Tags.Contains(MarkerTag) || !Actor->HasAnyFlags(RF_Transient))
+		{
+			if (!bAll)
+			{
+				RefusedNonTransient.Add(FString::Printf(
+					TEXT("%s (%s)"), *Actor->GetActorLabel(), *Actor->GetClass()->GetName()));
+			}
+			continue;
+		}
+		Targets.Add(Actor);
+	}
+
+	auto Result = MCPSuccess();
+	if (!RefusedNonTransient.IsEmpty())
+	{
+		Result->SetBoolField(TEXT("success"), false);
+		Result->SetStringField(TEXT("error"),
+			TEXT("Refusing to destroy an actor this action did not create. Only actors spawned by level(spawn_transient_actor), which carry the UEMCP_TransientVerification tag and RF_Transient, can be destroyed here. Use level(delete_actor) or level(delete_actors) for a real level actor."));
+		Result->SetArrayField(TEXT("refused"), MCPStringListToJson(RefusedNonTransient));
+		return MCPResult(Result);
+	}
+
+	TArray<FString> Destroyed;
+	TArray<FString> Failed;
+	for (AActor* Actor : Targets)
+	{
+		const FString Description = FString::Printf(
+			TEXT("%s (%s)"), *Actor->GetActorLabel(), *Actor->GetClass()->GetName());
+		if (World->DestroyActor(Actor))
+		{
+			Destroyed.Add(Description);
+		}
+		else
+		{
+			Failed.Add(Description);
+		}
+	}
+
+	Result->SetBoolField(TEXT("success"), Failed.IsEmpty());
+	if (!Failed.IsEmpty())
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d transient actor(s) refused to be destroyed; see failed."), Failed.Num()));
+	}
+	Result->SetNumberField(TEXT("matched"), Targets.Num());
+	Result->SetNumberField(TEXT("destroyed"), Destroyed.Num());
+	Result->SetArrayField(TEXT("destroyedActors"), MCPStringListToJson(Destroyed));
+	Result->SetArrayField(TEXT("failed"), MCPStringListToJson(Failed));
+	if (Targets.IsEmpty())
+	{
+		Result->SetStringField(TEXT("zeroMatchNote"),
+			TEXT("Nothing matched. A transient verification actor does not survive a map reload or an editor restart, so it may simply be gone already. level(list_transient_actors) shows what is still there."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// list_transient_actors (#956)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::ListTransientActors(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));
+	}
+
+	const FName MarkerTag(MCPTransientActorTag);
+	TArray<TSharedPtr<FJsonValue>> Actors;
+	int32 Total = 0;
+	for (TActorIterator<AActor> It(World); It; ++It)
+	{
+		AActor* Actor = *It;
+		if (!Actor || !Actor->Tags.Contains(MarkerTag)) continue;
+		++Total;
+		if (Actors.Num() < MCPTransientMaxListed)
+		{
+			Actors.Add(MakeShared<FJsonValueObject>(MCPDescribeTransientActor(Actor)));
+		}
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetStringField(TEXT("worldName"), World->GetName());
+	Result->SetNumberField(TEXT("total"), Total);
+	Result->SetNumberField(TEXT("returned"), Actors.Num());
+	Result->SetBoolField(TEXT("truncated"), Actors.Num() < Total);
+	Result->SetArrayField(TEXT("actors"), Actors);
+	Result->SetStringField(TEXT("note"),
+		TEXT("These are RF_Transient verification actors spawned by level(spawn_transient_actor). A save cannot write them into the map, and they do not survive a map reload, but they are in the open world until destroyed."));
+	return MCPResult(Result);
+}