an overview of source control, in the AGS Editor and in plugins?

[Monsieur OUXX]

Tell me everything you know about source control in the latest AGS Editor ( 3.4.0.6).
I know what source control is.

But:
1. how do you put it in action in the AGS Editor? typically: provide a scenario where I can see the checking-in and the checking out? (I imagine we're talking script files here?)
2. How would you set the source control provider using the Editor Gui? (or outside the Editor Gui?)
3. What is the "put sound and sprite files in source control" option? How does it work? Please illustrate with a typical conflict.
4. In the Editor plugin API, I can see the objects below. Can you give a basic code snippet using any of these, for doing ... well, anything at all (your choice).

Code: ags

_editor.SourceControl
_editor.SourceControlProvider

At the moment I'm trying to figure out AGS source control, possibly to contribute or at least to explain it as extensively as I once explained fonts.

[Khris]

You should probably check out Manual -> Other Features -> Source Control Integration

AGS will apparently auto-detect MSCCI compatible source control systems and add editor menu items.

Though I imagine you could always do it independently with git or the like.

[Monsieur OUXX]

You should probably check out Manual -> Other Features -> Source Control Integration

Dammit I had no idea such a section existed in the manual.

[Monsieur OUXX]

I had actually read this article's online version after doing a few Google searches.

2.1. Has anyone ever (ever!) installed Sourcesafe to use it with an AGS game?
2.2. Is it relevant to install SourceSafe nowadays, since it's not supported anymore? do you think TFS also implements MSSCI and would be detected by AGS?
2.3. I'd still be very interested in hearing the experience of someone who added sprites to source control.

[Crimson Wizard]

I never used source control integration, because frankly I do not trust AGS Editor enough in this aspect.
I know that monkey0506 was adding a plugin API for source control, therefore it should be theoretically possible to write an Editor plugin that works with, e.g. SVN or Git repository.

I was using Git for my AGS projects, doing everything outside of the editor.

There was one thing to remember: rooms (CRM files) are not fully compatible with source control, because they are stored in compiled form: background + properties + objects + compiled scripts, all in one binary file.
This defeats the idea of source control: since a single file is both source and output at the same time.
Every time you add anything to any of the global scripts or script modules, and then test the game, the room scripts are recompiled, and so CRM files change.

Since I did not want to clutter my repository with thousands of updates of rooms, which I did not modify, but which got modified by compilation, so I made myself a rule to only put new version of a CRM into commit when I explicitly changed something in the room, that is not saved somewhere else: background, properties/events, or room objects/regions. (Room scripts are saved in ash/asc files)
This is not obligatory, but helps to keep a source control concept at least.


Regarding sprites, I was committing acsprset.spr and sprindex.dat.

[Monsieur OUXX]

About the sprites: I'm not sure how what you're saying relates to the "put sound and sprite files in source control" option.

I'm going to try. However I can't find any tutorial explaining how to hook up any non-MS repository (non-SourceSafe, non-TFS) to MSSCCI. I'd like to start off with a local, lightweight SVN or git server. If anyone has a lead...

[ChamberOfFear]

About the sprites: I'm not sure how what you're saying relates to the "put sound and sprite files in source control" option.

If you check the option for sound and sprites the Source Control integration will add the files Crimson Wizard mentioned on check-ins. That's what the feature does, it adds "acsprset.spr" and "sprindex.dat".

I'm going to try. However I can't find any tutorial explaining how to hook up any non-MS repository (non-SourceSafe, non-TFS) to MSSCCI. I'd like to start off with a local, lightweight SVN or git server. If anyone has a lead...

I don't think you can, at least that was my conclusion when I was doing experiments on this a year back. The AGS Editor code recognizes Source Control Software with a registry check to a value which is used by Microsoft to store Source Control Providers.

Spoiler

Code: c#

private void GetSourceControlProviderDLL()
{
  RegistryKey key = Registry.LocalMachine.OpenSubKey(@"SOFTWARE\SourceCodeControlProvider");
  if (key != null)
  {
    string providerPath = (string)key.GetValue("ProviderRegKey");
    key.Close();
    if (providerPath != null)
    {
      key = Registry.LocalMachine.OpenSubKey(providerPath);
      if (key != null)
      {
        _providerName = (string)key.GetValue("SCCServerName");
        _providerDLL = (string)key.GetValue("SCCServerPath");
        key.Close();
      }
    }
  }
}

[close]

However if I remember correctly it isn't really an impressive feature, it pretty much just boots up the external software using modified project files as arguments. You're probably better off using independent tools outstide the editor like Crimson Wizard and Khris has already mentioned. Using a fine tool like Git Extensions or TortoiseGit complimented with a good gitignore would give you capabilities identical to the AGS integration, minus the menu-dialogs.

[Monsieur OUXX]

About the sprites: I'm not sure how what you're saying relates to the "put sound and sprite files in source control" option.

If you check the option for sound and sprites the Source Control integration will add the files Crimson Wizard mentioned on check-ins. That's what the feature does, it adds "acsprset.spr" and "sprindex.dat".

Yes, that I understand, but once I know that, I still know nothing. when I add sprites in a source-controlled AGS project, I've observed that it checks out/in game.agf. IIRC, "acsprset.spr" and "sprindex.dat" are just cache files? What is the immediate consequence of having checked-in an up-to-date game.agf, but leaving out those files?

You're probably better off using independent tools outstide the editor like Crimson Wizard and Khris has already mentioned. Using a fine tool like Git Extensions or TortoiseGit complimented with a good gitignore would give you capabilities identical to the AGS integration, minus the menu-dialogs.

Yes, but my goal would be to add an Editor plugin adding permissions to some actions (e.g. "add a sprite") and manage the check-in/check out in a manner that is as integrated as possible.

[Crimson Wizard]

when I add sprites in a source-controlled AGS project, I've observed that it checks out/in game.agf. IIRC, "acsprset.spr" and "sprindex.dat" are just cache files? What is the immediate consequence of having checked-in an up-to-date game.agf, but leaving out those files?

acsprset.spr IS the cache file, but it is used at all times by the Editor, and when compiling the game, similar to AudioCache folder.
The entries made in Game.agf are sprite properties (Width, Height, Alpha Channel flag, etc), including path to the source file. This path is needed only when you use "Replace from the source file" context command, otherwise it may be ignored.
So, for new sprite, you probably need to commit [Game.agf AND (acsprset.spr OR the sprite source file)].

Note, that when you import from clipboard, or cut a piece of original sprite (or do tiled import), source sprite file is not remembered. Therefore I find it safe to just commit acsprset.spr.

[Monsieur OUXX]

TUTORIAL: One possible way of integrating AGS with a "modern" source control system
("modern" = not SourceSafe, which is discontinued)

This tutorial assumes that you have a notion of source control, and understand basic notions such as code check-in, code check-out.

1. Go to the CodePlex website. They host opensource projects for free. Create an account, create a project
2. when you create a project, select "Team foundation Server" (a.k.a. TFS) --> "Team Explorer". Note 1 : You could use any other system (git?) but you'll also need an MSSCCI provider that works (see below), and so far I only know how to find one that works with TFS. Note 2: You could install a TFS server yourself, but that's a lot overkill.
3. On the website, navigate to your newly created project, and click on the "connect" button, which gives you connection details. Notice the url (something like https://tfs.codeplex.com:443/tfs/TFS40 ) and the connection credentials (something like snd\YOURLOGIN_cp )

Now you have an online code repository. And you have the code Editor (AGS). But AGS does not offer the GUI options to use the features of the source control. You need something in-between. AGS can only display the source-control-related buttons and windows if they are "installed" on your computer, as a sort-of standalone program, which is called an "MSSCCI provider". You need to install an MSSCCI provider that is able to connect to your newly-created TFS server.

4. Go to https://visualstudiogallery.msdn.microsoft.com/06c8e056-7f77-4a5c-9b8b-49318c143df8 This is an MSSCCI provider that works for TFS (that's what you want because TFS is the kind of server you picked on CodePlex) and that works with 32-bits systems. I believe AGS can only recognize that but I'm not sure at all.
5. After the installation, open your AGS game. File-->Add to Source Control. You will be asked for the TFS server address (use info from step 3.) and then your credentials (use info from step 3. again)
6. From this point on, every time you modify a file (either by typing text into a script or adding a sprite through the GUI then saving) the Editor will ask you if you want to check out the file. Then at any time you can go to File-->See pending check-ins. That opens a custom window allowing you to see file histories, compare, etc. Finally, you can check in your changes.

Note: It work for a short while then I kept having error 407 in the Editor. If someone has an idea...

[Monsieur OUXX]

The entries made in Game.agf are sprite properties (Width, Height, Alpha Channel flag, etc), including path to the source file. This path is needed only when you use "Replace from the source file" context command, otherwise it may be ignored. So, for new sprite, you probably need to commit [Game.agf AND (acsprset.spr OR the sprite source file)].

I use that all the time.
I think I'll have two different repositories. One for the code (where I constantly do check-ins check-outs) and one for the sprites, that each developer is supposed to download locally before he starts working, but almost not modify. And they should download it to a given location that matches the sprite's source location.

[Monsieur OUXX]

Dammit, I can't seem to get rid of that "http error 407". It worked for a while, and now AGS won't connect to the TFS anymore. I tried erasing my credentials in Windows' password vault, but to no effect.