[Modding] Custom block shapes

This guide will teach you how to create your own Reassembly block shapes with LUA code and the shapes.lua file.

Introduction

I'm pretty sure we've all seen the modding tutorials here. I was suprised to see however that not a single one of those (there apparently are many that I overlooked, sorry for that. find the one that suits you best!) contains any instructions for custom block shapes.
That's why I created this guide to help anyone reading this to make their own shapes with a shapes.LUA file.
Also, I will assume that anyone reading this guide does have some experience with making mods, meaning that I'll not explain any of the block modding code.

The basics

I'll get straigt to the point:
block modding is done by defining some point in an order, wich the modding engine will than convert to a shape. This does sadly mean hollow shapes ARE impossible.
These points are defined by coordinates. Example:

verts={
  {2.5,2.5}, -- the numbers are the coordinates in a grid. the normal block is 10 by 10, this one 5 by 5
  {2.5,-2.5},
  {-2.5,-2.5},
  {-2.5,2.5}
}

this small piece of code defined 4 coordinates to act as a block. This is not a valid block however, since it misses some critical information:
- shape name/id (identical to block ID in function)
- attachment points
- scales (ie: defining the bigger and smaller or even entirely different versions of the block, while still being part of the same shape), used with the "scale=x" command.

connection points are defined like this:

ports={
  {0, 0.5, THRUSTER_IN},
  {1, 0.5},
  {2, 0.5, THRUSTER_OUT},
  {3, 0.5}
}

you can see that this looks a little strange.
every point needs some values. this shape has 4 points.
every point needs a shape side, and a relative value on that side. 0 meaning all the way left, 1 meaning all the way right
OPTIONAL: point modifier: configures the point to be one off: (please note any that I missed)
- THRUSTER_IN
- THRUSTER_OUT
- WEAPON_IN
- WEAPON_OUT
Thanks for Zergur Vorghiz for the following points
- LAUNCHER & MISSILE
- ROOT

- possibly more that I missed

Creating your first shape:

This part will be simple.
all brackets:
first { } opens and closes the shapes file
second { } opens and closes a shape (put the block ID here!)
third { } opens and closes a scale for that shape
fourth { } lets you allow the shape or it's connections points.
fifth { } lets you allow the specivic points
NOTE: even if there ARE only around 70-80 shapes in the current game, I still like to start at 100 for a little headroom when updates arrive (thats the 101 at the second line)
example:

{ -- opens the code
  {101,   -- circle_0   -- I always name the shape. I recomment this to anyone working with shapes
    { --  enter other scale levels between these brackets
      { -- open the information for this specific scale
        verts={ -- just a normal 1x1 block square (ten units) square
          {5, 5},
          {5, -5},
          {-5, -5},
          {-5, 5}
        },
        ports={ -- only default connection points on the center of each side
          {0, 0.5},
          {1, 0.5},
          {3, 0.5},
          {2, 0.5}
        } -- these close off the corresponding brackets
      }
    }
  }
}

and to use this shape in a block:

{
	{
		1, -- the block ID
		group=40, -- your own group
		name="test block",
		shape=101, -- THIS is the important part. this is the shape we defined above (notice the 101 present in both?)
		fillColor=0x4b3d47,
		durability=1,
		growRate=1,
	},
}

A practical but complex example.

I have personally used this file for half a year now, and its far more complex and less documented as the examples above, but it does show us some of the real possibilities.
NOTE: the last shape has multiple scales. (the game also has a shapes.lua file you can examine, that's why I was so suprised with the lack of custom shapes for half a year now)

{
  -- circle_0
  {101,
    {
      {
        verts={
          {-4.619, -2.5},
          {-4.619, 2.5},
          {4.619, 3.827},
          {4.619, -3.827}
        },
        ports={
          {0, 0.5},
          {1, 0.5},
          {3, 0.5},
          {2, 0.5}
        }
      }
    }
  }
  -- circle_1
  {102,
    {
      {
        verts={
          {-4.619, -2.5},
          {-4.619, 2.5},
          {4.619, 3.161},
          {4.619, -3.161}
        },
        ports={
          {0, 0.5},
          {1, 0.5},
          {3, 0.5},
          {2, 0.5}
        }
      }
    }
  }
  -- circle_2
  {103,
    {
      {
        verts={
          {-4.619, -2.5},
          {-4.619, 2.5},
          {4.619, 2.94},
          {4.619, -2.94}
        },
        ports={
          {0, 0.5},
          {1, 0.5},
          {3, 0.5},
          {2, 0.5}
        }
      }
    }
  }
  -- circle_3
  {104,
    {
      {
        verts={
          {-4.619, -2.5},
          {-4.619, 2.5},
          {4.619, 2.83},
          {4.619, -2.83}
        },
        ports={
          {0, 0.5},
          {1, 0.5},
          {3, 0.5},
          {2, 0.5}
        }
      }
    }
  }
  -- commandLock
  {105,
    {
      {
        verts={
          {-2.5, -2.5}
          {-2.5, 2.5},
          {2.5, 2.5},
          {2.5, 1},
          {1.5, 1},
          {1.5, -1},
          {2.5, -1},
          {2.5, -2.5}
        }
        ports={
          {4, 0.5}
          -- {6, 0.5}
        }
      }
    }
  }
  -- commandKey
  {
    106,
    {
      {
        verts={
          {-2.5,2.5},
          {2.5,2.5},
          {2.5,-2.5},
          {-2.5,-2.5},
          {-2.5,-1},
          {-3.5,-1},
          {-3.5,1},
          {-2.5,1}
        }
        ports={
          {0,0},
          {1,0.5},
          {2,1},
          {5,0.5}
        }
      }
    }
  }
  -- small_corner
  {
    107,
    {
      {
        verts={
          {-2.5,2.5},
          {2.5,-2.5},
          {-2.5,-2.5}
        }
        ports={
          {0,0.5},
          {1,0.5},
          {2,0.5}
        }
      }
    }
  }
  -- half_Block
  {
    108,
    {
      {
        verts={
          {2.5,2.5},
          {2.5,-2.5},
          {-2.5,-2.5},
          {-2.5,2.5}
        }
        ports={
          {0,0.5},
          {1,0.5},
          {2,0.5},
          {3,0.5}
        }
      }
    }
  }
  -- circle_0_thruster
  {109,
    {
      {
        verts={
          {4.619, 2.5},
          {4.619, -2.5},
          {-4.619, -3.827},
          {-4.619, 3.827}
        },
        ports={
          {1, 0.5},
          {0, 0.5, THRUSTER_IN},
          {3, 0.5},
          {2, 0.5, THRUSTER_OUT}
        }
      }
    }
  }
  -- circle_1_thruster
  {110,
    {
      {
        verts={
          {4.619, 2.5},
          {4.619, -2.5},
          {-4.619, -3.161},
          {-4.619, 3.161}
        },
        ports={
          {1, 0.5},
          {0, 0.5, THRUSTER_IN},
          {3, 0.5},
          {2, 0.5, THRUSTER_OUT}
        }
      }
    }
  }
  -- circle_2_thruster
  {111,
    {
      {
        verts={
          {4.619, 2.5},
          {4.619, -2.5},
          {-4.619, -2.94},
          {-4.619, 2.94}
        },
        ports={
          {1, 0.5},
          {0, 0.5, THRUSTER_IN},
          {3, 0.5},
          {2, 0.5, THRUSTER_OUT}
        }
      }
    }
  }
  -- circle_3_thruster
  {112,
    {
      {
        verts={
          {4.619, 2.5},
          {4.619, -2.5},
          {-4.619, -2.83},
          {-4.619, 2.83}
        },
        ports={
          {1, 0.5},
          {0, 0.5, THRUSTER_IN},
          {3, 0.5},
          {2, 0.5, THRUSTER_OUT}
        }
      }
    }
  }
  {113
    {
      {
        verts={
          {-1.77, 6.04},
          {1.77, 2.5},
          {1.77, -2.5},
          {-1.77, -6.04}
        }
        ports={
          {3, 0.5, WEAPON_IN}
        }
      }
    }
  }
  {114
    {
      {
        verts={
          {-1.77, 6.04},
          {1.77, 6.04},
          {1.77, -11.04},
          {-1.77, -11.04}
        }
        ports={
          {1,0.354, WEAPON_OUT},
          {2,0.5},
          {3,0.646, WEAPON_OUT}
        }
      }
    }
  }
  {115
    {
      {
        verts={
          {-2.5, 4.11},
          {2.5, 4.11},
          {2.5, -4.11},
          {-2.5, -4.11}
        }
        ports={
          {0,0.5},
          {1,0.5},
          {2,0.5},
          {3,0.5}
        }
      }
    }
  }
  --weapon mount
  {116
    {
      {
        verts={
          {-2.5,1.25},
          {2.5,1.25},
          {2.5,-1.25},
          {-2.5,-1.25}
        }
        ports={
          {0,0.5,WEAPON_OUT},
          {2,0.5}
        }
      }
    }
  }
  -- OCTAGON_WEAPON
  {117,
    {
      {
        verts={
          {5, -2.071},
          {2.071, -5},
          {-2.071, -5},
          {-5, -2.071},
          {-5, 2.071},
          {-2.071, 5},
          {2.071, 5},
          {5, 2.071}
        },
        ports={
          {1, 0.5, WEAPON_IN},
        }
      },
      {
        verts={
          {-5,11.94},
          {5,11.94},
          {11.94,5},
          {11.94,-5},
          {5,-11.94},
          {-5,-11.94},
          {-11.94,-5},
          {-11.94,5}
        }
        ports={
          {1, 0.5, WEAPON_IN},
        }
      }
    }
  }
}

[Neon]

For port types you missed:
LAUNCHER - Indicates where a launcher will replicate blocks
MISSILE - Where a projectile will connect to it's launcher
ROOT - Allows blocks to connect to other blocks (Honestly i don't know if the root actually does anything because i recently had a problem where my custom command was attaching to asteroids with a normal port, even though there was a root in the back. I fixed it by making the root the first port in the shape's code.)