Source 2 Hammer introduction

  Source 2 Hammer introduction

The focus of this tutorial is to provide a crash course for level designers, beginner or Source 1 veteran alike, wanting to learn Source 2’s level design tool, Hammer.

This tutorial uses SteamVR as a base and is gradually tailored towards Half-Life Alyx.

This is a living document and heavily WIP, feel free to leave comments or editing suggestions if there are any inaccuracies in the doc.

Planned video breakdown

  1. Interface, viewports, navigation, selection https://youtu.be/HrfsfgYpYN0

  2. Block tool, basic transformation, grid, snap & Hammer units

  3. Mesh editing https://youtu.be/modE6y3o58U

Plausible advanced tutorials

  1. 3D Skybox

    Skybox_reference (3D skybox separate vmap, entity at  0 0 0), create a prefab named skybox, set the map properties map type to 3D Skybox. Then reference your skybox vmap in the skybox_reference entity. Sky_camerai is used to control the scale of the skybox which should be set to 1/16th or 0.0625 for X Y Z, this also means you have to scale all the assets in the skybox vmap down by 1/16th or they will not be scaled correctly to the world.

  2. HLA navigation

  3. Prefab randomizing through variables and choice groups.


External resources

Bootleg Hammer setup

Tools

This program can open Valve's VPK packages and most Source 2 assets

(maps, models, meshes, materials, textures, sounds, and more!)

All Source 2 projects are supported: Dota 2, Half-Life: Alyx, SteamVR, Underlords, and others.
Can supposedly also decompile .vmdl_c

Tutorials

PBR materials in Source 2

Special thanks

  • Rectus

  • Daneel Filimonov

  • Steve

  • DankParrot

  • Gvarados

The differences with Source 1

If you are coming from Source 1, a lot of the concepts will be familiar to you, there are however a few key differences.

  • BSP is no longer used, long live BSP

  • Leaks no longer exist 

  • Everything is mesh based

  • Source 2 Hammer is a basic modelling tool

  • Real time preview lighting in editor 

  • A new proprietary physics engine, Rubikon

Things that are still the same compared to Source 1

  • Maps still need to be compiled

  • Lighting needs to be compiled

  • The Input / Output scripting system is still in use, but works hand in hand with Vscript Lua scripts.


New file formats


The Source 2 engine has a content and game directory. The content directory contains all work files, the game directory contains all game format files. Assets saved in the content directory are automatically converted to game ready formats by the engine.
File extensions for assets (textures, materials, models, maps) in game ready format are identified by the _c postfix. These game ready files cannot be edited in the tools, in order to do so you need access to the original content files. 

Updating content assets (material, models, particles & sounds) will automatically recompile them for the game side.

Getting assets in the game has been streamlined and is far less painful than Source 1.

Gone are the days of writing .vmt or .qc files!

Each asset type has its own editor now.

  • Material editor

  • Model editor

  • Particle editor


Note: When compiling .vmaps, the VMAP_C is automatically packed into a VPK

Note: Some of the files in the game directory only exist in the game directory, notably the external Vscript files.

Source 1

Source 1 Compiled

Source 2

Source 2 Compiled

Map

.vmf

.bsp

.vmap

.vmap_c

Textures 

.vtf

.vtf

.vtex

.vtex_c

Materials

.vmt

.vmt

.vmat

.vmat_c

Models

.qc

.vmdl

.vmdl_c

.mdl

.vmdl
.vmesh

.vmdl_c
.vmesh_c

Particles

.pcf

.vpcf

.vpcf_c

Sounds

.wav & .mp3

.vsnd

.vsnd_c

Basics of 3D Modelling

Since Source 2 is no longer using BSP, it’s important to familiarise yourself with the basics of 3D modelling. We no longer have to deal with the limits of Source 1 brushes, meshes can have faces removed, concave meshes are valid, non flat surfaces are valid and will be converted into triangles when compiled.

  • vertex, a simple point, the corner point of an edge.

  • edge, straight line connection between 2 vertices

  • face, a flat polygon surface bound by edge

  • mesh, a collection of faces

  • object, can be meshes or entities

  • group, can contain a collection of entities and meshes, can be moved, rotated and scaled like a mesh or object, but will instead affect every object within the group.

The importance of clean geometry (aka topology)

http://wiki.polycount.com/wiki/Topology

Topology is the layout of a model, how the vertices and edges are placed to create the mesh surface. Good topology is essential for fast frame rates (real time) and good deformation (sculpting displacements). For real time rendering, bad topology can cause rendering problems.

Mastering good mesh or edge flow takes time and practice, meshes should be optimized to create a good silhouette, define edge-loops for better deformation, minimize extreme changes between vertex normals for better shading and allow for good UV seams.

Use quads where possible (4 sided face), faces are automatically triangulated during the compile process, avoid manually triangulating faces unless it is required.
Ngons (polygons with 5 or more vertices) can be acceptable in areas that do not require any deformation and are flat.

Good topology will;

  • save you time

  • is easy to modify (selecting loops and rings)

  • cause modifiers work smoothly (inserting edge loops, bevels)

  • prevent weird artifacts (lighting and displacements)

  • make it easier to unwrap (UV mapping / texturing)

  • use less memory and result in better performance

While Source 2 supports Concave meshes, it’s still possible to create “invalid” geometry with bad faces. The face normal of a face cannot be twisted.

Note: To fix this; either move the offending vertex manually or go into face selection, select 1 face on the mesh and click on Remove Bad Faces in the Tool Properties, the later option will simply remove the bad face, you should preferably still fix the faces clipping through each other.

Hammer units

1 unit = 1 inch = 2.54cm

Measurements are incredibly important in VR, players are inherently familiar with how big objects should be due to their familiarity with real world objects. Any object that feels off in its scale potentially breaks immersion.

It's absolutely worth grabbing a measuring tape and converting real world measurements for proper scaling.

Metric

Imperial / Hammer units

Door height

201 cm

80 inch

Door width

76 – 81 – 91 cm

30 – 32 – 36 inch

Kitchen counter height

91 cm

36 inch

Dining table height

71 – 76 cm

28 – 30 inch

Desk height

73.5 cm

29 inch

Chair stool height

40 – 58 cm 

16 – 23 inch

Interior room wall height

240 – 275 cm

94 – 108 inch

Wall exterior thickness

20 cm

8 inch

Wall interior thickness

10 cm

4 inch

Info_player_start height 

182 cm

72 inch

Note: These measurements are real-life measurements, for the sake of convenience, smoother navigation and gameplay, some of these measurements will be rounded up, down or increased/decreased. Stick to the measurements defined by the metrics of the game you are designing for!


Launching Hammer

Create an addon

  1. Start Half-Life Alyx

  2. Select Launch workshop tools

  3. Click create New Addon, name your addon

  4. Select your freshly created addon 

  5. If you want to launch in VR, tick the “enable VR” checkbox, then click Launch tools

Note: if you leave the Enable VR checkbox unchecked the tools launch in non-VR mode, you will not be able to test your map in VR until you restart the tools in VR mode, you can however launch your map after compiling and playtest with limited functionality (cannot test VR specific interactions, invisible HL2 weapons with the impulse 101 cheat).
You can launch the tools without a HMD attached in non-VR mode.

Asset browser

After creating and launching your own addon, you will be greeted with the Asset Browser window and the SteamVR window that mirrors the game.

Click the Hammer Icon to start Hammer.

Hammer Interface Overview 

WORK IN PROGRESS VIDEOhttps://youtu.be/xRXxoFKHKoA

This is what you will be greeted with when opening Hammer for the first time and opening a new map. Each menu can be docked and undocked or rescaled to your liking. If you ever accidentally close a menu or would like to reset the editor layout, go to View > Toolbars > Default layout to reset the editor.

 

All actions you can perform on the selected object or entity are also available with right click. Note that these menus are responsive and only show the actions possible with the tool and active selection.


Hotkeys can be displayed with right click  > All commands (or press F1), hovering over a button will also display the hotkey.

If you run into performance issues in Hammer while working on a large and complex map, it is worth reducing the “maximum number of undo levels” in the Hammer tools/options menu.
Undo history caches your map in your system’s RAM with every action made in the map, if you do not have a high-end computer it is recommended to turn down the undo history count to something as low as 20 to prevent your computer from slowing down.

Prolonged editing of complex maps with a high undo history count can result in engine processes (most noticeably, the rendering resolution of textures in your map) to suffer greatly.

Viewport navigation

In previous iterations of Hammer, the active viewport was determined by your current cursor position. This has changed. The active viewport in Hammer is now shown by a red bounding box around the active viewport. To change the active viewport, you must hover over it with your cursor and press one of the mouse buttons. It's recommended to press-and-drag RMB or press MMB to change the active viewport since LMB can deselect or select different objects.

  • Shift + Z toggles the active viewport to full size

  • Shift + A centers the selected object in the active viewport

  • Ctrl + Shift + E centers all viewports on the selected object

3D viewport

The 3D viewport shows you a 3D view of your map, much of your work will be done in this viewport, you can switch the lighting used by clicking on the dropdown menu at the top right of the viewport or press F5 (fullbright) and F6 (all lighting)

  • Right click and hold , move the mouse to rotate the camera, press the WSAD keys to move around 

  • Toggle fly mode with the Z key while the 3D viewport is active

  • Ctrl + L locks the 3D viewport camera height, this allows you to traverse the map without having to readjust the height when moving around. You can manually adjust the camera height in increments with the mouse wheel up/down.

  • Hammer also includes 3D modelling program style navigation, pressing Shift +A centers the view on the current selection, holding the Alt key and dragging with the Left Mouse Button will orbit the view around that centre point, right dragging moves in and out, while centre-dragging strafes the view left and right, up and down.

2D viewport

The 2D viewport gives you a top, front, or side view of your map,this is useful when you want to see an object from a certain view or work on geometry constrained along certain axes.

  • Right click and drag within an active 2D viewport

  • Scroll to zoom in and out, the zoom is focussed on your cursor location.

  • Ctrl + Spacebar cycles through top, front and side views

  • Ctrl + A + Spacebar cycles through the top, front and side views while centering the view on your selection


Asset Browser

The Asset Browser can be shown in one of the Hammer viewports, it is similar in functionality to the Asset Browser Tool that launches when you start the tools, it contains tabs for each of the various types of pieces of content used to create a map: Materials, Decals, Models, Particles, Prefabs, Used in Map and Selection.

The Name Filter allows you to search for assets by name.

Tags, Mods and Asset Types allow you to filter and customize your displayed results.

Tip: Any of the viewports can be changed to the Asset pane by clicking the drop down button in the top right of any given viewport.

Viewport Asset Browser

Asset Browser (standalone)

Tags

Filter assets with tags.

Mods

Toggle visibility of mod content in the Asset Browser.

Asset Types

Allows you to quickly filter on certain asset types, clicking the “Only” button will only show the respective asset types.


Quick Rundown of the Tools

This section covers the available tools to perform tasks in Hammer. When a tool is active, the Tool Properties pane to the right shows the unique properties and commands.

Tip: hover over buttons to display the shortcut keys.

Selection Tool

Shift +S

Select geometry elements, objects and groups.

Translate / Move Tool

T

Move your selection along the XYZ axes.

Rotate Tool

R

Rotate your selection along the XYZ axes.

Scale Tool

E

Scale your selection, Source 2 also allows scaling models.

Pivot Tool

The Pivot Tool allows changing the selection’s pivot point.

Entity Tool

Shift + E

Place any type of point entity. (player spawns, AI spaws, logic entities, props)

Block Tool

Shift + B

Create basic geometric shapes, known as meshes.

(Quad, Block, Cylinder, Spike, Sphere)

Polygon Tool

Polygonal drawing.

Clipping Tool

Shift + X

Slice geometry, cuts must be made in the 2D viewport and confirmed with Enter.

Mirror Tool

Shift + F

Mirror the active selection along a drawn axis.

Texture Projection Tool

Used for basic UV mapping.

Paint Tool

Shift + V

Paint blend materials on meshes or displacements.

Displacement Tool

Shift + D

Sculpt geometry, commonly but not exclusively used for terrain sculpting.

Asset Spray Tool

Create a list of assets that you can paint with a brush over surfaces. Useful for vegetation and scattering detail assets.

Physics Simulation Tool

Shift + C

Used to simulate physics in Hammer on func_physbox mesh entities and models or entities that have a supporting physics mesh.

Note: Physics simulation also works on prop_static to settle them or to scatter detail in an environment.

Path Tool

Shift + P

Used to draw various paths.

Switch between the selection modes.

Point entities can only be selected with Meshes, Objects and Groups selection modes and the Navigation menu..

Meshes and mesh entities can be selected with every selection mode.

Mesh entity Object Properties can only be edited in Objects or Groups selection modes.

Control various editing settings, from left to right;

  • Use world space axes for gizmo

  • Use local space axes for gizmo

  • Pick workplane from objects and surfaces

  • Reset the workplane

  • Texture lock (locks texture to object when moving objects around)

  • Texture lock scale (clamps texture when scaling meshes or objects)

  • Texture lock component manipulations (clamps textures to when manipulating vertices, edges or faces )

  • Enable lasso select through

  • Enable lasso select partial intersection

  • Enable backface selection

  • Run map (opens the map compile window)

Toggle visibility in editor, from left to right;

  1. Show helpers

  2. Show editor only objects

  3. Show tool materials

  4. Force all lights on

  5. Vis preview

  6. Show collision models

  7. Toggle selection overlay (shows yellow highlight on selection)

  8. Gray out objects outside instances

  9. Toggle mesh subdivision (toggle displacement subdivision visibility)

  10. Toggle model animation (toggle animations playing in editor)

  11. Toggle mesh tiles in 3D views

  12. Toggle mesh tiles in 2D views

  13. Restart particles

  14. Toggle particles

  15. Toggle grass

  16. Cycle view distance

  17. Tonemap scale

Toggle overlay visibility and manage cordons, from left to right;

  1. Toggle ‘Nav Always Visible’

  2. Toggle ‘Nav Markup Visible’

  3. Toggle overlay shapes

  4. Toggle cordoning

  5. Set cordons visible

  6. Create new cordon

Tool Properties

Access all functions available with the active tool and selection, context sensitive.
Greyed out buttons do not function with your active selection.

Active Material

Displays the currently active material.

The browse button opens the material browser from where you can pick another material.

Auto Vis Groups

Control visibility of various entity types world geometry (meshes).

Automatically generated by Hammer.

Selection Sets

Manually create selection sets for easy selection and manage their visibility.

Similar to manually created visgroups in Source 1.

Becomes more useful in complex or large maps.

Outliner

Similar to Entity Report.

Map > Entity Report

Provides an overview of all objects in the map. Objects can be selected from within the Outliner.

Undo History

Travel back in time to undo your mistakes.

(I wish this existed in real life)

A handy visual overview when Ctrl + Z isn’t doing it for you.

Clicking an entry reverts the map to that state.

Object Properties

Contains everything that defines a particular entity, it also includes the Input and Output tabs of the logic system (see Basic Scripting).

Select object, press Alt + Enter to bring up the Object Properties in a new window.

Grid and Snap settings

  • Grid size

  • Enable snapping

  • Grid snapping

  • Vertex snapping

  • Rotation snapping

  • Angle for rotation snapping

Tool Menu 

At the top right you can start other tools.

Creating Geometry

Block tool

  1. Click the block tool. 

  2. Set the Geometry Type in the Tool Properties tab.

  3. In the 3D view, hold LMB and drag out a rectangle.

  4. Drag the red, green and blue controls to adjust its size.

  5. Press Enter when done.

  6. You can still adjust an object by selecting it and pressing Q and drag the handles to adjust the size.

    Note: The block tool can be used to create; quads (plane), blocks, cylinders, spikes and spheres.

Note: Invalid geometry is highlighted with red edges, usually caused by overlapping vertices, you can either fix this manually or select any face on a mesh and click on remove bad faces in the tool properties. Invalid geometry will not cause compiles to fail.

Polygon tool

  1. Click the polygon tool .

  2. Click in the viewport, everytime you click it will add a vertex.
    Double click to finish drawing the polygon.

    Note: A polygon with more than 4 vertices is called a ngon.These are bad when deforming the polygon (ex: displacement sculpting) and can cause render or smoothing issues, quads are preferred, you can manually fix this in vertex mode by connecting vertices to optimize the ngon. Polygons will be triangulated during the compile, if you are certain that your ngon will always be flat it is acceptable to have ngons.

Note: The polygon tool is also useful for creating .vsnap Particle Snapshot files within Hammer. There is an option to convert any mesh, including polygons created by the polygon tool into a .vsnap reference, or be used by particle in-Hammer as a reference (without creating a vsnap).

BUG: the Polygon Tool only works correctly in the 3D viewport, the 2D top viewport and on custom workplanes. Drawing a polygon in the 2D side or front viewport will result in wonkiness.

Selection tool 

  • Press 1-6 to switch selection modes.

  • Press Spacebar to cycle between vertex, edge and face selection or between mesh, object, groups, depending on your current selection. 

  • Pressing Shift + Spacebar switches between the two sets

  • Selected elements are highlighted in yellow.

  • Hold Shift and click to select multiple elements.

  • Hold Ctrl and click to remove elements from your selection.

  • Ctrl + I invert selection.

  • Ctrl + A selects everything.

  • Pressing + in vertex, edge or face mode grows your selection.

  • Pressing in vertex, edge or face mode shrinks your selection.

  • Hold LMB while in face, edge or vertex mode allows you to “paint over” to select multiple elements.

  • Holding Shift and switching selection mode will carry over your selection to the other selection mode.

    Example: select a face, hold Shift and switch to edge selection by pressing 2, this will result in having all the edges of the face selected.

  • Double clicking selects the entire element.

  • Double clicking a vertex selects all the vertices on the object

  • Double clicking an edge selects the entire edge loop

  • Double clicking a face selects all faces on the object

  • Selecting an edge, hold Shift, then double click on a second edge on the same edge loop will select the edges on the shortest distance between the 2 selected edges.

  • Selecting a face and selecting a second face on the same loop will select the faces on the shortest distance between the 2 selected faces.

  • Selecting a face and the face right next to it will select the faces in a loop.

  • Hold Alt and double left click to select all faces on a plane of an object, combine with Shift to select multiple planes.

Basic transformations

Translate T

Rotate R

Scale E

Above you can see a set of manipulator handles in the shape of a 3axis coordinate system icon used for manipulating objects in 3D, also known as a gizmo. Every transformation is done with the gizmo.

Space is defined in three axes-X, Y, and Z-representing width, height, and depth. The three axes form a numeric grid in which a particular point is defined by coordinates set forth as (#,#,#), corresponding to (X,Y,Z), respectively. At the zero point of these axes is the origin. This is at (0,0,0) and is the intersection of all three axes.

 

World Space Axis

The 3D space defined by these three axes is called the World axis, in which the XYZ axes are fixed references. The axis in World Space is always fixed.

Local Space Axis

Because objects can be oriented in all sorts of directions within the World axis, it's necessary for each object to have its own width, height, and depth axis independent of the World axis. This is called the Local axis. The Local axis is the XYZ-coordinate space that is attached to every object.. When that object rotates or moves, its Local axis rotates and moves with it. This is necessary to make transforming an object easier as it orients and moves around in the World axis.

Red Axis = X

+X = forward / East

-X = backwards / West

Green Axis = Y

+Y = left / North

-Y = right / South

Blue Axis = Z

+Z = up

-Z = down

Every object or group can also be precisely transformed with numerical values in the Object Properties.

Grid

  • Increase or decrease grid size with the [ ] keys.

  • The intersection of the green lines on the grid is 0 0 0 (absolute center).

  • The grid is highlighted every 1024 units with an orange line.

  • Holding Ctrl while moving objects temporarily disables grid snapping.

  • Holding Ctrl while rotating objects allows for smooth rotation instead of snapping.

Grid buttons, from left to right

  1. Grid size

  2. Enable snapping

  3. Grid snapping

  4. Vertex snapping

  5. Rotation snapping

  6. Angle for rotation snapping


Basic Mesh Editing

When using a tool on a mesh, Spacebar applies your action without exiting the tool, pressing Enter will apply and finish your action, then switches to the selection tool.

Vertices

  • Merge, select multiple vertices and press M to merge the vertices into one.

    Note: The last selected vertex will be the vertex all other selected vertices are merged towards.

Note: It is not possible to merge vertices from 2 different objects together, in order to successfully weld 2 vertices together, they need to share a face or edge.

  • Bevel, used to create rounded corners, select a vertex and press F, this applies a flat bevel to the vertex using the grid size setting.

  • Connect, select 2 vertices that do not share an edge and press V, this will connect these 2 vertices with an edge.

    Note: Does not work on open edges.

Edges

  • Dissolve, removes the edge and its corner vertices, 

select an edge and press Backspace.

  • Collapse, welds together the 2 corner vertices of the selected edge at the center of said edge.

  • Bevel, used to create rounded corners, select an edge and press F, this applies a flat bevel to the edge using the grid size setting.

BUG: The bevel tool can sometimes lead to unexpected results, such as vertices being shifted out of place and creating bad faces.

  • Extrude, select an edge, hold Shift and drag with LMB or press X.

  • Connect, select 2 edges and press V, this inserts an edge.

Tip: Quickly insert edge loops by selecting an edge, pressing G (ring) or L (loop), then press V to insert an edge loop.

  • Extend, select an open edge and press Shift while dragging with LMB or press N.

  • Merge, select 2 open edges and press M.

  • Split, splits edges into open edges.

  • Fill hole, press P when you have an open edge loop selected.

  • Bridge edges, select 2 open edges and press B.

    Note: If you click bridge in the Tool Properties you get extra options, such as; interpolations and twist, the green handles follow the normal direction, this can be used to create arches.

  • Hard Normals, creates a hard edge.

  • Soft Normals, creates a soft, smooth edge.

Note: Mesh objects have a smoothing angle (default 40°) so if your edge smoothing is working as you want, select the mesh in object selection and  increase or decrease this value.

  • Default Normals, resets the normals to their default.

  • Select Loop, select an edge and press L or double click on an edge to select a loop.

  • Select Ring, select and edge and press G.

  • Select Ribs, select and edge and press Ctrl + G.

  • Edge Cut Tool, press C to cut an edge.

Note: The edge being added turns orange when it's aligned with the grid. This is useful when working on irregularly-shaped objects or are fighting against perspective. 

Note: You can use RMB and other navigation shortcuts such as "WASD" to move the camera without stopping the cutting operation.

  • Edge Arc Tool, select and open edge and drag the green handles to create and arc.

Faces

  • Extrude, press T, select a face, hold Shift + drag.

  • Inset, select a face and press E to enter scale transformation, click and drag the handle to create an inset.

  • Flip face normal, select a face then press F, faces only have a single solid side, defined by the face normal, in order to quickly make a hollow room, select a face and press F, the entire object will have its normals flipped.

  • Delete face, select a face and press Delete.

  • Extract face, the face is no longer part of the same mesh or object.

  • Detach face, the face is detached from the mesh but still part of the mesh.

  • Thicken face, press G.

Note: This only works on faces with open edges, this creates a new block, facing away from the face normal, based on your current grid side setting.

  • Collapse face, press O, this merges all the corner vertices of the selected face into 1 vertex.

Meshes & Objects

  • Merge Meshes, select multiple meshes and press M to merge meshes together.

  • Separate Mesh Components, select a merged mesh and press Alt + N to separate the merged mesh back into the original meshes.

  • Merge Meshes by Edge, select multiple meshes, meshes with overlapping open edges will be merged together.

Note: It is not possible to separate a mesh that has been merged by edge with separate mesh components.

Groups

Groups generally behave the same as meshes and objects, but can contain any selection of meshes and entities.They are generally used for organizing your work and easily moving large selections.

Good practices

  • Do not leave open edges on your meshes, merge your open edges, open edges in a mesh double the amount of vertices.

  • While it’s technically possible to make an entire map out of a single mesh, this is not recommended because it will make selecting and editing the mesh a lot harder. Keeping meshes modular will benefit your workflow and efficiency.

  • Remove faces that are never seen by the player to optimize, unless they reflect a significant amount of light or require collision, in which case it is recommended to use tool textures such as nodraw or blocklight.

  • Remove vertices that do not define a corner.

  • Remove edges loops that are not needed to define a shape, select the edge loop by double clicking the edge and press Backspace.

  • Add edge loops quickly: select an edge, press G to select a ring, press V to insert an edge loop.

Note: SteamVR uses vertex lighting for ambient lighting, in this case it is beneficial to add more support edge loops to create uniform quads, this will vastly improve the lighting quality. This is however unlikely to be a requirement for Half-Life Alyx, since HLA will support lightmaps, similar to Source 1.

Advanced Mesh Editing

Pivot tool

  • Move the pivot to allow for easier manipulation of objects.
    The pivot can also be used in conjunction with extrude to create some very advanced geometry.

  • Clear pivot (Tool Properties) resets the pivot on your selection to the default position.

  • Freeze transform (Tool Properties) resets the scale, rotating, position and the pivot to 0 0 0 without moving the geometry in world space.

  • Set Origin to Pivot (Tool Properties) sets the origin of the selection to the pivot.

  • Center Origin (Tool Properties) snaps the pivot to the center of the object.

  • Next and Previous buttons (Tool Properties) cycle the pivot on all corner vertices and the center of the bounding box of your selection.

Clip tool

  • Shift + X clips the selection in 2, depending on the keep mode, clipping will either preserve both sides or delete 1 side.

  1. Select an object, mesh or group.

  2. Press Shift + X to activate the Clip Tool.

  3. Press and hold LMB to draw an axis in the 2D or 3D viewport. (Axis is always XY  in 3D viewport).

  4. Set the Keep Mode in the Tool Properties and press Spacebar to apply.

  • Cap new surfaces (Tool Properties) will fill the open edge loops after clipping.

Mirror tool

  • Press Shift + F, Click and drag in the 2D viewport to create an axis along which the active selection is mirrored. After mirroring press enter to confirm your action.

  1. Select an object, mesh or group.

  2. Press Shift + F to activate the Clip Tool.

  3. Press and hold LMB to draw an axis in the 2D or 3D viewport. (Axis is always XY  in 3D viewport).

  4. Set the Keep Mode in the Tool Properties and press Spacebar to apply.

Note: Mirroring does not auto merge edges, nor does it remove overlapping faces. You will need to manually select and merge open edges or delete overlapping faces after mirroring.

Note: Mirroring  does not work on models. Models must first be converted into an editable mesh through the right-click drop-down menu before they can be mirrored. After mirroring an editable mesh, you can then convert the mesh into a new model with the same right-click drop-down menu.

  • If the Mirror Tool does not provide you the desired result, you can use Flip.

Ctrl + Shift + J Tools > Flip Selection Horizontally

Ctrl + Shift + K Tools > Flip Selection Vertically

Note: Flip does not work on models, it will simply rotate them.

Note: Flipping does not happen relative to the pivot, geometry stays relative to the world space, the pivot is flipped relative to the world space.

Workplane (custom Hammer grid)

  • Shift + Q pick a workplane from objects and surfaces, the gizmo aligns to the face normal and takes the closest corner vertex of the selected face for its position.

LMB picks workplane from surface

Shift + LMB picks workplane from object

Shift + T translates the workplane

Shift + R rotates the workplane

  • Alt + Shift + Q Reset workplane to the default Hammer grid centered on 0 0 0.


Displacements

Displacement tool

Displacements are mesh based subdivided surfaces that can be freely deformed or sculpted in Hammer, they are generally but not exclusively used for building terrain.

  • They can be altered using the Displacement tool, Shift + D, to sculpt a wide variety of shapes, well beyond what can be created with meshes.

  • A blend material can be painted per-vertex to blend between two textures on a mesh or displacement.

  • Can be automatically populated with detail props.

Most of the limitations from Source 1 no longer apply, the biggest difference with Source 1 is that every face can be made into a displacement, this includes triangles and ngons, however these might result in undesirable deformations. Sculpting works best on meshes with uniformly sized quads. Faces that are not subdivided cannot be sculpted upon.

In Source 2, displacements can also be made into mesh entities, parented and moved.
Displacement meshes can be set up to act as a giant occluder, by checking the Use as occluder checkbox in the meshes Object Properties, geometry behind a displacement is not rendered.

Since leaks no longer occur, it is not required to seal maps with nodraw brushes under displacements.

Construction

In order to make a face sculptable you have to add subdivisions, select the faces you wish to subdivide and go to the Tool Properties.

Set the faces to the desired amount of subdivisions, by increasing / decreasing subdivisions or setting the subdivision level directly.

If you are working with huge faces and lack the resolution for reaching the desired sculpting quality, you can use Quad Slice to reduce the size of your faces to something more manageable. Alternatively you can bake down the subdivisions, however once a subdivision is baked down, it can no longer be sculpted upon.


After baking down subdivisions, you can add more subdivisions. It’s however not recommended to go too crazy with this, as a face (2 tris) with subdivision 2 becomes 16 polygons (32 tris), while a face with 4 subdivisions becomes 256 polygons (512 tris), polygon count will increase exponentially.

Once you add a subdivision to a face you can start sculpting the subdivided faces with the displacement tool. These behave similar to Source 1’s displacement tools with a few minor differences.

  • LMB Paint

  • MMouse Adjust radius

  • SHIFT Smooth modifier

  • CTRL + SHIFT Erase modifier

  • CTRL Reverse modifier

  • CTRL + RMB Pick normal
    CTRL + ALT + RMB Reset normal

  • SPACEBAR Drop tool

  • CTRL + ALT + LMB Recalculate erosion lines

  • I Update image projection

Press F8 to toggle the wireframe overlay, this visual helper will make it easier to avoid overstretching displacements while sculpting terrain.

F
G
H
Z
C
V
X
B

Push / Pull

Flatten

Move

Inflate

Clay

Pinch

Erase

Smooth

Erode

Image Projection

Noise

  • Radius, hold MMouse and move the 

mouse left to decrease and right increase the radius

  • Strength, hold MMouse and move the mouse up to increase and down to increase the strength

  • Offset

  • Smooth amount

  • Normal mode

(direction of the displacement sculpt)

Average / Screen / Mouse Down / X / Y / Z

Control the falloff curve for the displacement brush, use presets or define your own custom settings.

Sculpt displacements on all subdivided meshes or only on your active selected displacements.

Tips for working with displacements

  • Approximate the shape you want to create with meshes before you start sculpting, try to keep subdivided quads uniform in size, keep sculpting deformation simple without going to extremes. Stretched polygons do not look good when textured. 

  • Work in big strokes with low Strength, decrease the radius as you refine your displacements while you continue sculpting.

  • Start with low subdivision levels and increase the subdivision level if you lack the resolution to achieve the desired displacement smoothness.

If you need tighter smooth curves when smoothing displacements on corners, insert support edge loops to control the tightness of the curve. Support edge loops will retain the shape of the mesh better.

How to retain the edges of a displacement:

  1. Create a plane displacement.

  2. Extrude the edges.

  3. Set the subdivision from the extruded faces to 0.

  4. Sculpt the displacement.

  5. Remove the extruded faces.


Paint tool

The Paint tool allows blending of multiple textures in a single material to create smooth transitions between two or more textures. The equivalent of Source 1 displacement Alpha Paint Tool (WorldVertexTransition).

You can paint on any face with a blend material applied to it, even without subdivisions, but since the paint data is stored in the vertices you will need a sufficient amount of vertices to get enough control over where you want to paint, adding subdivisions to faces is the easiest way to achieve this. 

  1. Click browse in the Active Material window, in the tags filter for Blend Materials. Select a blend material to set it as the active material.

  1. Select the faces you wish to apply the blend material to, in the Tool Properties, click on Apply Current Material (Shift + T). 

  1. Once the blend material is applied, select the Paint tool (Shift + V).

  1. In the Tool Properties window set the Paint On setting and pick a channel.

  1. Hold LMB and drag over the faces with the blend material applied to it to paint.

  1. Switch to other channels and play around with the radius and strength until you achieve the desired look.

Paint on settings

  • You can paint on everything or limit to your active selection (objects, faces, edges, vertices)

  • Back-Facing Surfaces will allow you to paint on the blend materials on the backfaces, instead of only on the front faces.

  • Limit to Active Material will stop you from painting over multiple blend materials

Visualization settings

  • Show Verts highlights the vertices within Radius

  • Highlight Paintable Selection will highlight your selection based on your Paint On settings

  • Debug mode with show a greyscale vertex with the blend paint weight per vertex 

  • Black is fully painted

  • White is not painted

Painting

  • Flood fill fills your entire selection with the selected channel

Note: If "Everything" is enabled under the "Paint On" section,  you will flood-fill ALL displacements in your map with the currently selected layer. Be careful to not accidentally erase painting progress over multiple displacements with this tool property!

  • Radius is the size of the paint brush

  • Strength controls the opacity of the paint strokes

  • Channel allows you to pick an active channel, up to 4, to paint with

Active Material displaying the active blend material


Asset spray tool

The Asset Spray Tool allows any asset to be "painted" onto surfaces in the world, useful for spraying vegetation assets on terrain or quickly scattering detail assets.

Assets sprayed with the asset spray tool are prop_static.

The “Do not place on models” checkbox prevents sprayed assets being played on top of hand placed props, it does not account for sprayed models nor does it exclude props being placed in the locations of sprayed or hand placed props, this will result in overlapping props which might be undesirable.

  • ALT + LMB drag, erases sprayed assets.

  • ALT + LMB click, while the erase % is lower than 100%, allows to erase a defined %.

  • MMB drag, allows for rescaling the brush radius.

  • Ctrl + RMB on a slider will reset the value to 0.

  • Right click on any slider will allow you to manually input a value.

  • Right click on an element in the asset sprayer list to disable/enable or remove elements from the list.

Asset Sprayer settings

Reproject All aligns all sprayed assets with their pivot to the surface normal, one potential use-case is to re-align sprayed assets after adjusting meshes or displacements that you used the Asset Spray Tool on.

Select Sprayed Objects, select all sprayed objects, useful for deleting or changing prop type.

Load / Save Preset to use previously saved presets. Clear brush settings empties the element list and resets all settings to default (does not delete saved presets).

Spray elements

Drop and drag assets to add new elements to the spray preset.

Modify count multiplier, scale, pitch, yaw, roll and spacing multiplier per element.

Master up X Y Z defines the up direction of sprayed assets, this will re-orient the asset origin to align the local up axis, Z, to the master up direction.

Prefabs & Instances

Prefabs and instances allow you to easily create reusable pieces of content, they can be geometry, models and entities.

Prefabs

A prefab is a seperate .vmap that can be referenced into any other .vmap. All changes applied to the original prefab .vmap will be reflected in every reference. This makes it ideal for entity setups or asset collections that are frequently reused across multiple maps.

Note: Prefabs are similar to Instances in Source 1.

Creating prefabs

Method 1) 

  1. Right click on your selection you wish to make into a prefab 

  2. Click on Selected objects > New Prefab From Selection

  • (Maintain World Offset) creates a prefab using 0 0 0 as the origin

  • (Center On Origin) creates a prefab using the current pivot location

  1. Save your prefab under an appropriate name

Method 2)

  1. Create a new empty .vmap

  2. Create your prefab

  3. Save your .vmap under maps/prefabs

Note: I recommend using proper naming conventions, once you end up with hundreds of prefabs, you do not want to open every single prefab to remember which one contains what.

Editing prefabs

Double click the prefab in your 3D viewport to start editing it. Saving the map will save the changes to your prefab as well.

Collapsing prefabs

To collapse a prefab select it, right click to bring up the context menu Selected Prefabs > Collapse. When a prefab is collapsed all the objects are left in the world and can be edited on their own as if they were placed individually.

Instances

Instances are similar to prefabs but cannot be referenced in other maps, instances are local to the current .vmap. One of the benefits is improved rendering speeds, similar to models, where if the same model is repeated over and over again, it will be batched up into a single rendering pass.

Creating instances

  1. Select a number of object and/or meshes

  2. Right click on your selection > Selected Objects > Create Instance

Editing instances

Double click on an instance to edit it. Any changes will be reflected on all other instances inside the map.

Collapsing instances

Right click on an instance > Selected objects > Collapse Instances. Similar to collapsing a prefab.


Applying Materials

Texturing in Hammer is similar to Source 1, each face can have a unique texture assigned to it. Due to the changes in how geometry is created, there are more methods available to improve the texturing process.

Active Material

The first step of the texturing process is picking and applying a material to your selection.
In the Active Material window, click on Browse and pick a material to set it as the Active Material. Switch to face selection mode, select the faces and apply the material.

  • Shift + T apply Active Material to selection

  • Ctrl + M set material from selection to active material.

  • Shift + RMB trace and lift material from.

  • Ctrl + RMB paint material.

  • Alt + RMB wrap texture.

Texture Locks

Texture locks allow for manipulating meshes and objects while preserving texture alignment.

  • Texture lock: toggles texture locking to objects when moving (T) or rotating (R) them in meshes, objects or groups selection mode.

  • Texture lock scale: toggles texture locking when scaling (E) meshes in meshes, objects or groups selection mode.

  • Texture lock component manipulations: toggles texture locking when manipulating in any selection mode. Underlying UV information is locked, this allows for significant deformations. Be careful when deforming objects to avoid texture stretching.

Face edit tool properties

While in face selection mode, Tool Properties allows for precision manipulation of textures on selected faces.

Texture State

Scale / Shift / Rotate

The default texture scale is 0.25

Negative scale values flips the texture

Modify Texture

  • Align ( grid / face)

  • Scale

  • Shift, shifts the texture based on grid size

  • Rotate, rotates based on angle snap value

  • Fit, fits the texture to the face

  • Justify, align texture with edge of face

Treat as one, combine all selected faces and treat them as a single face.

Align to grid sets all values to default.

  • Apply Current Material

  • Find / Replace Materials

  • Fast Texture Tool

  • Apply Material By Hotspot 

(fits texture to active face selection)


Edge edit tool properties 

Weld UVs 

Ctrl + F

Note: Weld UV also works in vertex selection.

UV Peel

Useful for texturing curved surfaces such as arches and roads.

  1. Select an edge loop by double clicking an edge.

  2. Scroll down to UV Peel in the Tool Properties.

  3. Adjust the Primary U or V Axis.

  4. Check the World Space checkbox.

  5. Click UV Peel.

Optional:

  1. Uncheck the World Space checkbox.

  2. Manually input the UV Repeats and UV Offset.

  3. Click UV Peel.

Tip: Split the mesh into multiple parts (ex: floor, walls, ceiling) for additional control, later re-merge the meshes by edge again.

Tip: Texture distortion resulting from UV Peel can be reduced by adding subdivisions on faces.

Texture Projection Tool

The texture projection tool has two projection modes, plane and cylinder, useful to create seamless UV projections.

Example for seamless cylinder texture projection.

  1. Select the faces.

  2. Select the Texture Projection Tool.

  3. Set the projection to cylinder.

  4. Set the U and V Axis Repeats to achieve a consistent texture ratio.

  5. Click Finish to apply the UV projection.

Hotspot materials

Applying hotspot materials is a quick way to texture level geometry by aligning a sheet or rectangular panels to faces, they typically consist of different sized panels called subrects.
These can be created using the image subrect editor tool, subrect files can be shared on materials with similar layouts.

Hotspot materials can be found by filtering for the hotspot folder and/or by the “hs” in the material name, ex; materials/architecture/hotspot/concrete_hs01a_vanim.vmat.

Hotspots can be applied to world geometry by selecting faces you want to texture and pressing Alt + h, the hotspotting system will then apply the closest fitting panel to your selection, some subrects have multiple variations, pressing Alt + h will cycle through them.

Nodraw, applied to faces that require collision but do not need to be rendered, ex: faces that will never be seen by the player, such as; rooftops, areas outside the playable area. Does not block vis and does not cast shadow, if you want to block vis and cast shadows use light block solid instead.

Trigger, automatically applied to meshes when converted to a trigger entity.

Blocks bullets but not projectiles. To allow NPCs and their line of sight to pass through, turn the mesh into a non solid func_brush entity

Solid to players and NPCs.

Solid only to players.

Solid only to NPCs.

Blocks line of sight for NPCs.

Navigation attributes. Used on func_hlvr_nav_markup.

Navigation clip. Used on func_nav_blocker.

Used for blocking vis, often used on simple meshes overlapping with big props.

OBSOLETE, do not use it. Use the skybox tool material instead.

Used for func_occluder entities.

Casts artificial shadows, does not block vis.

Casts artificial shadows and is solid, does block vis.

Applied on meshes to define high quality lightmap areas.

Prevents the placement of VR teleport markers by the player.


Useful to stop the player from teleporting through small holes in walls or barred windows.

Placing Assets

Drag and drop assets from the asset browser, use the filters in the asset browser to filter on asset type (as explained earlier in Hammer Interface Overview / Asset browser)

When dragging assets into the 3D viewport they are aligned to the face normal when placing them onto meshes, if placed on an empty grid they maintain their default orientation.

Once placed, assets can be manipulated with the translate, scale and rotation tools.

It is still possible to use the old Source 1 method to place a prop_static entity and then browse for a world model in the object properties (Alt + Enter or double click the prop).

Props

Props aka models, highly detailed, repeatable geometry can be hand placed to spiffy up your maps. Assets dragged and dropped are prop_static by default, but the prop type can be swapped out in the object properties.

Note: One of the major differences with Source 1 is that models are scalable.

  • Clear rotation and scale, CTRL + Numpad 0.

  • Move object down by trace, CTRL + Numpad 1.

  • Move object down by local trace, CTRL + Numpad 2.

  • Alt + Up / Down / Left / Right, nudge rotate, based on rotation snap.

Prop_static

Prop_static is an internal point entity, which does not exist after compiling a map, it is used to cheaply add a model to the world, it can not move, animate or accept input. The majority of models in a map are prop_static. Prop_static will collide with other objects, given that it has a collision mesh.

  • Contributes to indirect lighting.

  • Cannot be parented.

  • Can have its default assigned material be overridden.

Prop_physics

Prop_physics is a point entity used to add rigid, physics simulated models to the world.

(prop_destinations_physics for SteamVR)

  • Does not contribute to indirect lighting.

  • Can be parented but will no longer behave correctly, use a phys_constraint entity instead.

Note: In order to optimize performance, physics entities can be settled with the physics simulation tool and set the start asleep spawnflag in the object properties.

Prop_dynamic

Prop_dynamic is a point entity used to add a model to the world that can animate itself.

  • Does not contribute to indirect lighting.

  • Can be parented to other entities.

  • Unlike prop_static, it cannot have its material overriden, however if the asset has multiple materials you can use the skin key-value property instead.

Note: Preview animations in Hammer with the toggle animation button in the View Settings menu..

Overlays

Overlays are a type of material that is projected onto a mesh or model. Used for adding 2D detail, such as; graffiti, posters, signs, dirt & blood, to surfaces, similar to decals.


Overlays in Source 2 support specular, normal mapping, texture animation, self-illumination and more.

  1. In the Active Material window, browse and set an overlay as the active material

  2. Switch to the Block tool, Shift + B

  3. Click and drag to create a block

  4. Press Enter to confirm

Overlays can also be dragged and dropped from the Asset Browser, once placed overlays can be moved, scaled and rotated.

Note: Materials need to have the overlay flag checked in the material browser to work as overlays, translucency is defined with a _trans material, a grayscale texture defining translucency, as opposed to embedding a grayscale texture in the alpha channel in Source 1.

Static overlay entity properties

Projection Distance

Z- axis distance over which the overlay is projected, this can result in the overlay being projected through walls, set the distance to an appropriate range.

Render Order

If multiple overlays are overlapping they will flicker and fight to be rendered on top (Z-fighting), set a render order value on each of the overlapping overlays to fix this. Higher values will be rendered later.

Color

Color value to create additional variation in the overlay appearance, white uses the default color of the overlay material. Useful in combination with grey scale overlays to create colored variants of signs, numbers, ect …


Projection Mode

Limit the projection to;

  • All (default)

  • Only world geometry

  • Only models

  • Target Objects (set automatically when picking a projection target)

Project on Backfacing

In some rare cases you will want overlays to project on the back faces of a model or mesh, enabling this checkbox will render the overlay on both sides of a face.

Projection Targets

Pick a mesh or model to limit the overlay to only project on the selected target.

Particles

Info_particle_system is a point entity that spawns a particle system built using the particle editor. Particles can either be dragged and dropped from the Asset Browser or by placing an info_particle_system entity and picking a particle system name.

Restart particles Ctrl + Shift + F11

Toggle particle visibility in Hammer.

Particle system name

The name of the particle system to spawn.

Start active

Whether the particle system should begin as soon as the entity spawns.

Particle snapshot file

Name of .VSNAP to be loaded and used by this particle system.

Particle snapshot mesh

Id of a mesh in the map to be used to generate a particle snapshot, if specified Particle Snapshot File is ignored. The vertices of the mesh will be used as the location coordinates of a particle system with the appropriate functions and operators which allow it to spawn multiple sprites based on a snapshot reference.

Control points 

If set, control point 0 of the effect will be at this entity's location. (Otherwise it is at the info_particle_system origin)

When a particle is set up to use local space, the particle will inherit the info_particle_system entities orientation.

Control Points (CPs) are the basic external input mechanism for a particle system, each system can have up to 64. Control points have a position, orientation, and an entity they can reference. By default control point 0 is the particle system's origin and orientation.

If a CP is associated with an entity it can be parented to the entity or an attachment point. In this same way, each additional control point in a system can be assigned a position in space, an orientation, and an entity. 

This can also allow a single system to emit across multiple point or model sources if necessary, to provide an effect such as a growing fire.

As the various elements of a particle system can access CP data, this can allow multiple dynamic elements to influence a system. While control points act as a position in space by default, other data can be stored in each point if needed, which allows external code or entities to pass generic data into a system that can then be remapped to properties of the system.

Control point parent

If set and nonzero, control point x of the effect will use this point for its parent.

Creation of custom particle systems will not be covered in this tutorial, for more information on creating your own particles, check out these links.
https://developer.valvesoftware.com/wiki/Particle_System_Overview

https://developer.valvesoftware.com/wiki/Category:Particle_System


Tile editor WIP

https://developer.valvesoftware.com/wiki/Dota_2_Workshop_Tools/Level_Design/Tile_Editor_Basics

https://developer.valvesoftware.com/wiki/Dota_2_Workshop_Tools/Level_Design/New_Tilesets


Entities

Entities provide all functionality and interactivity to maps. They can be divided into 2 main categories, point and mesh entities, both have a different set of properties and effects but work the same.

Point entities

Point entities are entities created at a single point position and have no physical size, they are used to position an effect or model, or to keep track of information.

Point entities are created with the entity tool, Shift + E

Logic entities are invisible entities that affect the game, creating or adding to various environmental and game controlling systems, such as AI managers, lighting, sound, math counters, choreography and scripted sequences.

Prop entities are objects that use a model for their appearance and functionality, they can be static, dynamic, physics or ragdoll.

NPC entities are computer controlled “Non-Player Characters” that are driven by AI coding and can interact with the player and environment, NPCs generally rely on a navigation mesh or node graph for their movement.

Point entity examples:

  • Logic_auto

  • Logic_case

  • Logic_relay

  • Math_counter

  • Point_sound_event

Mesh entities 

Mesh entities differ from point entities because they occupy a physical space or “trigger” zone that needs to be touched, hit or used to perform a function which is defined by the entity that is tied to the mesh, similar to Source 1 brush entities.


Mesh entities are created by tying an entity to a mesh in the map.

Ctrl + T,  or right click Tools > Tie to Entity.

Ctrl + Shift + W, or click the “Untie From Entity” button in the entity properties, this turns the entity meshes back into world meshes.

Note: To add additional meshes to a mesh entity select the mesh entity and the meshes you wish to add to the mesh entity, tie to entity will add the additional meshes into the mesh entity.

Often tool materials such as nodraw or trigger are applied to mesh entities to prevent them from being rendered ingame, however mesh entities can also be physical objects that can move. 

Mesh entity examples:

  • Func_button

  • Func_door

  • Func_physbox

  • Func_tracktrain

  • Trigger_multiple

Entity class

The entity class of selected entities can be changed in the object properties by clicking on the dropdown arrow and selecting another entity type or typing out the entity type.

Properties

Properties are the variables of an entity, they can contain any value or a set range of values. There is a property and key value. The key value stores the information about the property.

Alt + Enter, opens the object properties of your selection.

Note: Most entities and their properties have a short description of their intended purpose at the bottom of the Object Properties window.

Spawnflags

Flags are simple boolean conditions of an entity, often they change the fundamental behaviour of an entity. Flags themselves cannot be changed ingame, but sometimes the properties they affect can be.

Inputs and outputs

Information is passed between entities through inputs and outputs (I/O), they directly link to each other. When an output condition is met, it is triggered and that information is then passed into an input, which will then cause changes in the receiving entity.

Entity hierarchy (parenting)

When entities are parented together, they form a rigid hierarchy family which will move together as if all the entities were one physical object. Each child-entity will follow the parent’s movement.

A child-parent relationship is defined in the object properties of the child-entity.
All entities can have parents, but it may not function correctly for prop_physics, which should use a physics constraint system instead.

The Offset is the distance (and any rotational offset) between the Child and Parent entities at the time the relationship is activated. Whilst the offset is maintained, the Child will move parallel to its parent's movements, and "orbit" the parent's origin at the offset distance when the parent rotates. Only the SetParentAttachment input changes the offset; it instantly "teleports" the child to the parent's attachment point and holds it there instead.

Note: The Child's Solidity is suspended whilst it is parented. It will pass through walls and other solid objects.

Note: If the Parent is Killed, all of its current Children are also removed from the game.

Parenting through Object Properties

Parent

The name of this entity's parent in the movement hierarchy. Entities with parents move with their parent, set the child-entity's parentname keyvalue to the parent-entity name to create a child-parent relationship between two entities. The parent can also be a keyword, such as !activator.

Parent Model Bone / Attachment Name

The name of the bone or attachment to attach to on the entity's parent in the movement hierarchy. Use !bonemerge to use bone-merge style attachment.

When the attachment name is set, the child is parented and teleported to said attachment point’s position defined by the parent.

Model Attachment position offset

Offset in the local space of the parent model's attachment/bone to use in hierarchy. 

Not used if you are not using parent attachment.

Model Attachment angular offset

Angular offset in the local space of the parent model's attachment/bone to use in hierarchy. 

Not used if you are not using parent attachment.

Model Attachment scale

Scale in the local space of the parent model's attachment/bone to use in hierarchy. 

Not used if you are not using parent attachment.

Use Model Attachment Offset

Whether to respect the specified local offset when doing the initial hierarchical attachment to its parent.

Parenting through Input and Output

  • SetParent input can be used to set a parent of the child via I/O.

  • SetParentAttachment input requires having a parent set and a 0.01 delay.

  • SetParentAttachmentMaintainOffset input requires having a parent set and a 0.01 delay, maintains relative offset from the parent’s attachment point at the time it is attached.

  • ClearParent input clears the child-parent relationship from the child.

  • KillHierachy input removes the parent and all of its children in the world.


Basic Scripting

Input / Output

Entities communicate with each other through inputs and outputs (I/O).

Each entity has a set of outputs, defined by the level designer, which can be triggered when a condition is fulfilled, when triggered, information is passed as an input to the receiving entity, which will then result in a change in the receiving entity.

example

My Output

The condition which must be fulfilled in order to send the input to the target entity.

Trigger_multiple which will send an input when an entity starts touching the trigger.

Target Entity

The entity name or classname receiving the input.

Prop_dynamic.

Target Input

The input which will be sent to the target entity, these are context sensitive, based on the type of target entity.

Prop_dynamic will play an animation when receiving the input.

Parameter

Additional information passed with the input.

The name of the  animation to play.

Delay

How long to wait to send the input after triggering.

Wait 1 second before playing the animation.

Only Once

If yes, the output will only be fired once, if no, the output will be fired every time it is triggered

Only play the animation once.

The same output, but seen from the input window on the target entity.

Tips

  • Target Entity accepts both targetname (arm_01) and classname (prop_dynamic).

  • Wildcards (*) can be used to target multiple entities that only partially match the targetname. Example: setting arm* as the target entity will also include arm_01, arm_02, arm_cargo, ect … 

  • If a name is bold and orange, it points to multiple entities that share the same name and will all receive the same input.

  • If a name is red, the entity name does not exist.

  • Double clicking on an input will switch to the source entity output window and vice versa.

Debugging WIP

Source provides various debugging tools for when an I/O chain is not working as expected.

Foremost among them is the object properties dialog itself. Invalid inputs outputs are highlighted red in the entity's input or output list; the I/O icons at the bottom of the dialogue also change accordingly. Invalid outputs also show up in Check For Problems ). It's a good idea to check for problems before every compile.

Bug: Valid classname and wildcard values will be flagged as errors. Don't worry: the engine will recognise them!

Away from Hammer, there are a number of console commands and variables that will help you spot errors while your map is running:

Developer <0-2>

Developer mode reports all entity I/O to the console, and unless you're playing on a dedicated server that enables cheats (which is needed for all of the commands below). If you are in developer 2, you will also get the last eight lines of the console displayed at the top of your screen.

Ent_messages_draw <bool>

This displays the same information as developer mode, except that instead of appearing in the console it's drawn in the 3D world at the location of the entities in question.

Ent_fire <targetname or classname> <input> <parameter>

This extremely useful command allows you to manually fire inputs on any entity at any time. If you want to unlock a door ahead of time, you would type ent_fire my_door unlock, followed if you're feeling lazy by ent_fire my_door open.

Like the "output target" field in Hammer, ent_fire supports classnames and wildcards. If you want to ent_fire npc_* ignite, you can!

Note: ent_fire is where the special !picker targetname comes in. Use it to target whatever is under your crosshair.

Ent_pause

This command pauses all entities in the map except the player; submit it again to unpause. It is designed for use with ent_step.

Ent_step <number of steps>

When used with ent_pause, this command makes entities perform a specified number of I/O steps before pausing again (default is 1).

Vscript 

VScript is a virtual machine for scripting that acts as an abstract binding layer between the Source engine and external scripts.

https://developer.valvesoftware.com/wiki/VScript

https://developer.valvesoftware.com/wiki/Entity_Scripts

https://developer.valvesoftware.com/wiki/SteamVR/Environments/Scripting

AI WIP

NPC types

Only a handful of NPCs have fully functioning AI, meaning they can independently navigate, coordinate as a squad, target and shoot enemies. Some legacy Half-Life 2 npcs still work, but most are obsolete and are missing their assets.

  • Npc_antlion

  • Npc_barnacle

  • Npc_headcrab

  • Npc_headcrab

  • Npc_headcrab_armored

  • Npc_headcrab_black

  • Npc_headcrab_runner

  • Npc_manhack

  • Npc_zombie

  • Npc_zombie_blind

  • Npc_strider, can only move with scripted_sequences

  • Npc_combine_s 

Variants available by changing the model option

  • Npc_furniture
    An entity used for non-NPCs that need to synchronise their animation with an NPC in a scripted_sequence. Usually a pieceof furniture or door that an NPC needs to manipulate within a scripted_sequence.

  • Npc_enemyfinder

A special entity  that can oversee an area and share information (enemy positions) to AI with the same squad name.

All other NPCs encountered in Half-Life Alyx do not have any ai (metrocops, vortigaunts, scanners, dropships, Russell, Gman, Eli, ect …) and use a generic_actor entity.

Basic AI setups

Spawning AI

  • Point_template referencing the npc. Trigger with forcespawn to spawn the entities.

  • Npc_maker referencing an npc class.

  • Npc_template_maker referencing a template npc.

AI movement

  • Aiscripted_schedule

  • Ai_goal_assault

  • Scripted_sequence

Navigation WIP

CONSOLE COMMAND INFO DUMP
https://docs.google.com/spreadsheets/d/145zi3yDIHbbkBdFROzGN4U8SJKA8ieehvRUc1y0Rs9s/edit?usp=sharing

materials/tools/toolsnavattribute.vmat => func_nav_markup

materials/tools/toolsnavclip.vmat => func_nav_blocker

Walkable seed => func_hlvr_nav_markup?

AI navmesh

In order for AI to be able to navigate around your level, you will need to generate a navigation mesh.

Open the Navigation menu, click create a walkable seed and drag out a small volume in an area that should be walkable. The navmesh is generated on all connected walkable areas, if you want navmesh on multiple levels that are not connected to each other with a walkable area you will need to add a walkable seed in each of those areas in order to correctly generate the navigation mesh.

You can preview the navigation mesh in Hammer before doing your map compile by clicking on the Nav Preview button in the Navigation menu. Once you verified all the navmesh looks to be generating correctly you can compile your level.

Press F9 to bring up the map compile menu and check the “generate nav” checkbox, then start the map compile, once complete your AI should be able to navigate your level.

Debug navmesh

There are 3 different navmeshes for various agents

  • Agent 0 for NPCs with a small hull, height 24 (headcrabs)

  • Agent 1 for humanoids, height 79 (combines and zombies)

  • Agent 2 for antlions, height 69 (possibly antlions)

Cleanup of the nav mesh is done in Hammer via the debug draw / debug stages menu and then saved back to the nav file.

Nav debug, check both the build nav and save debug stages to file, compile the map.
Once the compile is completed open the navigations menu.

Load nav from VPK

Debug draw must be set to stages, then you can select the nav mesh to modify it.

Select a floor nav poly and click on recast

AI nodes

Still used for flying NPCs such as birds and manhacks.

  • info_node_air_hint

  • info_node_hint

Player WIP

Player navigation

Player teleportation

Limiting teleportation can be done with the teleport clip material (toolsteleportclip.vmat) applied to a mesh or plane. If you want to temporarily block teleportation you can use a trigger_traversal_no_teleport, this trigger will clip the teleport trace. You must texture this entity with the toolsteleportclip material to enable functionality. You can control this entity though I/O with enable, disable or toggle inputs.

Player ladders

Player elevators

Player interaction


Lighting

Lights can be both direct (real time / per-pixel) and/ or indirect (baked), the lighting system is broken down into multiple components. 

Direct light is usually fully dynamic, using per-pixel lighting based on distance and angle to each light source, but can also be baked. When named, direct lights can be modified at runtime to change the lighting.


Indirect light is the more subtle ambient lighting provided by the light bouncing around the scene, notice that corners and crevices are darker than the rest of the room. Indirect lighting requires calculation in a separate stage. Indirect light for dynamic objects (prop_dynamic, prop_physics, npcs) is calculated from light probe volumes. 


Environment Cubemaps are used for simulating reflections on objects, each cubemap consists of six textures mapped to a cube, hence the name cube-map. Cubemaps are automatically generated during the map compile from positions defined in the map.

As mentioned before, levels no longer need to be sealed and leaks no longer occur, therefore lighting is not affected by these issues that used to plague Source 1 mappers.

Lighting entities

  • Light_environment, a directional light imitating the sun, used for illuminating large outdoor areas (set range to 0), uses cascaded shadow maps to allow shadows to be cast over a wide area. Sets the color and angle of the light from the sun and sky.

  • Light_omni, point light which cast light out equally in all directions without casting shadows. 

  • Light_spot, point light which casts in a specific, spotlight-like direction and can cast shadows. Can use Light Cookies to customize the projected texture.

  • Light_ortho, a point light which cast an orthogonal projection, useful for volumetric light coming in through windows.

  • Env_cubemap, cubemap for sampling indirect specular reflection.

  • Env_cubemap_box, an env_cubemap with box projection.

  • Env_light_probe_volume, a grid of precomputed light probes (voxels), used for lighting dynamic (ex; prop_physics, prop_dynamic) that cannot use vertex baked lighting or lightmaps.

  • Env_combined_light_probe_volume, combination of an env_cubemap_box and an env_light_probe_volume.

Note: Faces in Source 2 have no backface, faces lit from behind do not block light. Translucent or alpha test double sided materials will cast shadows, but only for fully opaque parts.

  • Light brightness values in Source 1 ranged from 0-255, in Source 2 these values are remapped but not limited to 0-1.

  • Lights set to only cast baked direct and indirect light will show as a green light gizmo in the editor, these “static” lights cannot be modified at runtime.

  • It can be difficult to work on a map before the indirect lighting is baked, toggling the viewport between Fullbright (F5) and All Lighting (F6) can help working in dark areas.

Alternatively you can also turn on the worklight, by clicking on the viewport dropdown menu and enabling ‘show worklight’

  • Maps without any light will be rendered fullbright, maps taking place in darkness need at least 1 low brightness light.

  • Env_cubemaps or env_combined_light_probe_volume entities that show partially black on the sphere need their Bake Far Z distance increased.

Environmental lighting

Typical setup:

  1. Create an env_sky entity to use as your skybox.

  2. Create a light_environment entity and set Sky IBL Source to the name of the env_sky entity.

  3. Right-click on your light_environment entity and select 'Selected environment light -> Estimate lighting from HDR skybox'.

  4. Adjust the angle and brightness of the sunlight as you see fit.

Shadows

Cascaded shadow mapping casts an accurate real time shadow over the entire map, which works by rendering a highly detailed shadow map  which becomes lower resolution depending on the distance the player is from the surface.

Cascade 0 is closest to the player and requires a higher cascade resolution, each subsequent cascade uses a lower resolution and a larger distance.

Note: if the distance is bigger than the resolution you will end up with light / shadow stepping

Sky

IBL Image Based Lighting

Set the IBL Source to the entity name of the env_sky to use image based lighting.

Ambient occlusion


AO has no extra cost in terms of performance but slightly increases the light baking time.

Ambient light
Color tints the indirect lighting

Ambient occlusion

Ambient occlusion is a light type in computer graphics to simulate global illumination, AO is a simple simulation of the shadowing caused by objects blocking the ambient (indirect) light, because ambient light is environmental, it does not depend on light direction and thus can be pre-computed for static objects. When used correctly ambient occlusion adds an extra layer of realism to the visuals.

Notice that AO is not as present in direct light. AO looks best when used subtly.

Enable AO in the object properties of the light_environment entity.

  • Max Distance limits the distance of the rays being cast for AO computation, controls the “tightness” of the AO shadows.

  • Fully Occluded Fraction determines how much AO an object should generate on other objects.

  • Occlusion Exponent controls the fall-off or the contrast of the AO.


AO is computed during the light baking process and has no extra cost in terms of performance but slightly increases the light baking time. AO is baked on static models, static models affect the AO on Hammer meshes, models can in addition also use their own AO texture in their material. The AO generated during the light baking process is overlaid on the AO embedded in the model's materials.

Note: In order to quickly preview AO without having to rebake all the lighting you can click on the All Lighting downdown menu in a viewport and select RT Baked AO Lighting in the 3D viewport to quickly generate a preview.

Preview baked lighting (vrad2)

Preview baked lighting is used to preview indirect lighting in the editor without having to compile the map, depending on the complexity of the scene and the amount of lights, this can take some amount of time, but should still be faster than baking lightmaps during the map compile. It works by firing photons around which can bounce off surfaces into areas out of direct sight of a light source.

The baked lighting preview uses vertex lighting, so it will not accurately represent the lighting from baked lightmaps.

Do NOT ship levels with preview lighting, the performance cost is immense and will result in bad performance in VR, you ll want to ensure a steady 11ms or lower so players will not feel uncomfortable while playing your map in VR.

Note: The preview baked lighting  process is seperate from the map compile, if you compile the map without lightmaps, vertex lighting from the preview baked lighting will be used as a fallback.

Save the map, then Click Preview baked lighting / Bake All Lighting and wait for the light baking process to finish.

Everytime level geometry is altered or new geometry is added the photon map needs to be recompiled. When editing lighting only without changing world geometry you can re-use the existing photon map.

It is not always required to rebake all lighting for the preview, you can select the modified geometry or added meshes and Bake Lighting On Selection.


Setting up a light_importance_volume limits photons being cast for the baked lighting preview to the volume of the light_importance_volume instead of the map bounds, this can vastly reduce the time required to preview the baked lighting. Limit the volume to the area of the level that requires high quality indirect lighting, distant meshes can and should be excluded, meshes outside the volume will only have simplified indirect lighting computed.

Note: Importance volume entities cannot be rotated and multiple volumes are merged into one, making them less useful for maps that aren’t rectangularly shaped.

Lightmaps

A lightmap is a generated texture applied additively to faces to simulate lighting.

Lightmaps are compiled and automatically packed into an atlas texture, the resolution of this atlas texture is set in the map compile options (F9), before starting the map compile process. Higher lightmap resolutions result in better baked shadows, but since all lightmaps are combined into a single lightmap atlas texture, you are limited by the resolution of the lightmap atlas texture. Complex and larger maps will require a higher lightmap resolution, however the higher the resolution will increase compile times.

Both Hammer meshes and prop_static entities can have baked lightmaps, they both share the same lightmap atlas texture.

Every hammer mesh is set to the default lightmap resolution bias when created, bias can be increased or decreased per face with the slider in the tool properties, a higher bias will result in crisper, more accurate shadows, a lower bias will result in softer less accurate shadows.

With the default 0 scale bias, every face is weighted equally in the lightmap atlas texture, when the lightmap resolution scale or bias of a face is increased it does so at the cost of other faces because the lightmap is limited by its resolution, meaning that due to the scaled up face there is less space in the atlas for all the other faces, which will have their lightmap quality reduced.

Prop_static, lightmaps are baked by default, can be disabled in the object properties

Can set lightmap scale bias

Prop_physics, can not have lightmaps baked, uses light_probes
Lightmap Static: How this geometry influences baked lighting

  • No

  • Yes

  • Bounce only

Cannot set lightmap scale bias

Prop_dynamic, can not have lightmaps baked, uses light_probes

Lightmap Static: How this geometry influences baked lighting

  • No

  • Yes

  • Bounce only

Cannot set lightmap scale bias

Mesh entities (func_brush)

Setting up a mesh with the lightmap player area material is necessary to optimally generate lightmaps, the amount of light bounces outside this volume is limited, resulting in basic lighting. It is recommended to set up the volumes only around the areas the player will be able to explore up close and therefore requires high quality lightmaps. Using a single large volume is bad practice as it would give the same priority to every part.

Lighting compile (vrad3)

Prerequisites

The level needs to contain the following in order to compile the baked lighting:

  • Lights with indirect lighting set to baked for ambient lighting in areas that are not lit by direct per pixel lights.

  • Lights with direct lighting set to baked (optional).

  • Light probes for indirect lighting on dynamic entities.

  • Cubemaps for indirect specular reflection.

  • Mesh with materials/tools/toolslightmapres.vmat material

Env_light_probe_volume and env_cubemap_box entities can be functionally combined through the use of env_combined_light_probe_volume, there should be one per room, placed at eye height (64 units above the floor) and in the approximate center of the room. The blue box around the probe is the bounding box of the light probe volume, as well as the bounds for the cubemap projection box. These bounds need to enclose the room they are surrounding, so extend the bounds a little past the walls of the room. Cubemaps are computed at the end of the light baking process.

Meshes can only be affected by one cubemap at a time, it is recommended to split your geometry accordingly, building buildings out of a single mesh will require them to be split later on for correct cubemap reflections.

Once all these ingredients are present the map is ready for compiling the baked lighting.


Press F9 to bring up the Build Map menu.

By default lightmaps are not generated in Full and Fast compiles, but you can expose the settings and check the “generate lightmaps“ checkbox.

As a quick reference I recommend setting these values.

  • Fast Compile set the resolution to 512 and quality to fast

  • Full Compile set the resolution to 1024 and quality to standard

  • Final Compile set the resolution to 2048 and quality to final (or higher)

Higher resolutions will give better results but increase compile times, for quick testing purposes there is no point in having high resolution, high quality lightmaps, as this would put development to a crawl.

During development I recommend to keep the lightmap resolution as low as possible for testing, once your lightmap does not have enough resolution to pack all the faces the compiler will throw an error and fail to compile, in case this occurs, increase the lightmap resolution in your compile settings.

It is not recommended to use the fast Quality settings as it results in very bad lighting not representative of the end result.

  • Generate lightmaps, toggle lightmap generation, when disabled indirect and baked direct lighting for meshes and prop_static will not be baked during the map compile.

  • Resolution, size of the lightmap atlas texture.

  • Quality, amount of light bounces, more bounces results in better quality but increased compile times, recommended to keep on fast or standard, unless preparing a level for shipping.

  • Compression, enable / disable lightmap compression, reduces the file size.

  • Disable lighting calculations (debug texel density / chart allocation).

  • Deterministic Charting Computations (slow).

  • Noise removal, toggle lightmap denoiser, when disabled lightmaps are very noisy.

  • Write Debug Path Trace Info

Optimizing lighting

Light probe volume

Reducing the Voxel Size resolution on env_light_probe or env_combined_light_probe_volume  entities speeds up the generation but reduces indirect light quality for dynamic objects.

Per-pixel lighting

Per-pixel lighting is very costly, in Half-Life Alyx only one per-pixel light can be active at a time, the player flashlight counts as a per-pixel light, so make sure to disable the player flashlight when you need another per-pixel light to be active.

Bake as many lights as you can, if you need to use a per-pixel light you can in order to maintain good performance:

  1. Reduce the size of the shadow texture.

  2. Optimize the range and shadow start / end fade dis

  3. In extreme cases, reducing mesh complexity may be required.

Shadow texture resolution examples

The default value (0) equals 1024*1024 pixels, higher resolutions provide crisper shadows, but are more costly and limit the amount of shadow casting light_spots you can have inside the Potential Visible Set (PVS).

Max active per pixel shadow casting by shadow resolution, the higher the shadow texture resolution the less shadow casting lights you can have at a time (light_spot)

  • 8129 x 1 no overlap

  • 4096 x 1 no overlap

  • 2048 x 8 overlap

  • 1024 x 16 overlap (default)

Max active per pixel non shadow casting (light_omni & light_spot)

  • x 16

There is no limitation to baked lights.

Depending on the light angle and shadow resolution, lights can display a stepped effect, often when parallel with walls, either increase the shadow resolution or angle the light differently.


Baked lighting complexity

Each face can only be affected by 4 lights at once, to check the complexity of your baked lights, press F7 to show the tools visualisation mode, in the dropdown on the top right corner of the 3d viewport select tools visualisation mode / baked lighting complexity.

The colors show how many lights are overlapping, ideally as few lights overlap as needed.
White and cyan colors in the light complexity should be avoided as they will lead to strange artifacts in your baked lightmaps and affect performance.

Black

None, no direct lighting, only indirect

Red

1 direct light

Orange

2 overlapping direct lights

Yellow

3 overlapping direct lights

White

4 overlapping direct lights

Cyan

5 overlapping direct lights

A good example of light complexity

A bad example of light complexity


Here are some ways to reduce the light complexity:

  • Reduce the amount of lights

  • Keep more distance between lights

  • Reduce the range of lights

  • Reduce the angle of lights

  • Set Direct baked lighting to none, for lights used to boost indirect lighting or on lights used for volumetric fog

  • Uncheck Baked Light Indexing
    (Note that this will disabl