This wiki is more oriented to current and potential developers of the Tabletop Simulator mod that implements the Era of Tribes board game. It documents submission guidelines and the recommended workflow for how to make edits to the mod that follow those guidelines.

If you are here and are just interested in playing the mod on Tabletop Simulator, please go to the Era of Tribes Tabletop Simulator Steam Workshop Page and click on the "Subscribe" button. Rules for the game may be found in game or downloaded from the Era of Tribes BoardGameGeek page.

For you hardcore fans who are designers and developers out there the rest of this page is for you! While this mod is officially sanctioned and welcomed by Arne Lorenz, creator of Era of Tribes, and most of the artwork assets in the mod come directly from Arne, the mod is 100% fan developed and supported. It really is a labor of love! It can be hard for any one person to find time to make this mod be all that it can be which is why we welcome anyone with the appropriate skills (or even just a desire to learn those skills) to work with us on the mod and make submissions through this GitHub repository!

Thank you all!

If you are still reading then hopefully that means that you are interested in helping us out on this project! The following guidelines are here to help you submit a pull request that is easy to review, easy to integrate into the main project, and helps to ensure that multiple people may work on the project in parallel.

Important! Generally speaking, making a modification in Tabletop Simulator, saving the mod and submitting that file will not be sufficient! Tabletop Simulator tends to move a lot of objects, just a little, as a mod is loaded. I call this "the nudge". When you save the file and then compare with the previous version you will see way more changes than what you made. This makes it very difficult to review the changes and makes for a very hard to read git history. It also makes it basically impossible for others to rebase their changes on yours.

• Submissions may be made using the standard [GitHub Pull Request|https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request] process.
  • Reason: This process is easy to use and one of the major advantages of GitHub!
• When modifying a Lua script associated with an in game object, update a copy of the Lua script in the references/ folder.
  • Reason: Due to the way that Lua scripts are stored in the main JSON object, it is very difficult to diff and review * Ensure that your submission only has the changes that you made to the mod, and does not contain "nudged" items
  • Reason: As described in the Important section above, keeping the change set to a minimum is easier to review and is less likely to cause merge conflicts for other users. them. Keeping them in a separate file like this allows the history of the file to be properly tracked.
• Do not reorder objects in the JSON file. (Tabletop simulator often reorders objects in the file when creating a new save game)
  • Reason: When objects in the JSON file are reordered, it becomes very difficult to diff the file and review what the actual changes to the mod are!
• Use a CR/LF at the end of every line
  • Reason: This mod was originally created in Windows, and for the sake of consistency, should stay in the Windows text file format.

If your submission is rejected at first due to these guidelines, don't get discouraged! We'll help you clean your patch up for everyone's sake! Everyone benefits from your hard work!

This workflow is not really specific to the Era of Tribes mod, but I've not actually seen it documented anywhere, and it will help you to produce changes which follow the Submission Guidelines above!

Before getting into the workflows themselves, first a few notes:

• These workflows assume that you are using the official Tabletop Simulator plugin for the Atom text editor. There are other plugins available for other text editors that are known to work though, and I'm sure the workflow doesn't change much.
• With apologies to my Mac and Linux using friends, these workflows are geared to Windows users. Again, I'm sure the workflows won't differ too much on other systems but default file paths are sure to be different.
• The detailed workflows recommend the use of a graphical diff tool. I (Ben a.k.a. Hazelrah) personally use Beyond Compare so that's what you see in the screenshots of the detailed workflow. However, there are other such tools that may be used such as the free and open source [Meld|meldmerge.org/] project.

This sets up a starting point that is used by the other workflows. When modifying a mod, you have to modify a save game and not the mod directly, so this sets up a save game that can be used as a "scratchpad" of sorts for our edits.

This is the condensed version. See Create Save Game (Detailed) if you are having trouble following this section

• In TTS Create a Single Player Game
• Load the Era of Tribes mod
• Create a new Save Game.
• Note the number of the new save game.
• Open your favorite file explorer program to locate the save file.
• Also locate your local clone of this git repository and find the EoT_TTS.json file, and pull in the latest master branch.
• Copy the contents of the EoT_TTS.json file over the TS_Save_#.json file.
  • This step ensures that if the mod is not at the latest version, your save game will be at the latest version in the git repo.
• In TTS, load the modified save game
• Open the Atom text editor (with the TTS plugin already installed)
• From the Packages menu, select "Tabletop Simulator > Get Lua Scripts"

With this last step, you are ready for modifying the TTS mod!

Use this work flow to edit the position, rotation, or properties of an object that is already in the game.

• In TTS, load the updated save game (see "Creating a Save Game as a Work Project")
  • This will be called the "original save" below
• If editing an existing object
  • Locate the object that you wish to modify. Most objects are in bags, so you may have to remove the object from the bag.
  • Make the desired modification to the object.
• If adding a new object
  • Add the desired object and set up all of its properties
• Right click on the object and copy its GUID
• Make a new save game
• Open the new save game
• Locate the modified object by searching for its GUID
• Copy the JSON of the entire object
• Open the original save game in a text editor
• If editing an existing object
  • Locate that same object by searching for its GUID
  • Select the JSON of the entire object, and then paste the new object
  • Revert any unnecessary changes to the position and rotation to avoid needless lines in the diff.
• If adding a new object
  • If adding to a bag
    • Locate the bag the new object should be in by GUID
    • Scroll down the "ContainedObjects" list
  • If adding to the main table
    • Locate the top level object list just above the "DecalPallet" entry
  • Paste the new object in the list
  • Ensure that the tabbing is appropriate
• Save the modifications to the original save
• In TTS, load the original save file again and test your changes
• Once satisfied with the results, copy the contents of the original save file back to the EoT_TTS.json file in the git repository.
• Use git's diff tool or use another diff tool to ensure there are no extra modifications.
• Commit, push and submit a pull request.

Use this workflow to add Lua code to the main module. As much as possible, Lua code should be stored in the main Global.-1.ttslua file rather than on objects as Lua code for objects stored in bag isn't automatically exported as files for Atom to modify.

Modifying the global UI code (Global.-1.xml) or Lua code for objects is a very similar process.

Use this work flow to edit the position, rotation, or properties of an object that is already in the game.

• In TTS, load the updated save game (see "Creating a Save Game as a Work Project")
  • This will be called the "original save" below
• Open Atom and run the "Get Lua Scripts" function of the Tabletop Simulator plugin
• In Atom, modify the Lua code in Global.-1.xml
• After making the modifications, run the "Save and Play" function of the Tabletop Simulator plugin
  • This will actual modify the original save file, updating the Lua code in it, but otherwise not modifying it.
  • It will also cause Tabletop Simulator to automatically reload the original save file
• Test your changes
• Once satisfied with the results
  • Copy the contents of the original save file back to the EoT_TTS.json file in the git repository.
  • Locate the Global.-1.ttslua temporary file created by Atom
    • By default this will be in C:\Users\<UserName>\AppData\Local\Temp\TabletopSimulator\Tabletop Simulator Lua\Global.-1.ttslua
  • Copy the Atom Global.-1.ttslua file over the references\Global.-1.ttslua file in the git repository.
• Use git's diff tool or use another diff tool to ensure there are no extra modifications.
• Commit, push and submit a pull request.

If multiple people are making changes to the main Lua script at the same time then, due to the way the lua scripts are stored in the mod JSON file, this will ALWAYS create a merge conflict. We recommend rebasing your changes on the latest master branch to remove this merge conflict.

Unfortunately, the same problem that causes this to always create a merge conflict also makes rebasing more difficult than it would be in a normal project. Therefore we are providing this guide on rebasing code.

Note: In general, this procedure will not be necessary when editing the properties of in-game objects, only when editing Lua scripts

• Before rebasing, make absolutely certain that the reference/Global.-1.ttslua script (or any other Lua script or UI XML file) is properly committed to your branch
• In the git repository, check out your branch (which is now out of date)
• Start the rebase on the master branch
  • The rebase will immediately fail if both you and the master branch has mad modifications to a Lua script
• Fix up any merge conflicts that may be in the reference/Global.-1.ttslua file
  • This is where the real merge happens
• Perform a git checkout EoT_TTS.json to revert the JSON file to the contents in the master branch
• In TTS, load the updated save game (see "Creating a Save Game as a Work Project")
  • This will be called the "original save" below
• Open Atom and run the "Get Lua Scripts" function of the Tabletop Simulator plugin
• Copy the contents of the reference/Global.-1.ttslua file into the Global.-1.ttslua file in Atom
• After making the modifications, run the "Save and Play" function of the Tabletop Simulator plugin
• Test your changes
• Once satisfied with the results copy the contents of the original save file back to the EoT_TTS.json file in the git repository. Lua\Global.-1.ttslua`
• Use git's diff tool or use another diff tool to ensure there are no extra modifications.
• Perform a git rebase --continue to complete the rebase.

If there are several new commits to the Lua scripts on the master branch, then this process will need to be repeated for each commit.