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,632
    Positive Ratings:
    1,723
    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.
     
    • Thanks Thanks x 23
    • Like Like x 1
    Last edited: Sep 23, 2018
  2. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,632
    Positive Ratings:
    1,723
    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,035
    Positive Ratings:
    3,992
    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:
    951
    Positive Ratings:
    937
    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,035
    Positive Ratings:
    3,992
    :hint:
     
  7. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,632
    Positive Ratings:
    1,723
  8. Hotel Detective

    Hotel Detective L4: Comfortable Member

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

    aa Narpas Failing at Scaling

    Messages:
    219
    Positive Ratings:
    203
    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
     
  10. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,632
    Positive Ratings:
    1,723
    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
     
    • Thanks Thanks x 3
    • Like Like x 1
    Last edited: Sep 23, 2018
  11. CaskoChan

    CaskoChan L1: Registered

    Messages:
    4
    Positive Ratings:
    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?
     
  12. DrSquishy

    DrSquishy L9: Fashionable Member

    Messages:
    668
    Positive Ratings:
    220
    You can just ignore that issue - it occurs with most skyboxes and is harmless
     
    • Thanks Thanks x 1
  13. Micnax

    aa Micnax I maek map

    Messages:
    2,062
    Positive Ratings:
    1,396
    So this would work rather well with Git?
     
  14. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,632
    Positive Ratings:
    1,723
    Very much so, git can even solve merge conflicts on vmf files since they are text based (for when you have 2 mappers editing the same vmf at the same time)
     
    • Thanks Thanks x 1
  15. CaskoChan

    CaskoChan L1: Registered

    Messages:
    4
    Positive Ratings:
    1
    My issue is that the skybox texture never changes to what i tell it to change too.
     
  16. fubarFX

    aa fubarFX The "raw" in "nodraw"

    Messages:
    1,632
    Positive Ratings:
    1,723
    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)
     
    • Thanks Thanks x 1
  17. CaskoChan

    CaskoChan L1: Registered

    Messages:
    4
    Positive Ratings:
    1
    • Like Like x 1