WorldSweep
A batch scripting system for executing custom operations across large UE5 World Partition maps, cell by cell.
Overview
WorldSweep is an Unreal Engine 5 editor plugin that lets you run custom batch operations across your entire world, regardless of how large it is. Instead of manually iterating through levels or writing boilerplate asset tooling, WorldSweep handles all the cell loading, unloading, and iteration for you. You define what to do; WorldSweep figures out how to do it efficiently.
It works with World Partition maps, Streaming Level setups, and flat single-level worlds, detected automatically. From auditing actor names to mass-replacing classes or enforcing Nanite standards, any repeatable world operation becomes a clean, cancellable, resumable batch job.
Cell-by-Cell Iteration
Automatically partitions any world into cells and processes them one at a time, no memory spikes, no editor freezes.
Blueprint & C++ Scripts
Write batch logic in Blueprint or C++. Subclass WorldSweepScript and implement only the events you need.
Audit Before You Apply
Every built-in script ships with a dry-run mode. See exactly what would change before committing a single modification.
CI/CD Ready
Run any batch headlessly from the command line. Integrate world validation or mass-update pipelines directly into your build process.
World-Type Auto-Detection
No setup needed. WorldSweep detects whether your world uses World Partition, Streaming Levels, or is a flat level and adapts automatically.
Priority-Based Passes
Scripts with the same priority share a cell pass, minimising load/unload cycles. Fine-tune execution order when scripts depend on each other.
Auto-Save & Source Control
Optionally auto-save modified packages per cell. Automatically attempts checkout when source control is active.
Visual Map View
Dedicated editor panel shows a live grid of your sweep area with cell-by-cell progress as the batch runs.
Getting Started
Running your first sweep takes five steps. No configuration files, no project settings, just a data asset and your script.
Enable the plugin
In the editor go to Edit → Plugins, search for WorldSweep, enable it, and restart the editor. The WorldSweep panel will appear under the Tools menu.
Create a Batch Asset
Right-click in the Content Browser and choose Miscellaneous → Data Asset → WorldSweepBatch. Name it to describe the operation, e.g. DA_AuditNanite.
Add scripts to the batch
Open the batch asset. In the Scripts array, add one or more WorldSweepScript instances, choose from the built-in scripts or your own custom ones. Configure each script's properties.
Define the sweep area
Open the WorldSweep panel (Tools menu), select your batch asset, and set the sweep bounds. Click Use Entire World to cover the full map automatically.
Run and review
Click Run. A progress dialog shows cells processed and actors visited in real-time. You can cancel at any point. Results and any warnings are written to the WorldSweep message log.
Batch Asset
A WorldSweepBatch is a data asset you create in the Content Browser. It acts as the recipe for a batch run, it holds which scripts to execute, how the world should be partitioned, and whether changes should be saved automatically. Create one per logical operation and reuse them as needed.
| Property | Type | Description | Default |
|---|---|---|---|
| Scripts | Array | The scripts to execute. Scripts run in array order within the same priority group for each cell. | , |
| CellSize | float (cm) | Size of each sweep cell in world units. Smaller values give finer iteration at the cost of more load/unload cycles. Match your World Partition streaming cell size for best results. | WP default |
| ActorClassFilter | Class | Optional. When set, only actors of this class or subclasses are passed to any script's OnActorFound. Leave empty to process all actors. | None |
| SweepMode | Enum | The iteration strategy to use. Auto is recommended, it detects the correct mode from the world type at runtime. | Auto |
| bSaveModifications | bool | Auto-saves and checks out packages dirtied by scripts during the sweep. Only packages made dirty after the batch started are tracked, pre-existing dirty packages are left untouched. In World Partition / Streaming Levels mode, packages are saved per cell before GC. In Flat Level mode, at the end of the batch. Attempts source control checkout automatically when active. | false |
Sweep Script
A WorldSweepScript is the unit of work in WorldSweep. Subclass it in C++ or Blueprint to implement any batch operation. Each script declares which lifecycle events it participates in via its Scope, allowing the runner to skip unnecessary cell loads when no actor iteration is needed.
Event Flags
Scripts declare which events they need via an EventFlags bitmask. The runner uses this to skip unnecessary cell loads, a script that only needs batch-level events never triggers streaming at all. Flags can be combined freely.
CellEvents
Opt in to cell lifecycle events, OnPreCellLoad, OnCellStarted, OnCellCompleted. No actor or component callbacks.
Actors
Opt in to OnActorFound for every matching actor per cell. Combine with CellEvents when you need both.
Components
Opt in to OnComponentFound for every component on every matching actor. Implies actor iteration, no need to also set Actors.
OnBatchStarted and OnBatchCompleted, no cell loading is performed at all. Lifecycle Events
| Event | Flag Required | Description |
|---|---|---|
| OnBatchStarted | Always | Called once before the batch begins, after all script instances are initialised. |
| OnPreCellLoad | CellEvents | Called before a cell loads. Use to record timestamps or prepare per-cell state. |
| OnCellStarted | CellEvents | Called after a cell loads and before actors are processed. |
| OnActorFound | Actors | Called for each actor found in the current cell. Respects ActorTagFilter and the batch's ActorClassFilter. |
| OnComponentFound | Components | Called for each component on every matching actor in the current cell. Receives the component, its owner actor, and the cell bounds. Use when your logic targets components rather than actors directly. |
| OnCellCompleted | CellEvents | Called after all actors and components in the cell are processed, before the cell unloads. Ideal for applying deferred modifications. |
| OnBatchCompleted | Always | Called once after the entire batch finishes or is cancelled. Receives the total cells processed. |
Script Properties
| Property | Type | Description |
|---|---|---|
| EventFlags | Bitmask | Declares which events this script receives. Combine CellEvents Actors Components freely. The runner uses this to skip unnecessary cell streaming, set only the flags you actually need. |
| ActorTagFilter | Array<Tag> | If non-empty, OnActorFound is only called for actors that have at least one of these tags. |
| Priority | int32 | Lower values run first. Scripts sharing the same priority run in the same pass, sharing a single cell load/unload cycle. |
| World | UWorld* | The world being swept. Set by the runner before OnBatchStarted. Use to query or spawn actors during the batch. |
Sweep Modes
WorldSweep supports three world architectures, each with a dedicated execution strategy. Setting the batch's SweepMode to Auto detects the correct mode automatically, you only need to override this manually in edge cases.
Auto
Detects the world type at runtime and selects the appropriate strategy. Recommended for all projects.
World Partition
For UE5 World Partition maps. Iterates cells within the defined sweep area and streams each cell on demand.
Streaming Levels
For worlds composed of streaming sub-levels. Each sub-level is treated as a cell and processed individually.
Flat Level
For traditional single-level worlds. All actors are processed in one pass; packages are saved at the end of the batch.
Built-in Scripts
WorldSweep ships with seven ready-to-use scripts covering the most common world auditing and maintenance tasks. Every script that modifies data includes a bApplyChanges toggle, leave it off to run a safe dry-run first and review what would change.
Logs every actor found in each cell to the WorldSweep message log. Use as a starting point for building your own custom scripts, or to get a full inventory of actors in a region.
Replaces all actors of a given class with actors of another class, preserving their transform. Changes are collected during iteration and applied after the cell is fully processed to avoid modifying the iterator mid-flight.
Measures and logs how long each cell takes to stream in. After the batch completes, reports the minimum, maximum, and average load times across all cells, helping you identify slow-loading regions before they become runtime streaming hitches.
No configuration required, add it to any batch and it runs automatically.
Audits or sets the collision profile on all primitive components of every actor visited. Ensures collision standards are consistent across a world that may have been modified by multiple team members over time.
Validates actor display names against a configurable regular expression. Logs a warning for every actor whose label does not match the pattern, making it easy to enforce naming standards across an entire world.
^SM_ flags any actor whose label does not start with SM_. Audits or toggles Nanite on static mesh assets referenced by actors in the world. Automatically deduplicates by asset path so each mesh is evaluated exactly once, regardless of how many actors reference it.
Scans actors for Static Mesh or Skeletal Mesh components that have no mesh asset assigned. Unset mesh references are a common source of invisible geometry and silent runtime errors, this script surfaces them all in a single pass.
Command Line
WorldSweep includes a commandlet for running batches headlessly, ideal for automating world validation, mass-updates, or QA checks in CI/CD pipelines without opening the editor UI.
Usage
UnrealEditor.exe <Project>.uproject <MapPath> \ -run=WorldSweep \ -Batch=/Game/WorldSweep/Batches/MyBatch \ -SweepMinX=-100000 -SweepMinY=-100000 \ -SweepMaxX=100000 -SweepMaxY=100000
Arguments
| Argument | Required | Description |
|---|---|---|
| -Batch=<path> | Required | Soft object path to the WorldSweepBatch asset. Example: /Game/WorldSweep/Batches/MyBatch |
| -SweepMinX / -SweepMinY | Optional | Minimum X/Y bounds of the sweep area in world units (cm). Required for World Partition mode; acts as a spatial filter in other modes. |
| -SweepMaxX / -SweepMaxY | Optional | Maximum X/Y bounds of the sweep area in world units (cm). |
Exit Codes
0
Batch completed successfully.
1
Invalid or missing arguments.
2
Batch was cancelled before completion.