This article relates to the game "Half-Life: Alyx". Click here for more information.
This article relates to the workshop tools for "Half-Life: Alyx". Click here for more information.
This article's documentation is for Source 2. Click here for more information.


From Valve Developer Community
Jump to: navigation, search
English Русский 简体中文 

本文旨在解释《Half-Life: Alyx》游戏引擎和开发工具背后的一些基本概念。使用过《SteamVR Home》创意工坊工具的用户会有一定优势,因为这些工具采用的框架与《Dota 2》等其他游戏所提供的框架相同。不同的是:光照系统得到了极大的改善,其中ModelDoc是模型编辑器的全面改进版,标准着色器有所不同,并且还有更多的实体和内容可供使用。尽管并非全部都能直接适用,但本Wiki上的SteamVR Home创意工坊工具文档仍然可以为制作《Half-Life: Alyx》插件的人们提供一些有用的信息。且已经被汉化的文章相对Half-Life: Alyx要更多。



插件, 以及content和game文件夹

插件是一组文件,这些文件依靠于基础游戏上,其概念与Source 1的mod相似,但允许在运行时更改插件。 您的文件将分为两种类型-源文件(原始文件)和成品文件(处理或编译后的文件)。


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


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




content文件夹中的所有文件都是对用户友好的格式,有的是被用户放在这里,有的则是在《Half-Life: Alyx》工具中创建,而game文件夹中的文件通常由content文件夹中的文件产生,并且都能被引擎直接使用。


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.
  • 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.
  • Geometrymap 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.




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.


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.png 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.png 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.


一些样例地图被放在了 \Steam\steamapps\common\Half-Life Alyx\content\hlvr\maps

  • workshop_examples 放有一些带有注释的《Half-Life: Alyx》功能演示地图。
  • release 放有最终游戏成品的全部地图源文件。

您不应该去自己重新编译游戏成品的地图。完整的音频和光照计算对于一般家用个人电脑来说会消耗大量的时间 - 但你可以通过地图扩展功能来对现有地图增加实体类内容。


最后,欢迎来到Valve Developer Community Wiki!本文档一直都在编写中,并且是由像你一样的的人所建立 - 每个页面都有一个讨论区,而且如果你认为有需求,每个页面都可被编辑和扩写。如果你有任何疑问,请将其发在讨论区 - 如果你有答案,也请发出来!