Skip to content

Contributing

Jump to bottom
Manuel Quiñones edited this page Mar 10, 2026 · 7 revisions

We welcome contributions to Threadbare! This document lays out some of the requirements for a contribution to be expected. There is a corresponding document for Reviewing Contributions.

Licensing

Please see the separate Licensing documentation. This is more important than anything else in this document. If your contribution uses code or assets under an unsuitable license, we cannot accept it, even if it meets the other requirements below.

(By constrast, the maintainers can normally fix suitably-licensed contributions if they don't quite meet the requirements below.)

Language

In-game text and dialogue for the main storyline should be written in English, for translation into other languages. Text and dialogue in StoryQuests may be written in another language if preferred.

Prefer US English spellings for in-game text and dialogue, as well as source code, comments, and pull request descriptions:

  • “Color”, not “colour”
  • “Traveler”, not “traveller”

Use “dialogue” when referring to in-game speech (following the DialogueManager API), but “dialog” if referring to a dialog box.

Coding style

GDScript source code should follow the GDScript style guide. This is enforced using gdlint and gdformat from godot-gdscript-toolkit when changes are submitted to the project.

You can use pre-commit to run the same checks locally. pre-commit. pre-commit is written in Python, so if you don't have Python installed, you'll also need to install Python. The Threadbare team recommends using uv to install and manage pre-commit, as well as installing Python if needed.

Install pre-commit with uv

  1. Install uv using these instructions

  2. Install pre-commit:

    uv tool install pre-commit

  3. If you need to upgrade pre-commit in future, use this command:

    uv tool upgrade pre-commit

Note

If you prefer to install pre-commit another way, that's fine!

Set up pre-commit for Threadbare

Run the following command in your Threadbare checkout to set up pre-commit:

pre-commit install

Now, coding style checks will be enforced when you run git commit.

Threadbare's Godot conventions

Use Unique Names to reference nodes in scripts

We prefer to reference nodes in scripts by their Unique Name. In the Scene tree dock, right-click on the node and select Access as Unique Name in the context menu. Suppose we have a node named "HitBox" of type Area2D. With unique name, dragging and dropping the node from the Scene tree to the Script will paste %HitBox, and doing drag & drop while the Ctrl key is pressed will paste the line:

@onready var hit_box: Area2D = %HitBox

Which is very useful.

Connect signals to callbacks through the editor interface

We prefer to use the Signals tab next to the Inspector tab for connecting to signals. Thus, avoid connecting through the script like: (bad example follows) hit_box.body_entered.connect(_on_body_entered). When connecting through the editor interface you can select the node who's script the callback will be added. Plus there are a number of tricks:

  • Add extra call arguments. For example, the same _on_button_pressed() callback can be used by multiple buttons, each passing a different value to an extra argument.
  • Unbind (drop) signal arguments if you don't need them.
  • Tick options like Deferred, One Shot.

See the Godot Documentation for a step-by-step tutorial.

Use scene file + components/ subfolder structure

To make it easy to find the the .tscn file, leave it as the only file in the folder and move all related scripts or resources to a components/ subfolder. Example:

  • scenes/game_elements/characters/npcs/cat/cat.tscn
  • scenes/game_elements/characters/npcs/cat/components/cat.png
  • scenes/game_elements/characters/npcs/cat/components/cat.tres
  • scenes/game_elements/characters/npcs/cat/components/pet_interaction.gd

Exceptions:

  • For reusable assets, use the assets/first_party/ or assets/third_party/ folders instead.
  • For reusable scripts, use the scenes/game_logic/ folder instead.

Pull request descriptions

Pull requests should have:

  • A short title describing the intent of the change. The title should be in the imperative mood and formatted in sentence case (i.e. with a leading capital letter) but no trailing full stop or other punctuation mark. If appropriate, prefix the title with the component being modified.

  • One or more paragraphs explaining the change in more detail.

  • If the pull request resolves an issue, link the pull request to the issue with a line like this at the end of the description:

    Resolves https://github.com/endlessm/threadbare/issues/XYZ

    If the pull request relates to an issue without resolving it, include the issue link but not the Resolves keyword.

Here is an example:

Ink combat: Add ink follow player feature

The ink can now have a Node2D to follow. A constant force in that node direction will be set every frame.

The enemy has a boolean export to throw ink that follows the player node (the first and only node that should be in the "player" group).

Resolves https://github.com/endlessm/threadbare/issues/71

Your pull request will be squashed into a single commit when it is merged, and the title and description of the pull request will be used as the commit message. If you want to make several separate changes, open a separate pull request for each one. This is subjective, so use your judgement!

These articles and presentations give more background on how and why to craft a good commit message:

Multiple authors

If multiple people have contributed to a single change, special care must be taken to make sure they each receive credit for their work. If a pull request is made up of several commits, with different authors, this is sufficient. But if all commits on a pull request are made by the same person, the other contributors must be identified with a specially-formatted tag in the pull request description, as described in GitHub's Creating a commit with multiple authors guide. In brief, if Jane Doe submits a pull request to add a new enemy, with original art created by Alice Jones, the pull request description should end with:

Co-authored-by: Alice Jones <alice.jones@example.com>

If you're not sure how to do this, the Threadbare maintainers will be happy to help.

Clone this wiki locally