Ship Editor Tutorial

## Interface

The **Ship Editor** interface consists of an input body of text taking up the left half of the screen, as well as a rendered output of the ship on the right. Any edits made to the input text will cause the output render to immediately update unless the text includes some type of syntactical error, in which case the model shown will be of the last error-free script provided. The right-hand side consists of a rendered image of the ship itself in the center, which can be clicked and dragged to change the orientation, and silhouette of a top-down view of the current hitbox of the ship. Atop the render body is a series of eight buttons. The first two allow you to save the current body of text to a text file or load a text file into the editor. The second two buttons allow you to download a PNG image of the ship in its current orientation, or download a converted .obj file. The fifth and sixth buttons solely affect the cosmetics of the rendered ship, by changing the color of the ship and the material respectively. This is to preview how this ship would look if a user with an Elite Commander Pass was to use that ship with a material other than the standard zinc scheme selected. The next button in the row will allow you to load a file of any ship that is currently in the game into the editor. Upon clicking that button, the player will be greeted with an up-to-date version of the ship upgrade tree. Any ship currently in the game can then be selected to import the code into the editor terminal. The final button above the rendered output is a link to the terms of use of the ship editor, which you must agree to to be granted access to the editor. Note the tree is not very accurate in it right now.

The Starblast.io ship editor can be found here.

## Ship Script Part 1

### GinoRDASyntax Constants:

As is the case with any type of script, syntax is the most important factor to consider when editing. If improper syntax is used within the editor, the code could either render incorrectly, or fail altogether. In this case, the number of indentations preceding a line of text is registered by the editor and thus must be of the correct length for the desired outcome. With this editor, a difference of two spaces defines a parent from a child.

```
      section_segments: 8
      offset:
        x: 1
        y: 50
        z: 10
      position:

```

The above snippet of text is an example of how lines of text are nested within each other. `main:` has one more indentation preceding it than `bodies:` and is one line after, which means that the latter is defining something within the former. `section_segments:`,`offset:` and `position:` are one position further than `main:` which means they are all defining attributes within `main:`.

```
        x: 1
        y: 50
        z: 10
      section_segments: 8
      position:

```

The above text would act exactly the same as the first. The order of nested attributes can be rearranged freely as long as their child attributes are directly after them.
`return model =`
The line above is a required bit of syntax and should always take up the first line in the editor. This should be left alone. This is essentially telling the editor that any content within this should be passed on and rendered as the final ship.

### Ship Stats:

```
return model =
  name: 'spedd'
  level: max
  model: max
  size: max
      capacity: [225,400]
      reload: [7,10]
    generator:
      capacity: [70,130]
      reload: [30,48]
    ship:
      mass: 200
      speed: [75,105]
      rotation: [50,70]
      acceleration: [80,120]

```

1. ***The*** ship statistics define how the ship will behave in game. As they are a child of the first line they will begin with one indentation, or two spaces. The above code is an example taken from the Condor code. For every instance of two numbers in brackets separated by a comma (`[15,20]`), the values will be interpreted as a minimum and maximum respectively. The first value will correspond with the ship without any relevant upgrades whereas the second value will determine the fully upgraded statistic.

* `name: 'Condor'` means that the name of the ship will be Condor. This can be changed to anything as long as it stays within a pair of single quotes.
* `Designer: 'Neuronality'` is not found in any of the vanilla ships, but it is in the racing and BR codes. In this case, if the ship is in a ship choice menu (found in Pro Deathmatch, Racing, and Battle Royale), then it will say Designed by: Neuronality below it. It is optional.
* `level: 6` means that this ship will appear at level 6 in the upgrade tree. This can be changed to any integer, though should range from 1 and 7, as there are currently only seven tiers of ship. Custom decimal tiers such as 1.2 or 5.9, and so on, can also exist in modding, although a custom decimal model will not work. A ship with a decimal level will not appear on the shiptree and can only be attained with a command or button. The gem capacity of a custom level ship is between the levels (a level 1.5 will theoretically have 50 gems, as a level 1 has 20 and a level 2 has 80).
* `model: 4` Modding was released recently, giving this number a meaning. This determines where it will be in the ship tree and what it upgrades into. For example, a level 3 model 3 ship will replace Shadow X-1.
* `size: 1.5` means that the ship size will be multiplied by a factor 1.5 when in game. This can be any positive number.
* `zoom: 4` means that the view range of the ship will be multiplied by 1/4 in game. This can be any positive number. Out of default ships, it is only found in the Shadow X-1. It is optional, and a higher zoom number means that the player have a smaller view, while a smaller number gives the player a larger (better) view.
* `shield:`
	+ `capacity: [225,400]` means that the ship has a minimum of 225 shield capacity and a maximum of 400 shield capacity. These can be any positive integers.
	+ `reload: [7,10]` means that the ship has a minimum of 7 shield regeneration per second and a maximum of 10 shield regeneration per second. These can be any positive integers.
* `generator:`
	+ `capacity: [70,130]` means that the ship has a minimum of 70 max weapon energy capacity and a maximum of 130 max weapon energy capacity. These can be any positive integers.
	+ `reload: [30,48]` means that the ship has a minimum of 30 weapon energy regeneration per second and a maximum of 48 weapon energy regeneration per second. These can be any positive integers.
* `ship:`
	+ `mass: 200` means that the ship will weigh 200 units where the higher number means the ship will weigh more. This can be any positive integer.
	+ `speed: [75,105]` means that the ship will have a minimum terminal velocity of 75 and a maximum terminal velocity of 105. These can be any positive integers.
	+ `rotation: [50,70]` means that the ship will have a minimum rotational speed of 50 and a maximum rotational speed of 70. These can be any positive integers.
	+ `acceleration: [80,120]` means that the ship will have a minimum acceleration rate of 80 and a maximum acceleration rate of 120. These can be any positive integers.
	+ `dash:`
		- `burst_speed: [80,100]` means that the ship will have a minimum initial ram speed of 80 and a maximum initial ram speed of 100. These can be any positive integers.
		- `speed: [90,110]` means that the ship will have a minimum sustained charge speed of 90 and a maximum sustained charge speed of 110. These can be any positive integers.
		- `acceleration: [80,85]` **means that the ship will have a minimum acceleration rate from its speed to its burst speed, and from burst speed to dash hold speed, and dash hold speed to speed of 80, and a maximum of 85.**
		- `initial_energy: [30,30]` means that the ship will have a minimum initial ram cost of 30 and a maximum initial ram cost of 30. These can be any positive integers.
		- `energy: [70,100]` means that the ship will have a minimum sustained charge cost of 70 per second and a maximum sustained charge cost of 100 per second. These can be any positive integers

Additionally, if the ship charges rather than firing lasers (or both) in the manner of the Barracuda, it has another few lines appended to the end as a child of `ship:`.

```
      dash:
        rate: 13
        burst_speed: [80,100]
        speed: [90,110]
        acceleration: [80,85]
        initial_energy: [30,30]
        energy: [70,100]

```

## Ship Script Part 2

After the ship statistics are defined, the next logical step would be to design the model itself. There are two types of structures that all ships are constructed out of; the first of which being **bodies** and the second being **wings**. These both act the same in regards to collision detection. Both `wings:` and `bodies:` are children of the first line in the editor so they will have one indentation. For any instance of a set of numbers in brackets separated by a comma (`[13,25,33]`), that is a set of sequential points or segments. There is no limit to the quantity of values you can put in here separated by commas. The origin is the point in the 3-D space located at 0,0,0. For the purpose of this tutorial, there will be two parts referred to in each structure. These being the joints and the segments. Joints are essentially the actual measurements, while the segments are the polygons and segments drawn between two joints.

### Wings

The wings class of structures solely effect the look and hitbox of the ship. Every instance of wings will be mirrored along the X axis, making it impossible to create asymmetrical wings. All joints of a wing or set of wings lies on a Y axis.

```
        x: 0
        y: 25
        z: 10
      length: [90,40]
      width: [70,50,30]
      angle: [-30,40]
      position: [0,20,0]
      texture: [11,63]
      doubleside: true
      bump:
        position: 10
        size: 20

```

* `wings:`
	+ `back:` this can be named anything at all as long as the syntax is maintained.
		- `offset:`
			* `x: 0` means that the initial point of the wings is offset by 0 units along the X axis. This can by any number.
			* `y: 25` means that the initial point of the wings is offset by 25 units on the Y axis. This can be any number.
			* `z: 10` means that the initial point of the wings is offset by 10 units on the Z axis. This can be any number.
		- `length: [90,40]` means that the length of the first segment of these wings will be 90 units long, and the second will be 40 units long. These can be any numbers.
		- `width: [70,50,30]` means that the width of the first joint of these wings will be 70 units wide, the second will be 50 units wide, and the third will be 30 units wide. These can be any numbers.
		- `angle: [-30,40]` means that the angle around the Y axis of the first segment of these wings will be -30 degrees, and the second will be 40 degrees. These can be any numbers.
		- `position: [0,20,0]` means that the offset along the Y axis of the first joint of these wings will be 0 units, the second will be 70 units and the third will be 0 units. These can be any numbers.
		- `texture: [11,63]` means that the texture of the first segment of these wings will be texture 11, and the second will be texture 63. These can be any numbers, though only a select few will be unique textures.
		- `doubleside: true` means that both sides of this structure will be rendered. This can be either true or false.
		- `bump:`
			* `position: 10` means that the bump will occur on the wings at 10 units along the y axis. This can be any number.
			* `size: 20` means that the bump will have a height of 20 units which is dependent on the width of each segment. This can be any positive number.

### Bodies:

The bodies class of structures are, unlike the wings, capable of firing lasers from the front and a propulsion effect from the back. The latter is purely cosmetic as the speed and agility of the ship was defined in part 1. The body structures will not be mirrored on the left and right sides unless the offset on the x axis is not equal to 0, meaning that it is possible to make asymmetric bodies as long as they each joint is individually offset.

```
      section_segments: 12
      offset:
        x: 0
        y: -30
        z: 10
      position:
        x: [0,0,0]
        y: [0,10,35]
        z: [0,-3,12]
      width: [5,13,4]
      height: [0,8,4]
      texture: [63,8,2]
      propeller: true

```

* `bodies:`
	+ `main:` this can be named anything at all as long as the syntax is maintained.

* `section_segments: 12` means that along the Y axis 12 faces will be drawn to the later specifications. This can be any positive number above 2.`[-45,45,135,225]` covers 4 edges but 3 sides,one side parallel to the top when using. Adding 315 at last covers the last missing sides. Each item inside indicates a certain angle from the “core” of a join,which rotates anticlockwise looking from the back of the ship considering normal forward movement in game as the value increases.(as with offset: x:0.mirrored versions have them rotated by 180 degrees). `[0]` covers one edge along the Y axis at the very top considering the Z axis.The Howler uses the array method.

* `offset:`
	+ `x: 0` means that the origin point of the body is offset by 0 units on the X axis. This can by any number. (X-axis is the axis of the right and left of the ship)
	+ `y: -30` means that the origin point of the body is offset by -30 units on the Y axis. This can be any number. (Y-axis is the axis of the front and bottom of the ship)
	+ `z: 10` means that the origin point of the body is offset by 10 units on the Z axis. This can be any number. (Z-axis is the axis of the top and bottom of the ship)
* `position:`
	+ `x: [0,0,0]` means that the offset along the X axis of the first joint will be 0 units, the second will be 0 units and the third will be 0 units. These can be any numbers.
	+ `y: [0,10,35]` means that the offset along the Y axis of the first joint will be 0 units, the second will be 10 units and the third will be 35 units. These can be any numbers.
	+ `z: [0,-3,12]` means that the offset along the Z axis of the first joint will be 0 units, the second will be -3 units and the third will be 12 units. These can be any numbers.
* `width: [5,13,4]` means that the width of the first joint will be 6 (2\*3) units wide, the second will be 26 (2\*13) units wide and the third will be 8 (2\*4) units wide. These can be any positive numbers.
* `height: [0,8,4]` means that the height of the first joint will be 0 (2\*0) units wide, the second will be 16 (2\*8) units wide and the third will be 8 (2\*4) units wide. These can be any positive numbers.
* `texture: [63,8,2]` means that the texture of the first segment of this body will be texture 63, the second will be texture 8 and the third will be texture 2. These can be any numbers, though only a select few will be unique textures (see above).
* `propeller: true` means that given the correct conditions, this body will produce a propulsor animation out of the back. This can be either true or false.
* `laser:`
	+ `damage: [30,60]` means that this laser will deal a minimum of 30 damage and a maximum of 60 damage. These can be any positive numbers.
	+ `rate: 2` means that this laser will fire at a rate of twice per second. This can be any positive number
	+ `type: 2` Use type 1 for minor rapid-fire lasers. Use type 2 for large pulses, so the energy bar will light up when you have enough energy to fire the shot.
	+ `speed: [150,200]` means that this laser's projectiles will travel at a minimum velocity of 150 units per second and a maximum velocity of 200 units per second. These can be any positive numbers.
	+ `number: 1` means that each round will fire 1 laser. This can be any positive number (it can be less than 1, but more than 0).
	+ `angle: 0` means that each laser will fire at a 0 degree angle. This can be any number.
	+ `error: 0` means that each laser can fire off target by 0 degrees. This can be any positive number.

For the body to fire a laser a few more lines need to be appended to the end of the above code.

```
      laser:
        damage: [30,60]
        rate: 2
        type: 2
        speed: [150,200]
        number: 1
        angle: 0
        error: 0

```

## Designing A Ship

This next section will include a step by step tutorial on how to design a ship from scratch. This will assume that you have a good understanding of the terminology and syntax presented in the above sections. For the purpose of this tutorial we will be making a basic level 4 ship called the Gale.

### Creating A Sketch:

When designing a ship the best way to start, if you have a design in mind, is to draw a simplistic top down view as you would expect it to appear in game. For the initial sketch feel free to draw curves as we will be converting this later on. I chose to color it to get a rough idea of what the final textures will be. If you'd rather use the editor without the use of a sketch, skip ahead to Creating The Model.

The next step will be to convert it into a sketch that will be possible within the confines of the editor. As noted above, there are two structures that you will have access to in the editor. The bodies will all have joints along different X-Z planes, while the wings will all have joints along different Y axes. This means that when you create the sketch you'll need to make all the joints vertical if they are wings, and horizontal if they are bodies.

The final step for the sketch is to draw lines where you plan on making different segments in the editor. I chose to make these different colors to the outline as to keep it looking somewhat organized. It is also useful to find the center of all the joints and make a small bisecting indicator. This will come in hand later on when you are converting it to the components of a ship. If you want to ensure that there wont be a gap between a wing and a body, It's helpful to draw a bit of them overlapping as that part wont be seen.

### Creating The Model:

Now that we have a basic sketch of the design, we are going to need to create the ship piece by piece. Before we do that however, we must initialize the ship code and fill in the ship stats. This ship is going to be about as agile as the Crusader, with lesser shields and a bit more energy regeneration, so this is the starting stats I settled on:

```
return model =
  name: 'Gale'
  level: 4
  model: 4
  size: 1.3
      capacity: [120,180]
      reload: [5,8]
    generator:
      capacity: [100,120]
      reload: [20,35]
    ship:
      mass: 180
      speed: [75,105]
      rotation: [30,75]
      acceleration: [70,90]

```

I will be making both bodies first, followed by the 5 sets of wings. I plan on making the ship a bit larger than the crusader in the editor for the sake of screenshots, but the final product will be slightly smaller so rather than a 1.6 size I went with a 1.2. The next step will be to create the main body. The sketch I created luckily was a perfect size to use actual pixel measurements for the editor, but in some cases you'll either need to convert the pixels to another form of measurement, or scale the entire image up/down. I'll be using gimp to get the pixel measurements easily for this. The main body has a series of 10 joint and thus 9 segments. Since the X will be the center, or point of rotation of the ship, I'll need to measure the distance between the tip of the ship and the center to start. This came out to be 76 pixels up which means I will translate the start of the body -76 pixels along the Y axis.

This is where I'll place my first joint with a width of 0 and a height of 0. Next I will measure the distance between the first and second joint, along with the width which came out to be a distance of 12 and a width of 5. This body will be cylindrical so the height will in turn be 5. I'll add a random texture and an offset of 0 pixels on the Y and Z axes to allow this first segment to render.

Doesn't look like much yet, but just wait until we add a few more joints. I will repeat the previous step for all of the the joints in the main body measuring the distance from the tip to the next joint. You can leave the texture brackets with just one number to make the entire body/wing one texture, but to make it easier to differentiate between all the segments I chose a pattern of textures 1,3,1,3...

```
      section_segments: 8
      offset:
        x: 0
        y: -76
        z: 0
      position:
        x: [0,0,0,0,0,0,0,0,0,0]
        y: [0,12,9,25,66,84,120,126,154,148]
        z: [0,0,0,0,0,0,0,0,0,0]
      width: [0,5,6,14,14,14,14,17,13,0]
      height: [0,5,6,14,14,14,14,17,13,0]
      texture: [1,3,1,3,1,3,1,3,1]

```

Not a bad start. Next we will be creating the two bodies on either side of the main body. As stated earlier, if the offset on the X axis is not 0 the editor will automatically mirror any bodies on the opposite side. The two side bodies will be identical in dimensions to the main body, so I will essentially copy the main body with a new name and translate it to the desired location (this time being 41 px along the X axis and 90 px along the Y axis). Of course we can name bodies and wings anything, though to keep this somewhat organized I decided to name the outer two bodies "sides". Set the section\_segments to whatever looks the best.

```
    sides:
      section_segments: 8
      offset:
        x: 41
        y: -90
        z: 0
      position:
        x: [0,0,0,0,0,0,0,0,0,0]
        y: [0,12,9,25,66,84,120,126,154,148]
        z: [0,0,0,0,0,0,0,0,0,0]
      width: [0,5,6,14,14,14,14,17,13,0]
      height: [0,5,6,14,14,14,14,17,13,0]
      texture: [1,3,1,3,1,3,1,3,1]

```

Well, this ship is starting to take shape. Now that all the bodies are completed, we can move onto the wings. The first will be the wings connecting the two bodies. The first step here will be finding the innermost joint and using the bisector to find the offset on both the X and Y axes, which came out to be 12 px and 3 px respectively. We will then make the first joint width the length of vertical line we drew along the first joint.

Of course with only one joint and zero segments nothing new will be rendered, so we'll need to move on to the next joint. To create the next joint for this wing, we will need to find the Y offset from the first wing and set that to position, then find the X offset and set that to the length. This is because the length refers to the length between joints. These measurements came out to be 18 px along the X axis and 16 along the Y axis. Since the shape we drew for this set of wings in a parallelogram, the width of the first joint can be copied over. The angle of this wing segment will be set to 0 and the bump will have a size of 0. We can also leave doubleside at false since you will never see the underside of this wing.

```
      doubleside: false
      offset:
        x: 12
        y: -3
        z: 0
      length: [18]
      width: [75,75]
      angle: [0]
      position: [0,-16]
      texture: 1
      bump:
        position: 30
        size: 0

```

Now this is starting to look a bit more like a ship. Next we will be creating the outer two wings in the same fashion as the last set which I will skip over. Do note that, for the thinner wing to be visible, we will either need to make the bump larger or move it higher along the Z axis. Also remember to name each new part something different.

```
    topout:
      doubleside: false
      offset:
        x: 49
        y: -17
        z: 4
      length: [124]
      width: [48,30]
      angle: [0]
      position: [0,10]
      texture: [3]
      bump:
        position: 30
        size: 10
    bottomout:
      doubleside: false
      offset:
        x: 46
        y: -16
        z: 0
      length: [105,14]
      width: [82,52,30]
      angle: [0,0]
      position: [0,7,10]
      texture: [1,3]
      bump:
        position: 10
        size: 3

```

Well, this ship is finally starting to look like the original design. The next step will be to add the tail fins. The only difference between the other wing structures and these tail fins is that these will all be at an angle of 15 degrees. With these being a bit higher up, and at an angle, the underside may occasionally become visible. Because of this, just to be safe, doubleside should be set to true.

```
    winglets1:
      doubleside: false
      offset:
        x: 8
        y: 61
        z: 4
      length: [12]
      width: [18,10]
      angle: [15]
      position: [0,3]
      texture: [1,3]
      bump:
        position: 10
        size: 5
    winglets2:
      doubleside: true
      offset:
        x: 52
        y: 50
        z: 4
      length: [12]
      width: [18,10]
      angle: [15]
      position: [0,3]
      texture: [1,3]
      bump:
        position: 10
        size: 5

```

Congratulations! The ship model has been successfully converted from a sketch to a model in the editor. If you are satisfied with the design as is you can skip to the next part, though I usually like to fine tune the model at this point and give some parts a bit more depth and character.

### Cosmetics and Lasers: true

The next logical step is to add texture to the model. Since this part is solely a matter of taste, you will be able to change the textures as you see fit. Along with this, we should also add a cockpit somewhere. This is purely cosmetic and, more often that not, it will not effect the size or shape of the hitbox, so it can be placed anywhere. All three main bodies will also have the engine effect, so we will need to set propeller equal to true on these parts. The engine effect will will be the size of the furthest joint downwards, and not necessarily the last joint. These all have a final joint above the lowest joint. For the laser, the Gale will have three cannons, one from each body shooting heavy lasers.

This concludes the ship editor tutorial. Best of luck designing a ship!

```
return model =
  name: 'Gale'
  level: 7
  model: 4
  size: 1.3
      capacity: [120,180]
      reload: [5,8]
    generator:
      capacity: [90,120]
      reload: [30,40]
    ship:
      mass: 180
      speed: [75,105]
      rotation: [30,75]
      acceleration: [70,90]
      section_segments: 8
      offset:
        x: 0
        y: -44
        z: 20
      position:
        x: [0,0,0,0]
        y: [0,2,20,25]
        z: [-1,2,7,6]
      width: [5,8,9,5]
      height: [3,4,5,3]
      texture: [9]
    main:
      section_segments: 8
      offset:
        x: 0
        y: -76
        z: 10
      position:
        x: [0,0,0,0,0,0,0,0,0,0]
        y: [0,12,9,25,66,84,120,126,154,148]
        z: [0,0,0,0,10,10,0,0,0,0]
      width: [0,3,6,14,14,14,14,17,13,0]
      height: [0,3,6,10,14,14,14,14,10,0]
      texture: [6,13,3,2,2,2,4,12,13]
      propeller: true
      laser:
         damage: [30,40]
         rate: 1
         type: 2
         speed: [90,130]
         number: 1
         angle: 0
         error: 0
    sides:
      section_segments: 8
      offset:
        x: 41
        y: -90
        z: 0
      position:
        x: [0,0,0,0,0,0,0,0,0,0]
        y: [0,12,9,25,66,84,120,126,154,148]
        z: [0,0,0,0,10,10,0,0,0,0]
      width: [0,3,6,14,14,14,14,14,10,0]
      height: [0,3,6,14,14,14,14,17,13,0]
      texture: [6,13,4,3,8,3,4,13,13]
      propeller: true
      laser:
         damage: [30,40]
         rate: 1
         type: 2
         speed: [90,130]
         number: 1
         angle: 0
         error: 0
      doubleside: false
      offset:
        x: 12
        y: -3
        z: 15
      length: [18,0]
      width: [75,75,0]
      angle: [-20,0]
      position: [0,-16,-16]
      texture: [63]
      bump:
        position: 7
        size: 10
    topout:
      doubleside: false
      offset:
        x: 49
        y: -17
        z: 6
      length: [124]
      width: [48,30]
      angle: [-2]
      position: [0,10]
      texture: [63]
      bump:
        position: -16
        size: 10
    bottomout:
      doubleside: true
      offset:
        x: 46
        y: -16
        z: 0
      length: [105,14]
      width: [82,52,30]
      angle: [-1,10]
      position: [0,7,10]
      texture: [4]
      bump:
        position: 10
        size: 10
    winglets1:
      doubleside: true
      offset:
        x: 10
        y: 61
        z: 14
      length: [12]
      width: [18,10]
      angle: [15]
      position: [0,3]
      texture: [63]
      bump:
        position: 10
        size: 10
    winglets2:
      doubleside: true
      offset:
        x: 50
        y: 50
        z: 0
      length: [12]
      width: [18,10]
      angle: [0]
      position: [0,3]
      texture: [63]
      bump:
        position: 10
        size:15

```

## Helpful Videos

Over the past years of this game very kind and generous people have created very helpful videos of Ship Editor to help people! Here are some helpful ones down below:

* L.Gaming - https://www.youtube.com/watch?v=fy4tABmKkQU

* Kleinem - https://www.youtube.com/watch?v=ECj59OSQWbY

* Schickenman - https://www.youtube.com/watch?v=kpVTL8P8QSE

These videos are very helpful for beginners and I suggest you check them out!

## See Also

### Tutorials

* Advanced Ship Editing
* Modding Tutorial

### Tools

* Ship Editor
* Mod Editor
* Map Editor (by community)