mapping collaboration - or using manifest and version control

fubarFX

The "raw" in "nodraw"
aa
Jun 1, 2009
1,720
1,978
Mapping Collaboration
or using manifest and version control

People don't collaborate on maps, maybe it's because our methodologies don't really allow for it. What can we do to improve? more importantly, how can we make it easier to collaborate on a map project? It used to be that people would share a vmf file on dropbox to get things done. Such peasantry will not be tolerated going forward. The problem with dropbox is that things can get messy really rapidly, it's easy to overwrite and the history feature is not ideal when the time comes to identify what modifications have been made. Not to mention that you simply cannot have multiple people working on the same map at a given time. BUT WE WILL FIX ALL THAT. This article is an exercise in understanding how valve does things, evaluating how we have been doing as modders and bridging the gap.

The manifest!

There are inherent problems with having multiple people working on the same file. Having a big file that contains all of your work is not convenient. The manifest features fixes that. The manifest allows you to break your map into submaps. Under the hood, the manifest turns your map into a vmm. Vmm files are just a text file that references vmf files to include in a map. Isn't that a lot like instances then? well yes and no. instances are meant to be repeated multiple times while submaps are just chunks of your maps that will only appear once. In the end they are both independent vmfs, but the fundamental difference is that instances have their own origin while submaps all share the same origin (instance having their own origin is what breaks displacements, submaps are not affected by this problem). In case this is not entirely clear, you cannot reference a vmf twice as a submap because they will be superposed. A submap can only occupy one area as any copy of it will share its origin. In the end, the real difference between instances and submaps is that instances are meant for things that are repeated often, while submaps are more suited for one time world geometry. For those times suited for instances, you can always use instances inside your submaps, go wild!

tldr: Manifest files allow us to cut a map into smaller parts without the inconveniences of instances.

Why is this a good idea? well, handling one big file is never a good idea
- In the case of corruption, you're toasted. you may have lost all your work if you cannot debug your vmf.
- Having multiple people working on one file is always problematic, now you can have multiple people working on their part of the map without interfering with each other.
- Having small files makes it easier to track changes (more on that later).
- You have a map that is made of reusable parts! Say you are building a 5cp/koth, your maps (two different vmm) will now share common areas (vmf submaps) and changes made on shared parts will be automatically updated on both sides.


But how does it work?

First step is to turn your existing map into a manifest map.
Go to the top bar of hammer and hit instancing > Create Manifest...
You will be greated with the greenish goodness that is now your map. if you don't have the little manifest window, you want to activate it from View > Screen Elements > Manifest Bar

1-1.jpg


So, what happened? my map that was called "manifest.vmf" is now called "manifest.vmm" (manifest.vmf is still there tho, you can delete that).
Our map has exactly one part that we're going to call a submap, named unnamed. If you double click on it in the manifest window you will get to this screens.

1-2.jpg


From here you can conveniently rename that default name to something more interesting. I'll call mine "main". Now notice the path under there, hammer has created a folder for all submaps of my map. The vmf we previously had got copied there and it's now referenced as a submap.

Let's add more submaps shall we!
for that you want to right-click in the manifest menu and add an empty submap (alternatively you can add an already existing submap which is any vmf really).

1-3.jpg


You'll have to give it a friendly name and a filename. I'll name both "building" to make it less confusing. So now, you are in the new "building" submap, which should be highlighted in you manifest window. Now's the time to map away!

1-4.jpg


And here is my building, a fine piece of work I know. This building is pretty much perfect as far as I'm concerned so really, I'm done working on it. So now it's time to change between our submaps, if I want to go back and edit the "main" submap, all I have to do is double click on any geometry of that submap (alternatively, you can select the submap of your choice from the manifest window).

If you have worked with instances before, you probably noticed that switching from a vmf to an other has never been this easy. Also, since we are clearly defining to hammer what parts of the map we are working on, it makes selecting things from the 2d viewports a whole lot more viable and makes your work area a lot less cluttered. You can also click the little eye icon to toggle the visibility of each submaps which lessens the need for visgroups. Note that submaps do not share user visgroups. Each submaps has its own set of visgroups.

So the file structure of our map right now is something like this:
Code:
mapsrc\
    mapname.vmm
    mapname\
        \mapname.vmf
        \building.vmf

Nothing stops you from working on the vmf files individually but working on all of them from the vmm is damn fun.

Now how do we compile?
You can feed vbsp with vmm files just fine. Compiling a vmm is no different than compiling any other vmf.

So this is it, that's roughly all you need to know to get you started. Go out there and find all the great ways you can fit this in your workflow. Doing a 5cp + koth at the same time or sharing some vmfs and collaborating with other mappers over multiple files are some of the more exciting applications to me.
 
Last edited:

tyler

aa
Sep 11, 2013
5,102
4,621
This is something I've never understood, so thanks for writing it out! I knew you could use them for mirrored maps but the documentation was so dense I forgot about it entirely.
 

Tumby

aa
May 12, 2013
1,084
1,190
I tried using manifests like a year ago and I couldn't get instances to work. The compiler couldn't find them and reopening hammer caused all func_instances to appear "empty". Like, the filepath was there but I had to manually click Apply for stuff to actually show up again.
I think I also had other problems with instances, but I can't remember.
 

Narpas

Takes way to long to make and update maps
aa
Jun 11, 2015
433
436
I'll do it soon I swear
In Valve Time, I see

Honestly though, this is a pretty good tutorial about an overlooked feature, and I can't seem to find anywhere else talking about version control, so I'd love to see it finished
 

fubarFX

The "raw" in "nodraw"
aa
Jun 1, 2009
1,720
1,978
In Valve Time, I see

Honestly though, this is a pretty good tutorial about an overlooked feature, and I can't seem to find anywhere else talking about version control, so I'd love to see it finished
Holy crap, has it already been 3 years? Woooooops

Yeah, I was supposed to finish this as a parting gift from the tf2m community but realistically I don't really have the free time to do it atm. Plus it's a difficult subject to bring into this community because version control basically doesn't exist in the collective mind of tf2 mapping, so I'd basically start from scratch and that's a ton of work. But cool to see interest I guess, I'll consider coming back to this if and when I can.

Edit: Just reuploaded the pictures while I'm here
 
Last edited:

CaskoChan

L1: Registered
Sep 24, 2018
4
1
When i try to compile, the console says
material "skybox/rt" not found.
Can't load skybox file skybox/ to build the default cubemap!
Can't load skybox file skybox/ to build the default cubemap!

did anyone else have that issue?
 

DrSquishy

we've all had better times to die
aa
Feb 10, 2017
1,297
974
When i try to compile, the console says
material "skybox/rt" not found.
Can't load skybox file skybox/ to build the default cubemap!
Can't load skybox file skybox/ to build the default cubemap!

did anyone else have that issue?
You can just ignore that issue - it occurs with most skyboxes and is harmless
 

fubarFX

The "raw" in "nodraw"
aa
Jun 1, 2009
1,720
1,978
My issue is that the skybox texture never changes to what i tell it to change too.
Yeah, this tutorial is kind of a lie and you can't actually compile .vmm files. You see, if you do that, the resulting bsp will have an empty worldspawn entity resulting in a randomly chosen sky. My advice would be to have a side vmf that's that contains all submaps as instances and a properly defined worldspawn. You'd use that one to compile and use the .vmm to edit in hammer.

other options are:
- Adding VMMC to your compiling pipeline.
- Using a modified version of vbsp.exe. (some guy on github seems to have the source code for a bspzip.exe that would allow vmms to be compiled)