Halo Space Station Evolved
Workflow tutorial for developing ships, shuttles, space stations, asteroid bases - Printable Version

+- Halo Space Station Evolved (https://projectunsc.org/forum)
+-- Forum: UNSC Operational Test and Evaluation Center (UNSCOTEC) (https://projectunsc.org/forum/forumdisplay.php?fid=4)
+--- Forum: Development (https://projectunsc.org/forum/forumdisplay.php?fid=17)
+--- Thread: Workflow tutorial for developing ships, shuttles, space stations, asteroid bases (/showthread.php?tid=218)



Workflow tutorial for developing ships, shuttles, space stations, asteroid bases - Cael_Aislinn - 05-17-2016

Here is a reasonably comprehensive guide for the full workflow I've developed from start to finish based on our current code. You will need intermediate skill at mapping (or basic skill and a little help), very basic skill with spriting and very basic skill with coding. I'm writing this up so that mappers can get an idea of the full process and we can make contributing a little easier in all areas to hopefully encourage a little more contribution. This is a multidisciplinary process but if you follow the steps carefully and ask for advice/help at different stages along the way anyone can learn to do the full thing. It's also a long guide so you may want to take it in stages, or split the work up between a couple of people.

1. Decide the kind of ship or station you want to make, its size and its purpose. For performance reasons we want to minimise the number of things using 2 or more zlevels (separate decks) by themselves but don't be afraid to make something bigger if you want to. Engines are props and there's no other ship mounted machinery like weapons, comms antennae, sensors etc at the moment but leave space for them as they'll get added eventually. Covenant turfs aren't in the code yet so stick to human ships. Space stations and asteroid bases are basically the same as capital ships but a little bit simpler. In the code stations and asteroid bases are treated identically. Anything larger than 20x20 must be either a capital ship or station (not a shuttle) and can use one or more zlevels.

2. Map the internal layout. Size guidelines for some possible ship/shuttle types are:

- Small shuttle, dropship, personnel lighter, escape pod: up to 6x6 tiles (shuttle class)
- Large shuttle, tug, gunboat, heavy dropship, small yacht: up to 20x20 tiles (shuttle class)
- Stealth vessel, light freighter, transport ship, patrol boat, sub-prowler/sub-corvette, luxury yacht: 1 zlevel (capital class)
- Corvette, light frigate, medium freighter, personnel transport: 2 zlevels (capital class)
- Frigate, light destroyer, heavy freighter, refinery ship: 3 zlevels (capital class)
- Destroyer, heavy frigate, light cruiser, light carrier, colony ship: 4 zlevels (capital class)
- Heavy cruiser, carrier: 5 zlevels (capital class)

Space stations and asteroid bases can be anywhere from 1-5+ zlevels depending on their purpose. Shuttle class ships are able to physically move around inside and dock with capital class ships. We can theoretically make shuttles up to around 50x50 or larger, but any larger than 20x20 and gameplay/performance issues crop up. There are also specific turfs you need to use for shuttles. Capital class ships and space stations occupy entire zlevels and have static layouts. On the overmap both type of ships work near identically but should be given different sized sprites to represent their size difference. Place a minimum 50 tile margin of empty space around the edge of anything occupying one or more zlevels.

Map your shuttles facing north (up) and map your capital ships facing east (right). Don't ask me why because I was probably drunk at the time. I might get drunk and make them the same someday but forget to tell anyone so all the ships suddenly start flying sideways. Spacestations and asteroids can do whatever they want. Make sure that the map z dimension is always 1 and split separate decks off into separate mapfiles labelling then myship-1.dmm myship-2.dmm etc.

2(a). Shuttle specific stuff

The shuttle code requires that the only turf type used internally are of type /turf/simulated/shuttle/hull (for the shuttle) and /turf/unsimulated/blocker (for any empty space around it). To achieve a desired visual effect, you will need to modify the icon and icon_state of the turf in the map editor to match what you want. To do this right click on the turf, go to the dropdown for it and select "Edit..." then scroll down to where it says icon in the left column. In the right column enter the path of the icon you want to use inside single brackets (eg 'icons/turf/space.dmi') then press "OK". Go to the edit menu again, and this time scroll down to where it says icon_state in the left column and put the name of the icon state you want in the right column in double brackets (eg "plating"). To find a list of possible turf sprites to use, navigate to icons/turf inside Dreammaker.

For floor turfs (ie are non-dense and non-opaque) use /turf/simulated/shuttle/hull/floor and for windows (dense and non-opaque) /turf/simulated/shuttle/hull/window the parent hull type /turf/simulated/shuttle/hull function as walls (dense and opaque). Don't worry about maglocks, they don't use specific turfs for now.

Do not map out any areas, but make sure you place exactly 1 APC somewhere (SMES and cabling are optional but there if you want them) and at least 1 /obj/machinery/computer/shuttle_helm to fly the shuttle. Lighting is also required, and you can use ordinary airlocks as normal to divide internal cabins and rooms. Place some /obj/machinery/door/airlock/external/shuttle to allow players to enter and exit the shuttle while it is in flight (not maglocked). Putting the machinery for a cycling airlock is not necessary as most shuttles will be flying to and from hangars or planets with atmosphere, but you can do it if you want (eg for a salvage or SAR shuttle).

The map file containing this layout should use the exact same dimensions. Eg if your shuttle is 12x15 then the map should be 12x and 15y.

Nothing other than shuttles should use these turf types.

3. Get an overmap sprite for your ship or station

Shuttles: the sprite should be around 16x16 from one end to the other (use a standard 32x32 dmi size) with a little bit of leeway either size (eg you could do a 10x10 or 20x20 sprite). Create it as an state in code\modules\overmap\overmap_vehicles\icons\overmap_vehicles.dmi and call it whatever you want but remember it for the next step (4). Make sure the sprite is facing north and don't bother creating directional states.

Capital ships or space stations: The overmap sprite should be 32x32 for things that are 1 full zlevels, 64x64 for things that are 2 full zlevels, 96x96 for things that are 3 zlevels, 128x128 for things that are 4 or more zlevels. Also include icon states for thrusting and braking (reverse thrust). For the dimensions larger than 32 you will need to use an external editor then import it into Dreammaker, I recommend Paint.NET as it's free, small and fast but with loads of features. Place it as a new icon inside the folder code\modules\overmap\ships and name the icon states "base" "thrust" and "brake" for ships. Make sure all 3 icon states exist (if ship), but just reuse the base sprite if you don't have the extra ones. Make sure the sprites are facing north and don't bother creating directional states. 32x32 station sprites can go into code\modules\overmap\ships\sector_icons.dmi or just as new icons into code\modules\overmap\overmapobj (sorry it's a little bit disorganised). Remember the icon name and icon_state for the next step (4a and 4b and 4c).

3(a). Shuttle top-down sprites

The top-down sprite is used for the shuttle when it is in flight (eg docking with or leaving a hangar) and the dimensions need to match the full pixel dimensions of the internal layout so an external editor is required. To calculate the size required, count the x width and y-height of the shuttle excluding any empty space then multiply by the standard Byond turf size of 32x32. For example, a shuttle that is 5 turfs wide and 10 turfs high will need a top-down sprite with dimensions 160 (5 x 32) by 320 (10 x 32).

Once you figure out the required dimensions either obtain the services of an artist or map out the "roof" in Dreammaker using whatever turfs you like then take a screenshot and scale/crop it to the required proportions. Place the image into its own DMI (ensuring it is facing north) and call the icon state "shuttle". Call the icon itself whatever you want, but remember it for the next step (4a).

3(b). Sensor HUD images

Everything the size of a fighter or larger needs a unique sprite to quickly identify it when it pops up on a player's sensor HUD. The sprite should be 32x32 and grayscale (because it is coloured in according to its faction or light blue for environmental stuff like asteroids and stars). Place the sprite in code\modules\overmap\overmap_vehicles\icons\overmap_vehicle_hud.dmi and name it whatever you want but remember it for the next step (4).

4(a). Implementing shuttles in code

Open up code\modules\overmap\overmap_vehicles\instances\shuttles.dm then scroll down to the bottom of the file and copy paste the following code at the end:

Code:
/obj/machinery/overmap_vehicle/shuttle/my_shuttle_path
   name = "My Awesome Shuttlecraft"
   desc = "For transporting Super Cool Dudes while making spacey noises with your mouth."
   icon = 'code/modules/overmap/overmap_vehicles/shuttles/my_shuttle_icon.dmi'
   overmap_icon_state = "unsc_shuttle"
   maglock_strength = 8
   bound_width = 192
   bound_height = 384
   layout_file = 'maps/ships/my_shuttle_layout.dmm'
   layout_x = 6
   layout_y = 12
   iff_faction_broadcast = "UNSC"
   hull_remaining = 250
   hull_max = 250
   armour = 75
   maglocked_at_spawn = 0

We will now edit some lines to customise this code. Some lines are optional and if they aren't changed then they can be deleted to make the code a little cleaner. We'll go through the lines one by one.

Code:
/obj/machinery/overmap_vehicle/shuttle/my_shuttle_path

Change my_shuttle_path to whatever you want but keep it reasonably simple and only use lower case letters and underscores (eg colonial_salvage_shuttle).

Code:
   name = "My Awesome Shuttlecraft"
   desc = "For transporting Super Cool Dudes while making spacey noises with your mouth."

Change these to whatever you want. This is what the players see when they mouse over or examine the shuttle.

Code:
   icon = 'code/modules/overmap/overmap_vehicles/shuttles/my_shuttle_icon.dmi'

Change this to the icon containing your top down sprite you made in step 3(a).

Code:
   overmap_icon_state = "unsc_shuttle"

This should match the icon_state of the overmap icon you made in step 3.

Code:
   maglock_strength = 8

This is the number of adjacent or overlapping walls and floors required to "maglock" or dock with a capital ship. Pick the side you want to use to dock (usually the one with airlocks in it) and this number should be slightly less than that. Eg if the sides of your shuttle are 8 tiles high then the maglock strength should be 6.

Code:
   bound_width = 192
   bound_height = 384

This should be changed to the exact dimensions of the top down sprite.

Code:
   layout_file = 'maps/ships/my_shuttle_layout.dmm'
   layout_x = 6
   layout_y = 12

Change the layout file to be the map file containing your layout, and make sure the layout_x and layout_y match the map dimensions.

Code:
   iff_faction_broadcast = "UNSC"

Optional: Determines the faction alignment for sensors. Available options are "UNSC" "Insurrection" "Covenant". Probably just leave this as UNSC for now because the Insurrection aren't in a habit of broadcasting their presence.

Code:
   hull_remaining = 250
   hull_max = 250
   armour = 75

Optional: hull_remaining and hull_max should be set the same and represent the overall health of the shuttle. armour functions as damage mitigation and anything that deals less damage than this value is ignored. If something deals more damage than the armour value then hull is removed according to the function hull_remaining -= damage / armour means something that deals the same amount of damage as the shuttle has armour will only remove 1 point of hull. Be sensible and look at existing values to balance this. If you're in doubt then don't change it.

Code:
   maglocked_at_spawn = 0

Optional: determines if the shuttle spawns in as maglocked (docked) at the start of the game.

4(b). Implementing capships in code

Open up code\modules\overmap\ships\unique_ships.dm then scroll down to the bottom of the file and copy paste the following code at the end:

Code:
/obj/effect/zlevelinfo/ship/my_ship
    name = "UNSC Derpaderp"
    desc = "For a brick it flies pretty good."
    icon = 'code/modules/overmap/ships/my_ship_icon.dmi'
    faction = "UNSC"
    init_bounds_dims = 96
    use_me_to_initialise = 0
    sensor_icon_state = "7th_column"

We'll break it down line by line. Sensors are definitely working but leave speed and acceleration etc alone again for now.

Code:
/obj/effect/zlevelinfo/ship/my_ship

Change my_ship to something simple and clear and only using lowercase letters and underscores.

Code:
    name = "UNSC Derpaderp"
    desc = "For a brick it flies pretty good."

What the players see. Remember that UNSC specifically refers to navy ships (including ONI). For civilian ships use CAA (Colonial Administration Authority), UEGS (United Earth Government Ship), your own made up acronym or nothing at all. The desc should be describe it's origins and purpose while being informative and short.

Code:
    icon = 'code/modules/overmap/ships/my_ship_icon.dmi'

Change this to the icon you made in step 3.

Code:
    faction = "UNSC"

For sensor faction purposes. Available values are "UNSC" "Insurrection" "Covenant" but again best left as "UNSC" for now.

Code:
    init_bounds_dims = 96

Set this to the dimensions of your overmap sprite (which should be square).

Code:
    sensor_icon_state = "7th_column"

Set this to the icon_state you created in step 3(b).

Code:
    use_me_to_initialise = 0

This is a magic number and should be kept as 0. We'll look at it in step 5a.

4©. Implementing stations and asteroid bases in code

These are the simplest to do. Open up code\modules\overmapobj\unique.dm (it might not exist and need to be created). Scroll to the end and copy paste the following code:

Code:
/obj/effect/overmapobj/my_station_thingy
    name = "a station or something"
    desc = "a thingy"
    icon = 'code/modules/overmap/ships/sector_icons.dmi'
    icon_state = "mysprite"
    faction = "UNSC"
    init_sensors = 1
    sensor_icon_state = "mysensorsprite"

Then we gonna edit some lines.

Code:
/obj/effect/overmapobj/my_station_thingy

Change to something short with only lowercase and underscores.

Code:
    name = "a station or something"
    desc = "a thingy"

What the players see. Do something descriptive.

Code:
    icon = 'code/modules/overmap/ships/sector_icons.dmi'
    icon_state = "mysprite"

Change this to the icon and icon_state you created in step 3.

Code:
    init_sensors = 1

Keep this line and make sure it is set to 1. ~~magic~~

Code:
    faction = "UNSC"

This is for sensor alignment colour. Available options are "UNSC" "Insurrection" "Covenant" but you can also set it to any random value and it will stay in grayscale.

Code:
    sensor_icon_state = "mysensorsprite"

This should match the icon_state you created in step 3(b). Sensors might not setup correctly at the moment but remind me to fix it because it's probably just a quick tweak.

5. Final steps - testing (read this for shuttles, ships, stations, asteroids)

Press control+k or choose Build -> Compile (from the top menu list). Shuttles can skip the rest and go directly to 5c

What we need to do now is to make sure the map files are loaded correctly by the code. When they are loaded should be handled by the code (ie the gamemode or whatever code spawns your thing in midround) but we need to do some final stuff to determine how they are loaded. Compile the code and open up each of the map files for your ship or station. If there are any errors double check you have copy pasted the code correctly. In step 4 we defined a metaobject which contains the information on how to properly load, create and initialise our ship or station. Ships and stations/asteroids are done slightly differently (eventually I'm going to make them the same which will simplify this a bit). In order to initialise both and spawn them on the map for testing we need to place a specific meta info object on each of the map files for our thing then place a different kind of meta info object into the overmap at the coordinates we want it to spawn in for testing.

Note 1: If you can't find it in the object list then remember to click the + for each / in the type path and explore until you find it (make sure you have compiled at the start of this step).

Note 2: If you are having trouble placing one of the meta info objects make sure your placement cursor type is set to "Add" (an icon of a filled in box with a plus side in the top right corner) which is the leftmost of 3 buttons near the bottom of the middle pane directly left of the map window. If you are in "Fill" mode you might need to click and drag to place the object, and if you are in "Select" mode you won't be able to place it at all.

Note 3: The object list displays the PATH but not the NAME. Once placed on the map you will see something's name when you right click on it. If done correctly both kinds of meta objects (for ships) or the meta object we place on the overmap (for stations and asteroid bases) should be the same dimensions and sprite as our ship when it appears on the overmap. The meta object we place in the map files for stations and asteroids should just appear as a blue cross.

5a. Final steps for ships

(i) In the bottom left corner of EACH MAP FILE, place exactly one of that meta object we defined in the code in step 4b (/obj/effect/zlevelinfo/ship/my_ship which you should have renamed).

(ii) In the top map file (the highest on the list) right click on the meta object we just placed, open up the dropdown list and select "Edit..." then scroll down to where it says use_me_to_initialise in the left hand column. Change the value on the right to 1. This doesn't strictly need to be done on the top map file but it should only be done on exactly one of them.

(iii) Finally open up the map __overmap.dmm and place a /obj/effect/overmapobj/ship then rename it to exactly the same name as the meta info object we created in step 4(b) and placed down in 5(a)(i). To change the name, right click on it and select "Edit..." then scroll down to where it says "name" in the left column. Put the name into the corresponding box in the right column. Remember the coordinates on the overmap where you placed it, then tick the map files to include them in the DME (note: this should only be done for testing). Delete the object from the overmap after you have finished testing it.

5b. Final steps for stations/asteroids

(i) In the bottom left corner of EACH MAP FILE, place exactly one of /obj/effect/zlevelinfo and name it the same as the meta info object we created in step 4© (note: the NAME not the TYPE). To change the name, right click on it and select "Edit..." then scroll down to where it says "name" in the left column. Put the name into the corresponding box in the right column.

(ii) In the top map file (the highest on the list) right click on the meta object we just placed, open up the dropdown list and select "Edit..." then scroll down to where it says use_me_to_initialise in the left hand column. Change the value on the right to 1. This doesn't strictly need to be done on the top map file but it should only be done on exactly one of them.

(iii) Finally open up the map __overmap.dmm and place a /obj/effect/overmapobj then rename it to exactly the same name as the meta info object we created in step 4©. To change the name, right click on it and select "Edit..." then scroll down to where it says "name" in the left column. Put the name into the corresponding box in the right column. Remember the coordinates on the overmap where you placed it, then tick the map files to include them in the DME (note: this should only be done for testing). Delete the object from the overmap after you have finished testing it.

5c. Final steps for shuttles

Shuttles should simply be placed into a pre-existing ship or station (ie one of the hangars in the cruiser map) and they're good to go (make sure your map cursor is set to "Add" mode).

6. Running the code and testing your thingy

Recompile and run your code after editing the map. If you are testing a shuttle, just go to where you put it in the cruiser map. Otherwise steer the cruiser to the coordinates you placed your ship on the overmap, jetpack over and start exploring or flying it around. A little creative adminghosting, adminporting and/or var-editing will get you there much faster, or you can place player spawn markers onto your ship and spawn there at round start (a little bit more complex).

Revisit any of the previous steps to modify or tweak things as needed. This is a long and complex guide so if you have any issues come to me for help. And if you find any bugs or think something is broken, go ahead and create an issue on github to get it addressed! There are also a few tweaks which I need to do which will simplify some stuff like step 5.

In total this guide is 3.5 hours, 3447 words, 265 lines and 7 standard drinks worth of Sailor Jerry's Caribbean Spiced Rum.