This guide will attempt to assist a mapper in posting a Black Mesa map to the Workshop so that players can merely subscribe to it and have it appear in their workshop tab. No need to know the map name or use a console map "name" cheat to get it started.

Example of a subscribed map correctly listed in the BM Steam Workshop:


As of December 2020 I don't know if this is the official way of doing this or if this is the approved way of doing this. I merely worked out how to do it by looking at .vpk files for maps that I subscribed to that got added to my "steam workshop" tab in Black Mesa correctly.

This is, of course, subject to change and in the future there may be tools provided to do this automatically.

If anyone has already posted this and knows better than let me know and I can update or remove this guide. Thanks.

Basically the blackmesa_publish.exe (located in the Black Mesabin folder) works..., if you do a few things.

Make the Image 512x512 pixels and provide a folder to a valid .vpk file that contains a map in .bsp format.

However, what is inside that .vpk file makes a big difference to the BM Steam Workshop User Interface (herein referred to as the BMSWUI).

So how are you supposed to get this to work? I'm not totally sure but this seems to work so far.

Let's say you used Hammer to make a map and compiled it on advanced settings for both ldp and hdp and you know have a .bsp map file you want to upload. Cool. But just putting a map in a .vpk won't work for Black Mesa. Or should I say, it WILL work, but it won't go into the Workshop tab of Black Mesa. You, and all subscribers, will have to start it from the console with map "mapname"

If, however, you add a bit more to the .vpk file you get more. Here is the folder structure and files you need to create. Here I will use the name of one of my BM Maps; SectorQ.

Create a folder named SectorQ and then create the following sub folders under it:

"campaigns"
"maps"
"materials"
"ui"

[Without the quotes of course]


As far as I know the structure is pretty flexible to, if you wanted to create the "ui" folder under "campaigns" that would work as long as you reference the ui folder correctly later.

For the map though, "maps" should be as is and under it "graphs" (more on that later).

Inside the campaign folder create a text file using any text editor with a .json file extension. Here I will create sectorQJ5.json. I am not sure the name of the file means anything. It could be the same as the maps .bsp file or not it seems. Someone please correct me if I am wrong here.

Let's look at the structure of the JSON file now:


If you are not familiar with JSON please Google it. I am a programmer and know it.

It is basically a way of formatting data so computers can read it. It's also fairly human-friendly as I'm sure you can almost tell what everything does here just by reading it.

"author": This can be anything (maybe even blank, not sure, I'd put your steam username by default)

"url": This can be anything, I think in future it might do something but doesn't do anything now. I put the url to my profile.

"title": Required, as far as I can tell, (at this stage) and why shouldn't it be? Give your map a title!

"description": Optional AFAIK. I'd use it though.

"imageSource": This references an image you are going to place in the "ui" folder. This will be the maps TitleCard/Icon in the BMSWUI. I haven't noticed any size restrictions here, but I'd say keep it landscape and large but not huge. PNG is def supported, I've not tried a JPG, but it might also work.

"chapters": This is in [], or what programmers call and array. A list of items. Here only one item is in the list, and you need at least one. So copy and paste from here into yours and make changes where appropriate.

The "levelname": is the key here. Its the .bsp files name without the .bsp extension.

For the "maps" folder, add your .bsp file to it. Create a "graphs" folder under "maps", for your .ain file.

---

Where do I get the .ain file you ask? What is it?

Ever notice a map starts by saying Node Graph Out of Date Rebuilding? That's because no .ain file was supplied so the engine made one on the fly when it started the map. That is also how you get one to package up. Run your map from Hammer and then, quit and look in the \Black Mesa\bms\maps\graphs folder for the corresponding .ain file. It will be the maps name .ain file. So a SectorQ.bsp has a SectorQ.ain in \Black Mesa\bms\maps\graphs.

Copy and paste this into the "\maps\graphs" folder of the file structure we are building.

---

The only thing left is to add the image into the "ui" folder. Remember in the JSON file the line:

"imageSource": "image://game/ui/bm_sectorq.png",

You must provide the bm_sectorq.png in the ui folder. If your ui folder was under the campaigns folder then in the sectorQJ5.JSON the image source would refer to it there instead. As in:

"imageSource": "image://game/campaigns/ui/bm_sectorq.png",

Optionally the "materials" folder would contain your VTFs in sub folders where appropriate. I am not able to get this to work, but other mappers seem to make it work. Maybe someone can explain to me what I do wrong with that one.

I am pretty sure you could also include folders for "scripts" and other map related items.

Once you have all that drag and drop the SectorQ folder onto vpk.exe in \Black Mesa\bin and then upload that .vpk file using the blackmesa_publish.exe with a 512x512 image.

Go to your workshop and subscribe and start BM and your item should now appear in the workshop which is listing maps alphabetically, so scroll over until you see your map, by name.

Here is a screenshot in-game after subscribing to Sector Q

Here I will provide a copy of the JSON shown for copy and paste.

{
"author": "Shinval",
"url": "https://sp.zhabite.com/id/Shinval/",
"title": "Sector Q",
"description": "A Black Mesa singleplayer map.",
"imageSource": "image://game/ui/bm_sectorq.png",
"chapters": [
{
"title": "Sector Q",
"description": "",
"imageSource": "image://game/ui/bm_sectorq.png",
"levelName": "bm_sectorqjl5"
}
]
}

Note: Real JSON use tabs which Steam has filtered out. Add them back in so the file resembled the screenshot above - if you want, as long as the structure is correct the computer will not care if tabs exist or not.

If you subscribe to your own map, and then go into hammer and try to edit it and run it, BM will lock up and not work. The mapname must differ from all subscribed maps. So sure, test it on the workshop, but then MAKE SURE THAT YOU UNSUBSCRIBE from it -- if you are still editing it in Hammer.

If its done and dusted, you're all set.

I continue to subscribe to my own maps as a test and then wonder why Black Mesa locks up when loading my map, because I am an Idiot. Don't be an Idiot.

I wrote this very quickly. I hope it helps someone. Positive feedback is always appreciated and let me know if anything is wrong, or outdated and I will either update or remove this guide.

I also think that this JSON file and structure will someday be created by the publish tool itself and this guide will no longer be necessary.