mapping collaboration - or using manifest and version control

Discussion in 'Tutorials & Resources' started by fubarFX, Jul 2, 2015.

  1. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,619
    Positive Ratings:
    1,709
    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

    [​IMG]

    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.

    [​IMG]

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

    [​IMG]

    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!

    [​IMG]

    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.
     
    • Thanks Thanks x 22
    Last edited: Oct 21, 2015
  2. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,619
    Positive Ratings:
    1,709
    Reserving this post for an article on version control that should be coming shortly
     
  3. nightwatch

    aa nightwatch

    Messages:
    640
    Positive Ratings:
    446
    nice
     
    • Agree Agree x 1
  4. tyler

    aa tyler snail prince, master of a ruined tower

    Messages:
    5,033
    Positive Ratings:
    3,980
    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.
     
    • Thanks Thanks x 1
  5. Tumbolisu

    aa Tumbolisu  I ⌄ I 

    Messages:
    944
    Positive Ratings:
    922
    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.
     
  6. tyler

    aa tyler snail prince, master of a ruined tower

    Messages:
    5,033
    Positive Ratings:
    3,980
    :hint:
     
  7. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,619
    Positive Ratings:
    1,709
  8. Hotel Detective

    Hotel Detective L4: Comfortable Member

    Messages:
    187
    Positive Ratings:
    189
    that's my :trigger:
     
    • Funny Funny x 1