ue-mcp 1.2.3 → 1.3.0

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

@@ -0,0 +1,1571 @@
+// Level-wide writes that used to be Python loops (#984, #941, #907, #987).
+//
+// The read side of this problem is level(query_components): a level-wide
+// question had no editor-side answer. These are the same complaint on the
+// write side. Every one of them was a loop over an editor-side selector that
+// the client had to reproduce for itself:
+//
+//   #984  190 SpotLights tagged LichtTest, moved, retinted and shadow-toggled
+//         one call at a time. batch_translate exists but wants an explicit
+//         label list, and auto-numbered labels make that list a generated
+//         payload rather than a selector.
+//   #941  NavModifierComponent.AreaClass across dozens of placed
+//         StaticMeshActors. set_component_property is one actor per call.
+//   #907  230 orphaned SplineMeshComponents across 23 actors. Their names are
+//         auto-generated (SplineMeshComponent_0, _1, ...) and remove_component
+//         takes one name at a time, so there was no way to name them all.
+//   #987  A SpotLight at every lamp post, positioned from each lamp
+//         component's own bounds. place_actors_batch is StaticMesh only and
+//         spawn_light takes a single position.
+//
+// The property writes deliberately delegate to FLevelHandlers::SetActorProperty
+// and ::SetComponentProperty rather than reimplementing them. Those two carry
+// years of accumulated behaviour (actor-label object refs, TArray-of-actor
+// refs, instanced sub-object descent, the EditDefaultsOnly override), and a
+// batch that quietly meant something narrower than the single-item action
+// would be worse than no batch at all.
+
+#include "LevelHandlers.h"
+
+#include "Components/ActorComponent.h"
+#include "Components/MeshComponent.h"
+#include "Components/SceneComponent.h"
+#include "Components/SplineComponent.h"
+#include "Dom/JsonObject.h"
+#include "Dom/JsonValue.h"
+#include "Editor.h"
+#include "Engine/World.h"
+#include "EngineUtils.h"
+#include "FileHelpers.h"
+#include "GameFramework/Actor.h"
+#include "HandlerQuery.h"
+#include "HandlerRegistry.h"
+#include "HandlerUtils.h"
+#include "Materials/MaterialInterface.h"
+#include "ScopedTransaction.h"
+// #985: bulk HLOD layer assignment. UHLODLayer has to be a complete type for
+// AActor::SetHLODLayer and for the asset load.
+#include "WorldPartition/HLOD/HLODLayer.h"
+
+namespace
+{
+	// Bounds. Each of these actions replaced an unbounded loop, and an
+	// unbounded batch is the same failure with fewer round trips.
+	constexpr int32 MCPBatchMaxActors = 5000;
+	constexpr int32 MCPBatchMaxProperties = 32;
+	constexpr int32 MCPBatchMaxResultRows = 1000;
+	constexpr int32 MCPBatchDefaultMaxSpawn = 500;
+	constexpr int32 MCPBatchHardMaxSpawn = 5000;
+	constexpr double MCPBatchMinSplineSpacing = 1.0;
+
+	/**
+	 * The selector every action in this file shares.
+	 *
+	 * Naming rule, and it is a rule rather than a style: a parameter that says
+	 * `label` matches the EDITOR LABEL, a parameter that says `name` matches
+	 * the internal object name, `Prefix` is a prefix and `Contains` is a
+	 * substring. Two level actions that took similar-sounding filters and
+	 * matched different things is exactly how #963 happened.
+	 */
+	struct FMCPBatchSelector
+	{
+		TArray<FString> ActorLabels;
+		FString LabelPrefix;
+		FString LabelContains;
+		FString Tag;
+		UClass* ActorClass = nullptr;
+		FString ActorClassFallback;
+		bool bMatchSubclasses = true;
+		FString FolderPath;
+		FString FolderPathPrefix;
+		bool bAny = false;
+	};
+
+	TSharedPtr<FJsonValue> MCPBatchReadSelector(
+		const TSharedPtr<FJsonObject>& Params,
+		FMCPBatchSelector& OutSelector)
+	{
+		const TArray<TSharedPtr<FJsonValue>>* LabelValues = nullptr;
+		if (Params->TryGetArrayField(TEXT("actorLabels"), LabelValues) && LabelValues)
+		{
+			OutSelector.ActorLabels = JsonArrayToStringList(LabelValues);
+		}
+		OutSelector.LabelPrefix = OptionalString(Params, TEXT("labelPrefix"));
+		OutSelector.LabelContains = OptionalString(Params, TEXT("labelContains"));
+		OutSelector.Tag = OptionalString(Params, TEXT("tag"));
+		OutSelector.FolderPath = OptionalString(Params, TEXT("folderPath"));
+		OutSelector.FolderPathPrefix = OptionalString(Params, TEXT("folderPathPrefix"));
+		OutSelector.bMatchSubclasses = OptionalBool(Params, TEXT("matchSubclasses"), true);
+
+		const FString ClassSpec = OptionalString(Params, TEXT("classFilter"));
+		if (!ClassSpec.IsEmpty())
+		{
+			OutSelector.ActorClass = MCPResolveClassOfType(ClassSpec, AActor::StaticClass(), true);
+			if (!OutSelector.ActorClass)
+			{
+				// Substring on the class name is what the older level actions
+				// accept, so a call that used to work keeps working.
+				OutSelector.ActorClassFallback = ClassSpec;
+			}
+		}
+
+		OutSelector.bAny =
+			!OutSelector.ActorLabels.IsEmpty() ||
+			!OutSelector.LabelPrefix.IsEmpty() ||
+			!OutSelector.LabelContains.IsEmpty() ||
+			!OutSelector.Tag.IsEmpty() ||
+			OutSelector.ActorClass != nullptr ||
+			!OutSelector.ActorClassFallback.IsEmpty() ||
+			!OutSelector.FolderPath.IsEmpty() ||
+			!OutSelector.FolderPathPrefix.IsEmpty();
+
+		return nullptr;
+	}
+
+	bool MCPBatchActorMatches(const FMCPBatchSelector& Selector, AActor* Actor, const FString& Label)
+	{
+		if (!Selector.ActorLabels.IsEmpty() && !Selector.ActorLabels.Contains(Label)) return false;
+		if (!Selector.LabelPrefix.IsEmpty() && !Label.StartsWith(Selector.LabelPrefix, ESearchCase::CaseSensitive)) return false;
+		if (!Selector.LabelContains.IsEmpty() && !Label.Contains(Selector.LabelContains, ESearchCase::IgnoreCase)) return false;
+		if (!Selector.Tag.IsEmpty() && !Actor->ActorHasTag(FName(*Selector.Tag))) return false;
+		if (Selector.ActorClass)
+		{
+			const bool bMatches = Selector.bMatchSubclasses
+				? Actor->IsA(Selector.ActorClass)
+				: (Actor->GetClass() == Selector.ActorClass);
+			if (!bMatches) return false;
+		}
+		else if (!Selector.ActorClassFallback.IsEmpty() &&
+			!Actor->GetClass()->GetName().Contains(Selector.ActorClassFallback, ESearchCase::IgnoreCase))
+		{
+			return false;
+		}
+		if (!Selector.FolderPath.IsEmpty() &&
+			!Actor->GetFolderPath().ToString().Equals(Selector.FolderPath, ESearchCase::IgnoreCase))
+		{
+			return false;
+		}
+		if (!Selector.FolderPathPrefix.IsEmpty() &&
+			!Actor->GetFolderPath().ToString().StartsWith(Selector.FolderPathPrefix, ESearchCase::IgnoreCase))
+		{
+			return false;
+		}
+		return true;
+	}
+
+	/** Every actor the selector picks, in a deterministic order. */
+	void MCPBatchCollectActors(UWorld* World, const FMCPBatchSelector& Selector, TArray<AActor*>& OutActors)
+	{
+		OutActors.Reset();
+		for (TActorIterator<AActor> It(World); It; ++It)
+		{
+			AActor* Actor = *It;
+			if (!Actor) continue;
+			if (MCPBatchActorMatches(Selector, Actor, Actor->GetActorLabel()))
+			{
+				OutActors.Add(Actor);
+			}
+		}
+		OutActors.Sort([](const AActor& A, const AActor& B)
+		{
+			return A.GetPathName() < B.GetPathName();
+		});
+	}
+
+	/**
+	 * Labels the selector asked for by exact name and did not find.
+	 *
+	 * A destructive or sweeping call that matched nothing must say so with the
+	 * reason, not return success and a zero. That is #963's actual harm.
+	 */
+	TArray<FString> MCPBatchMissingLabels(const FMCPBatchSelector& Selector, const TArray<AActor*>& Matched)
+	{
+		TArray<FString> Missing;
+		if (Selector.ActorLabels.IsEmpty())
+		{
+			return Missing;
+		}
+		TSet<FString> Found;
+		for (AActor* Actor : Matched)
+		{
+			Found.Add(Actor->GetActorLabel());
+		}
+		for (const FString& Label : Selector.ActorLabels)
+		{
+			if (!Found.Contains(Label))
+			{
+				Missing.Add(Label);
+			}
+		}
+		return Missing;
+	}
+
+	FVector MCPBatchReadVector(const TSharedPtr<FJsonObject>& Obj, const FVector& Default)
+	{
+		if (!Obj.IsValid()) return Default;
+		FVector Value = Default;
+		double Component = 0.0;
+		if (Obj->TryGetNumberField(TEXT("x"), Component)) Value.X = Component;
+		if (Obj->TryGetNumberField(TEXT("y"), Component)) Value.Y = Component;
+		if (Obj->TryGetNumberField(TEXT("z"), Component)) Value.Z = Component;
+		return Value;
+	}
+
+	FRotator MCPBatchReadRotator(const TSharedPtr<FJsonObject>& Obj, const FRotator& Default)
+	{
+		if (!Obj.IsValid()) return Default;
+		FRotator Value = Default;
+		double Component = 0.0;
+		if (Obj->TryGetNumberField(TEXT("pitch"), Component)) Value.Pitch = Component;
+		if (Obj->TryGetNumberField(TEXT("yaw"), Component)) Value.Yaw = Component;
+		if (Obj->TryGetNumberField(TEXT("roll"), Component)) Value.Roll = Component;
+		return Value;
+	}
+
+	/** Pull the { ok, error } verdict out of a delegated single-item handler. */
+	void MCPBatchReadVerdict(const TSharedPtr<FJsonValue>& Response, bool& bOutOk, FString& OutError, FString& OutPrevious)
+	{
+		bOutOk = false;
+		OutError.Reset();
+		OutPrevious.Reset();
+		if (!Response.IsValid() || Response->Type != EJson::Object)
+		{
+			OutError = TEXT("handler returned no result");
+			return;
+		}
+		const TSharedPtr<FJsonObject> Object = Response->AsObject();
+		bOutOk = Object->HasField(TEXT("success")) ? Object->GetBoolField(TEXT("success")) : true;
+		Object->TryGetStringField(TEXT("error"), OutError);
+		Object->TryGetStringField(TEXT("previousValue"), OutPrevious);
+	}
+
+	/** Resolve one named component on an actor, matching the case-insensitive
+	 *  rule set_component_property already uses for SCS components. */
+	UActorComponent* MCPBatchFindComponent(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;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// batch_set_actor_properties (#984)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::BatchSetActorProperties(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	const TSharedPtr<FJsonObject>* PropertiesObject = nullptr;
+	if (!Params->TryGetObjectField(TEXT("properties"), PropertiesObject) ||
+		!PropertiesObject || !(*PropertiesObject).IsValid() || (*PropertiesObject)->Values.Num() == 0)
+	{
+		return MCPError(TEXT("Missing 'properties' (an object of propertyName -> value; dotted paths are supported)"));
+	}
+	if ((*PropertiesObject)->Values.Num() > MCPBatchMaxProperties)
+	{
+		return MCPError(FString::Printf(
+			TEXT("'properties' exceeds the maximum of %d entries"), MCPBatchMaxProperties));
+	}
+
+	FMCPBatchSelector Selector;
+	if (auto Err = MCPBatchReadSelector(Params, Selector)) return Err;
+	if (!Selector.bAny)
+	{
+		return MCPError(TEXT("Pass at least one selector: actorLabels, labelPrefix, labelContains, tag, classFilter, folderPath or folderPathPrefix"));
+	}
+
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), false);
+	const bool bForce = OptionalBool(Params, TEXT("force"), false);
+	const FString TransactionLabel = OptionalString(
+		Params, TEXT("transactionLabel"), TEXT("MCP batch set actor properties"));
+
+	TArray<AActor*> Actors;
+	MCPBatchCollectActors(World, Selector, Actors);
+	if (Actors.Num() > MCPBatchMaxActors)
+	{
+		return MCPError(FString::Printf(
+			TEXT("The selector matched %d actors, over the maximum of %d. Narrow it."),
+			Actors.Num(), MCPBatchMaxActors));
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetNumberField(TEXT("matched"), Actors.Num());
+	MCPNoteLoadedOnlyEnumeration(World, Result);
+	{
+		const TArray<FString> Missing = MCPBatchMissingLabels(Selector, Actors);
+		if (Missing.Num() > 0)
+		{
+			Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(Missing));
+		}
+	}
+	if (Actors.IsEmpty())
+	{
+		const FString Needle = !Selector.LabelPrefix.IsEmpty()
+			? Selector.LabelPrefix
+			: Selector.LabelContains;
+		if (const TSharedPtr<FJsonObject> Hint = MCPDescribeZeroActorMatch(World, Needle))
+		{
+			Result->SetObjectField(TEXT("zeroMatchHint"), Hint);
+		}
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Updated = 0;
+	int32 Failed = 0;
+	int32 PropertyWrites = 0;
+	int32 PropertyFailures = 0;
+
+	// One transaction for the whole batch, so 190 lights is one undo rather
+	// than 190. Skipped entirely on a dry run, which writes nothing.
+	TUniquePtr<FScopedTransaction> Transaction;
+	if (!bDryRun && !Actors.IsEmpty())
+	{
+		Transaction = MakeUnique<FScopedTransaction>(FText::FromString(TransactionLabel));
+	}
+
+	for (AActor* Actor : Actors)
+	{
+		const FString Label = Actor->GetActorLabel();
+		TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+		Row->SetStringField(TEXT("actorLabel"), Label);
+		Row->SetStringField(TEXT("actorClass"), Actor->GetClass()->GetName());
+
+		TArray<TSharedPtr<FJsonValue>> PropertyRows;
+		bool bActorOk = true;
+		for (const TPair<FString, TSharedPtr<FJsonValue>>& Pair : (*PropertiesObject)->Values)
+		{
+			TSharedPtr<FJsonObject> PropertyRow = MakeShared<FJsonObject>();
+			PropertyRow->SetStringField(TEXT("propertyName"), Pair.Key);
+
+			if (bDryRun)
+			{
+				// A preview has to be a real check, or it is not a preview.
+				// Resolve the path against this actor's class and say whether
+				// the write would land.
+				FString ResolvedType;
+				const TSharedPtr<FJsonValue> Current =
+					MCPQuery::ReadDottedProperty(Actor, Pair.Key, ResolvedType);
+				const bool bResolvable = Current.IsValid();
+				PropertyRow->SetBoolField(TEXT("ok"), bResolvable);
+				if (bResolvable)
+				{
+					PropertyRow->SetField(TEXT("currentValue"), Current);
+					PropertyRow->SetStringField(TEXT("propertyType"), ResolvedType);
+				}
+				else
+				{
+					PropertyRow->SetStringField(TEXT("error"), FString::Printf(
+						TEXT("Property '%s' does not resolve on %s"), *Pair.Key, *Actor->GetClass()->GetName()));
+					bActorOk = false;
+					++PropertyFailures;
+				}
+				PropertyRows.Add(MakeShared<FJsonValueObject>(PropertyRow));
+				continue;
+			}
+
+			// Delegate to the single-actor writer. Reimplementing it here
+			// would quietly support fewer value shapes than set_actor_property
+			// does, which is the worse failure: the call succeeds and means
+			// something narrower than the caller asked for.
+			TSharedPtr<FJsonObject> SubParams = MakeShared<FJsonObject>();
+			SubParams->SetStringField(TEXT("actorLabel"), Label);
+			SubParams->SetStringField(TEXT("propertyName"), Pair.Key);
+			SubParams->SetField(TEXT("value"), Pair.Value);
+			if (bForce) SubParams->SetBoolField(TEXT("force"), true);
+
+			bool bOk = false;
+			FString Error;
+			FString Previous;
+			MCPBatchReadVerdict(FLevelHandlers::SetActorProperty(SubParams), bOk, Error, Previous);
+			PropertyRow->SetBoolField(TEXT("ok"), bOk);
+			if (!Previous.IsEmpty()) PropertyRow->SetStringField(TEXT("previousValue"), Previous);
+			if (!bOk)
+			{
+				PropertyRow->SetStringField(TEXT("error"), Error);
+				bActorOk = false;
+				++PropertyFailures;
+			}
+			else
+			{
+				++PropertyWrites;
+			}
+			PropertyRows.Add(MakeShared<FJsonValueObject>(PropertyRow));
+		}
+
+		Row->SetBoolField(TEXT("ok"), bActorOk);
+		Row->SetArrayField(TEXT("properties"), PropertyRows);
+		if (bActorOk) ++Updated; else ++Failed;
+		if (Rows.Num() < MCPBatchMaxResultRows)
+		{
+			Rows.Add(MakeShared<FJsonValueObject>(Row));
+		}
+	}
+
+	Result->SetBoolField(TEXT("success"), Failed == 0);
+	if (Failed > 0)
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d of %d actors had at least one property that did not write; see results[]."),
+			Failed, Actors.Num()));
+	}
+	Result->SetNumberField(bDryRun ? TEXT("wouldUpdate") : TEXT("updated"), Updated);
+	Result->SetNumberField(TEXT("failed"), Failed);
+	Result->SetNumberField(TEXT("propertyWrites"), PropertyWrites);
+	Result->SetNumberField(TEXT("propertyFailures"), PropertyFailures);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Actors.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (!bDryRun && Updated > 0)
+	{
+		MCPSetUpdated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("The level is left dirty and is NOT saved. Call level(save) when you are done."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// bulk_set_component_property (#941)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::BulkSetComponentProperty(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	FString ComponentName;
+	if (auto Err = RequireString(Params, TEXT("componentName"), ComponentName)) return Err;
+	FString PropertyName;
+	if (auto Err = RequireString(Params, TEXT("propertyName"), PropertyName)) return Err;
+
+	const TSharedPtr<FJsonValue>* ValueField = Params->Values.Find(TEXT("value"));
+	if (!ValueField)
+	{
+		return MCPError(TEXT("Missing 'value' parameter (pass JSON null to clear an object reference)"));
+	}
+
+	FMCPBatchSelector Selector;
+	if (auto Err = MCPBatchReadSelector(Params, Selector)) return Err;
+	if (!Selector.bAny)
+	{
+		return MCPError(TEXT("Pass at least one selector: actorLabels, labelPrefix, labelContains, tag, classFilter, folderPath or folderPathPrefix"));
+	}
+
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), false);
+	const FString TransactionLabel = OptionalString(
+		Params, TEXT("transactionLabel"), TEXT("MCP bulk set component property"));
+
+	TArray<AActor*> Actors;
+	MCPBatchCollectActors(World, Selector, Actors);
+	if (Actors.Num() > MCPBatchMaxActors)
+	{
+		return MCPError(FString::Printf(
+			TEXT("The selector matched %d actors, over the maximum of %d. Narrow it."),
+			Actors.Num(), MCPBatchMaxActors));
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetStringField(TEXT("componentName"), ComponentName);
+	Result->SetStringField(TEXT("propertyName"), PropertyName);
+	Result->SetNumberField(TEXT("matchedActors"), Actors.Num());
+	MCPNoteLoadedOnlyEnumeration(World, Result);
+	{
+		const TArray<FString> Missing = MCPBatchMissingLabels(Selector, Actors);
+		if (Missing.Num() > 0)
+		{
+			Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(Missing));
+		}
+	}
+
+	TUniquePtr<FScopedTransaction> Transaction;
+	if (!bDryRun && !Actors.IsEmpty())
+	{
+		Transaction = MakeUnique<FScopedTransaction>(FText::FromString(TransactionLabel));
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Updated = 0;
+	int32 Failed = 0;
+	int32 WithoutComponent = 0;
+
+	for (AActor* Actor : Actors)
+	{
+		const FString Label = Actor->GetActorLabel();
+		TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+		Row->SetStringField(TEXT("actorLabel"), Label);
+
+		UActorComponent* Component = MCPBatchFindComponent(Actor, ComponentName);
+		if (!Component)
+		{
+			// An actor that has no such component is neither a success nor an
+			// error: it is a fact the caller has to be told, because a
+			// selector wide enough to be useful will pick some up.
+			++WithoutComponent;
+			Row->SetBoolField(TEXT("ok"), false);
+			Row->SetStringField(TEXT("status"), TEXT("no_such_component"));
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+		Row->SetStringField(TEXT("componentClass"), Component->GetClass()->GetName());
+
+		if (bDryRun)
+		{
+			FString ResolvedType;
+			const TSharedPtr<FJsonValue> Current =
+				MCPQuery::ReadDottedProperty(Component, PropertyName, ResolvedType);
+			const bool bResolvable = Current.IsValid();
+			Row->SetBoolField(TEXT("ok"), bResolvable);
+			Row->SetStringField(TEXT("status"), bResolvable ? TEXT("would_write") : TEXT("property_not_found"));
+			if (bResolvable)
+			{
+				Row->SetField(TEXT("currentValue"), Current);
+				Row->SetStringField(TEXT("propertyType"), ResolvedType);
+				++Updated;
+			}
+			else
+			{
+				++Failed;
+			}
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+
+		TSharedPtr<FJsonObject> SubParams = MakeShared<FJsonObject>();
+		SubParams->SetStringField(TEXT("actorLabel"), Label);
+		SubParams->SetStringField(TEXT("componentName"), ComponentName);
+		SubParams->SetStringField(TEXT("propertyName"), PropertyName);
+		SubParams->SetField(TEXT("value"), *ValueField);
+
+		bool bOk = false;
+		FString Error;
+		FString Previous;
+		MCPBatchReadVerdict(FLevelHandlers::SetComponentProperty(SubParams), bOk, Error, Previous);
+		Row->SetBoolField(TEXT("ok"), bOk);
+		Row->SetStringField(TEXT("status"), bOk ? TEXT("written") : TEXT("failed"));
+		if (!Previous.IsEmpty()) Row->SetStringField(TEXT("previousValue"), Previous);
+		if (!bOk)
+		{
+			Row->SetStringField(TEXT("error"), Error);
+			++Failed;
+		}
+		else
+		{
+			++Updated;
+		}
+		if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+	}
+
+	Result->SetBoolField(TEXT("success"), Failed == 0);
+	if (Failed > 0)
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d of %d matched actors did not accept the write; see results[]."), Failed, Actors.Num()));
+	}
+	Result->SetNumberField(bDryRun ? TEXT("wouldUpdate") : TEXT("updated"), Updated);
+	Result->SetNumberField(TEXT("failed"), Failed);
+	Result->SetNumberField(TEXT("actorsWithoutComponent"), WithoutComponent);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Actors.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (!bDryRun && Updated > 0)
+	{
+		MCPSetUpdated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("The level is left dirty and is NOT saved. Call level(save) when you are done."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// remove_components_by_class (#907)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::RemoveComponentsByClass(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	FString ComponentClassSpec;
+	if (auto Err = RequireString(Params, TEXT("componentClass"), ComponentClassSpec)) return Err;
+
+	UClass* ComponentClass = MCPResolveClassOfType(ComponentClassSpec, UActorComponent::StaticClass(), true);
+	if (!ComponentClass)
+	{
+		return MCPClassNotFoundError(ComponentClassSpec, TEXT("componentClass"));
+	}
+	const bool bMatchComponentSubclasses = OptionalBool(Params, TEXT("matchComponentSubclasses"), true);
+	const FString ComponentNameContains = OptionalString(Params, TEXT("componentNameContains"));
+
+	FMCPBatchSelector Selector;
+	if (auto Err = MCPBatchReadSelector(Params, Selector)) return Err;
+	// actorClassFilter is the name #907 asks for; classFilter is what every
+	// other level action calls it. Accept both rather than make the caller
+	// remember which action they are in.
+	const FString ActorClassFilter = OptionalString(Params, TEXT("actorClassFilter"));
+	if (!ActorClassFilter.IsEmpty() && !Selector.ActorClass && Selector.ActorClassFallback.IsEmpty())
+	{
+		Selector.ActorClass = MCPResolveClassOfType(ActorClassFilter, AActor::StaticClass(), true);
+		if (!Selector.ActorClass) Selector.ActorClassFallback = ActorClassFilter;
+		Selector.bAny = true;
+	}
+
+	// dryRun DEFAULTS TO TRUE. This deletes components whose auto-generated
+	// names a caller cannot enumerate, which means it is the one level action
+	// where the caller most needs to see the list before it happens. Same
+	// default, and same reason, as delete_exact_labeled_actors_in_levels.
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), true);
+	const bool bSave = OptionalBool(Params, TEXT("save"), false);
+	const FString TransactionLabel = OptionalString(
+		Params, TEXT("transactionLabel"), TEXT("MCP remove components by class"));
+
+	TArray<AActor*> Actors;
+	if (Selector.bAny)
+	{
+		MCPBatchCollectActors(World, Selector, Actors);
+	}
+	else
+	{
+		// No actor selector means every loaded actor. That is a legitimate
+		// request (230 orphans across 23 actors nobody had named yet), which
+		// is exactly why dryRun defaults to true.
+		for (TActorIterator<AActor> It(World); It; ++It)
+		{
+			if (AActor* Actor = *It) Actors.Add(Actor);
+		}
+		Actors.Sort([](const AActor& A, const AActor& B) { return A.GetPathName() < B.GetPathName(); });
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetStringField(TEXT("componentClass"), ComponentClass->GetName());
+	MCPNoteLoadedOnlyEnumeration(World, Result);
+	{
+		const TArray<FString> Missing = MCPBatchMissingLabels(Selector, Actors);
+		if (Missing.Num() > 0)
+		{
+			Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(Missing));
+		}
+	}
+
+	TUniquePtr<FScopedTransaction> Transaction;
+	if (!bDryRun)
+	{
+		Transaction = MakeUnique<FScopedTransaction>(FText::FromString(TransactionLabel));
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 ScannedActors = 0;
+	int32 MatchedComponents = 0;
+	int32 RemovedComponents = 0;
+	int32 SkippedNonInstance = 0;
+	int32 TouchedActors = 0;
+
+	for (AActor* Actor : Actors)
+	{
+		++ScannedActors;
+
+		TArray<UActorComponent*> Targets;
+		for (UActorComponent* Component : Actor->GetComponents())
+		{
+			if (!Component) continue;
+			const bool bClassMatches = bMatchComponentSubclasses
+				? Component->IsA(ComponentClass)
+				: (Component->GetClass() == ComponentClass);
+			if (!bClassMatches) continue;
+			if (!ComponentNameContains.IsEmpty() &&
+				!Component->GetName().Contains(ComponentNameContains, ESearchCase::IgnoreCase))
+			{
+				continue;
+			}
+			Targets.Add(Component);
+		}
+		if (Targets.IsEmpty())
+		{
+			continue;
+		}
+
+		// Deterministic order so a dry run and the commit that follows report
+		// the same names.
+		Targets.Sort([](const UActorComponent& A, const UActorComponent& B)
+		{
+			return A.GetName() < B.GetName();
+		});
+
+		TArray<FString> RemovedNames;
+		TArray<FString> SkippedNames;
+		for (UActorComponent* Component : Targets)
+		{
+			++MatchedComponents;
+			// Only instance components can be removed. A native or SCS
+			// component belongs to the class, and destroying it here would
+			// come back on the next construction rerun looking like the
+			// removal silently failed.
+			const bool bIsInstanceComponent = Actor->GetInstanceComponents().Contains(Component);
+			if (!bIsInstanceComponent)
+			{
+				++SkippedNonInstance;
+				SkippedNames.Add(Component->GetName());
+				continue;
+			}
+			if (bDryRun)
+			{
+				RemovedNames.Add(Component->GetName());
+				continue;
+			}
+			const FString Name = Component->GetName();
+			Actor->Modify();
+			Component->Modify();
+			Actor->RemoveInstanceComponent(Component);
+			Component->DestroyComponent();
+			RemovedNames.Add(Name);
+			++RemovedComponents;
+		}
+
+		if (RemovedNames.IsEmpty() && SkippedNames.IsEmpty())
+		{
+			continue;
+		}
+		++TouchedActors;
+		if (Rows.Num() < MCPBatchMaxResultRows)
+		{
+			TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+			Row->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+			Row->SetStringField(TEXT("actorClass"), Actor->GetClass()->GetName());
+			Row->SetNumberField(bDryRun ? TEXT("wouldRemove") : TEXT("removed"), RemovedNames.Num());
+			Row->SetArrayField(TEXT("components"), MCPStringListToJson(RemovedNames));
+			if (SkippedNames.Num() > 0)
+			{
+				Row->SetArrayField(TEXT("skippedNonInstanceComponents"), MCPStringListToJson(SkippedNames));
+			}
+			Rows.Add(MakeShared<FJsonValueObject>(Row));
+		}
+	}
+
+	Result->SetNumberField(TEXT("scannedActors"), ScannedActors);
+	Result->SetNumberField(TEXT("actorsAffected"), TouchedActors);
+	Result->SetNumberField(TEXT("matchedComponents"), MatchedComponents);
+	Result->SetNumberField(
+		bDryRun ? TEXT("wouldRemoveComponents") : TEXT("removedComponents"),
+		bDryRun ? MatchedComponents - SkippedNonInstance : RemovedComponents);
+	Result->SetNumberField(TEXT("skippedNonInstanceComponents"), SkippedNonInstance);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < TouchedActors);
+	Result->SetArrayField(TEXT("results"), Rows);
+
+	if (MatchedComponents == 0)
+	{
+		Result->SetStringField(TEXT("zeroMatchNote"), FString::Printf(
+			TEXT("No component of class '%s' was found on any of the %d actors enumerated. Check the class name with level(query_components, componentClass:'%s', countOnly:true) before assuming there is nothing to remove."),
+			*ComponentClass->GetName(), ScannedActors, *ComponentClassSpec));
+	}
+
+	if (!bDryRun && RemovedComponents > 0)
+	{
+		MCPSetUpdated(Result);
+		if (bSave)
+		{
+			const bool bSaved = FEditorFileUtils::SaveCurrentLevel();
+			Result->SetBoolField(TEXT("saved"), bSaved);
+			if (!bSaved)
+			{
+				Result->SetStringField(TEXT("saveError"),
+					TEXT("The removal landed but saving the level failed. The change is in memory and undoable; save from the editor or call level(save)."));
+			}
+		}
+		else
+		{
+			Result->SetBoolField(TEXT("saved"), false);
+			Result->SetStringField(TEXT("saveNote"),
+				TEXT("The level is left dirty and is NOT saved. Pass save=true, or call level(save), to commit it."));
+		}
+	}
+	else if (bDryRun)
+	{
+		Result->SetBoolField(TEXT("saved"), false);
+		Result->SetStringField(TEXT("dryRunNote"),
+			TEXT("dryRun defaults to TRUE for this action because it deletes components whose auto-generated names you cannot enumerate. Pass dryRun=false to commit."));
+	}
+
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// spawn_actors_batch (#987)
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::SpawnActorsBatch(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	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 bool bDryRun = OptionalBool(Params, TEXT("dryRun"), false);
+	const FString LabelPrefix = OptionalString(Params, TEXT("labelPrefix"));
+	const int32 MaxSpawn = FMath::Clamp(
+		OptionalInt(Params, TEXT("maxSpawn"), MCPBatchDefaultMaxSpawn), 1, MCPBatchHardMaxSpawn);
+	const FString TransactionLabel = OptionalString(
+		Params, TEXT("transactionLabel"), TEXT("MCP spawn actors batch"));
+
+	const TSharedPtr<FJsonObject>* SharedProperties = nullptr;
+	Params->TryGetObjectField(TEXT("properties"), SharedProperties);
+
+	// ── Build the transform list ────────────────────────────────────────────
+	//
+	// Three sources, and exactly one of them per call. The derived ones exist
+	// because the transforms in #987 were a function of geometry already in
+	// the editor: round-tripping 190 component bounds out and 190 transforms
+	// back in is what made it a Python job.
+	struct FPlannedSpawn
+	{
+		FTransform Transform;
+		FString Label;
+		FString Source;
+		TSharedPtr<FJsonObject> Properties;
+	};
+	TArray<FPlannedSpawn> Planned;
+	FString PlanSource;
+
+	const TArray<TSharedPtr<FJsonValue>>* InstanceValues = nullptr;
+	const TSharedPtr<FJsonObject>* FromComponents = nullptr;
+	const TSharedPtr<FJsonObject>* AlongSpline = nullptr;
+	const bool bHasInstances = Params->TryGetArrayField(TEXT("instances"), InstanceValues) && InstanceValues;
+	const bool bHasFromComponents = Params->TryGetObjectField(TEXT("fromComponents"), FromComponents) && FromComponents;
+	const bool bHasAlongSpline = Params->TryGetObjectField(TEXT("alongSpline"), AlongSpline) && AlongSpline;
+
+	const int32 SourceCount = (bHasInstances ? 1 : 0) + (bHasFromComponents ? 1 : 0) + (bHasAlongSpline ? 1 : 0);
+	if (SourceCount == 0)
+	{
+		return MCPError(TEXT("Pass exactly one of 'instances' (explicit transforms), 'fromComponents' (one actor per matched component's bounds) or 'alongSpline' (scatter by distance)"));
+	}
+	if (SourceCount > 1)
+	{
+		return MCPError(TEXT("Pass only ONE of 'instances', 'fromComponents' or 'alongSpline'; combining them makes the spawn count ambiguous"));
+	}
+
+	if (bHasInstances)
+	{
+		PlanSource = TEXT("instances");
+		for (int32 Index = 0; Index < InstanceValues->Num(); ++Index)
+		{
+			const TSharedPtr<FJsonValue>& Entry = (*InstanceValues)[Index];
+			if (!Entry.IsValid() || Entry->Type != EJson::Object)
+			{
+				return MCPError(FString::Printf(TEXT("'instances[%d]' must be an object"), Index));
+			}
+			const TSharedPtr<FJsonObject> Row = Entry->AsObject();
+			const TSharedPtr<FJsonObject>* LocationObject = nullptr;
+			const TSharedPtr<FJsonObject>* RotationObject = nullptr;
+			const TSharedPtr<FJsonObject>* ScaleObject = nullptr;
+			Row->TryGetObjectField(TEXT("location"), LocationObject);
+			Row->TryGetObjectField(TEXT("rotation"), RotationObject);
+			Row->TryGetObjectField(TEXT("scale"), ScaleObject);
+
+			FPlannedSpawn Spawn;
+			Spawn.Transform = FTransform(
+				RotationObject ? MCPBatchReadRotator(*RotationObject, FRotator::ZeroRotator) : FRotator::ZeroRotator,
+				LocationObject ? MCPBatchReadVector(*LocationObject, FVector::ZeroVector) : FVector::ZeroVector,
+				ScaleObject ? MCPBatchReadVector(*ScaleObject, FVector::OneVector) : FVector::OneVector);
+			Row->TryGetStringField(TEXT("label"), Spawn.Label);
+			Spawn.Source = TEXT("instance");
+			const TSharedPtr<FJsonObject>* RowProperties = nullptr;
+			if (Row->TryGetObjectField(TEXT("properties"), RowProperties) && RowProperties)
+			{
+				Spawn.Properties = *RowProperties;
+			}
+			Planned.Add(MoveTemp(Spawn));
+		}
+	}
+	else if (bHasFromComponents)
+	{
+		PlanSource = TEXT("fromComponents");
+		const TSharedPtr<FJsonObject> Source = *FromComponents;
+
+		const FString ComponentClassSpec = OptionalString(Source, TEXT("componentClass"));
+		UClass* ComponentClass = ComponentClassSpec.IsEmpty()
+			? nullptr
+			: MCPResolveClassOfType(ComponentClassSpec, UActorComponent::StaticClass(), true);
+		if (!ComponentClassSpec.IsEmpty() && !ComponentClass)
+		{
+			return MCPClassNotFoundError(ComponentClassSpec, TEXT("fromComponents.componentClass"));
+		}
+		const FString ComponentNameContains = OptionalString(Source, TEXT("componentNameContains"));
+
+		FMCPBatchSelector Selector;
+		if (auto Err = MCPBatchReadSelector(Source, Selector)) return Err;
+
+		// Local by default, and this is the whole point of the mode. A
+		// component's WORLD bounds are axis-aligned, so on a rotated lamp post
+		// "the top of the mesh" computed from world bounds is not on the lamp
+		// post. The local bounds carry the component's own orientation, and
+		// transforming the offset by the component transform puts the spawn
+		// where a human would point.
+		const FString Space = OptionalString(Source, TEXT("space"), TEXT("local")).ToLower();
+		if (Space != TEXT("local") && Space != TEXT("world"))
+		{
+			return MCPError(TEXT("'fromComponents.space' must be either 'local' (default) or 'world'"));
+		}
+		const bool bLocal = Space == TEXT("local");
+
+		const TSharedPtr<FJsonObject>* OffsetObject = nullptr;
+		Source->TryGetObjectField(TEXT("offset"), OffsetObject);
+		const FVector Offset = OffsetObject ? MCPBatchReadVector(*OffsetObject, FVector::ZeroVector) : FVector::ZeroVector;
+
+		const TSharedPtr<FJsonObject>* FractionObject = nullptr;
+		Source->TryGetObjectField(TEXT("extentFraction"), FractionObject);
+		const FVector ExtentFraction = FractionObject
+			? MCPBatchReadVector(*FractionObject, FVector::ZeroVector)
+			: FVector::ZeroVector;
+
+		const bool bInheritRotation = OptionalBool(Source, TEXT("inheritRotation"), false);
+
+		for (TActorIterator<AActor> It(World); It; ++It)
+		{
+			AActor* Actor = *It;
+			if (!Actor) continue;
+			if (Selector.bAny && !MCPBatchActorMatches(Selector, Actor, Actor->GetActorLabel())) continue;
+
+			for (UActorComponent* Component : Actor->GetComponents())
+			{
+				USceneComponent* SceneComponent = Cast<USceneComponent>(Component);
+				if (!SceneComponent) continue;
+				if (ComponentClass && !SceneComponent->IsA(ComponentClass)) continue;
+				if (!ComponentNameContains.IsEmpty() &&
+					!SceneComponent->GetName().Contains(ComponentNameContains, ESearchCase::IgnoreCase))
+				{
+					continue;
+				}
+
+				const FTransform ComponentTransform = SceneComponent->GetComponentTransform();
+				FVector Location;
+				if (bLocal)
+				{
+					const FBoxSphereBounds LocalBounds = SceneComponent->GetLocalBounds();
+					const FVector LocalPoint =
+						LocalBounds.Origin + LocalBounds.BoxExtent * ExtentFraction + Offset;
+					Location = ComponentTransform.TransformPosition(LocalPoint);
+				}
+				else
+				{
+					const FBoxSphereBounds WorldBounds = SceneComponent->GetBounds();
+					Location = WorldBounds.Origin + WorldBounds.BoxExtent * ExtentFraction + Offset;
+				}
+
+				FPlannedSpawn Spawn;
+				Spawn.Transform = FTransform(
+					bInheritRotation ? ComponentTransform.Rotator() : FRotator::ZeroRotator,
+					Location,
+					FVector::OneVector);
+				Spawn.Source = FString::Printf(TEXT("%s.%s"), *Actor->GetActorLabel(), *SceneComponent->GetName());
+				Planned.Add(MoveTemp(Spawn));
+			}
+		}
+		Planned.Sort([](const FPlannedSpawn& A, const FPlannedSpawn& B) { return A.Source < B.Source; });
+	}
+	else
+	{
+		PlanSource = TEXT("alongSpline");
+		const TSharedPtr<FJsonObject> Source = *AlongSpline;
+
+		FString SplineActorLabel;
+		if (auto Err = RequireStringAlt(Source, TEXT("actorLabel"), TEXT("actorPath"), SplineActorLabel)) return Err;
+		// #983: the spline the batch runs along is selected the same way as
+		// any other actor, and a duplicated label refuses rather than picking
+		// a spline at the other end of the map to scatter along.
+		TSharedPtr<FJsonValue> SplineErr;
+		AActor* SplineActor = MCPResolveActor(World, Source, SplineErr);
+		if (!SplineActor) return SplineErr;
+		SplineActorLabel = SplineActor->GetActorLabel();
+		const FString SplineComponentName = OptionalString(Source, TEXT("componentName"));
+		USplineComponent* Spline = nullptr;
+		for (UActorComponent* Component : SplineActor->GetComponents())
+		{
+			USplineComponent* Candidate = Cast<USplineComponent>(Component);
+			if (!Candidate) continue;
+			if (SplineComponentName.IsEmpty() ||
+				Candidate->GetName().Equals(SplineComponentName, ESearchCase::IgnoreCase))
+			{
+				Spline = Candidate;
+				break;
+			}
+		}
+		if (!Spline)
+		{
+			return MCPError(FString::Printf(
+				TEXT("No SplineComponent%s on actor '%s'"),
+				SplineComponentName.IsEmpty() ? TEXT("") : *FString::Printf(TEXT(" named '%s'"), *SplineComponentName),
+				*SplineActorLabel));
+		}
+
+		const double Spacing = OptionalNumber(Source, TEXT("spacing"), 0.0);
+		if (Spacing < MCPBatchMinSplineSpacing)
+		{
+			return MCPError(FString::Printf(
+				TEXT("'alongSpline.spacing' must be at least %.0f cm; a smaller value would spawn an unbounded number of actors"),
+				MCPBatchMinSplineSpacing));
+		}
+		const double SplineLength = Spline->GetSplineLength();
+		const double StartDistance = FMath::Clamp(
+			OptionalNumber(Source, TEXT("startDistance"), 0.0), 0.0, SplineLength);
+		const double EndDistance = FMath::Clamp(
+			OptionalNumber(Source, TEXT("endDistance"), SplineLength), StartDistance, SplineLength);
+		const bool bAlignToTangent = OptionalBool(Source, TEXT("alignToTangent"), true);
+
+		const TSharedPtr<FJsonObject>* OffsetObject = nullptr;
+		Source->TryGetObjectField(TEXT("offset"), OffsetObject);
+		const FVector Offset = OffsetObject ? MCPBatchReadVector(*OffsetObject, FVector::ZeroVector) : FVector::ZeroVector;
+
+		for (double Distance = StartDistance; Distance <= EndDistance; Distance += Spacing)
+		{
+			const FRotator Rotation = Spline->GetRotationAtDistanceAlongSpline(
+				Distance, ESplineCoordinateSpace::World);
+			FVector Location = Spline->GetLocationAtDistanceAlongSpline(
+				Distance, ESplineCoordinateSpace::World);
+			// The offset follows the spline's frame when aligning to it, so
+			// "20cm to the left of the path" stays to the left round a corner.
+			Location += bAlignToTangent ? Rotation.RotateVector(Offset) : Offset;
+
+			FPlannedSpawn Spawn;
+			Spawn.Transform = FTransform(
+				bAlignToTangent ? Rotation : FRotator::ZeroRotator, Location, FVector::OneVector);
+			Spawn.Source = FString::Printf(TEXT("%s@%.0f"), *Spline->GetName(), Distance);
+			Planned.Add(MoveTemp(Spawn));
+
+			if (Planned.Num() > MCPBatchHardMaxSpawn)
+			{
+				break;
+			}
+		}
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetStringField(TEXT("actorClass"), ActorClass->GetPathName());
+	Result->SetStringField(TEXT("source"), PlanSource);
+	Result->SetNumberField(TEXT("planned"), Planned.Num());
+
+	if (Planned.Num() > MaxSpawn)
+	{
+		Result->SetBoolField(TEXT("success"), false);
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("The plan produced %d spawns, over maxSpawn (%d). Narrow the selector or raise maxSpawn deliberately."),
+			Planned.Num(), MaxSpawn));
+		Result->SetNumberField(TEXT("maxSpawn"), MaxSpawn);
+		return MCPResult(Result);
+	}
+	if (Planned.IsEmpty())
+	{
+		Result->SetNumberField(TEXT("spawned"), 0);
+		Result->SetArrayField(TEXT("results"), TArray<TSharedPtr<FJsonValue>>());
+		Result->SetStringField(TEXT("zeroMatchNote"),
+			TEXT("The plan produced no positions. For fromComponents, check componentClass and the actor selector with level(query_components, countOnly:true); for alongSpline, check the spline length against startDistance/endDistance."));
+		return MCPResult(Result);
+	}
+
+	TUniquePtr<FScopedTransaction> Transaction;
+	if (!bDryRun)
+	{
+		Transaction = MakeUnique<FScopedTransaction>(FText::FromString(TransactionLabel));
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Spawned = 0;
+	int32 Failed = 0;
+	int32 PropertyFailures = 0;
+
+	for (int32 Index = 0; Index < Planned.Num(); ++Index)
+	{
+		const FPlannedSpawn& Plan = Planned[Index];
+		TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+		Row->SetNumberField(TEXT("index"), Index);
+		Row->SetStringField(TEXT("from"), Plan.Source);
+		Row->SetObjectField(TEXT("location"), MCPVec3ToJsonObject(Plan.Transform.GetLocation()));
+		Row->SetObjectField(TEXT("rotation"), MCPRotatorToJsonObject(Plan.Transform.Rotator()));
+		Row->SetObjectField(TEXT("scale"), MCPVec3ToJsonObject(Plan.Transform.GetScale3D()));
+
+		if (bDryRun)
+		{
+			Row->SetBoolField(TEXT("ok"), true);
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+
+		FActorSpawnParameters SpawnParameters;
+		SpawnParameters.SpawnCollisionHandlingOverride = ESpawnActorCollisionHandlingMethod::AlwaysSpawn;
+		AActor* Actor = World->SpawnActor<AActor>(ActorClass, Plan.Transform, SpawnParameters);
+		if (!Actor)
+		{
+			++Failed;
+			Row->SetBoolField(TEXT("ok"), false);
+			Row->SetStringField(TEXT("error"), TEXT("SpawnActor returned null"));
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+		++Spawned;
+
+		FString Label = Plan.Label;
+		if (Label.IsEmpty() && !LabelPrefix.IsEmpty())
+		{
+			Label = FString::Printf(TEXT("%s%d"), *LabelPrefix, Index);
+		}
+		if (!Label.IsEmpty())
+		{
+			Actor->SetActorLabel(Label);
+		}
+		Row->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+		Row->SetBoolField(TEXT("ok"), true);
+
+		// Per-instance properties override the shared ones, so a caller can
+		// set one field per spawn without repeating the rest.
+		TArray<TSharedPtr<FJsonValue>> PropertyRows;
+		auto ApplyProperties = [&](const TSharedPtr<FJsonObject>& Properties)
+		{
+			if (!Properties.IsValid()) return;
+			for (const TPair<FString, TSharedPtr<FJsonValue>>& Pair : Properties->Values)
+			{
+				TSharedPtr<FJsonObject> SubParams = MakeShared<FJsonObject>();
+				SubParams->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+				SubParams->SetStringField(TEXT("propertyName"), Pair.Key);
+				SubParams->SetField(TEXT("value"), Pair.Value);
+				SubParams->SetBoolField(TEXT("force"), true);
+
+				bool bOk = false;
+				FString Error;
+				FString Previous;
+				MCPBatchReadVerdict(FLevelHandlers::SetActorProperty(SubParams), bOk, Error, Previous);
+				TSharedPtr<FJsonObject> PropertyRow = MakeShared<FJsonObject>();
+				PropertyRow->SetStringField(TEXT("propertyName"), Pair.Key);
+				PropertyRow->SetBoolField(TEXT("ok"), bOk);
+				if (!bOk)
+				{
+					PropertyRow->SetStringField(TEXT("error"), Error);
+					++PropertyFailures;
+				}
+				PropertyRows.Add(MakeShared<FJsonValueObject>(PropertyRow));
+			}
+		};
+		ApplyProperties(SharedProperties ? *SharedProperties : nullptr);
+		ApplyProperties(Plan.Properties);
+		if (PropertyRows.Num() > 0)
+		{
+			Row->SetArrayField(TEXT("properties"), PropertyRows);
+		}
+
+		if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+	}
+
+	Result->SetBoolField(TEXT("success"), Failed == 0);
+	if (Failed > 0)
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d of %d planned spawns failed; see results[]."), Failed, Planned.Num()));
+	}
+	Result->SetNumberField(bDryRun ? TEXT("wouldSpawn") : TEXT("spawned"), bDryRun ? Planned.Num() : Spawned);
+	Result->SetNumberField(TEXT("failed"), Failed);
+	Result->SetNumberField(TEXT("propertyFailures"), PropertyFailures);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Planned.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (!bDryRun && Spawned > 0)
+	{
+		MCPSetCreated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("The level is left dirty and is NOT saved. Call level(save) when you are done."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// set_component_materials (#946)
+//
+// material(build_material) writes the ASSET's material slots. A placed actor
+// usually needs the other thing: a per-slot COMPONENT override, which is what
+// the details panel edits and what SetMaterial writes into OverrideMaterials.
+// There was no action for that. set_actor_material does one slot, on whichever
+// primitive component it happens to find first, so dressing a placed skeletal
+// mesh meant a Python loop over get_num_materials().
+// ---------------------------------------------------------------------------
+TSharedPtr<FJsonValue> FLevelHandlers::SetComponentMaterials(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	FMCPBatchSelector Selector;
+	if (auto Err = MCPBatchReadSelector(Params, Selector)) return Err;
+	if (!Selector.bAny)
+	{
+		return MCPError(TEXT("Pass at least one selector: actorLabels, labelPrefix, labelContains, tag, classFilter, folderPath or folderPathPrefix"));
+	}
+
+	const FString ComponentName = OptionalString(Params, TEXT("componentName"));
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), false);
+	const bool bClearOverrides = OptionalBool(Params, TEXT("clearOverrides"), false);
+	const FString SingleMaterialPath = OptionalString(Params, TEXT("material"));
+
+	const TArray<TSharedPtr<FJsonValue>>* MaterialValues = nullptr;
+	const bool bHasMaterialList = Params->TryGetArrayField(TEXT("materials"), MaterialValues) && MaterialValues;
+
+	const int32 ModeCount = (bHasMaterialList ? 1 : 0) + (SingleMaterialPath.IsEmpty() ? 0 : 1) + (bClearOverrides ? 1 : 0);
+	if (ModeCount == 0)
+	{
+		return MCPError(TEXT("Pass 'materials' (per-slot paths), 'material' (one path applied to every slot) or clearOverrides=true"));
+	}
+	if (ModeCount > 1)
+	{
+		return MCPError(TEXT("Pass only ONE of 'materials', 'material' or clearOverrides; together they would fight over the same slots"));
+	}
+
+	// Resolve every requested material up front. A path that does not load is
+	// a caller error, and finding that out after writing half the slots on
+	// half the actors is not a useful place to find it out.
+	TArray<UMaterialInterface*> SlotMaterials;
+	if (bHasMaterialList)
+	{
+		for (int32 Index = 0; Index < MaterialValues->Num(); ++Index)
+		{
+			const TSharedPtr<FJsonValue>& Entry = (*MaterialValues)[Index];
+			FString Path;
+			const bool bIsClear = !Entry.IsValid() || Entry->Type == EJson::Null ||
+				(Entry->TryGetString(Path) && Path.IsEmpty());
+			if (bIsClear)
+			{
+				// An explicit null clears that one slot's override, so a caller
+				// can reset slot 2 without touching the rest.
+				SlotMaterials.Add(nullptr);
+				continue;
+			}
+			UMaterialInterface* Material = LoadObject<UMaterialInterface>(nullptr, *Path);
+			if (!Material)
+			{
+				return MCPError(FString::Printf(
+					TEXT("Material not found for 'materials[%d]': %s"), Index, *Path));
+			}
+			SlotMaterials.Add(Material);
+		}
+	}
+	UMaterialInterface* SingleMaterial = nullptr;
+	if (!SingleMaterialPath.IsEmpty())
+	{
+		SingleMaterial = LoadObject<UMaterialInterface>(nullptr, *SingleMaterialPath);
+		if (!SingleMaterial)
+		{
+			return MCPError(FString::Printf(TEXT("Material not found: %s"), *SingleMaterialPath));
+		}
+	}
+
+	TArray<AActor*> Actors;
+	MCPBatchCollectActors(World, Selector, Actors);
+	if (Actors.Num() > MCPBatchMaxActors)
+	{
+		return MCPError(FString::Printf(
+			TEXT("The selector matched %d actors, over the maximum of %d. Narrow it."),
+			Actors.Num(), MCPBatchMaxActors));
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetNumberField(TEXT("matchedActors"), Actors.Num());
+	MCPNoteLoadedOnlyEnumeration(World, Result);
+	{
+		const TArray<FString> Missing = MCPBatchMissingLabels(Selector, Actors);
+		if (Missing.Num() > 0)
+		{
+			Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(Missing));
+		}
+	}
+
+	TUniquePtr<FScopedTransaction> Transaction;
+	if (!bDryRun && !Actors.IsEmpty())
+	{
+		Transaction = MakeUnique<FScopedTransaction>(FText::FromString(
+			OptionalString(Params, TEXT("transactionLabel"), TEXT("MCP set component materials"))));
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Updated = 0;
+	int32 WithoutComponent = 0;
+	int32 SlotWrites = 0;
+	int32 OutOfRange = 0;
+
+	for (AActor* Actor : Actors)
+	{
+		TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+		Row->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+
+		UMeshComponent* MeshComponent = nullptr;
+		if (ComponentName.IsEmpty())
+		{
+			MeshComponent = Actor->FindComponentByClass<UMeshComponent>();
+		}
+		else
+		{
+			MeshComponent = Cast<UMeshComponent>(MCPBatchFindComponent(Actor, ComponentName));
+		}
+		if (!MeshComponent)
+		{
+			++WithoutComponent;
+			Row->SetBoolField(TEXT("ok"), false);
+			Row->SetStringField(TEXT("status"), TEXT("no_mesh_component"));
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+		Row->SetStringField(TEXT("componentName"), MeshComponent->GetName());
+		Row->SetStringField(TEXT("componentClass"), MeshComponent->GetClass()->GetName());
+
+		const int32 SlotCount = MeshComponent->GetNumMaterials();
+		Row->SetNumberField(TEXT("slotCount"), SlotCount);
+		const TArray<FName> SlotNames = MeshComponent->GetMaterialSlotNames();
+
+		if (bHasMaterialList && SlotMaterials.Num() > SlotCount)
+		{
+			// Extra entries would silently do nothing, which reads as a
+			// successful assignment that did not happen.
+			++OutOfRange;
+			Row->SetBoolField(TEXT("ok"), false);
+			Row->SetStringField(TEXT("status"), TEXT("too_many_materials"));
+			Row->SetStringField(TEXT("error"), FString::Printf(
+				TEXT("%d materials given but the component has %d slots"), SlotMaterials.Num(), SlotCount));
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+			continue;
+		}
+
+		TArray<TSharedPtr<FJsonValue>> SlotRows;
+		const int32 WriteCount = bHasMaterialList ? SlotMaterials.Num() : SlotCount;
+		for (int32 SlotIndex = 0; SlotIndex < WriteCount; ++SlotIndex)
+		{
+			UMaterialInterface* Before = MeshComponent->GetMaterial(SlotIndex);
+			const bool bWasOverride =
+				MeshComponent->OverrideMaterials.IsValidIndex(SlotIndex) &&
+				MeshComponent->OverrideMaterials[SlotIndex] != nullptr;
+
+			UMaterialInterface* Desired = nullptr;
+			if (bHasMaterialList) Desired = SlotMaterials[SlotIndex];
+			else if (SingleMaterial) Desired = SingleMaterial;
+
+			if (!bDryRun)
+			{
+				MeshComponent->Modify();
+				// A null override is how the asset's own slot shows through
+				// again, which is the inverse of what this action does and is
+				// otherwise unreachable.
+				MeshComponent->SetMaterial(SlotIndex, bClearOverrides ? nullptr : Desired);
+				++SlotWrites;
+			}
+
+			UMaterialInterface* After = bDryRun ? Before : MeshComponent->GetMaterial(SlotIndex);
+			const bool bIsOverride = bDryRun
+				? bWasOverride
+				: (MeshComponent->OverrideMaterials.IsValidIndex(SlotIndex) &&
+				   MeshComponent->OverrideMaterials[SlotIndex] != nullptr);
+
+			TSharedPtr<FJsonObject> SlotRow = MakeShared<FJsonObject>();
+			SlotRow->SetNumberField(TEXT("slotIndex"), SlotIndex);
+			SlotRow->SetStringField(TEXT("slotName"),
+				SlotNames.IsValidIndex(SlotIndex) ? SlotNames[SlotIndex].ToString() : FString());
+			SlotRow->SetStringField(TEXT("previousMaterialPath"), Before ? Before->GetPathName() : FString());
+			SlotRow->SetStringField(TEXT("previousSource"),
+				bWasOverride ? TEXT("componentOverride") : (Before ? TEXT("meshDefault") : TEXT("none")));
+			SlotRow->SetStringField(TEXT("materialPath"), After ? After->GetPathName() : FString());
+			// Read back rather than echoing: the difference between "the
+			// component now overrides this slot" and "the asset happens to
+			// have that material" is the whole distinction #946 is about.
+			SlotRow->SetStringField(TEXT("source"),
+				bIsOverride ? TEXT("componentOverride") : (After ? TEXT("meshDefault") : TEXT("none")));
+			SlotRows.Add(MakeShared<FJsonValueObject>(SlotRow));
+		}
+
+		if (!bDryRun)
+		{
+			MeshComponent->MarkRenderStateDirty();
+			Actor->MarkPackageDirty();
+			++Updated;
+		}
+		Row->SetBoolField(TEXT("ok"), true);
+		Row->SetStringField(TEXT("status"), bDryRun ? TEXT("would_write") : TEXT("written"));
+		Row->SetArrayField(TEXT("slots"), SlotRows);
+		if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+	}
+
+	Result->SetBoolField(TEXT("success"), OutOfRange == 0);
+	if (OutOfRange > 0)
+	{
+		Result->SetStringField(TEXT("error"), FString::Printf(
+			TEXT("%d actor(s) were given more materials than their component has slots; see results[]."), OutOfRange));
+	}
+	Result->SetNumberField(bDryRun ? TEXT("wouldUpdate") : TEXT("updated"),
+		bDryRun ? Actors.Num() - WithoutComponent : Updated);
+	Result->SetNumberField(TEXT("slotWrites"), SlotWrites);
+	Result->SetNumberField(TEXT("actorsWithoutMeshComponent"), WithoutComponent);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Actors.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (!bDryRun && Updated > 0)
+	{
+		MCPSetUpdated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("These are COMPONENT overrides on placed actors, so the LEVEL is dirty and is NOT saved. The mesh ASSET is untouched; use material(build_material) or asset(set_property) to write the asset's own slots."));
+	}
+	return MCPResult(Result);
+}
+
+// ---------------------------------------------------------------------------
+// set_actor_hlod_layer (#985)
+// ---------------------------------------------------------------------------
+//
+// Assigning an HLODLayer override across 295 InstancedFoliageActors was a
+// Python loop, for the same reason every other action in this file exists: the
+// selector vocabulary lived on the client and every actor cost a round trip.
+//
+// This lives beside the other selector-driven batch writes rather than with the
+// World Partition settings, because the selector, the bounds, the dry run and
+// the missing-label reporting are all shared with them, and a second copy of
+// that vocabulary would be one more thing to drift.
+//
+// The write goes through AActor::SetHLODLayer rather than through the reflected
+// property. HLODLayer is a private UPROPERTY and reflection would reach it, but
+// the engine's own setter is what the HLOD system expects to have been called,
+// and a bulk write that skipped it would be the kind of edit that looks applied
+// and behaves differently from one made in the details panel.
+TSharedPtr<FJsonValue> FLevelHandlers::SetActorHLODLayer(const TSharedPtr<FJsonObject>& Params)
+{
+	MCP_CHECK_GAME_THREAD();
+	REQUIRE_EDITOR_WORLD(World);
+
+	// null clears the override, which is a legitimate request and has to be
+	// distinguishable from "the parameter was omitted".
+	if (!Params->HasField(TEXT("hlodLayer")))
+	{
+		return MCPError(TEXT("Missing 'hlodLayer': an HLODLayer asset path, or null to clear the per-actor override"));
+	}
+	FString LayerPath;
+	Params->TryGetStringField(TEXT("hlodLayer"), LayerPath);
+	LayerPath.TrimStartAndEndInline();
+
+	UHLODLayer* Layer = nullptr;
+	if (!LayerPath.IsEmpty())
+	{
+		Layer = LoadAssetByPath<UHLODLayer>(LayerPath);
+		if (!Layer) return MCPAssetLoadError(LayerPath, TEXT("UHLODLayer"));
+	}
+
+	FMCPBatchSelector Selector;
+	if (auto Err = MCPBatchReadSelector(Params, Selector)) return Err;
+	if (!Selector.bAny)
+	{
+		return MCPError(TEXT("Pass at least one selector: actorLabels, labelPrefix, labelContains, tag, classFilter, folderPath or folderPathPrefix"));
+	}
+
+	const bool bDryRun = OptionalBool(Params, TEXT("dryRun"), false);
+	const bool bHasAutoLODField = Params->HasField(TEXT("enableAutoLODGeneration"));
+	const bool bEnableAutoLOD = OptionalBool(Params, TEXT("enableAutoLODGeneration"), true);
+	const FString TransactionLabel = OptionalString(
+		Params, TEXT("transactionLabel"), TEXT("MCP set actor HLOD layer"));
+
+	TArray<AActor*> Actors;
+	MCPBatchCollectActors(World, Selector, Actors);
+	if (Actors.Num() > MCPBatchMaxActors)
+	{
+		return MCPError(FString::Printf(
+			TEXT("The selector matched %d actors, over the maximum of %d. Narrow it."),
+			Actors.Num(), MCPBatchMaxActors));
+	}
+
+	auto Result = MCPSuccess();
+	Result->SetBoolField(TEXT("dryRun"), bDryRun);
+	Result->SetStringField(TEXT("hlodLayer"), Layer ? Layer->GetPathName() : FString());
+	Result->SetBoolField(TEXT("clearing"), Layer == nullptr);
+	Result->SetNumberField(TEXT("matched"), Actors.Num());
+	MCPNoteLoadedOnlyEnumeration(World, Result);
+	{
+		const TArray<FString> Missing = MCPBatchMissingLabels(Selector, Actors);
+		if (Missing.Num() > 0)
+		{
+			Result->SetArrayField(TEXT("missingLabels"), MCPStringListToJson(Missing));
+		}
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	int32 Updated = 0;
+	int32 Unchanged = 0;
+	{
+		const FScopedTransaction Transaction(FText::FromString(TransactionLabel));
+		for (AActor* Actor : Actors)
+		{
+			if (!Actor) continue;
+			UHLODLayer* Previous = Actor->GetHLODLayer();
+			const bool bWouldChange = Previous != Layer;
+
+			TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+			Row->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+			Row->SetStringField(TEXT("actorClass"), Actor->GetClass()->GetName());
+			Row->SetStringField(TEXT("previousHLODLayer"), Previous ? Previous->GetPathName() : FString());
+
+			if (!bWouldChange && !bHasAutoLODField)
+			{
+				// Already what was asked for. Reporting it as an update would
+				// make a no-op look like work, which is what makes a rerun
+				// impossible to reason about.
+				++Unchanged;
+				Row->SetStringField(TEXT("status"), TEXT("unchanged"));
+				if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+				continue;
+			}
+
+			if (bDryRun)
+			{
+				Row->SetStringField(TEXT("status"), TEXT("would_write"));
+				if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+				continue;
+			}
+
+			Actor->Modify();
+			Actor->SetHLODLayer(Layer);
+			if (bHasAutoLODField)
+			{
+				// The layer only matters when the actor is allowed to build
+				// HLODs at all, so the two are settable in one call.
+				Actor->bEnableAutoLODGeneration = bEnableAutoLOD;
+			}
+			Actor->PostEditChange();
+			Actor->MarkPackageDirty();
+			++Updated;
+
+			UHLODLayer* After = Actor->GetHLODLayer();
+			Row->SetStringField(TEXT("hlodLayer"), After ? After->GetPathName() : FString());
+			Row->SetBoolField(TEXT("enableAutoLODGeneration"), Actor->bEnableAutoLODGeneration);
+			Row->SetStringField(TEXT("status"), TEXT("written"));
+			if (Rows.Num() < MCPBatchMaxResultRows) Rows.Add(MakeShared<FJsonValueObject>(Row));
+		}
+	}
+
+	Result->SetNumberField(bDryRun ? TEXT("wouldUpdate") : TEXT("updated"),
+		bDryRun ? Actors.Num() - Unchanged : Updated);
+	Result->SetNumberField(TEXT("unchanged"), Unchanged);
+	Result->SetNumberField(TEXT("returnedResults"), Rows.Num());
+	Result->SetBoolField(TEXT("resultsTruncated"), Rows.Num() < Actors.Num());
+	Result->SetArrayField(TEXT("results"), Rows);
+	if (!bDryRun && Updated > 0)
+	{
+		MCPSetUpdated(Result);
+		Result->SetStringField(TEXT("saveNote"),
+			TEXT("On a World Partition map each actor lives in its own package, so this dirties one package per actor. Save them with level(save) or editor(save_dirty). HLOD assignment takes effect on the next HLOD build."));
+	}
+	return MCPResult(Result);
+}