Custom Levels

Custom levels are backed by Unreal Engine Level assets. The Creating a Level section covers how to create a level asset.

SML provides a data asset for holding data about your custom level for SML’s main menu changes to use. Although it’s technically possible to have a custom level without this, you must code some other way to transport the user to the level if you don’t use SML’s systems.

The tutorial later on the page will have you copy an existing one for your use, but if you ever need to create a new one, you can do so by right clicking in a Content Browser then using Create Advanced Asset → Miscellaneous → Data Asset then search for SMLGameMapData.

Register your Game Map data asset with SML by listing it in the Game Maps field on your Game Instance Module.

Because there are a lot of "gotchas" in the process of setting up a custom level, we highly recommend you copy the existing Example Level from the Starter Project’s ExampleMod as opposed to creating a level from scratch. Copying the Example Level as a starting point avoids many confusing error states and mistakes.

Copying an Unreal asset results normally in the copy pointing back to the same assets it was previously referencing. This is usually a good thing, but not what we want right now when copying the Example Level. If we used the standard method of copying files, we would end up with a level that still references all of the Example Mod’s assets, meaning that if the Example Mod was not installed, parts of your level would no longer work.

In order to avoid this we’ll be using the Migrate Asset action. Navigate to the Example Mod’s content folder in your editor and find the game map data asset for the example level (/ExampleMod/Maps/ExampleLevel/GameMapAsset_ExampleLevel) - notably NOT the level asset itself. Right click on it, then go to the Asset Actions dropdown and select Migrate…​, which will cause a popup to open. This popup’s default settings include more assets than we want to copy, so we’ll have to narrow it down.

Uncheck anything that is outside of the the /ExampleMod/Maps/ directory. When you’re done, it’ll look like this:

Press Ok to be taken to a system file browser window. Navigate to your mod’s Content folder and press Select Folder to continue. If everything worked correctly, you should now have a /Maps/ExampleLevel folder in your mod’s content folder and copies of assets referenced by the Example Level. You may need to relaunch your editor for them to appear.

Check to make sure that the migrated assets are correctly referencing your mod’s content and not ExampleMod’s. You can do this by right clicking on your version of the Example Level and selecting Reference Viewer…​, then hovering over any of the items in the first branch level to the right of the Level in the viewer. The path should start with your own mod reference and not /ExampleMod/.

You should start to rename your copied versions of the assets to avoid the game (and you) from getting confused about which level assets are which. At the very least, rename the following assets:

The migration process already created a Game Map Data asset for you (it’s one of the files you just renamed in the last step).

Open it up and configure it to your liking. The purpose of each field is described in this section.

If you don’t already have a Game Instance Module, create one now and mark it as the root module. Then add your level’s Game Map data asset to the Game Maps field.

You can open your level in the editor by double clicking on the level asset. You can fly around the level in a viewport editor with the usual editor camera controls. Making changes to the level will be covered in later sections.

You may discover some floating spinning question mark actors in the level when flying around in the editor. These Documentation Actors only appear in the editor are originally intended for opening UE documentation links. However, the Example Level repurposes them to leave "comments" about features in the level. Clicking their "Open Help Documentation" button will open a 404 page in the UE docs because this is not their purpose.

In order to view the comment, select the actor in the level then look at the Details window. Scroll down to the "Help Documentation" section and view the "Document Link" text field to read the comment. You can also hover over the field to get a tooltip containing the full comment text.

Each game level has a special blueprint called the Level Blueprint. This is a good place to run level-specific setup code. To view and edit the Level Blueprint, open it with the dedicated button in the top bar’s Blueprints button.

Since you copied the example level, there is already some code in here. Some of it is required to prevent the game from crashing when the player enters and some of is from the example level’s custom functionality - read the comments to learn more.

Making changes to the level will be covered in later sections.

You should now be able to test your level in the game. It should look and behave exactly like the Example Level since we haven’t changed anything yet. Make sure all assets are saved then package your mod with Alpakit and launch the game. Open the New Game tab, and, assuming everything was done correctly, your custom map should appear as an option you can load into.

To add new starting location, Open "Window"→"Level Editor"→"Place Actor". Then Search "Player Start" in search bar.

You will see "Player Start", drag and drop it into Viewport window, place wherever you want. When you look closer to "Player Start", you will see skyblue arrow. This arrow indicates where player will look when it spawned.

Select placed "Player Start", In Details tab, you will see "Object"→"Player Start Tag". Put the name then go back to SMLGameMapData and put your "Player Start Tag" name to SMLGameMapData’s "Player Start Tag" field.

If you have a custom level loading, odds are you want some objects in there, this list details how to do just that.

To add items, use Place Actor window or manually drag and drop from Content Browser. Let’s place an ore node. To add this, simply go to /Content/FactoryGame/Resource/BP_ResourceNode, and drag it onto your level. It won’t quite look right in editor, but when loaded at runtime, it will automatically be replaced with the right model, and textures.

Or If you want to see actual model, search "ManuallyPlacedIronNode" in Outliner window, then duplicate it. You need to change StaticMesh and Materials.

After you place the node, you can select it in the viewport (it doesn’t have any model, so you might have to use the World Hierarchy instead), then on the side in the details panel you can set all the properties, such as what the node produces, the node purity, or how much it can produce.

As you try open Minimap(M) in game, game will crash. To avoid this crash, assign a mMinimapCaptureActor in the World Settings.

Open "Window"→"World Settings" window. Scroll down to find "Minimap" section. Search "BP_MinimapCaptureActor" in Outliner window then assign it to that field.

The minimap will still display an image of the base game’s map by default. To change map texture, you need to change /Content/FactoryGame/Interface/UI/Minimap/Widget_Map→mMap→Appearance→Brush→Image material using a CDO.