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

TODO