View source for SketchUp to Hammer Export plugin

{{update}}

__TOC__
The '''SketchUp to Hammer''' export plugin allows you to create models in [http://sketchup.google.com/ Google SketchUp] and then export them to the [[VMF|.vmf format]] for use in [[Hammer|Hammer]], the world editor for the Source game engine. Hammer is used to create game levels for games such as Half-Life 2, Portal, Counter-Strike, and Left 4 Dead. 

== How it works  ==

First you create groups of 3D geometry in SketchUp. Each group is typically a simple "solid" form such as a box or cylinder, or anything with a convex topology. The plugin translates each group/component into a Hammer "[[brush|brush]]". If a component is named a certain way, it will export not as a brush, but rather as an "[[entity|entity]]" which can be a light or other prop. If you've named your materials with the game's naming convention, the specified game materials will be assigned to brush faces. The result is a .VMF file, which is a source (raw) file that can be opened directly in Hammer.

Once in Hammer, you can further edit and append game level, as well as compile or "bake" your level into a .BSP file. BSP files can be loaded and played directly by Source engine games. You can build levels in either Hammer or Sketchup, or, most probably, you'll find it handy to go back and forth, making building blocks in SketchUp, importing the pieces into Hammer, and then using cut and paste to aggregate them bit by bit into a final map using Hammer. 

SketchUp is useful for making quick mockups or complex brushes, but it doesn't support all of the game features. Hammer is a full-featured game level editor, and it's where you'll want to end up doing your later stage work. This is especially true if you plan on making high-quality, releasable game levels.

If you're new to editing game levels using Source, it's recommended that you visit the [[Level Design|Level Design documentation pages]]. There you'll find the best source of information on how to setup and get started using Hammer.

== Installation  ==

See the main [[SketchUp Source Tools]] page for detailed installation instructions.

You may also need a previous version of SketchUp as the available plugins have not been updated for SketchUp 2016 and beyond.

== Textures ==

Currently you are required to manually create materials in SketchUp based on the materials you want to use from the Source Engine.
The only requirement is that the name of the material match the name of the .vmt file in hammer.  Include the full path, i.e. "concrete/concretewall01a".

== Exporting maps  ==

Let's start by going through the entire map exporting process with a simple example map. You're probably itching to draw your own map right away, but it's recommended that you make sure you can export, import, compile, and run this test map first.   

To Start, launch Sketchup and load the file "myfirst_su_level.skp". It is provided with the plugins and can be found in the <code>valve_library</code> folder, typically found here: 

 C:\Program Files\Google\Google SketchUp 7\Plugins\valve_library

[[File:Su scene1.jpg|thumb|256px|right|caption|First loading "myfirst_su_level.skp"]]

1. The game map is a simple box volume with a few objects inside. The large, boxy objects are drawn so that they will export to hammer as "brushes", or solid building blocks in the game. In order to make a game level that runs properly, the "habitable" volume must be fully enclosed by brushes. In this example, the front box that fully encloses the habitable space has been hidden so that we can see inside. You can unhide it if you want: From the menu bar, go to the Edit menu and select '''Unhide > All'''. The volume inside is "watertight", fully sealed from the outside space. Go ahead and click the tab at the top of the 3D window labeled "Scene 2" 

{{clr}}

[[File:Su scene2.jpg|thumb|256px|right|caption|info_player_start Entity]]

2. The box with the green figure is a SketchUp object that has been named "<code>ENT_info_player_start</code>". When this file is exported as a .vmf and opened in Hammer, this object will become an entity called "<code>info_player_start</code>" and tell the game engine where to initially place your point of view. Go ahead and click the tab at the top of the 3D window labeled "Scene 3".

{{clr}}

[[File:Su scene3.jpg|thumb|256px|right|caption|Light Entity]]

3. This is another object named "<code>ENT_LIGHT</code>" it will export to the game as, you guessed it, a light. You can edit the properties of this light later when you get it inside Hammer. Click the tab labeled "Scene 4".

{{clr}}

[[File:Su scene4.jpg|thumb|256px|right|caption|Painted Surfaces]]

4. Some of the surfaces in the model have been painted with materials. Click on the '''Paint Bucket''' tool (icon) on the toolbar, and then click on the home icon of the window that pops up. This shows you materials that are being used in the scene. If you hover over the brick texture, you'll see that this material has been named "<code>dev/dev_brickwall012d</code>". This corresponds to a material that shipped with Left 4 Dead. When materials are given game pathnames like this, they will come into Hammer with those material assignments.
{{clr}}

5. Let's make sure everything is set up properly. Go ahead and, from the menu bar, select '''Plugins > Export VMF...''' When prompted, use the default name "<code>myfirst_su_level.vmf</code>", and save the file somewhere convenient like your desktop. 

{{note|If you recieve a message about "Unsupported Stuff", you may safely ignore it. The plugin doesn't know what to do with the text callouts in this tutorial. If you delete them, the message should go away.}}


6. Start '''Steam''', go to the '''Tools''' tab, and launch "'''Left 4 Dead Authoring Tools'''". Click "'''Hammer World Editor'''" from the list. When Hammer launches, open the .vmf file that you exported in the previous step. Your map should appear in wireframe. 

7. From Hammer's '''View''' menu, select '''3D Shaded Textured Polygons''' The 3D Camera View in the upper left hand corner should now appear solid. We'll dive into Hammer more a bit later.

8. In the Hammer window, select '''File''' > '''Run Map...'''. Leave the default options and click '''OK'''.
  
9. Hammer will process the map and calculate lighting. When it's done, it will launch Left 4 Dead and open the new map. Dismiss the "Map is unplayable!" message. You should now be in game!

{{note|The "Map is unplayable!" message comes up because the game needs something called a navigation mesh for the AI-controlled characters. But we don't need one to walk around and view the level. You can learn how to make nav meshes later.}}

Next, let's add your own forms in SketchUp...

== Creating your own brushes  ==

1. Exit the game and go back to your SketchUp model. We're going to make some changes, so it's best to do a quick '''Save As...''' to a new file somewhere. 

2. Click on the "Scene 2" tab to position the camera next to a good drawing surface. 

3. Activate the '''Rectangle Tool'''. [[File:Su_ico_rect.jpg]]  You can activate it from either the toolbar or the '''Draw''' menu. Make a rectangle on the ground by clicking and dragging across the floor surface. 

4. Activate the '''Push/Pull Tool'''. [[File:Su_ico_pp.jpg]]   You can activate it from either the toolbar or the '''Tools''' menu. Click and drag the rectangle you created previously to extrude it into a box. 

5. Let's get a different perspective of this brush in 3D. Click this icon to activate the '''Orbit Tool''' [[File:Su_ico_orbit.jpg]]  and press and drag your mouse across the 3D screen. This orbits your view. view. You can also hold down your middle mouse button to orbit while in other tool modes. You may also activate it through the main menubar with '''Camera > Orbit'''. 

6. Use your mouse scroll wheel to zoom in and out. Alternatively, you can use the '''Zoom Tool''' icon[[File:Su_ico_zoom.jpg]]  or the '''Camera > Zoom''' menu item.

7. Next reactivate the '''Push/Pull Tool''' [[File:Su_ico_pp.jpg]] and press and drag the sides of the box. This allows you to adjust it's sides. Try not to make it too big; it should be a small object inside the overall box for now.

8. Activate the '''Select Tool''' [[File:Su_ico_arrow.jpg]] and drag a rectangle around the box from left to right. This will select all of its faces and edges. Make sure that you've selected only the box, and not the 2D figure or anything else as well. If you select from right to left, it will select anything that intersects your box, and that may include geometry behind the box by mistake. Another handy way to select the whole box alone is to triple click one of its faces.

9. From the '''Edit''' menu, select '''Make Group'''. Your box should now be grouped and highlighted. Congratulations! You've made your first game building block! This box will now appear as solid to the player when imported into the game. 

10. Activate the '''Move Tool''' [[File:Su_ico_move.jpg]] and click on the box. It should follow your cursor until you your mouse button a second time. Now try the same action while holding down the {{key|CTRL}} key. Now you're making copies... Make as many copies as you like. It's OK if they overlap one another in volume.

11. Try clicking on the small red "plus" signs that appear when you hover over the boxes with the move tool. This allows you to rotate each box along that side.You can use the '''Select Tool''' [[File:Su_ico_arrow.jpg]]  to deselect a box, or to select one or more boxes. 

12. Try activating the '''Scale Tool''' from the '''Tools''' menu, and stretching the building blocks in different directions. 

13. Let's go ahead and try exporting again. From the '''Plugins''' menu, select '''Export Hammer VMF...''' Again, you will be prompted for a file location. Notice that the default name of the .vmf is filled in using the name of your SketchUp file. Go ahead and save it. When you switch back to Hammer, you'll see the previous unchanged .VMF map. Go ahead and close it, then open the updated .VMF that you just saved. You should see your new changes, and if you run the map as before, you should see your changes in game.


You're now on your way to making awesome levels. There's a lot of stuff to learn when you're starting out making game content, but you can do it. If you run into stumbling blocks, remember to visit the [[Level Design|Level Design documentation]] pages.

== Hammer tips ==

Like all Source Engine tools, Hammer has standard content folders. It's preferable that .vmf files be saved in the <code>sdk_content\mapsrc</code> directory. The default location for mapsrc in Left 4 Dead is:

 C:\Program Files\Valve\Steam\SteamApps\common\left 4 dead\sdk_content\mapsrc

After you've opened the .VMF file you saved from SketchUp in Hammer, it's handy to have a look around.

1. You can navigate the 3D view in the upper right corner using the {{key|W}}{{key|A}}{{key|S}}{{key|D}} keys, similar to how you walk in the game.

2. If you tap the {{key|Z}} key, the mouse will switch from a cursor to "look around" mode. This mimics how you look around in game and is handy to use while pressing the {{key|W}}{{key|A}}{{key|S}}{{key|D}} keys. Tap {{key|Z}} again to switch back to mouse cursor mode.

3. If your 3D view is in wireframe, you can, from the 'View' menu, select '3D Textured Shaded Polygons' You will notice that the plugin has created a green "<code>player_start</code>" location as well as light entities where their SketchUp components were placed.

4. Learn more about navigating in Hammer [[View_Navigation|here]].

== Modeling tips  ==

* Each individual group should have a convex topology. [[Concave|Concave forms]] will not export to Hammer properly, and you may get an "invalid solid" message. Forms such as arches must be built from many convex forms arranged together.

* When making your levels, try to build with simple building blocks. You can group many objects together to make a more complex form.

* By default, the forms you make will have a grey grid material. You can use the MaterialZoo.skp in the "valve_library" folder to grab some other materials. The name of the material in SketchUp will determine what material will be applied in Hammer.

* You can find many great videos online that can teach you to use SketchUp in just a few days.

== Exporting .VMF for other Source Engine games ==

Source Engine games released prior to Left 4 Dead use a separate SDK (Software Development Kit) which includes their own version of Hammer. You can use the SketchUp plugin that comes with the Left 4 Dead authoring Tools to export .VMFs for these games as well. To get the SDK:

# From Steam, go to the '''Tools''' tab.
# You should see '''Source SDK''' in the list. Launch it. (Steam will install it if it hasn't been already).
# When the Source SDK launcher window comes up, it has drop down menus that allow you to author for different engine versions and games. Make sure the '''Current Game''' you have selected is one that you have installed on your 'my Games' list and that the game has been run at least once. If it doesn't show up, switch the '''Engine Version''' and then check again. If it still doesn't appear, close the launcher, run the game once, then re-open the Source SDK.
# Select the game you wish to play in from the drop-down.
# Launch the '''Hammer Editor''' application.

* The default [[2D skybox|2D skybox]] texture is configured for Left 4 Dead. If you want to change it, create a sky component with the name "<code>SKY.''name_of_texture''</code>". You should only have one of these per level.

* If you want to place an entity in you game level, create a custom component and name it "<code>ENT.''name_of_entity''</code>". So if you want to place a zombie from Half-Life 2, name the component "<code>ENT.npc_zombie</code>". Name it "<code>ENT.weapon_physcannon</code>" to place the physics gun. The exporter will ignore the contents of the component. All that matters is the name and the position. The entity needs to be in the game you're compiling for, and a list of options is visible in Hammer. 

{{note|You can find a few game specific entities (components) in the valve_library folder.  To create new entities, you need [http://sketchup.google.com/product/gsup.html SketchUp Pro].  The free version can only duplicate and rename already existing entities.  (changes to any entity will effect all duplicates)}}

* The file '''valve_sketchup_tools_config.rb''' allows advanced users to configure plugin options.

== Known bugs ==

* Exporting .VMF files with the outliner open can cause a crash. This is usually caused by setting <code>$v_vmf_export_boundingbox = true</code> in the config file. Workaround 1: Close or minimize the outliner. Workaround 2: set <code>$v_vmf_export_boundingbox</code> to <code>false</code>.

== Comments and bugs ==

* Please send comments and feedback to [mailto:sketchuptools@valvesoftware.com sketchuptools@valvesoftware.com]

== See also ==
* [[SketchUp to SMD Export plugin]]
* [[SketchUp Source Tools]]

[[Category:Level_Design]]
[[Category:SketchUp]]