Creating Ship Templates

Ships in EmptyEpsilon are defined by ship template scripts, which are located in a set of ship template script files. A ship template script sets a ship's name, class, model, radar icon, speed, maneuverability, weapons, and defenses.

Unlike scenario scripts, ship template scripts are loaded when you launch EmptyEpsilon. While you can modify some traits of an existing ship template in a scenario script, you cannot create new ship types from scratch in a scenario script --- you must create them in a ship template script.

Note: If you want to create a new ship in a single scenario that uses the same model as an existing ship, it might be easier to simply create a variant of an existing ship's template. For details, see Creating a Variant Ship Template.

Locating ship template script files

There are several ship template script files in EmptyEpsilon's scripts directory that define ships:

• shipTemplates_StarFighters.lua: Light fighter-class ships, such as the MT52 Hornet.
• shipTemplates_Frigates.lua: Small capital ships, such as the Phobos T3.
• shipTemplates_Corvette.lua: Medium capital ships, such as the Atlantis X23.
• shipTemplates_Dreadnaught.lua: Heavy capital ships, such as the Odin. (And for now, only the Odin.)

Each of these files are loaded by the base shipTemplates.lua file. Any modifications you make to ships in these files are loaded when you launch EmptyEpsilon.

Note: There are two more ship template script files that we won't get into here:

• shipTemplates_Stations.lua: Defines space stations.
• shipTemplates_OLD.lua: Defines legacy ships.

Ships in the OLD file are deprecated and might be moved or removed in a future version. When making scenarios, avoid using ships in this file as they might not be available in future versions of EmptyEpsilon.

Adding a ship template script file

The easiest way to add new ship templates to EmptyEpsilon is to create a new ship template script file, then add that file to the shipTemplates.lua list.

Note: If you modify the default ship template script files, updating EmptyEpsilon might overwrite or delete your changes.

The shipTemplates.lua file contains lines like this:

require("shipTemplates_StarFighters.lua")

To add a ship template file, add a similar line to shipTemplates.lua with a different file name, such as:

require("shipTemplates_Custom.lua")

Then create a text file by that name in EmptyEpsilon's scripts folder.

Creating a ship template

In your ship template file, create a ship template with this line of code:

template = ShipTemplate():setName("NX-01 Initiative"):setClass("Corvette", "Destroyer"):setModel("battleship_destroyer_1_upgraded")

Let's break this line down piece by piece.

• template is a variable name that we'll use to set other ship traits.
• ShipTemplate() defines this variable as a ship template. It's required.
• setName("NX-01 Initiative") sets the ship template's name. This is what appears as the ship's model everywhere in the game. Note that this is different from a specific ship's callsign, which is either automatically generated when the ship is created, set by a scenario script, or set by the Game Master.
• setClass("Corvette", "Destroyer") sets the ship template's class (Corvette) and subclass (Destroyer). A ship template can use classes to determine how certain types of ships interact with each other. For instance, to allow Starfighter-class ships to dock with ships of a certain template, you'd add setDockClasses("Starfighter") to the carrier's template. While you can set any class and subclass that you want here, the common classes and subclasses are:
  • "Starfighter"
    • "Interceptor"
    • "Gunship"
    • "Bomber"
  • "Frigate"
    • "Cruiser"
    • "Cruiser: Anti-fighter"
    • "Cruiser: Light Artillery"
    • "Cruiser: Strike ship"
    • "Cruiser: Sniper"
    • "Light transport"
  • "Corvette"
    • "Destroyer"
    • "Support"
    • "Freighter"
  • "Dreadnaught"
    • "Odin"
• setModel("battleship_destroyer_1_upgraded") sets the 3D model used to depict the ship. Models are defined in the model_data.lua script file in the scripts folder; see Adding 3D Models.

While this line of code creates a new ship template, this ship is incomplete. Let's use the template variable to complete this template:

template:setRadarTrace("radar_dread.png")
template:setHull(100)
template:setShields(200, 200, 200, 200)
template:setSpeed(30, 3.5, 5)

Each of these lines extends the template with a new feature.

• template:setRadarTrace("radar_dread.png") sets the image that represents this ship on radar screens. This file should be in EmptyEpsilon's resources folder.
• template:setHull(100) sets the ship's hull value.
• template:setShields(200, 100, 200, 100) sets the ship's shields. A ship's shields are arranged like equal-sized slices of a pie chart, with the first value representing the front shields and proceeding in clockwise order. For instance, in this example the ship has front, right, rear, and left shields, with stronger front and rear shields (200) than left and right shields (100). If a ship template has a single shield value, shields of ships with that template are reduced equally when attacked from any angle.
• template:setSpeed(30, 3.5, 5) sets the ship's impulse speed and maneuverability.
  • The first value (30) is the ship's maximum impulse speed.
  • The second value (3.5) is the ship's rotation rate.
  • The third value (5) is the ship's acceleration rate. (TODO: Define these rates better.)

This gives us a minimally functional ship. If you'd like, you can save this ship template script file, load the game, enter a scenario, and enter the Game Master screen. You should be able to add an "NX-01 Initiative" Corvette to the scenario, give it orders, and watch it fly around.

However, this ship is unarmed. Let's give it some firepower:

--                  Arc, Dir, Range, CycleTime, Dmg
template:setBeam(0,100, -20, 1500.0, 6.0, 8)
template:setBeam(1,100,  20, 1500.0, 6.0, 8)
template:setBeam(2,100, 180, 1500.0, 6.0, 8)

template:setBeam(0, 100, -20, 1500.0, 6.0, 8) adds a beam weapon. Each value defines a trait of the weapon. In order, these traits are:

• Its ID number (0).
• Its arc in degrees (100).
• Its direction in degrees relative to the front of the ship (-20). Note that the arc extends with the direction in its center. In this example, the beam weapon is pointed 20 degrees to the left of the ship's forward facing, and its arc extends 50 degrees to each side of that direction.
• Its range in milliUnits (1500.0). This range of 1500 is equal to 1.5U.
• Its cycle time in seconds (6.0). Once fired, the beam takes this long to cool down before it can fire again.
• Its base damage (8). Each hit does this amount of base damage, which might be modified by things like a target's shields, or the degree to which the ship's beam frequency aligns with the target's shield frequency.

Each of these lines adds a new beam weapon. Note that each line has a unique ID number. A ship's beams should be defined in order, starting with 0 for the first beam, 1 for the second beam, and so on.

If you want to test this ship's beams, remember that you can save the template, load a new scenario, and add this ship from the Game Master screen.

Next, let's add some weapon tubes:

template:setTubes(4, 10.0)
template:setWeaponStorage("HVLI", 20)
template:setWeaponStorage("Homing", 4)
template:setTubeDirection(0, -90)
template:setTubeDirection(1, -90)
template:setTubeDirection(2,  90)
template:setTubeDirection(3,  90)

template:setTubes(4, 10.0) adds four weapon tubes (4), and sets the time it takes to load a tube to 10 seconds (10.0).

The next lines define those tubes, as well as the ship's weapon storage capacity:

• template:setWeaponStorage("HVLI", 20) and template:setWeaponStorage("Homing", 4) set the ship's HVLI and homing missile capacity, respectively, to 20 HVLI and 4 homing missiles.
• template:setTubeDirection(0, -90) sets the first weapon tube's direction in degrees relative to the front of the ship. In this instance, the first and second weapon tubes are aimed off the left side of the ship (-90), and the third and fourth tubes are aimed off the right side (90).

Finally, let's accessorize and describe our ship:

template:setJumpDrive(true)
template:setDescription([[The NX-01 Initiative is an experimental corvette model.

Only its designers know what it's truly capable of achieving.]])

template:setJumpDrive(true) adds a jump drive to the ship with a default range of 50U. If you want to change its range, use the setJumpDriveRange() script function. For instance, this sets the jump drive range to 100U (100000), and instructs the ship to not engage its jump drive to travel distances of less than 5U (5000):

template:setJumpDriveRange(5000, 100000)

template:setDescription(...) sets the text that appears in the Database View for this ship model. Note that it uses two square brackets ([[), which allows the text to contain line breaks.

Creating Player Ships

TODO

Player ships also need rooms depicting the ship's interior, which are used on the engineering screen for repair crew management. Use the addRoom, addRoomSystem (to make rooms for a ship system), and addDoor functions to accomplish this.

Creating a Variant Ship Template

Non-Player ships

Find a template to base your new ship on. I usually go by the 3D model first since that's something you cannot change when you are creating a variant. You'll want to consider the size of what you're creating, too. Let's look at one of the commonest models, the Adder MK5.

You can find it in the shipTemplates_StarFighters.lua file. The first line of the definition has the model name: template = ShipTemplate():setName("Adder MK5"):setLocaleName(_("Adder MK5")):setClass(_("Starfighter"), _("Gunship")):setModel("AdlerLongRangeScoutYellow") ... AdlerLongRangeScoutYellow

To get the best from your variant design, it's a good idea to look at the model entry, too. You'll find it in the model_data.lua file. If you search for "AdlerLongRangeScoutYellow" you won't find it. That's because there are several model groups that vary only by color. Search for "AdlerLongRangeScout" instead. The lines we are particularly interested in are these:

-- Visual positions of the beams/missiletubes (blender: -X, Y, Z)
model:addBeamPosition(1.8, 0, 0.03)
model:addBeamPosition(1.8, 0.13, 0.03)
model:addBeamPosition(1.8,-0.13, 0.03)
model:addTubePosition(1.8, 0, 0.03)

These tell us that the model assumes that beams and tubes will appear in a particular place when defined in a particular order. The non-3D screens (eg Helm, Weapons) rely heavily on the Y value. Zero represents the front, center of the ship. Notice that for the beams, the X and Z values are all the same. The first Y value is zero, the second Y value is positive and the third Y value is negative. If all of these values were zero or they were not defined, the beams would come out of the middle of the ship model. These numbers tell us that the first beam defined (index zero) will come out in the center, the second beam defined (index 1) will come out on the positive side of the ship (starboard, angle 5 to 45 would look good) and the third beam defined (index 2) will come out on the negative side of the ship (port, angle 315 to 35 or -5 to -45 would look good). So, when we define the direction of the beams, we should keep these beam positions in mind. The tube exit is in the same position as the first beam exit.

Beam Weapons

Let's modify the Adder MK5 to have a longer, narrower center beam.

local ship = CpuShip():setTemplate("Adder MK5")
--             Index,  Arc, Dir, Range, Cycle, Damage
ship:setBeamWeapon(0,   20,   0,  1000,   5.0, 2.0)	--narrower (vs 35) and longer (vs 800)

Before After
Notice that all the beam weapon parameters were required to be entered. I usually have the original specifications nearby so I can reference the numbers and have an idea of what the results of my changes will be. I also like adding a comment out to the side noting the original value(s). The comment line preceding the setting of the beam weapon values helps me remember which values go in which slots:

Parameter Position	Short comment name	Example Value	Description
1	Index	0	Which beam. Starts numbering at zero
2	Arc	20	Beam coverage in degrees. 360 is full coverage
3	Dir	0	Direction the beam points. 0 is forward, 180 is behind
4	Range	1000	How far the beam reaches. 1000 is one unit
5	Cycle	5.0	How long the beam takes to recharge in seconds at 100% power
6	Damage	2.0	How much damage the beam inflicts when it hits