ToME: the Tales of Maj'Eyal

If you would like to hack on ToME, perhaps submit patches containing new monsters or your own class, then version control can make your life a lot easier. Below I will outline how to set up the Mercurial distributed version control software (VCS) on Windows and get hacking on ToME. First a bit of background, though. The ToME code itself is using the SVN version control software. SVN is a centralized VCS, which means that there is a central copy and only people that have write privileges can make changes. On the other hand Mercurial is a distributed VCS and everyone that links this to ToME will be able to have their own, local copy to which they can make as many changes as they want. The local Mercurial copy can then be kept in sync with the ToME SVN copy (this is one of the reasons VCS is so powerful), and once you are ready you can submit one large patch to DG for acceptance into the official SVN copy. Other distributed VCS have good coupling with SVN (eg. Git) but I am personally familiar with Mercurial so that is what I will highlight here.

Enough background, lets get moving. First you will need to install the proper tools onto Windows. Install TortoiseHG (http://tortoisehg.bitbucket.org/) for a nice GUI version that integrates into the File Explorer (or whatever that thing is called). Next we need to install the HgSubversion extension to allow us to access the ToME SVN repository:

1. Navigate in the File Explorer to a place you feel comfortable adding the HgSubversion folder. (eg. a folder "coding" in your home directory)
2. Right-click on some white space in the folder. You should see a "TortoiseHg" menu. Select "Clone..."
3. Enter this into the source (without the double quotes): "http://bitbucket.org/durin42/hgsubversion"
4. Add this to the end of the destination (without the double quotes): "\hgsubversion"
5. Hit "Clone".

Now we need to tell TortoiseHG where to find HgSubversion:

1. Right-click on some white space in any folder. Select "TortoiseHG -> Global Settings."
2. Select the "Extensions" tab on the left-hand side.
3. Click on the "rebase" checkbox and hit Apply.
4. Click the "Edit File" button on the top.
5. Find the "[extensions]" section and add this below it: "hgsubversion = C:\path\to\your\hgsubversion\hgsubversion". (remember to replace the "path\to\your\hgsubversion" with the destination directory from the HgSubversion installation. The additional "hgsubversion" added to the end is intended, DO NOT FORGET IT! )
6. Save and exit.
7. Click "Ok" to exit the Extensions settings.
8. Click "Ok" again to exit the Global settings.

Time to download ToME! Since this step will download the entire history of the ToME project, we will do it in two steps. In the first step we will download only the first 100 revisions of ToME, and in the second update the other 1000+.

1. Navigate to a place you feel comfortable putting the ToME directory. (eg. a folder "coding" in your home directory).
2. Right-click on some white space in the folder. Select "TortoiseHG -> Clone..."
3. Enter this as your source (without the double quotes): "svn+http://svn.net-core.org/repos/t-engine4"
4. Add this to the end of the destination (without the double quote): "\t-engine4-hgsubversion"
5. Expand the "Advanced Options" menu.
6. Check the "Clone to revision" option. Enter 100 in the textbox to side.
7. Click "Clone". This step may take a while depending on your internet connection. Close the Clone window after the operation has completed.
8. Right-click on your new "t-engine4-hgsubversion" folder. Select "TortoiseHG -> Synchronize".
9. Click "Pull". This step WILL take a long time. Close the Synchronize window after the operation has completed.
10. Right-click the "t-engine4-hgsubversion" folder again. Select "TortoiseHG -> Repository Settings."
11. Select the "Synchronize" tab on the left-hand side.
12. Select "rebase" in the "After Pull Operation" pull-down menu.
13. Click "Apply" and then "Ok" (I am a bit paranoid about setting ).

And we are done! Now you can edit the code in your "t-engine4-hgsubversion" directory. I will outline a very basic workflow, but you should probably familiarze yourself with Mercurial (http://mercurial.selenic.com/) and TortoiseHG (http://tortoisehg.bitbucket.org/) documentation. Every time you feel like you have made progress and want to save the changes you can right-click on some white space inside of the directory and select "Hg Commit...". You can grab new revisions of the ToME code by selecting "TortoiseHG -> Synchronize" and pulling like we did above, but now the "rebase" operation should take place after the pull and move all of your code changes to the top of the history.

Once you are ready to send your work to DG you can right-click in your "t-engine4-hgsubversion" folder and select "Hg Repository Explorer." Click on the little button that point up (the tooltip is "Determine and mark outgoing changesets." This should add little up arrows to the graph on the far left side of the scrolling view and help you find where DG's official SVN revisions stop and your revision start. Left-click on your first (bottom-most) revision. Then scoll up and right-click on your last revision. Select the "Export Patches from here to selected" option. This will create a patch file for each of your revisions which you can now zip up and send to DG.

Thanks for posting this yufra.

Unfortunately it returns an error when I try to clone the repository. (says svn+http... not found)

I tried dropping the svn+ from the http:// and that prompts for a user name and password but doesn't accept the ones I imagine it would (it takes them without error just keeps reasking for them and then says it's not a repository).

Now that I have Tortoise SVN installed this seems to work. Went back today and made a second folder so I could play around with some stuff using these instructions and had no issues.

I updated to beta 12 last night without issues but can't download the latest change set. Anyone else having this problem or does anyone have an idea of how to fix it?

That looks like a mercurial-svn issue, not an SVN one so others probably won't see it. I'll try to debug it later with you.