-
Notifications
You must be signed in to change notification settings - Fork 18
Developer Codelab
Welcome to the world of contributing to the Super Complete Existential Dread Tabletop Simulator mod! Simply saying the name invokes dark powers that should better be left undisturbed… but here we are. This guide will introduce you to how the mod is structured and maintained, walk through a few basic changes, and give you all the tools to serve the darkness along with us.
SCED is a massive mod, with more than 10,000 objects organized in hundreds of containers, totalling more than 20MB of JSON definitions. To help keep this under control the mod is stored in a GitHub repository, giving us change control, history, and all the other powers provided by modern source control. This does make it complicated, and if you have questions please reach out on #contribution-creators-discuss.
As we’re using a GitHub repository, git is the tool we use for source control. If you’ve never worked with it before it can be intimidating, but there are many (many) online primers to help get you started, and we recommend them as trying to replicate an introduction to Git is beyond the scope of this document. There are a number of UIs for Git and GitHub that you can use if you prefer as well.
We use custom-built tools that decompose the mod into individual files, making changes more manageable. The same tools can assemble the mod from these files to recreate the save file which TTS can load and understand. Generally speaking, you’ll start by assembling the mod from your local repository, making some change in TTS, saving that change, then disassembling it to submit changes to the affected objects.
Before we start making an actual change, there are some guiding principles which inform how SCED development is set up. We ask that you follow these as much as possible when doing work you want to see in the mod.
- Pull Requests: All submissions to SCED should come through the repository via a pull request. Please take the time to learn this process, rather than working independently and asking someone else to merge your work. Custom content is explicitly excluded from this requirement. If you have a custom scenario or investigators to drop in they will be done so as they have been.
- Review: All submissions must undergo review. Code review is a fundamental practice in software, acknowledging that we all miss things or there may be better approaches. Our reviewers are experienced software professionals, TTS developers, and SCED owners. Their goal is to make the best mod possible, and they’re not out to just bash your work for the fun of it. Please respect their input, and open a dialogue if you disagree with their suggestions.
- Continuous Integration: The state of the repo should remain good at all times, so that it is possible to create a release from any point. Wherever possible changes should be submitted in small, reasonable pieces that can be easily reviewed and submitted independently.
- Code Style: There is no strict code style guideline for the mod. We do ask for 2-space indents and camelCase naming where reasonable, but reviewers will not reject submissions based on style.
There are a number of tools which you’ll have to install before you can start this codelab.
- Tabletop Simulator. Fairly obvious, but the only way to test your changes is within TTS
- Atom or VSCode with a TTS Plugin (Atom plugin, VSCode plugin). These editors make working with TTS code much easier, and the repository structure assumes you have them available if you’re making code changes. Either editor will work; while Atom development has been discontinued it is (at least for now) still functional with TTS.
- Git of some flavor.
- TTSModManager. This is the custom tool we use to decompose and assemble the mod
Note: While working with the VS Code plugin is recommended for beginners, it comes with some issues and is thus not used by "advanced" developers.
There are three codelabs presented here.
- Codelab 1, Moving an Object: This will teach you how to set up the repository, use our tools to assemble and decompose the mod, and make a change
- Codelab 2, Adding Code: This will walk through adding a new object with Lua script code, configuring the Atom or VSCode plugins to work with our search tree, and cover the principles of included code.
- Codelab 3, Changing Without TTS: Finally, we’ll explore the file structure of the mod while decomposed and look at what can be changed without ever having to load TTS at all.
In this codelab we’ll initialize our repository, build the mod, make a change by moving a few objects around, and commit that change to SCED.
To get started you'll need a copy of the repository at https://github.com/argonui/SCED. You should create a fork to work in, and a local version of your fork.
We try and keep pull requests small and manageable, which means individual branches for submissions. Create a new branch to work in your local repo, let's assume it's called codelab. It's always a good idea to create branches from main which has been synced recently . This minimizes the potential for merge conflicts down the line.
Before we can make any changes we need to assemble the mod. This is done with the following command:
ttsmodmanager –-moddir=D:\dev\TTS\ttslua\SCED --modfile=\codelab.json
Additional information can be found here: https://github.com/argonui/TTSModManager#readme
Once that completes, you will have a fully usable SCED mod save. modfile can go anywhere you want, even directly into your TTS Saves folder, but it's a good idea to put it somewhere outside your repository directly to avoid accidentally trying to commit it.
If you didn't put it there to begin with, copy codelab.json to your TTS saves directory just like you would for a new version of the mod.
Open TTS and load the codelab.json mod file. Now let’s make a simple change: Move the action tokens for the white player somewhere else (like up above the playmat). Save the mod, overwriting codelab. Then exit TTS (this isn’t actually necessary, but let’s focus on one thing at a time) and copy codelab.json from your Saves directory back to the original location.
Now it’s time to pull the mod, with our new change, back into the pieces for the repository. This is done by running the following command (this is all one line):
ttsmodmanager –reverse --moddir=D:\dev\TTS\ttslua\SCED
--modfile=D:\codelab.json
This will recreate the individual file elements of the mod, and place them in your directory.
Using your git tool, review the changes in your branch. This will show you the files which were changed by what we’ve done. Some of this is exactly what you’d expect. The objects we moved - the four Neutral tokens - are there, with new Transform.pos* values. But there may be other files as well, that you never touched. What gives?
The short answer is that TTS is inconsistent with how it handles some values, and Git detects those inconsistencies as changes. Our tools do their best to hide those but some may sneak through. There are also some objects which are simply subject to being in a different state after you use the mod, such as the Chaos Bag which shuffles the token order. It’s important to review the changes and only add the files you intended to change.
When you commit the changes, you can enter a message for the commit. Standard convention here is a short summary on the first line, then a more detailed description after that. More is better here! After you've created the commit, you can push the changes to your fork of SCED.
The final step is to create a pull request from your forked SCED to the central SCED main branch. This is the easiest step to attach any screenshots or other supporting artifacts that help you explain your changes.
Once you create the pull request it will be reviewed by one of the core contributors. They may have comments or ask you to make changes, and after those are resolved they will merge your change.
Congratulations! You’ve just made your first submission to SCED!