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.

Creating an Addon

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

Getting started

First make sure you have the Half-Life: Alyx Workshop Tools installed!

Once you've got the tools installed and are in the Workshop Tools launcher, create a new addon by selecting "Create New Addon," entering a name, and then clicking "Launch Tools."

Tip.png Tip: If you'll be testing your map without a VR headset, uncheck "Enable VR." This won't change how your final addon is played, it just disables SteamVR and lets you test your map using a debug-only version of WASD/mouselook controls on your monitor. You can check or uncheck this each time you launch the tools.

Create a map

You've made an empty addon, now it needs content!

Note.png Note: Addons can be more than just maps - in fact addons don't even need a map. They can be sounds, models, animations, textures, but a map is the simplest starting point so we'll use it for this example. See this page about the file structure of an addon for more, or look through documentation of the other Alyx Workshop tools.

Once the tools have loaded, open Hammer (the Half-Life: Alyx level editor) by clicking the hammer icon in the top left of the toolbar.

Creating an Addon-128485206-hammer.png

Instead of starting a new map from scratch, you can import a starter template. A basic starter map is included with the tools.

  • In the File menu, choose New Map From Template.
  • Browse to maps\templates\ and choose basic_setup.vmap
  • Your new map should open like this:


  • Save your map by pressing Ctrl-S or choosing Save from the File menu. For this example, save your map as "example.vmap."
Note.png Note: To really get into working with Hammer, try some of the SteamVR Home Hammer tutorials, and the Example Maps included with Half-Life: Alyx.

If you'd like to try building the map and walking around, now's the time!

  • Before you build, first you'll want to generate a preview light bake.
  • To do a preview bake, go to the Lighting menu and choose "Preview Baked Lighting." On a map this simple, this should only take a second.
Note.png Note: There is lots more information available about lighting and baking in Half-Life: Alyx.
  • To build and play your map, press F9 or choose Build Map from the File menu. It should already be set for Full Compile, which is what you want. Press the Build button and sit back while Hammer builds your map.
  • You'll know the build is done because the game engine window will come to the foreground, with your map loaded. If you're playing with VR enabled, put your headset on and walk around!

Add your map to your addon

Congratulations, you've made and built a map! Now it's time to formally add that map to your addon, so you can select the map from within Half-Life: Alyx's new game menu.

  • Close the tools, and re-launch them to return to the Tools Launcher.
  • Right-click your addon, or select it and press the gear icon, then choose "Edit Addon Info..."

Creating an Addon-128485204.png

In the window that pops up, click the + icon next to Maps, and add your test map by typing in its name. You don't need the file extension! These names are based on the file path starting at the maps directory, so since your test map is maps/example.vmap, you'd just type in "example." (If your map was located in maps/testmaps/example.vmap you would type in "testmaps/example")

Creating an Addon-128485205.png

In addition to editing addon info, the right-click menu contains some other useful options:

Edit Addon Info... 
Once you've created maps for your addon, this is where you'll list them.
Create Desktop Shortcut 
Places a shortcut on your desktop with the appropriate command switches to directly launch the tools with the appropriate addon. You can create separate shortcuts to launch your addon in tools with and without VR.
Show Launch Command Line 
Shows you the command line string to launch directly into this addon's tools with your current launch options.
Explore Content Folder & Explore Game Folder 
Opens a Windows Explorer window at the location of your addon's content directory (your source content, most of what you will be editing in tools), or game directory (your compiled content, and a few exceptions like LUA scripts and webm videos).
Set As Default 
Marks an addon as default when launching the Half-Life: Alyx Workshop Tools. Default is saved between sessions.
Creates an addon with the desired name and copies the files from your selected addon into a new directory.

Play your addon

Now that you've made a map and added it to your addon, you can play it locally in game:

  • Quit the tools and launch Half-Life Alyx normally from Steam.
  • Go to the Addons menu. You should see your addon there, in the list of local addons. Make sure your addon is enabled.
  • From the main menu, start a New Game.
  • Click through the tabbed menu at the top of the New Game menu to change from the main Alyx campaign to Addon maps.
  • Your addon should be there, ready to be played. Click it and start!


Upload your addon

Now that you've played your addon, if you think it's ready to be shared with the world, it's time to upload it in the Workshop.

Launch the Workshop Manager tool.

Creating an Addon-128485206.png

Select "New Submission."

Creating an Addon-128485207.png

Fill out the Publish dialog including a preview image, and hit submit.

Tip.png Tip: It's recommended to set your addon to Hidden or Friends-Only when you first upload, so you can test it with some privacy first. You can change this setting later.

Creating an Addon-128485208.png

Once your addon has been created and uploaded, the workshop web page for the addon will automatically open.

Update your addon

Launch the tools for your addon, as above. Go to the Workshop Manager tool, then right click the entry for your addon and select "Re-Upload."

Note.png Note: If you have multiple addons you should be sure to upload the active one!

Type a description of what's changed into the Change Log, make whatever other changes you see fit to the Title, Description, and Preview Image, and hit Submit.