The Ship: Creating a Deckplan

From Valve Developer Community
Jump to: navigation, search


To make a deckplan you'll need...

  • Everything required to make a regular Source engine texture, you can use VTF Edit.
  • A web image-mapping tool (something that converts rectangular areas of an image with individual attributes into HTML).
    • Try Mapedit - it's what Outerlight uses and has a free trial.
  • A tool to convert HTML image map data to a Source key-values file (Provided in The Ship SDK).


Although this guide is roughly sequential, you'll probably jump back and forth between hot-spotting and checking results in-game - run the game windowed and you can do everything at the same time.

Creating the deckplan images

The first stage in creating your deckplans is to create the background images. When creating the images, be sure to observe the following rules...

  1. Each deck should be contained within a separate 1024x256 targa image.
    1. Leave at least 100 pixels at the right of the image empty.
    2. Leave at least 10 pixels at the top and bottom of the image empty.
  2. The Ship should be pointing to the right.
  3. Images must use the correct filename and directory. Using the example of Batavier (batavier.bsp)...
    1. Deckplan images would be batavier_deck_a.tga, batavier_deck_b.tga, etc...
    2. Compiled materials must be in the folder materials/vgui/deckplans/batavier.
    3. Also export BMP versions of the images into scripts/deckplans/batavier.
  4. An 8-bit alpha channel is used to define transparency.

Once you have your images, use your preferred method of creating source engine materials to turn your TGA's into VMTs/VTFs for use in the game. Ensure they are in the folder materials/vgui/deckplans/<mapname>.

Getting reference shots

In order to make drawing the deckplan images simpler, you will want to get some reference screenshots of the level which you can then paint over. There are a few methods you may want to adopt to do this, but the general idea is to open your level in Hammer and create views of only one deck at a time. You may do this by separating the map into various VisGroups, allowing you to look at only one deck at a time by simply turning the others off. On the other hand, you could try using the cordon tool to cull out any elements of the map outside of a resizeable bounding box. Regardless of the method, you can then either take a screenshot of the deck directly within Hammer (either the orthographic top-down view, or from the 3D perspective view), or you can compile the cordoned map and get a screenshot in-game by flying above it using noclip.

A note on accuracy

These images can be thought of as artistic interpretations of the ship - they DO NOT have to mimic the ship 100% accurately. Feel free to draw the deckplans in a way that makes them easy to interpret and pleasant to look at rather than being completely accurate or to scale.

Awkward-shaped rooms

When in-game, the rooms on the deckplan flash due to certain events. These flashing areas are defined by axis-aligned rectangular boxes, as will be covered later. Rooms with curved or angled sections cannot be defined by a combination of axis-aligned rectangles alone and must have masks created for them. It would be sensible to create masks for these awkward rooms at the same time as you are drawing the deckplan images. Each mask should be separate TGA file with a alpha channel defining the shape of the room.

Creating the imagemaps

With the images created, you need to define the rooms within each deck such that they represent the rooms in the map defined as by the level designer. You do this through HTML imagemaps, which allows you to use tools such as Mapedit to define areas on an image and assign them with properties; href is used to specify information for a room.

Auto-generating the imagemaps

The first step is to auto-generate HTML imagemaps for each of the decks. Though the output will not match your deckplan images, it provides a good starting point and saves you entering room names and numbers manually. This is done in-game by running the deckplan_generate_all and deckplan_generate_deck console commands. These commands look at all of the ship_trigger_room entities placed in the level (or within the given deck) by the level designer and use their boundaries to build an accurate representation of the ship's room layout.

  1. Create the directory scripts/deckplans/<mapname>
  2. Launch the game in windowed mode and run the map you wish to generate deckplans for.
  3. Bring up the console and run the command deckplan_generate_all <rotation> <scale>.
    • <rotation> is a value, in degrees, to rotate the deckplans through. This should be a multiple of 90.
    • <scale> is the value you wish to scale the resulting coordinates by to make them more suited to the size of the deckplan images. Typically this should be around 0.2, but varies depending on the map.
  4. If you wish to generate the image map for a single deck, use the command deckplan_generate_deck <deckname> <rotation> <scale>
    • <deckname> is the name of the deck, using the format "#Ship_Deck<deck>", e.g. "#Ship_DeckA".
  5. Use Mapedit to open the generated HTML file for one of the largest decks.
    1. Check that the generated image map is oriented correctly.
    2. Check that all of the rooms fit on the image.
    3. If both of those checks are passed, then you are done with auto-generating our initial deckplans.
    4. If you get a message saying MapEdit cannot find the image, you haven't got the BMP of the deckplan in your scripts/deckplans/<mapname> folder.

Tweaking the imagemaps

With the deckplan imagemaps generated, the next job is to tidy them up.

  1. Open the first HTML deckplan file.
  2. Use the "Move or resize ENTIRE imagemap" tool to approximately line up the imagemap with the image. Rather than aligning with one of the extremities, try and line up the rooms in the centre - this will even out the inaccuracies between each end.
  3. Use the "Test and Edit Hotspots" tool to view a hotspot's properties.
    • The only property you care about is the URL, which is where you define the room properties.
    • Following the room name, a room number may be specified as a parameter with "\<room_number>". (e.g. "corridor \3".)
    • Hotspots on the same deck with the same room name and room number are treated as one room in-game.
  4. Use the "Move points (resize hotspot)" tool to select each hotspot, move it into position, and resize it as necessary. Remember that rooms will often be made up of more than one hotspot. Sometimes 2 or more hotspots with identical properties cover an area that could be safely covered with just one hotspot - feel free to use just one and delete the others.
    Warning.png Warning: Be careful not to ignore room numbers - they are just as important as room names!

Using image masks

  • Rooms that require masks should have their hotspot cover the entire room, even if this means overlapping other rooms.
  • You can define the mask in the URL by adding the parameter "\image <mask_image>".
    • <mask_image> is the filename of the mask image
    • e.g. "davy_jones_bar \image bar1_mask"

Adding needs icons

You can add icons to the deckplan that can be toggled on and off in-game by the player in order to help them find ways to fulfil their needs. You define these icons by adding them as a parameter to a hotspot URL, just in the same way as you do with room numbers and image masks. The icons will appear in the centre of the hotspot to which you assign them. Below are the various icons you can use; a hotspot can use as many or as few of these as necessary...


Example: "corridor \7 \icon_drink \icon_meal"

Bringing it together in-game

Once you are happy with the HTML deckplans, you need to get them into the format used by the game engine.

  1. Run the deckplan script generator (..\sourcesdk\bin\deckplanner\deckplanner.exe).
  2. Enter the corresponding info. This only needs to be done once because this info is stored for future use.
  3. Provided you have all of the HTML files in the correct directory, pressing Go! should now generate a .txt file in the same place.
  4. Run the game, and your deckplan will be functional for you to test.

Testing and making corrections

It is likely that during your testing you will notice some things are not correct in your deckplan. By running the game in windowed mode you can easily make changes to the deckplan and check them immediately, making the deckplans very easy to debug.

  1. To assist in debugging, force the game to display room numbers in your position info for all room types with "ship_force_show_all_room_numbers 1".
    Note.png Note: By default only cabins and a few other room types show their room numbers.
  2. If you find a problem with the deckplans, open Mapedit, make the necessary changes to whatever deck you are correcting, and save the HTML file.
  3. Re-run the deckplan script generator on your level.
  4. Switch back to the game, open the console, and type ship_cl_reload_deckplan.
  5. Check your changes and continue testing.