Overview: The USD-Native Workflow
Cargo 3.0 introduces a high-performance USD integration. By moving to a Blueprint-based actor system and utilizing Packed Level Instances (PLIs), Cargo 3 provides a seamless "gameplay-ready" experience with optimized collisions and material management.
Section 1: Connection & Migration
Upgrading from Cargo 2.0 to Cargo 3.0
To prevent project corruption or plugin conflicts, you must remove all legacy plugin files before installing the 3.0 connector.
Manual Cleanup: Close Unreal and Cargo. Navigate to your Unreal Engine directory (e.g.,
Engine/Plugins/Marketplace) and delete the Cargo folder.Install Connector: In Cargo 3, go to Software Settings > Unreal Engine, select your version (e.g., 5.6+), and click Install Connector.
Enable Plugin: Open your Unreal project. Go to Edit > Plugins, search for "Cargo," enable it, and Restart Engine.
The Handshake: Ensure your level is Saved. The connection icon in Cargo (bottom-left) should be glowing green.
Watch Video: How to Install Cargo 3.0 Connector for Unreal Engine
Section 2: Plugin Settings & Preferences
Advanced Project Settings
Configure Cargo behavior by navigating to Edit > Project Settings > Plugins > Cargo by KitBash3D:
Auto Connect to Cargo: Automatically attempts a handshake on project launch.
Default Import Path: We recommend
/Game/Cargofor better organization.Enable Manual Import: Toggle this ON to reveal the manual USD import menu in the toolbar.
Multi-Instance Note: Cargo links to the first Unreal window initialized. Close other projects to ensure a stable connection.
Watch Video Enabling Advanced Settings for Unreal Engine Plugin-in
Section 3: Importing Assets
1-Click Workflow (Models & Materials)
Importing Models: Cargo creates specialized folders under /Content/Cargo/. Assets are imported as Blueprints, not raw static meshes. Drag the Blueprint actor from the Content Browser into your level for full collision and material support.
Importing Materials (GSG & KB3D):
Standalone materials import as Material Instances.
Cargo automatically assigns these to the correct Master Material (Parent) to ensure high-end features like displacement and double-sided rendering are active without redundant shader compiling.
Watch Video Importing Models into Unreal Engine with Cargo 3.0
Manual & Batch Importing (Offline Workflow)
You can import assets without opening the Cargo app by clicking the Cargo icon in the Unreal toolbar:
Single Asset: Select the Root USD file (e.g.,
Wagon.usd) inside the7.0/Modelsfolder.
Batch Import (New!): Click Select Folder and target the entire Models folder within a 7.0 kit directory. Unreal will sequentially scan and import every asset in that folder, skipping any that already exist in your project.
Watch Video Importing and Applying Materials in Unreal Engine
Why USD 7.0?
Packed Level Instances (PLIs): Complex buildings are brought in as "Level Instances." This allows for optimized rendering and global editing—update one building, and every instance in your level updates automatically.
Asset Organization:
/Blueprints/: Ready-to-use actors./StaticMeshes/: Raw USD-derived geometry./Materials/: Master Materials and Instances.
Local Texture Links: Cargo creates a Textures folder next to your project file. This makes your Unreal project Portable; if you move the project to a new drive, your paths will not break.
Section 4: File Structure & Application
The USD 7.0 "Gameplay Ready" System
When you import a Kit (e.g., "Black Market"), Cargo 3.0 builds a standardized root folder at /Content/Cargo/[KitName].
Blueprints (The Core): This is your primary interaction point. It contains Buildings and Props.
Levels: These are the sub-levels that power the Packed Level Actors.
Static Meshes: The raw geometry.
Materials/Textures: Optimized PBR maps and Master Material instances.
Understanding Packed Level Actors (PLAs)
Cargo 3.0 imports assets as Packed Level Actors. This is a massive leap over standard static meshes.
What they are: A "container" that holds geometry, set-dressing, and instancing data in one easy-to-move actor.
The Benefit: * Memory Efficiency: Unreal handles these as instances, drastically reducing the draw calls and RAM overhead for massive scenes.
Pre-Set Dressing: Buildings (like the "Whisper Vault") come with their props (barrels, crates, lights) already placed in a professional layout.
Collisions: Custom vs. Generated
Every Cargo 3.0 asset comes with high-fidelity, custom-built collisions.
Simple Collision: This is the Custom Collision built by Kitbash3D specifically for each model to ensure players can navigate stairs, doorways, and interiors without "floating" or getting stuck.
Complex Collision: Generated by Unreal for per-poly accuracy (usually reserved for non-gameplay background items).
Usage: These are "Gameplay Ready" out of the box—just drop them in and your character can interact with them immediately.
Section 5: After You Import (Gameplay Ready)
Non-Destructive Level Editing
You can edit the layout of a building or a prop set without "breaking" it into a million loose pieces.
How to Edit: Right-click the PLA in the viewport -> Level -> Edit.
The Workflow: This opens the sub-level (e.g., the "Set Dressing" level). You can move barrels, remove crates, or add new items.
Global Sync: When you save your edits, every instance of that Packed Level Actor in your world will update to match the new layout.
Decomposing/Breaking the Level (Destructive)
If your project requires you to have total, individual control over every single mesh (e.g., for physics destruction or unique kit-bashing), you can "Break" the hierarchy.
The Action: Select the PLA -> Right-click -> Level -> Break.
Options:
Keep Folders: Highly recommended to keep your Outliner organized.
Depth Level: Choosing "1" breaks the building from its props. Choosing "2" or "3" continues to break the props into individual static meshes.
Warning: Once broken, the link to the original "Master" Packed Level Actor is gone. Edits will no longer propagate globally.
Collisions: All Cargo 3 Blueprints come with built-in, optimized collisions.
Master Material Customization: Open the Material Instance to adjust tiling, roughness, or displacement scale.
GSG Integration: GSG materials use a specialized Master Material that handles high-fidelity displacement. Ensure Nanite Tessellation (UE 5.3+) is enabled for the best results.
Environment Lighting (HDRIs)
The HDRI Backdrop Workflow
To use Cargo HDRIs as a high-quality 360-degree background in Unreal Engine, you should use the HDRI Backdrop actor.
Step 1: Enable the Plugin
Go to Edit > Plugins.
Search for "HDRI Backdrop" and check the box to enable it.
Restart Unreal Engine to finalize the activation.
Step 2: Placing the Actor
In the Place Actors panel, search for HDRI Backdrop and drag it into your level.
Details Panel Setup: * Size: Increase this significantly (e.g., 5000 or more) so the projection dome encompasses your entire playable area or building.
Intensity: Adjust this to balance the sky brightness with your scene's other lights.
Step 3: Importing from Cargo
In Cargo, navigate to the HDRI Kits.
Select an HDRI and click Download.
The Drag-and-Drop Method: Once downloaded, you can simply click and drag the HDRI file directly from the Cargo app into your Unreal Content Browser.
The Manual Method: Alternatively, go to your Cargo library on your hard drive. Drag the
.hdror.exrfile into Unreal. It will automatically import as a Texture Cube.
WATCH VIDEO: Easily Import HDRI's in Unreal with Cargo 3.0
Rapid Look-Development
You can cycle through different lighting scenarios (Midday, Dusk, Overcast) in seconds:
Download & Import: Bring several Cargo HDRIs into your Content Browser.
Assigning: Select the HDRI Backdrop in your Outliner.
Swap: Drag a new HDRI texture from your Content Browser onto the Cubemap slot in the Backdrop's Details panel.
Rotate: Use the Rotation slider in the Details panel to spin the sky and align the sun's direction with your architecture.
Post-Process & Exposure Control
To get the most out of your HDRIs, you need to control how Unreal "sees" the light.
The Post-Process Volume:
Search for Post Process Volume in the Place Actors panel and add it to your scene.
In the Details panel, check Infinite Extent (Unbound) so the settings apply to the whole world.
Exposure Settings: Under the Exposure tab, set Min Brightness and Max Brightness to the same value (e.g.,
1.0or2.0) to disable auto-exposure. This allows you to manually "dial in" the exact look of your HDRI without the camera constantly auto-adjusting.
Texture Kits & Gobo Lighting
What is an Unreal Gobo?
In Unreal Engine, a Gobo is implemented as a Light Function. This is a special type of material that masks the intensity of a light source, allowing you to project textures—like the window blinds or palm leaves found in Cargo’s Texture Kits—directly through a Spotlight or Point Light.
The Gobo Material Setup
Before applying a texture, you must create a "container" material that Unreal recognizes as a light mask.
Create the Material: Right-click in your Content Browser and select Material (e.g.,
M_Gobo_Master).Change Material Domain: In the Material Editor's Details panel, find Material Domain and change it from Surface to Light Function.
Import the Texture: Download your desired pattern from Cargo (Texture Kits > Gobo Textures). Drag the texture file from your Cargo library folder directly into the Unreal Material Editor.
Connect the Nodes: Wire the RGB output of your Texture Sample into the Emissive Color input of the main material node. Save and close.
Applying the Gobo to a Light
Place a Spotlight in your scene.
In the Spotlight's Details panel, scroll down to the Light Function section.
Drag your newly created material (
M_Gobo_Master) into the Light Function Material slot.Adjusting the Look: * Sharpness: Use the Inner Cone Angle and Outer Cone Angle to sharpen or soften the projection.
Distance: Adjust the Attenuation Radius to control how far the light (and the Gobo pattern) travels.
File Structure & Application (Advanced)
Rapid Iteration with Texture Samples
To swap Gobos quickly without creating a dozen materials:
Open your Light Function material.
Drag a new texture from your Content Browser into the graph.
Plug the new texture into the Emissive Color and hit Save.
Result: Every light using that material will update instantly with the new pattern (e.g., moving from "Flashlight" to "Palm Leaves").
WATCH VIDEO: Integrating Gobos from Cargo 3 into Unreal Engine
Troubleshooting
Common Issues & Quick Fixes
🔴 Symptom: "Failed to Send"
Cause: Your current level is not saved.
Fix: Save your level before importing. Cargo needs a saved project path to create local texture folders.
🔴 Symptom: Old assets not showing up
Cause: USD Versioning conflict.
Fix: Manual import only works for 7.0+ assets. Re-download older kits to update their file schema.
🔴 Symptom: Duplicate Master Materials appearing
Cause: Migration conflict from old plugins.
Fix: Follow the Section 1 Cleanup steps to delete the old
Engine/Plugins/Cargofolder entirely.
🔴 Symptom: Wrong Project Window (Cargo won't connect)
Cause: Multi-instance error.
Fix: Close all other Unreal windows. Cargo defaults to the first project instance opened.
Workflow Errors
"I can't move individual props inside a building"
Why: The asset is a Packed Level Actor (PLA), which groups items together for better performance.
The Fix: Right-click the asset > Level > Edit to enter the sub-level, or select Level > Break to turn the assembly into loose actors.
"The collision feels 'weird' or floaty"
The Check: Open the Static Mesh editor for the asset.
The Fix: Ensure Collision Complexity is set to Project Default or Simple And Complex. Cargo's "Simple" collision is a custom-modeled mesh designed for gameplay.
"Send" failed because of the wrong connector
The Fix: If you recently switched from another software (like Blender), you must manually switch Cargo back to Unreal Engine in the software settings. Cargo 3.0 only targets one active DCC at a time.
Cargo 3.0 & Unreal Engine FAQ
Why are my assets importing as Blueprints instead of Static Meshes?
In Cargo 3.0, assets are brought in as Blueprints to support the USD-native workflow. This allows for "Gameplay Ready" features like pre-configured collisions, optimized material instances, and Packed Level Instances (PLIs) that wouldn't be possible with raw geometry alone.
Can I still use my Cargo 2.0 assets in this Beta?
Cargo 3.0 uses a new USD 7.0 file schema. While your old downloads may still exist on your drive, they will not work with the new 3.0 features or manual import tools. We recommend re-downloading your favorite Kits to ensure they utilize the latest performance optimizations.
What is a "Packed Level Instance" (PLI) and why should I use it?
PLIs are used for complex assemblies (like large buildings). Instead of importing hundreds of individual mesh pieces, Cargo imports one "Level Instance." This significantly reduces draw calls and allows you to update one instance to reflect changes across your entire map.
How do I adjust materials now that they are Material Instances?
To tweak an asset's look, find the material in /Game/Cargo/Materials. Open the Material Instance to access parameters for:
Tiling and Offset
Roughness and Specular intensity
Displacement scale (via the GSG Master Material)
Can I move my project to a different computer or drive?
Yes! Because Cargo 3.0 creates a local Textures folder relative to your .uproject file, your file paths are now Portable. As long as you move the entire project folder, your textures will remain linked.
I have multiple Unreal projects open; why isn't Cargo connecting?
Cargo can only maintain a "handshake" with one Unreal Engine process at a time. It will default to the first project you opened. To switch projects, close both and open the desired project first, then launch Cargo.
The HDRI looks like a tiny ball in my scene
Fix: Increase the Size parameter in the HDRI Backdrop Details panel. It needs to be large enough to act as a "sky dome."
The background is black/missing
Cause: The Backdrop actor might be positioned below your floor or the HDRI texture failed to assign.
Fix: Reset the Actor's transform to (0,0,0) and ensure the Cubemap slot isn't empty.
The HDRI is too bright/blown out
Fix: First, adjust the Intensity of the HDRI Backdrop. If it's still too bright, use your Post Process Volume to lower the overall exposure.
Why did it import as a Texture Cube?
Note: This is normal! Unreal recognizes the "Long-Lat" format of Cargo HDRIs and automatically converts them into a Cube Map for optimal 360-degree projection.
Troubleshooting: Unreal Gobos
The pattern is blurry or stretched
Fix: Check your Spotlight's Cone Angle. If the angle is too wide, the texture will stretch. You can also add a TextureCoordinate node in the Material Editor to tile or scale the pattern.
The light is completely black
Cause: Your Light Function material might be outputting a value of 0, or the texture is not mapped correctly.
Fix: Ensure the texture is plugged into Emissive Color. If using a black-and-white texture from Cargo, the white areas allow light through, while black areas block it.
Can I use this with a Directional Light (The Sun)?
Yes: You can apply a Light Function to a Directional Light to create "Cloud Shadows" or "Overhead Canopy" effects across your entire level. Use a large scale in your TextureCoordinate node to ensure the pattern covers the landscape.