Version Control

From GECK
Jump to: navigation, search

Link to TES4 Construction Set Wiki: Version Control

New Vegas Users

The instructions for New Vegas are nearly identical with only these exceptions:

  • Replace "Fallout 3" with "Fallout New Vegas" (with space)
  • Replace "Fallout3" with "FalloutNV" (no space)
  • Replace "WhoCanMerge" with "SudoWhoCanMerge" (or add both)
  • Replace "WhoCanForceCheckout" with "SudoWhoCanForceCheckout" (or add both)

Introduction

A note to anyone intending on using Version Control. Version control is NOT for casual modders or for people who just want to merge a couple of mods. Version control is intended for teams of people who KNOW what they're doing.


During production of Fallout, the content team (artists, producers and designers) used version control as a way for everyone to work on content in the master file simultaneously without overwriting each other's work. Version control is a way for multiple users to work on content at the same time, and also provides a way for merging plugins into the master file.

Modders who create plugins for master files won't benefit from Version Control at all. However, single users working on master files can take advantage of Version Control in order to make working on large projects more manageable. Rather than having a central, remotely shared master file on a server that a team of developers work on, a single user can set up local network shares on their local computer essentially "spoofing" its intended use.

As a plugin grows in size, it takes longer and longer to save changes, and the GECK is more prone to crash during this time. When using Version Control, this issue is greatly alleviated by having the ability to work on small specific parts of a large mod at a time rather than saving the entire file every time a change is made.

The central idea being, that there is a "Remote Master" file located on your network which is the most up-to-date version of the file. There also exists a "Local Master" file which is consistently overwritten/updated over time. The Local Master file resides in the normal "\Fallout 3\Data\" folder and can be used as a master for plugins in development. You can then create a new empty plugin and set the master to the Local Master file (the plugin can already have data in it that you want to merge). You can then alter the plugin as needed which will later be merged into the finial master. Anything that has been changed since the last merge will have a green tint to it as well as having the asterisk mark *, making altered records easier to spot.

At any time, you can load up the GECK with the plugin (local) and the master (local) loaded and merge the contents of the plugin into the Remote Master file. When the operation completes, the plugin will be empty because the entries have been moved/merged into the Remote Master file. The same plugin file can be used over and over again since it's empty after the merge. The next time the GECK is started after a merge, a prompt will appear notifying you that the Remote Master is different than the Local Master and will ask you "Copy network version to local directory?". Selecting "Yes" will overwrite/update the local master file and the process can be repeated. The GECK automatically creates backups of the merged files which it stores in the local share folders.

Setting up Local Folders and Shares

These instructions assume you are setting up locally. Adjustments will be needed for remote destinations. The network IP address "127.0.0.1" refers to the "loopback" address which points back to the computer sending the request. You can also substitute 127.0.0.1 for localhost or the computers UNC name (IE: "YourComputersRealName"). Using network names generally requires additional services to be running in order to function properly. Using the IP address "127.0.0.1" should always work. Because of that, the IP should be used during setup and after VC is verified to be functional, then substitute the IP for a UNC name if desired. If 127.0.0.1 doesn't work for some reason, you are probably missing core windows network components (A Dial-Up connection is the minimum required).

Create the following folders inside your Fallout 3 installation directory:

\Fallout 3\Data\CheckInBackup
\Fallout 3\Merging\Data
\Fallout 3\Merging\VersionBackup

Enable network sharing on the following folders and ensure that you can write to them using the network address.

\Fallout 3\Data\CheckInBackup
\Fallout 3\Merging

Write permission can be tested by entering "\\127.0.0.1" (without quotes) into any explorer window address bar or from Start->Run or create a new shortcut and enter "\\127.0.0.1" (without quotes) for the path. You should then see the two shares you just created. Ensure that you can write to them by creating a new text document or equivalent. If you are unable to create new files in the network shares using the network path, the permissions for the share will need to be adjusted so that your account can read and write to it. Also, the "Security" (separate from "Sharing") for the folders may also need to be adjusted depending on the type of user account you have. Administrator accounts generally only need to set the permissions for the shares (Read by default) because Administrator accounts generally have "Full Control" under Security by default unlike normal User accounts.

If successful, after entering the path "\\127.0.0.1" you should see and be able to read/write to the following shares:

\\127.0.0.1\CheckInBackup
\\127.0.0.1\Merging

Tip

Alternate names can be used to accommodate multiple version control installations. For example, the folder "Fallout 3\Data\Merging" can be shared as "Fallout3_Merging" instead of just "Merging" under the sharing properties, in case other installations also use the same naming convention.

So that the actual paths looks like:

\Fallout 3\Data\CheckInBackup
\Fallout 3\Merging

But the network share paths look like:

\\127.0.0.1\Fallout3_CheckInBackup
\\127.0.0.1\Fallout3_Merging

If alternate names are used, those alternate names must be used in the ini settings for the GECK.

SNetwork Path=\\127.0.0.1\Fallout3_Merging\
SNewVersionBackupPath=\\127.0.0.1\Fallout3_Merging\VersionBackup\
SNetworkMasterPath=\\127.0.0.1\Fallout3_Merging\Data\
  • If the path contains spaces it may need to be enclosed in quotation marks.

Setting up Version Control

2K/XP:

  • C:\Documents and Settings\UserAccountName\My Documents\My Games\Fallout3\

Vista/Win7/8/10:

  • C:\Users\UserAccountName\Documents\My Games\Fallout3\

Open GECKCustom.ini with a text editor (the GECK automatically creates this file if it doesn't exist when it starts). Find and modify the following entries:

(mind the space in "SNetwork Path")

[General]
bUseVersionControl=1
SNetwork Path=\\127.0.0.1\Merging\
SNewVersionBackupPath=\\127.0.0.1\Merging\VersionBackup\
SNetworkMasterPath=\\127.0.0.1\Merging\Data\
SLocalSavePath=Saves\
SLocalMasterPath=Data\
SLocalBackupPath=Data\CheckInBackup\

Next, append the following to the end of the same file. This is needed to unlock some of functions only available to users allowed to use Version Control. Substitute your local computer login name for UserAccountName.

[WhoCanMerge]
UserAccountName=1

[WhoCanForceCheckout]
UserAccountName=1


Remember to include the Sudo in front of the edits if you are using VC for Fallout: New Vegas. Otherwise you will run into an issue detailed in the notes.

Append the following to the end of the file.

GECKPrefs.ini

[WhoCanMerge]
UserAccountName=1

[WhoCanForceCheckout]
UserAccountName=1

When the GECK loads, it should automatically create a new file "\Fallout 3\Merging\ConstructionSetNetwork.ini" and enter the user specified under "WhoCanMerge" into it under "Users" which looks like:

[Users]
1=UserAccountName
UserAccountName=1

If this file isn't created automatically, manually create it and fill in the [Users] info with your actual user accounts name which should match the one in GECKPrefs.ini.

Adding Master Files

Copy Fallout3.esm and any other master files you want to use Version Control on to the local folder "\Fallout 3\Merging\Data\" (net path: "\\127.0.0.1\Merging\Data\"). These will be the central remote master files. They will also be the destination files when merging plugins. You should never have to merge a plugin into a local master that exists in your \Fallout 3\Data\ folder because they are intended to and could possibly be overwritten.

Load up the GECK and you should get a warning like this for masters that haven't been set up yet:

---------------------------
Warning
---------------------------
TESBitArrayFile::OpenAndMapBitArrayFile could not find file 'Fallout3.fud'.


Context: DEFAULT

"Yes to all" will disable all Warnings this session.
---------------------------
Yes - No - Yes to all
---------------------------
  • It is Possible that this error will not show up for you. If that is the case, simply continue as normal. The files will be generated correctly.

Select "Yes" to let the GECK continue loading. Unless you're working on a total conversion, the first master to set up should be Fallout3.esm and any masters you want to merge into. Open the Data Files window and select/highlight the master you want to set up. Click on the Details button and select "Yes" when it asks you "Do you want to use an empty list to save memory?". When the empty list appears, press CONTROL + SHIFT + B and you will see the following:


---------------------------
Confirm Bit Array File Update.
---------------------------
You have chosen to create/update the bit array files for the current file.
This operation cannot be undone and may take a long time to complete.

Do you wish to continue?

---------------------------
Yes - No
---------------------------

Select "Yes" to create them. This will create 3 files in "\\127.0.0.1\Merging\Data\" using the same name as the master but with the extensions .fid .fud .fvd. Close the File Detail window. Repeat this process for any additional masters.

Select "OK" in the Data Files window to reload the master file or close the GECK and re-start it.

Notice

If you don't get a prompt to create an empty list after clicking Details, and instead a long list of forms loads, then there is most likely a problem with the user account name specified in the ini files. It is sometimes the case that the pre-packaged computer came with a default user account like "User" but was then later changed to be more personal like "MyLoginName". You may want to add/try both names if your login account name is different than the account name in the users path:

2K/XP:

  • C:\Documents and Settings\UserAccountName\

Vista/Win7/8:

  • C:\Users\UserAccountName\

GECKCustom.ini , GECKPrefs.ini

[WhoCanMerge]
UserAccountName=1
MyLoginName=1

ConstructionSetNetwork.ini

[Users]
1=UserAccountName
UserAccountName=1
1=MyLoginName
MyLoginName=1

Normal Usage

Important Note:

Never include a master to an esp in any esp you intend to merge. If you have for instance Test.esp with a master to Test2.esp, merging Test.esp will throw up a lot of errors in VC, and merging Test2 first will cause formid mismatches and severe headaches.


Load the GECK with your destination master ESM file (local) ticked and your source plugin ESP file (local) ticked with the plugin file marked as Active. When the GECK is done loading, click on the Version Control button to the far left of your upper toolbar.

Select all the forms you want to merge first and then click Check Out. After this process completes, select them again and press Check In. A new window will pop up asking for the location of the remote destination master file. Select the ESM you want to merge into and click Save. The GECK will then merge the content of your ESP file into your chosen ESM and resolves any FormID conflicts.

Select "OK" in the Data Files window to reload the master file or close the GECK and re-start it.

The next time the GECK loads, you will receive this message:

---------------------------
File Update Available
---------------------------
 
Master File YourMasterFile.esm does not match the one on the network. Copy network version to local directory?
 
---------------------------
Yes - No - Cancel
---------------------------

Select "Yes" to copy the newly updated remote master file to the local \Fallout 3\Data\ folder overwriting the existing older master file.

Notes

  • WARNING: Turn off VC when not being used actively for merging. For unknown reasons, having VC enabled will cause worldspaces and cells to randomly get switched to Runtime only, meaning that cell data gets wiped. Turn off VC when not being used.
  • There may be occasions where you may want to disable Version Control temporarily for some reason or another by setting bUseVersionControl=0 in GECKCustom.ini. Doing so will cause a warning message to appear every time you start the GECK if the file "ConstructionSetNetwork.ini" exists. Renaming or deleting that file and letting the GECK re-create it the next load version control is enabled can be used to disable the warning.
  • If you do not include the Sudo in front of the WhoCanMerge ini edits, some forms may be unable to be checked out, with an error stating that this form is of a different version. Make sure you include the sudo.
  • Version Control does keep backups of all the esms you've merged on, so if any issues occur during merging, simply use the backup.
  • Do not use GECK Extender with Version Control, there are some strange errors with it.
  • For teams: The more esps the better, separate your work as much as possible so that if a portion of your work doesn't work, only that single esp is affected and not all of your work.
  • Remember to check your esm with xEdit and GECK Extender each time you merge.
  • Clean your esps before merging. Avoid dirty edits.
  • Version Control does not support merging new land records into existing worldspaces. It will jam up and never merge correctly. Use the xEdit workflow using Inject forms into master and deep copy as override to merge new land records.

See Also