Godot Primer

I just want to quickly check out the game

If you just want to play the game in its current state without worrying about git, open the TetraForce GitHub page, click on the green "clone or download" button and select the "Download ZIP" link at the bottom. Extract that archive somewhere on your computer.

Next, install the Godot engine. The recommended way is by visiting the official homepage and click on "Download" at the top right. Chose the standard version for your operating system. Extract the ZIP file to your hard drive, there is no installation needed.

You can also get Godot via Steam, but the version on steam is lagging behind. This project is aimed at V3.2 right now while Steam only offers V3.1. But I was still able to start the game in Steam without any problems. Your mileage might vary.

Now you are able to boot up Godot, which opens up the Project Manager. Click the "import" button and select the directory you extracted the TetraForce.zip file to, which contains a "project.godot" file. Select that and hit "open", then "import & edit".

That will open the project in the Godot Editor. Don't be scared, you are just looking for the triangle shaped "play" button in the top right corner, or simply hit the F5 key to start the game. Have fun!

I want to contribute to the game

That's great! Here are a few steps to help you hit the ground running.

First off, you should create an account on GitHub. Although it is optional, it is recommended to also set up a key, so see the GitHub Help page on SSH keys for instructions.

You should also install Git on your computer, if it isn't available already (common on Mac and Linux, not so much on Windows). There are a lot of different frontends and user interfaces for Git, but this page will use commands to be entered into your terminal or the Git Bash on Windows. Open the shell right away and tell Git your username and email address:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

Once that is done, open the TetraForce GitHub page and click on "Fork" in the upper right. This will create a copy of the current development status on your own GitHub account.

Switch to your own GitHub account, select the new TetraForce project and click the green "clone or download" button. Select either the HTTPS or SSH option to clone, you can copy the link to your clipboard with the button to the right of the input box. Switch to the command line and enter

git clone git@github.com:yourusername/TetraForce.git or git clone https://github.com/yourusername/TetraForce.git

That will download all the needed files to a new folder called "TetraForce" in your current directory on your computer. Your local clone is connected to your GitHub repository by a remote connection caled "origin", which allows you to save your local changes to your server account. But to keep up to date with the official TetraForce repository, you should add another remote to your local repo:

git remote add upstream https://github.com/fornclake/TetraForce.git

You can check that you have both remotes available with the command

git remote

You should see both origin and upstream.

To make sure your local copy is up to date, issue

git pull upstream master

After that is done, you can also update your GitHub copy with

git push origin master

One last step: create a new branch to work on. That way conflicts will be reduced to a minimum when pushing or pulling changes.

git checkout -b yourfancybranchname

If you'd like to you could do any number of branches for different kinds of features you want to work on. Just keep in mind that you should keep all your changes to your own branches and not commit to the master branch.

OK, you are all set up with version control, but you still need to get the Godot engine if you don't have it installed already. Refer to the section above to download from the official site or through Steam, then continue up to the point where you could hit "run" (F5) to start the game in the editor. Go ahead, give it a try!

Godot is a pretty configurable editor, so layouts might change between versions and your personal preferences. For this game, two important buttons are the 2D and Script buttons in the top middle. 2D is for visual edits to the scenes that get displayed in the game, Script obviously opens up the source code.

Get yourself familiar with the editor and GUI, you might want to check out the manual. If you don't know what to work on, look at the open issues for the game. Make some slight changes and hit CTRL+s to save your work.

As you checked out your own branch earlier, your changes will be saved to that branch. You can get a list of changes and additions with

git status

Add the changes you made to prepare your first commit

git add newitem.gd updatedscene.tscn

Once that is done, write them to history with

git commit -m "A small step for mankind, a giant leap for my self-esteem"

But that only saved a local copy. To backup your changes to your GitHub account, use

git push origin yourfancybranchname

Now that your glorious changes are publicly available, you can ask for them to be included in the main repository. Open your project's GitHub page and hit the "New pull request" button. Select your branch, enter a description of the benefits this brings to the game and submit it. Maintainers will have a look and either merge them into mainline right away or ask for clarifications, cleanups or other such things. Don't worry, you already have the bulk of the workflow under your belt to carry on.

Thanks for your collaboration! Get in touch by joining the Discord, hang out with the gang, get inspired.