Creating and sharing custom ships

Official guide for converting an image of a space ship into a ship profile that can be used in Wayward Terran Frontier and how to upload it to the workshop as downloadable user generated content.

Understanding WTF Profiles

What are profiles

The first thing you need to know, is that the ship profiles you have created are already stored in the form of png images. In fact, the profiles you see when choosing a profile to edit from the main menu are nothing more than folders with images. The contents of a profile are the following:

• The folder itself - its name tells the game what files to search for when constructing the rest of the profile, as well as where to find them.
  
• <name> + Top.png - the "top" layer of your ship. This is the diffuse layer (the colors of your ship) however the alpha value of each pixel doubles as the health value of each tile of the top layer of your ship.
  
• <name> + Bop.png - the "bottom" layer of your ship. This is the interior design of your ship in its native data format, and the alpha layer doubles as the health value of each tile of the bottom layer of your ship.
  
• <name> + Spec.png - the specular layer. Poorly named since an upgrade in our rendering pipe has made this a roughness map. Alpha layer doubles as reflectivity coefficient, more on this later. Suffice to say, this image determines how shiny and reflective each pixel is.
  
• <name> + Emit.png - the emission layer. This layer determines what light your ship emits. Glow in the dark bits are drawn here.
  
• <name> + Bump.png - the normal map. This is an image where every pixel represents the angle of the surface relative to the camera, and it is how ships are made to look 3d when light shines on them in the game.
  
• <name> + Profile.tac - an optional binary file created by the game to remember what turrets you have selected and how many crew you have assigned in the design screen.

One important property of profile images is that they be the same height and width, or the game will not load them.

Where to find profiles

You can find all of your created profiles by right clicking the game in your steam library, selecting properties, selecting the local files tab, and choosing to browse local files. You will see a folder named "profiles" here containing all profiles. Note: you will also see a folder named "Dumps" here if you have saved a flotilla which we will do at the end of this guide.

Suggested tools

An image editor

I use paint.net which you can find here:

https://www.getpaint.net/

It is freeware supported by donations. Bonus points if you make a donation, as the tool really is excellent. It combines the simplicty of MS Paint, with the power of layers and infinite undo steps.

Of course any image editor will suffice so long as it lets you save 32 bit RGBA png image files without doing screwy things to the alpha values. Warning: some image editors think they are helping you and they like to "lose" data they think you won't need in order to make smaller files sizes. If your ship ends up a rectangle of transparent white blocks, this is why. Zero Falls cares about the color of transparent pixels and some image editors lose data about transparent pixels when saving.

Image composition mod tool

Go get Jan's mod tool.

Jans mod tool download[pubdownloads.blob.core.windows.net]

It was specifically designed by Jan (Artist behind Zero Falls) to aid in this exact process. It is meant to suppliment an image editor by helping to generate some texture maps from other texture maps and it allows you to tune the value of your maps with the ability to see what the final result will look like in the game.

Making layers

So you have an image of a space ship...



I drew this space ship. It's kinda ugly, but if you've followed development from the start you might remember it. I intend to put this ship onto the workshop as a flotilla mod file. First we are going to need some layers.

The easy layers

These are the bottom layer and the emission layer.

The bottom layer should just be every pixel of your ship set to the color (R=35, G=100, B=69, A=255) and every pixel outside your ship set to (R=0, G=0, B=0, A=0) Note that the mod tool will create this layer for you automatically when you tell it to export. That green color tells the game your ship is empty space valid for placing modules in the ship editor.

The emission layer can just be a solid black image the same size as your ship image, since black = no emission. Any part of you ship that you want to glow can be not black. Here you see I have taken the glowing windows from my original image and copied them into a black image of the same size. This will make my windows actually glow.

The not-so-easy layers

These are the roughness map and the normal map.

The roughness map is a map representing the material properties of each pixel. Since it is just determining the roughness and reflectivity of every pixel, worst case a solid grey image will produce a ship of uniform shininess. It can be drawn by hand with some effort, however since it isn't exactly intuitive there is also the option to have one generated from the mod tool using a normal map.

The normal map is the hardest map because it represents geometric information on a per-pixel basis and that's why it is mentioned last. There are 3 routes to generating a normal map, and I will list them in order of how good their results will be, with the best results being first.

You might notice a white box around the outside, that's because I resized these images...more on that later. However it is worth noting that the color of these pixels only matters if the base asset for your ship has pixels there as well.

Generating a normal map

Option #1 - 3d geometry

For best results, a normal map should actually be made from 3d geometry. For Zero Falls we use a process of capturing multiple renders of 3d geometry to get our diffuse map and our normal map from a source that began its life in a 3d scene. This will give you the best edges, the sharpest details, and will guarantee the contour matching your intended shapes. This also won't be an option for most people following this guide, and since we started with an existing 2d image, we will be using option 2...

Option #2 - Height map generation



I created this image myself. How? I drew white on the areas of the ship that would be closest to the camera and black on the areas farthest from the camera, and with some time spent messing with the gradient tool I managed to get it into a rough approximation of what I envisioned. Now, using this map in Jan's mod tool I can have a normal map generated for me automatically and tweak the values until I am satisfied with the results. Note here: the logic Jan wrote for converting a height map into a normal map is an amazing feat of engineering which should not be taken lightly. You already saw the normal map generated by Jan's tool up above, that came from this image.

Option #3 - Pure magic generation

the 3rd method of creating a normal map is the easiest, but will also produce the least reliable results. The mod tool can generate a normal map directly from the diffuse layer...It is literally using pure image processing magic to create 3d data where none exists. Magic. The process is impressive no doubt, but the results will vary depending on the contents and visual style of your source image. Since the computer has no way of knowing what 3d shape you actually imagined when drawing this 2d image it can only make its best guess approximation, which hopefully will be good enough.

To restate what is happening here, a normal map represents the 3d angle of each pixel used when determining how light will bounce off of an object and Jans tool can create one without any 3d information input by the user. If you are afraid of voodo, the dark arts, black magic, or witchcraft, please use option #2 above to avoid angering your god(s) and or deities through use of this tool.

Export that stuff!

Once you have all of your maps created, you might see something like this:



Next create a profile directory with the name you want, and name the various image layers appropriately based on the naming convention in the earlier section explaining profiles. Alternately hit "export" on the mod tool and select your directory. I had this ship named zero because it was the first ship I made so my directory looks like this after exporting:



That's it! Now you have a ship profile. If you put this folder in the profiles folder under your game files your new ship profile will be loaded when you launch Zero Falls.

Mapping the interior

If you got this far, hopefully your profile loaded properly and you can simply open it in the regular ship editor. I assume you know how to use the ship editor.



Oh noes! look what I did:


This image is too small for adding shields. I will have to manually resize all of the images. Good thing I know how to resize images. However you need to be careful to make sure ALL images get set to the same size or the profile will refuse to load.

The top and bottom layers need to have the color (0,0,0,0) in the new areas created around the edges to prevent creating strange artifacts, but the Spec and Bump layers won't be sampled at all so it doesn't matter what goes there.

Bonus fact: did you know you can draw shields in an image editor? I use it to make nice geometric shields which suit the ugliness of my ship design like this:


Shield tiles are a specific color just like all other single tile modules, so draw whatever you like. Just remember that we use the alpha layer to record damage state of the ship. That's why transparent white pixels are actually just a damaged unwanted portion added to your ship and your crew will attempt to repair it.

Conclusion

You now have a ship that you can fly around in the game. Good job. In the next section we will show you how to share it with your friends...or with strangers on the internet. It's okay to share space ships with strangers so long as you don't talk to them.

Making a flotilla

Creating a flotilla is as easy as dragging ships into a box with your mouse.

The purpose of a flotilla is to spawn multiple fully configured ships into a single player game campaign. The flotilla format contains more than just the profile information, it can have multiple ships and it stores the cargo, crew, and damage state of all ships in the flotilla. To make one, we need to spawn our profile as an actual ship into the game simulation.

Click the test ship button to get yourself into the debugging simulation environment, then press delete to open the debug spawn menu.



Your profile will already have crew count and turrets configured so you can spawn it, the options on the right allow you to choose the aggression tables of ships in your flotilla.

• The buttons on the right determine what faction the ship will be a member of, and thus also where the flotilla will spawn.
  
• The check boxes on the left determine which factions your ship will be hostile towards after it spawns.

Note that a flotilla can't have player faction ships, so those will convert to freelance faction ships neutral towards the player on flotilla creation.

Using the settings you like, spawn all of the ships of your flotilla. In my case I am only spawning the 1 ship because I want my flotilla to be a solo ship. If I were spawning multiple ships I would make sure the main ship is the first one in as all ships in a flotilla will be assigned to escort the first ship added.

Once all of your ships are spawned into the simulation, open the debug spawn menu and click on the flotilla creation button to get a nice big box to drag your ships into. This is how the flotilla file is actually configured.



When you hit export, your flotilla file will be saved to the Dumps folder inside your game directory. At this point you have created your mod and just need to upload it to the workshop. Of course the .flt file works on its own, and if you don't want to share you can simply put it into the /data folder to hav your flotilla spawn into your own singleplayer games.

The next section covers uploading to the steam workshop.

Manually placed flotillas

There exists a way to manually choose where your flotilla will spawn.

This is 100% optional, and it will modify the behavior of your flotilla with regards to spawning. When the game detects a flotilla intended to spawn in a specific location, that flotilla is immediately spawned once, and never again. All other flotillas have pre-determined spawn locations based on faction allegiance, and they will spawn randomly depending on how many flotillas are currently alive in the simulation.

Choosing a location

In order to manually choose its spawn location, you must create a .bdm file and upload it in the same directory as your flotilla.

Note: Every .bdm file will be combined and applied to every flotilla in the directory, so if you want ships with different behaviors, upload them as different workshop items.

What is a bdm file

.bdm files are just .png files with the extension changed to .bdm and the novelty that the game engine expects to parse information from the file name of files ending in .bdm

If you want an example to work with, go to your data folder and make a copy of the file named "280_-200.bdm" somewhere and rename it to "280_-200.png"

It probably looks like this:


This file tells the game that you will be providing data for some in-game grid locations by coloring pixels. The top left pixel is given the coordinate in the file name, in this case X=280, Y=-200 and all other pixels are simply relative to the top left. The file "280_-200.png" is actually the .bdm file used to create the map for the singleplayer story, so you can easily use the same file name in your mod for easy placement relative to the home system in Zero Falls.

When a .bdm file is used for placing flotillas the game only needs a list of locations, so in this instance color is irrelevant. Any color that isn't pure black will represent a sector where your ship can spawn and patrol inside. If you choose only a single sector your ship is guaranteed to spawn there, and it also will only patrol inside that sector.

.bdm files have other uses which will become relevant once more mod formats are supported in the future.

Publishing mods to the steam workshop

I'm the person who programmed this screen, so obviously I hope the process is intuitive, but let me explain what is happening when you click "mod upload" from the home screen so that the process is as clear as it can be.

Zero Falls uses the Steam API, which means while running the game can send messages to and from steam using functions written by valve. One of those functions is the ability to upload a directory which will represent what valve calls a "ready to use" workshop item. These items show up under your profile in the steam workshop and can be shared with others.

They are invisible by default after being uploaded, you will need to set their visibility to public inside the steam browser.


This screen is a form, once filled it will allow you to start the process of creating and uploading a "ready to use" item. The fields you see are essentially the same fields requested by Valve.

Id of existing item

If you have already uploaded a mod and people have subscribed to your mod, you may modify its contents at a later date by entering the id value of your mod in this field and refilling the other form elements. It's the first line because if you supply an id here the process changes to one of downloading and modifying an existing mod instead of creating a new mod. Leave it blank if you want to make a new workshop item.

The id of your mod is in its URL when viewing your item on the steam workshop.

Choose directory

--->>The entire directory is uploaded!<<---

If you intend to upload multiple mods, you will need to make multiple directories or all of your mods will contain all of your flotillas. I'm warning you here as best as I can, if you simply choose the Dumps folder and upload it every time you export a new flotilla your mod will quickly become a mess.

Title and description

These can be edited later via steam interface but when you re-upload your mod you need to re-enter these because I programmed it and I'm lazy.

Tags

These are to help when people search for mods of a specific type. They aren't mandatory however as far as I know there is no way to modify tags outside of this screen so you might want to consider them when doing your upload to save yourself the hassle of a re-upload later.

Preview image

Our workshop is set to accept square aspect ratio images. So if you want to upload a custom image for people to see on the main workshop screen I suggest checking that the image you have chosen is square or steam will make it look all stretchy. This image need not be part of your mod or inside your mod folder, it can be any image on your computer.

There is a maximum file size for this image of 2MB.

Some day I will make the script smart enough to warn you if the file you have chosen is too large.

[Marxon]

That link for modlab no longer works
It IS an app on steam though, literally search "Modlab"

[MyNameMeansBentNose]

I don't suppose it would be possible to add a 'vertical profile' option to complement the 'horizontal profile' for the bump maps?

[Blood_Red_Hunter]

If you would like I would invite you down to our discord server if you want modding tips/chat/feeback and such, we have afew active people there who are quite interested and helpful, including myself. https://discord.gg/MpjRsAp

[Feyn]

Thanks, I’ll do that.... can’t wait to show you guys my ship :D

[Blood_Red_Hunter]

Try looking at some of the TOP files of the vanilla Wayward Terran Frontier ships, or vanilla starsector sprites.

[Blood_Red_Hunter]

Advice is to have some slight shadowing along the edges, possibly some shading if the "part"
of the ship is below another, etc. Use shadowing to differentiate differences in height, higher, brighter, etc. All as if the light is from directly above.
The shadowing need not be too strong, and with colour and all, painted usually is better than solid/flat colours, advice is to draw/paint the sprite larger, then downscale it.

[Feyn]

One more question.
I’m new to using normal maps, I usually have to draw the shadows myself directly on the sprite assuming there’s a static light source at the right top corner. So when using normal maps how would I go about the shadows on the sprite? Should I just make pillow shadowing (as if the light source is behind the sprite), or should I make no shadows at all leaving a ugly shadowless Cinderella sprite that will somehow magically become a beautiful princess just by adding the normal map? I’m confused >.<

[Feyn]

Good to know thanks:)

[MyNameMeansBentNose]

As soon as you park your ship and leave it un-attended, everything powers down. That's when the shields will be gone regardless.

[Blood_Red_Hunter]

I see two scenarios, they spawn and degrade over time as there is no emitter to keep them up, or they dont spawn with shields.