Shape Modding Masterclass

An extensive guide on exactly how to make custom block shapes for reassembly, including how to make shape folding details!

Basics of shape modding

What exactly is shapes.lua and how can I make my own shapes?

Shape modding in Reassembly allows you to create custom convex[mathworld.wolfram.com] polygons to use in your mods. Shapes.lua is written with a series of coordinates that define a connect-the-dots to form your desired shape. A normal 1x1 square hull piece in Reassembly is 10 units by 10 units in the shapes.lua file. Shapes that are concave[mathworld.wolfram.com] don't always work, and I'll get into why they don't and how to make them anyways in a later section.

All shape modding in this demonstration will be done in Notepad++[notepad-plus-plus.org].

How do ports work?

Ports are defined as a percentage of distance in the form of a decimal from 0 to 1 along the specified edge. That's a little confusing, so for example, {0, 0.5}, Would place a default port halfway across the first edge (Edges start at 0, so 0 would be the edge between the first and second defined coordinates). Ports can also have specified properties, such as being a missile or launcher port, a thruster in or out port, etc. This is defined after the distance percentage, like this: {0, 0.5, MISSILE}, Placing a missile port halfway across the first edge. More documentation and formulas will be included in a dedicated ports section later in the guide.

Am I able to name my shapes instead of using a number?

Sadly, no you can't. However, you can add a commented out name for easier finding. In Notepad++ you can also minimize specific sets of brackets, allowing you to compress your code visually so that it's easier to find the shape you want.

Are there tools that can help me visualize my shape better?

Yes! There are a few graphing tools out there, but I personally use Desmos' Calculator[www.desmos.com]. EDIT: A tool has been created by Aurora to convert GeoGebra shapes into custom shapes here[lymia.moe]. To use their calculator as a visual reference, go to the top left corner, click the plus, and add a table. From there you can input your X and Y coordinates, and they will appear on the graph for you to see. If you want to see the lines between them, click the gear above the table, then click the green circle on your table, and enable the lines option. For example, this is what a 1x1 square would look like in Desmos:

Introduction to Syntax

In this section I'll demonstrate how to write a shapes.lua file. There are multiple ways to write the file, most of which take up less space, but this is how I learned it.



Please note that there are 4 spaces at the beginning of each new line, or set of brackets. This can also be achieved quickly by pressing 'tab' instead.

To add multiple scales, simply add another set of brackets in the 3rd set, as seen here:



When writing a shapes file, You can also include a mirrored version of a previously defined shape without needing to re-code it. Simply add this section:



This will allow shape 002 to be an exact mirror of 001.

Port editing

This section will teach you everything you need to know about ports!

So, to begin lets go over how ports work in more detail. Ports are placed using a percentage of the distance between vertex 0 and vertex 1, aka edge 0. This percentage is represented with a decimal between 0 and 1, with 0 being right on vertex 0 and 1 being right on vertext 1. For example, 0.5 would put a port halfway across the edge, 0.25 would put it a quarter way across, etc.

Now this is all fine and dandy, but how would I put multiple ports on my shape?

You can list multiple ports for one edge simply by keeping the edge number the same and changing the port's percentage. For example, a 2x2 cube with 2 ports to fit 2 1x1 cubes side by side would look like this:



This says that on edge 0, there is a port at 25% and a port at 75%.

How can I fit stuff on my shapes evenly?

To find how many ports fit onto a side length that is a multiple of 10, you can use this simple formula:
1/(((sideLength)/10)*2)

For example, a side length of 40 would be divided by 10 to get 4, multiplied by 2 to get 8, and then becomes the denominator. So each port would go along every 1/8, right? Well, almost. The first port is 1/8, but the next is 3/8, 5/8, and 7/8, skipping 1/8 between the middle ports. This is because 1/8 represents the distance between the edge of the 1x1 and the port. Since you want the cubes to fit evenly, you'll place them 2/8 away to compensate.

Here's another example: A side length of 70 would be divided by 10, getting 7. Next it's multiplied by 2 to get 14. Now we have our denominator, 14. On that side length we would add a port at 1/14, 3/14, 5/14, 7/14, 9/14, 11/14, and 13/14 to fit 7 1x1 cubes evenly on the side length.

EDIT: Reassembly now allows for expressions in your code! This makes ports easier since you can now simply write the fraction (1/14, 3/14, 5/14, etc) instead of calculating it beforehand, which saves time.

What if my side length isn't a perfect multiple of 10, and I still want to put 1x1 cubes on it?

Now that's where it gets a little more complicated. You'll need to adjust for the extra distance on either side, assuming you want the 1x1 cubes centered along the uneven edge. Here is an example of what I'm talking about:



The way you calculate ports with an offset edge like above is with these steps:

• Step 1: Find the overhang of your uneven edge. This is the extra space on either side of the row of 1x1 squares. For example, a side length of 48 would have an overhang of 4 on either side, fitting 4 1x1 squares between them.
  
• Step 2: Find the distance your ports would be if the length was, in this case, 40. If it was 40, you would place your ports at 5, 15, 25, and 35.
  
• Step 3: Add your over hang (4) to those ports above, resulting in 9, 19, 29, and 39.
  
• Step 4: Now you have your fractions: 9/48, 19/48, 29/48, and 39/48. Those are your ports!

This method can get a bit messy with side lengths of say, 67.439 - It's possible with the exact same method, but it can use some very small or confusing decimals.

Okay, but what if I want to fit a shape other than a 1x1 cube along an uneven side length?

The method is relatively the same, with some adjustments:

• Step 1: Find the overhang of space that you won't need. For example, if you're fitting 5 shapes with a width of 6, and your total side length is 34, your overhang would be 2 on either side.
  
• Step 2: Find the distance as usual, if it was 30 with 5 ports of 6 the distances would be 3, 9, 15, 21, and 27.
  
• Step 3: Add the overhang as usual, resulting in 5, 11, 17, 23, and 29.
  
• Step 4: Finally, simply write 5/34, 11/34, 17/34, 23/34, and 29/34.

What types of ports can I place on my shape besides the default?

Here's the complete list:

• THRUSTER_IN
  
• THRUSTER_OUT
  
• MISSILE --This port type is where the missile block connects to the launcher
  
• LAUNCHER --This port type is where missiles are grown from
  
• WEAPON_IN
  
• WEAPON_OUT
  
• ROOT --This port connects a structure to an asteroid
  
• NONE --This is used in rare situations to force invisible edges to be visible

Now you know how to add ports to your custom shape! Hooray

Breaking the "Convex polygons only" Rule

How can I make my shapes concave? Iv'e seen it before but mine always bug out

Well, this is due to the way that shapes are drawn in Reassembly's game engine. The game draws a line from the first vertex to each other vertex. You can think of this as a 'Line of Sight' of sorts, with the line of sight coming from your first vertex, and drawing lines to every other vertex. So, depending on where your first vertex is, lines can connect outside of your shape and look buggy. There are 2 simple ways to fix this:

• Method one: Use an inside corner for your vertices

This one is fairly simple, you can shift your starting vertex to a corner or vertex on the inside of your shape to allow it to reach more points without intersecting based on the position of the corner.

• Method two: Create an inner edge/vertex

You can create an edge leading to a vertex in or near the middle of your shape, allowing for a much broader line of sight to the other vertices. This can allow almost any shape to work, but it can be ugly to have a line through your shape. If you can find a way to incorporate it into your design, it's a very effective choice.

Adding extra details with Shape Folding

What is shape folding?

Shape folding is drawing shapes on top/inside of other shapes. For example, creating a smaller shape inside a larger shape to add detail. You can make parts of the block look sectioned off, like they're underneath the block, and more. The main thing you need to keep in mind when doing this is that your shape still needs to be a continuous line. Therefore, you'll need to figure out how to draw your details without breaking the line. Something important to know: 2 lines can be in the exact same position if need be, and they will be fine. Putting ports on them isn't a great idea, especially if they are in the same place, but with either a NONE port, or no port, they will be okay.

A prime example of shape folding and the code that makes it will be included below:





Okay, so let's go over what's going on here. The process behind this shape in particular is drawing a miniature square first and then connecting a larger square around it. We start with the larger square's corner, dipping inside to the smaller square and drawing the edges. Then we go back out to the larger square, and proceed around it's edges. When making a vertex for the larger square, we need to make sure we connect it to the smaller square's corresponding vertexes.

Making shape folding details can usually be less complicated, but it can also be more complicated depending on how detailed you want your shape to be.

EDIT: Renamed 'overdraw' to the proper term, shape folding.

Examples

Here are some examples of some shapes I made for my Bismuth+ mod:
Each picture has it's code beneath it:

Conclusion

To conclude, modding a shapes.lua file isn't as difficult as it seems. Hopefully this guide has covered everything you need to know about making your own shapes!

If you have any questions, or if you see any mistakes, feel free to contact me on steam or you can DM me on discord @Prototype#7548

[Overseer]

thank you friend! this has helped lots

[Prototype]

Glad to hear it!

[Iambob]

Thank you! It worked!

[Prototype]

My best guess is that your shape is coded counter clockwise. Reverse the order of your vertices and it should work fine

[Iambob]

I made a shape, with the code
{verts={
{-10, 2.5},
{-10, -2.5},
{10, -2.5},
{10, -1.5},
{8, -1},
{-2, -1},
{-2, 1},
{8, 1},
{10, 1.5},
{10, 2.5}
},
ports={
{0, 0.5},
{1, 0.25},
{1, 0.75},
{5, .5, WEAPON_OUT},
{8, 0.25},
{8, 0.75}
}},
(some code is cut out)
and for some reason, my block only snaps itself INSIDE of other parts. Why does it do this/what did I do wrong?

[Prototype]

You're missing an opening bracket for shape 204

[Prototype]

Like the code that you sent in your message earlier

[Prototype]

That means that they failed to load. Can you msg me your code on discord? or on steam

[Prototype]

No prob

[Prototype]

Looks like you're missing an opening bracket on the second shape