3.0 Porting Guide

Hello structure generator! If you're here it likely means you're trying to port your mods structures to the new 3.0 release from a 2.x version. This should hopefully be a much easier process than the 1.X => 2.X move, as there is an in-game porting tool you can use, and you wont be having to also move across a major Terraria and TModLoader version. We'll go over the 3 basic steps you'll need to do to port, and hopefully get your mod ported within 10 minutes.

Wait, why do I need to port?! What happened?!

With the 3.0 update I've introduced a new binary format for structure files. Ultimately this results in them being roughly half the size, or smaller than they were previously, as well as being able to generate much, much, much faster. For comparison, a structure containing an entire medium world would:

on the old version:

take about 1 minute to save
take roughly 15MB of disk space
cause the game to be killed as it hung for too long when trying to generate

With the new format:

saves almost instantaneously
takes less than 5MB of disk space
generates in about a second

Additionally, the new format supports new data, such as sign text and custom ITileData.

In short, by porting, you’ll make your mod smaller, speed up world generation, and gain more features to build with!

Step 0 - Back up your mod

As with any major change, you should make a backup of your mod before proceeding. If you’re using source control, commit the current state of your mod and work on porting in a separate branch. If not, back up your mod files (or at least your structures) in a safe place on your computer.

While you shouldn’t encounter any issues with the automatic porting tool, it’s always good to have these old files as a reference to confirm everything transferred correctly. If you do run into issues, having these old files will help me diagnose and fix the problem for future users.

Step 1 - Move your structures into the SavedStructures directory

If you've used the mod before you should be familiar with this directory, its where all your structures go when you save them! In order to port your structures, the mod will need to now read them back. If you have other unrelated files or files you don't want to port in here, you should move them to a separate directory temporarily.

Your folder should look something like this when you're done:

ReadyToPort

Step 2 - Use the porting wand

Once you're ready to port your structures, start up the game with your mod enabled. You wont be able to build, as the old Generator API has been deprecated! Just boot up the game as if you were going to play.

Once you're in-game, use your debugging tools of choice (I recommend DragonLens) to spawn in a porting wand. It will look like this: PortingWand

Then, simply left click while holding it -- just like swinging a sword.

Afterwards, your SavedStructures folder should look something like this:

Ported

you'll notice the files for the new format have an extension (.shstruct or .shmstruct). You can safely move these files back into your mod in place of the old files.

Step 3- Update your code

Now that your structures are ported, you'll need to update your code to use the new Generator API. It's very similar and provides all the same features of the previous API, but is now located in the StructureHelper.API namespace. Functionality is also now split between Generator for regular structures, and MultiStructureGenerator for multistructures. For more detailed documentation of the new API, check out the API documentation pages on this wiki:

Once you've updated your generation calls, you should be good to go! Make sure you test your world generation to ensure everything moved over correctly.

Help! Something went wrong!

It's possible I missed something in the porting tools or there is a bug with the new version. If you need immediate support, you can ping me (scalarvector) on the mods discord server, otherwise please open an issue.