Introduction

This article is designed to explain some of the basic concepts behind the Half-Life: Alyx engine and development tools to get started. Users arriving from SteamVR Home's content creation tools will have a head start since the utilities are powered by the same framework which other games like Dota 2 provide. A quick summary of differences: lighting is vastly improved, there's ModelDoc which is a completely overhauled version of the Model Editor, the standard shaders are different and there are a lot more entities and content to play with. While it won't all be directly applicable the SteamVR Home Workshop Tools documentation on this Wiki may still have some useful information for people making Half-Life: Alyx addons to utilize.

Starting the Half-Life: Alyx Workshop tools

See Creating an Addon.

Addons, and the Content and Game Folders

An addon is a collection of files which get placed over the underlying game which is similar in concept to Source 1’s mods but allows addons to be swapped at runtime. Your files will be split into two types – source content (raw files) and compiled content (processed or compiled files).

Source content location:

• \Steam\steamapps\common\Half-Life Alyx\content\hlvr_addons\your_addon_name

Compiled content location:

• \Steam\steamapps\common\Half-Life Alyx\game\hlvr_addons\your_addon_name

The content folder will not be redistributed while data in the game folder will be packed up into archives called VPKs when you upload your addon to the Workshop.

Content Compilation

Source content is generally saved in formats that aren’t all well suited for redistribution or fast loading and rendering. For example a texture may be a Photoshop document with dozens of layers encompassing hundreds of megabytes which will then get compiled into the engine-specific format optimized for rendering as quickly as possible. It throws away all the data it doesn’t need (layers or markup data for example) and compresses it into the form requested by the rendering system’s shaders (small programs running on the graphics card, responsible for all the pixels seen on-screen) making it suitable for loading and displaying as quickly and efficiently as possible.

All the files in the content folders are the user-friendly formats that have either been placed there or created in the Half-Life: Alyx tools while files in game folders are generally produced from those in content and are all used by the engine directly.

Generally things will be recompiled automatically when the content on disk changes allowing users to save a file in Photoshop and have everything update in the Material Editor and Hammer for example. There’s also the ability to force a recompile in case a change was not picked up.

Basic Files - Textures, Materials, Models, and Maps

• Textures – An image of some bricks on a wall for example, or a normal map (a description of precise surface direction, for imitating extra detail), or one of numerous other possibilities. Textures are usually made in software like Adobe Photoshop, The GIMP or similar and are automatically recompiled whenever content updates. To be rendered in game however requires them to be referenced by a Material.

• Materials – A description of how all the textures work together. For the brick wall a material might point at a color map, a normal map, a roughness map and so on to define what the brick wall is supposed to look like in game. You may have an alternative version of the brick wall which has a different color map but the same normal and roughness maps. The material untangles all of these, and allows simple configuration of all the shader’s inputs.
  • Materials are set up in the Material Editor.

• Models – Produced in a 3D modelling program such as Maya, Modo, or Blender for example. These are 3D shapes made out of triangles. Examples would include furniture, trees, details on buildings, and characters or creatures. A good deal of what you’ll see in Half-Life: Alyx is based around these 3D models. The surfaces these models are made out of are assigned to particular materials which in turn point at the appropriate textures to use. While the underlying model files will usually be built using external software, their use in the engine will be set up in ModelDoc.
  • Automatically recompiled when you change source content – aspects of the resulting compiled model can be defined by the materials it uses. For instance, a model with a simple, unlit material can be automatically compiled to be without vertex normals to save space – but you’ll need to force a model recompile if you subsequently change the material to use proper lighting. Similarly, you change your material to start using secondary UVs for something, you may need to recompile the model for it to render properly.

• Maps – Think of this as a container for everything in the world you are creating. Maps contain data for lighting, where props are placed, sounds to play when and where, and even the basic scripting linking object behaviors together. Everything you see in Half-Life: Alyx is ultimately placed into a map – it’s the film set or theatrical stage in which everything happens.
  • The Half-Life: Alyx Workshop Tools include Hammer as the map editor.
  • Maps are not automatically recompiled and always require a compile to view changes in game. This includes such processes as calculating lighting and visibility for example.

Other files include sounds, particle systems and more – these all have source versions in the content folder for your addon, and get compiled into streamlined, efficient versions in the game folder for your addon.

Exceptions to the Rule

There are some file types such as various script files which get consumed by the engine directly. These text files get placed somewhere inside the game folder and are not compiled. These include things like Soundscape definitions, localization, etc.

Entities, Geometry, Entity Logic and More

An empty map in Hammer is the blank canvas for a VR experience in Half-Life: Alyx. This is where just about everything gets placed and until you add things to your map the world will be entirely empty.

• Entities – Each of these are effectively custom bits of code written to execute a specific set of instructions which allow users, when combined with other entities, to create the various experiences in the game. They will almost always have a visible (and/or audible) representation in the world and will react to things in specific ways. A physics prop is an example of an entity where the user can specify which model should be rendered as a physics prop, how it should react to the player throwing it, etc. Some of that data is contained in Hammer and can be edited while other data specific to the model is contained in the model files. Another example would be NPCs (Headcrabs, Combine Soldiers), light sources, or an invisible trigger volume which tells another entity to do something when a specific entity enters it.

• Geometry – map geometry built in Hammer is mostly used like fixed architecture upon which everything happens. You can also tie particular sections of map geometry to specific entities – this tells the entity (such as a sliding door, or a rotating platform) to use that map geometry as its visible representation. In the case of that invisible trigger volume, a block of map geometry will define the space it encloses.

• Entity Logic – This is the basic glue sticking the behaviors of entities in a map together. Made from Input and Output definitions on entities an entity might experience a particular thing happening (such as a player putting a hand into a specified volume) which causes it to fire an OnTrigger Output. This is connected to an Input on another entity which tells it to do something else such as turn on a light. There is an in-depth article on Inputs and Outputs to read through for more information. Note this is a Source 1 tutorial so links and specifics will often wander off into topics not applicable to Half-Life: Alyx but the core concepts are the same.

Lighting

The engine uses a simulation of how light appears in real life to render objects allowing surfaces to respond realistically to light sources. Objects can cast shadows on to themselves and other objects. Lighting is a a huge aspect of a map and properly lighting worlds is a bit of an art in itself. There's an overview of the lighting system you can read to get a better idea as to its capabilities and limitations.

Command Console

Referred to simply as "the console" it is a command line interface that relays logs and messages back to the user and also accepts many text-based commands for controlling features deep inside the engine. It takes the form of a separate program and with the tools running you can bring it up by pressing the tilde key (~) just below the escape key to the top left of your keyboard, or from the Tools menu in the top right corner of most tool windows.

Performance

VR is extremely taxing on system requirements and as such various trade offs must be made when building content inside of Half-Life: Alyx. One of the largest computational costs is rendering a scene, and in this case, two binocular views in high definition at 90 frames per second. Any time the framerate drops, much more so than with games on a flat monitor, missed frames in VR can be pretty obvious and unpleasant. This may cause shimmering at best or painful juddering at worst. The rendering system and shaders in Half-Life: Alyx are specifically engineered to be as efficient as possible but it’s still very possible to overload it.

The adaptive fidelity system used in Half-Life: Alyx will dynamically enable and disable render size and features to get the best possible quality from your hardware but to prevent excessive blurriness it won’t go below a certain level. When running in Tools mode this will be disabled. It will be only enabled in game mode. Proper performance testing of your addon should be done in the game mode (as opposed to running the game with tools loaded in the background).

Here are some potential high cost areas:

• Too much geometry The world can be too detailed and building too detailed of geometry in Hammer or placing too many static props can start causing the framerate to drop. Use the example maps provided as a gauge.

• Expensive lighting – Having too many indexed (baked, precomputed lighting) light sources can all add to the rendering cost. While the lighting system in Half-Life: Alyx is remarkably efficient, misunderstandings and over-expectations can cause significant issues. A general rule of thumb is to not have too many indexed lights shining on any one surface. The hard limit is four, though the game will run more efficiently if there's only one or two indexed lights hitting a surface. Dynamic lights should be used conservatively, and are usually reserved for highly specialized use cases, such as the flashlight.
  Tip:There are various visualization modes available in Hammer's 3D view - use the menu at the top right to set 'Tools Visualization Mode' to 'Baked Lighting Complexity'. Black corresponds to zero indexed lights on that surface, red one, orange two, yellow three, white four and cyan is four plus (this should always be avoided as it will cause lighting errors when baking the lighting). There's more information in the lighting overview.
  • If you can, find a user with an entry-level GPU (such as an Nvidia GeForce GTX 1060 or AMD Radeon RX 580 with 6GB VRAM) to test things with as a good baseline to evaluate your map.

For an up-to-date view of current rendering cost, bring up the frame timing window in SteamVR : Settings : Performance : Display Frame Timing. At a very simplistic level, the GPU graph at bottom should stay below 11ms for a 90Hz display, without any non-zero red line popping up at the bottom – if running in game mode, the adaptive fidelity should try to maximize GPU usage, but it should rarely if ever go above 11ms.

Tip:Most performance discussions will revolve around milliseconds as opposed to frames per second. It takes marginally over 11ms a frame to maintain 90fps, so 'saving 2ms' is much more meaningful to say than 'saving five frames per second', as the latter gives no indication of the absolute rendering cost saved. Did you start at 10 or 1000 FPS?

If your CPU graph is frequently leaping above 11ms, then there are possibly some other performance costs going on. Here are some potential CPU costs:

• Too many entities – It’s much more likely to be some aspect of the specific entities you have in the map, rather than an overall count of all entities. If you have many more than usual of a certain thing, it may be worth investigating further. For example, a simple box map with a hundred Combine Soldiers may be challenging to render, but it's even more challenging to have all those AI calculate paths, targets, cover locations, and collision with the world.

• Complex rendering – Counter-intuitively, you can have a high rendering cost even if the GPU isn’t maxed out thanks to draw calls. If you have many separate models and/or materials, the CPU has to tell the GPU to render each one, which incurs a cost that goes up the more things you have.

• Complex physics – Having too many physically simulated objects in the scene at the same time can be a significant computational cost – and in particular, having one complex collision hull collide with another can be very expensive, causing severe frame drops. While the example maps may have hundreds of physics objects, not all of them are active at the same time. Keep this in mind when building your addons.

Example Maps

Some example maps are provided in \Steam\steamapps\common\Half-Life Alyx\content\hlvr\maps.

• workshop_examples contains some annotated examples of various Half-Life: Alyx features.
• release contains full sources for all the maps shipped in the final game.

You're not expected to recompile the release maps. The full lighting and audio calculations would likely take an excessive amount of time on a home PC - but you'll be able to add content at an entity level using the new Map Extensions feature.

Documentation

Finally, welcome to the Valve Developer Community wiki! This documentation is a never-ending work in progress and is built in part by people like you - each page has a discussion section, and each page can be edited and extended as you see fit. If you have any questions, please do post them - and if you have any answers, post those too!