Subjunctive – a tile-based puzzle game engine for Python 3

Note: Subjunctive’s API is not at all stable. We are still in the early development stages and things are likely to change a lot!

Status of the games

Think Green

Think Green is complete except for the following things, which are totally missing:


Floorpaint has partially complete level-file-loading, but that’s about it. It is missing:



Subjunctive requires:

Hint: If you’re not already using Linux, now would be a good time to consider doing so. Installing all this stuff would be as simple as

$ pacman -S git python3 python3-virtualenv sdl2 sdl2_gfx sdl2_image sdl2_mixer

To get all everything set up, clone our repository, create a virtualenv, and install dependencies:

$ git clone
$ cd subjunctive
$ virtualenv env
$ env/bin/pip install -e .

Notes for Windows users: You’ll have to modify the commands slightly to work for Windows. For example, the Windows version of virtualenv names the bin directory Scripts instead. You’ll also have to type the .py extension when you run If you have trouble, make sure that the directory containing is in your PATH environment variable.

$ git clone
$ cd subjunctive
$ env
$ env/Scripts/pip.exe install --allow-unverified pysdl2 -e .

We recommend running these commands via Git Bash (which should have been installed along with Git) instead of the Windows command prompt.

Running the games

After installing as described in the previous section, you can run the games like so:

$ env/bin/<game>.py

For example,

$ env/bin/


$ env/Scripts/python.exe env/Scripts/

Adding a new game

Add your game’s script to the scripts list in Then, re-run

$ env/bin/pip install -e .


$ env/Scripts/pip.exe install --allow-unverified pysdl2 -e .

Goals / design principles

Obviously the main goal is that it be significantly easier to implement a game with Subjunctive than without. To accomplish that, here are some general design principles:

And, as usual, the Zen of Python provides excellent guidance.



Code/text format

Commit messages

Refer to A Note About Git Commit Messages.

Set-up for contributing

So, you want to help out? It’s pretty easy, but there are a few things you need to set up first.

  1. Python

    You need Python 3.3 or newer. You should be able to open a terminal and run the Python interpreter by typing python or python3.

    If you already know some programming, the official Python Tutorial will teach you the basics. Be sure to run the Python interpreter and try the examples as you read! If you don’t know any programming yet, Codeacademy’s Python track is a good place to start.

  2. Git

    Install the standard Git from Unless you know better, use the default options. If you’re on Windows, you should also install the Git credential helper so you don’t have to enter your username and password every time.

    If you have never used Git before, I recommend Ry’s Git Tutorial to learn the basics. If you already know the basics but need a reference (and you find the manual pages too confusing), look at Git Reference.

    On Linux or Mac OS, you’ll run Git commands using any terminal program. On Windows, you’ll use Git Bash (which was installed with Git).

    Don’t forget to configure Git with your name and email address:

    $ git config --global "John Smith"
    $ git config --global ""

    Note that this email address will be publicly viewable through GitHub.

  3. GitHub

    Create an account on GitHub and log in. Make sure the email that you configured Git with is associated with your account (you can associate additional email addresses in the account settings).

    Navigate to this page and click the Fork button. Once the process completes, look down the right side of the page for the clone URL (on Windows you’ll want the HTTPS URL; on Linux or Mac OS you probably want the SSH URL). Use this to clone the repository to your computer.

    $ git clone <URL>

    This will create a directory called subjunctive.

    You’ll also want to set up our repository as a remote.

    $ git remote add ufgmg
  4. your editor

    I strongly recommend against trying to use an IDE for this relatively small project! For Linux, I recommend Vim (if you can handle the awesome) or Gedit. For Windows, I recommend Sublime Text (shareware but awesome) or Notepad++ (open source).

    Figure out how to set up your editor so that it follows the rules mentioned in the Code Guidelines above.

Git Workflow

  1. Fetch the latest commits from all of your remote repositories.

    $ git fetch --all
  2. Checkout a new branch for the feature you want to work on, starting from the ufgmg/master branch.

    $ git checkout ufgmg/master
    $ git checkout -b <new branch name>
  3. Do stuff. Write codes, consume foods, etc.

  4. Commit as necessary. Some steps are optional.

    $ git status          # See what files have uncommitted changes
    $ git diff            # See your actual changes line-by-line
    $ git add <files>     # Add files to the staging area
    $ git status          # Check that you've staged the right files
    $ git diff --cached   # (paranoid) see the line-by-line staged changes
    $ git commit          # Commit it
  5. Repeat steps 3–4 as necessary.

  6. Maybe rebase to include newer commits from other people.

    Say, for example, that a new feature or fix has been committed on ufgmg/master and you need to incorporate it into your branch. Usually the best way to do this is via a rebase.

    $ git fetch --all
    $ git rebase ufgmg/master

    Basically what this does is tries to apply your commits, one at a time, on to the commits already on ufgmg/master. If conflicts occur (which they often do!), the rebase will pause for you to fix the issues. Running git status liberally during a rebase will help you stay sane.

    Note that rebasing causes your commits to be re-written (i.e., they get new hashes), so if you’ve already pushed your branch then pushing it again after the rebase will most likely fail (because doing so would mean replacing the commits you had pushed earlier). If you know no one else is using your branch, you can use the --force option when you push; alternatively, you can just give your branch a new name and then push it.

  7. Repeat steps 3–6 as necessary.

  8. Push to your GitHub repository.

    $ git push origin <branch name>
  9. Repeat steps 3–8 as necessary.

  10. Maybe rebase to clean up your branch’s history.

  11. Send a pull request.