Jump to content
The Dark Mod Forums

Mapping and Version Control


Recommended Posts

Of course I'll defer to what the experienced mappers want, but in terms of specific integration features, my suggestions would be similar to what a modern IDE would show, e.g.:

  • An indication of the latest checked-out revision, its commit date and author (possibly in the status bar).
  • A log view that allows you to view the latest changes, and quickly revert to an earlier version.
  • In editor display of your local changes with respect to the last commit, as well as being able to view changes between revisions in the log view.

Obviously it's the last one which is the most difficult, because unlike with IDEs, a simple context text diff of a map file would be useless to mappers. For the diff to be in any way useful it would need to be parsed and displayed graphically, e.g.

  • If the change is to an entity spawnarg, show the entity name and the new/old spawnarg values in the diff view.
  • If the change moves an entity, show the old and new positions in the 2D/3D views (e.g. old position in red, new position in green, maybe an arrow pointing from start to finish).
  • If the change adjusts brush geometry, show the old and new brush sizes/positions with a similar mechanism (red lines for deleted geometry, green lines for added geometry).

But I'm aware that this would require a huge amount of diff parsing and intelligence in the algorithm — perhaps it might even be completely impractical to interpret the Git map diffs to this extent.

Link to comment
Share on other sites

52 minutes ago, greebo said:

Nothing happens immediately when you change the .map file on disk, DR will not care and continue working with what you have loaded into memory. In one of the recent versions, I forget which one, a safeguard has been introduced: once you hit "Save" DarkRadiant will warn you if the file has been changed in the meantime, possibly by some other process like git or a text editor. You can choose to overwrite or cancel (and save it somewhere else if you need to).

When I decide to update the working copy using Git on my end, for instance pulling a change from her laptop to mine, the map file will obviously be changed (which I expect to happen, no problems there). Still, I often had the thought that it'd be nice to have a small status indicator in the toolbar, such that I can see that the .map file has been altered by something other than the current DarkRadiant session. (An option to have those changes automatically integrate the changes from that file to my loaded version is a concept I'm currently trying to prove to be working.)

Okay, so at this point in time I guess the only option now is to reopen the map file?  

Having DR offer something like "The map file on disk has changed, do you want to load that instead?  You will lose all current changes" would be good.  The bit about losing your current changes wouldn't be an issue (but the warning would be necessary) because I would have committed/pushed/merged that previous work anyways.


Link to comment
Share on other sites

1 hour ago, stgatilov said:

Hmm... I don't think it is best practice of Git to be honest. Maybe best practice of GitHub.
I see two reasons for protecting main branch:

  1. External contributions from people who has no access and whom nobody even knows.
  2. Enforcing code review on all changes.

Frankly speaking, I think none of these points apply to our context.
External contributions are maybe possible after the map is released, but not while it is in development. Code review only makes sense for scripts and decls, but I think nobody will bother about it.


OK last comment about Git usage on this thread (we can open a new one for other feedback if anyone tries the tutorial).

A 3rd reason to protect the branch is against accidental pushes.  Very easy to do if you are not paying attention to your current branch.

I wanted to enforce code review in my use case - does that make me a 'nobody'?  I'm pretty sure you don't mean any offence (and none taken), but the way it's phrased makes it sound like you are speaking for everyone.  Are you just talking about your own particular use case?

Link to comment
Share on other sites

I'm on the phone, so I'll try to be brief, but in general I think it's an overkill, for multiple reasons.

First off, I use git at work, and I had difficulties with understanding it back when I started. I do git KTs for junior colleagues nowadays, and they do find it difficult to grasp the concept; usually they need a week or two to get the hang of it. Remember we're talking about technically proficient folks, now imagine how much harder this would be for everyone else.

I did take a look at the tutorial, and it's way too long, you might as well replace some of its sections with knowledge base links from git and atlassian websites, as they're shorter and they portion the knowledge better.

Last but not least, I had a chat with my senior devs at work on that, and they all agreed that there's no point in having a git repo for assets, more like Google drive directory, or that server setup Unreal engine uses for realtime collaboration.

I get that you like git very much, but it really is a tool for very specific tasks, especially considering the big picture. Since you already have trouble in explaining the concept in the simple terms, no wonder you get crickets or pushback as a response.

Edited by peter_spy
Link to comment
Share on other sites

For someone like myself who's creating assets, readables, voiceovers etc. in collaboration with a mapper working on the map file, I personally really enjoyed the convenience of GitHub. As someone who's never used Git for project management before, I got the hang of the basics pretty quickly. Essentially what is advantageous for me is that I can work on my own branch, adding new textures or models or xdata for the readables etc. without interfering in the mapper's work. I just update my branch with his progress as time goes on, and he then merges my branch into his main repository whenever I make progress on my side.

The process has been pretty seamless for us. I enjoy that I can just merge my branch with the main repository and then immediately run TDM (and DMAP) to then see all my additions in place in the latest update of the work-in-progress FM. Saves us having to transfer files to one another just to test our work, and also keeps the whole thing safe in an online repository if one us makes a mess of things on our local computers. 

Link to comment
Share on other sites

IMO it's not really convenient, because for assets you typically already have safeguards like original Photoshop files with layers for textures, 3d scenes with models that have modifier stacks, etc. So you can get back to an earlier version of any assets whenever something goes wrong. Nobody cares about having tons of snapshots for textures or models, you just need the latest version. You don't need thorough reviews or careful integration with other people's work, diffing is meaningless because of file formats, etc.

Learning the whole concept, framework, and tools is just tons of informational noise, in comparison to what you want to achieve.

Edited by peter_spy
Link to comment
Share on other sites

If we want something that's easy to use for mappers and encourages them to actually use the feature, please consider my idea to create an actual Git plugin for Darkradiant, and let me know what you think about it since I'm quite curious myself. Unlike my idea for realtime editing it's actually not something that radical to implement.

I'd basically go for a set of menu entries and toolbar buttons that automate the appropriate Git commands required to work with a map, a customized GUI for Git if you will. Obviously the OS needs to have Git installed else DR would issue unrecognized commands to the system... on Linux this is a given, not sure about Windows users. It operates on the idea that the current FM directory is a Git repository, while being able to turn it into one upon use if not. The only features and commands it's really going to need are:

  • Clone: Runs "git clone". Only needed if your FM isn't already a repository; This asks you for a Git URL and turns the FM directory into that repo.
  • Pull: Runs "git pull". The repository thus map file are updated from the network, map is automatically reloaded when ready. This may erase local edits or throw an error if the remote map is newer: I understand the commands needed to merge against local changes are "git stash; git pull; git stash pop" (source 1, source 2). If changes were made to the same brushes or entities there will be a conflict: We'll need a prompt that lets you pick which version to keep, ideally with realtime previews later on so you can see how items change in the viewport (local versus remote versions) then have the option to make your choice per group. Same for other text data such as defs or script files, there should be a diff previewer that makes it easy to pick which def / function / paragraph to keep in cases of conflict.
  • Push: Runs "git push". Uploads new commits to the remote repository. This should be pretty straightforward, the plugin only needs to support an additional menu asking for the username and password of the Git repository if they aren't set up in the config.
  • Commit: Runs "git commit -m Message". Records saved changes you made to the map, a window lets you write a commit message describing those changes. The menu should also list every file in the FM directory so you can add or remove map assets as you work with textures / sounds / scripts / etc... if that's too complicated it can automatically add all new files and delete ones that were removed, but only in subdirectories that hold valid map content (eg: "myfm/def").
  • Log: Runs "git log". Generates a simple commit list in which you may browse through all commits... no need to even account for origins and branches, a linear list of commits from the current branch should suffice for our purpose, long as they're listed in a readable format like short log + author + date. Double-clicking on a commit should prompt you to revert the repository / map to it locally in case you need to go back to an older version.

That should pretty much be it! Support for more Git options like branches could be added later but beyond this anything else can be optional. Needless to say mappers who want more features can use Git commands and other GUI Git tools on the FM repository separately: This is just to make it easy to do simple actions directly from DR... it also comes with perks that can be added later such as realtime previews of differences between commits, or a timer to automatically pull every X minutes so the mapper can be notified when there's a remote update and can click a button to reload the map with the new changes. The nice part is we can start with simple basics then expand with more features as needed.

  • Like 1
Link to comment
Share on other sites

9 hours ago, peter_spy said:

I get that you like git very much, but it really is a tool for very specific tasks, especially considering the big picture. Since you already have trouble in explaining the concept in the simple terms, no wonder you get crickets or pushback as a response.

@peter_spy I have to say, that is probably the most discouraging thing that anyone has said to me in recent memory.

@stgatilov I have taken your advice and replaced the rebase with merge (for pulling in collaborator changes).  Thanks for that suggestion, I think you're right in that rebase is probably unnecessary to introduce at this point.


  • Like 1
Link to comment
Share on other sites

6 hours ago, Frost_Salamander said:

 I have to say, that is probably the most discouraging thing that anyone has said to me in recent memory.

Don't let that discourage you at least from doing anything that works for you. Failure is normal, both at work and in personal projects. I failed to get my ideas across here more than several times, and I don't expect that everything I do or say will stick with others, even if it works for me brilliantly.

That said, I think brevity helps, time is our most precious currency anyway. Second thing is at least trying to keep wide group as possible in mind. IMO TDM is hard to work with as it is, and not sure if you're noticed, but there are literally no art guys here, the only resident modeler here is Epi, while there is no shortage of developers, or people with IT background. If you take a look at other design threads, avoiding the pitfall of thinking like a dev is already a problem, and so TDM risks falling into even further obscurity of being for IT crowd only.

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Recent Status Updates

    • JackFarmer

      Jeff, I sent you PM a few weeks back but you did not respond. Maybe your inbox is full?
      · 3 replies
    • The Black Arrow

      I was playing Skyrim, got bored fast. Got back to The Dark Mod just for one mission, played "Somewhere above the City" which is not really a great mission but still good, as in above-average.
      My biggest regret is living in this country, where there's a heat wave, I am sweating at 20c and I really wish for temperatures below 5c.
      · 10 replies
    • Skaruts

      Is there something wrong with the forums lately, or is it my browser? I've been having trouble formatting posts, and just now I couldn't format anything at all.
      I'm using Vivaldi.
      Usually I have to: select text, click bold, nothing happens, select again, click bold, then it works. 
      Same for other stuff, like creating spoilers, bullet points, links. Nothing works the first time. 
      · 1 reply
    • STiFU

      Back from a spontaneous 1-week trip to Lanzarote with wife and son. I hope beta testing has been going well...
      · 1 reply
    • datiswous

      Whenever I eat fried chicken these days I think of this scene in The Black Mage..

      · 1 reply
  • Create New...