CS315 Game Programming: Style

• Project structure
• Version control
• Code quality
• Asset files
• Content
• Intellectual property and licensing

Project structure

Include a README.md file at the top level of the project. This file will contain information about the project. Also include a file called EVALUATION.md that contains your self-evaluation. The self-evaluation documents which evaluation criteria you have fulfilled and what grade you therefore expect. If there are multiple iterations to an exercise, separate your self-evaluations with appropraite headings.

Your Godot project itself should be in the project subdirectory. For example, if your repository root is in a directory called my-game, then your directory structure for a new project should look like this:

my-game/
├── README.md
├── EVALUATION.md
└── project/
    ├── icon.svg
    └── project.godot

Group files together by feature, not by type. This keeps dependencies together and makes it easier to find things. For example, a hero directory might contain hero.tscn, hero.gd, hero_sprites.png, and attack.wav. Resources that are used across features should be in a top-level directory called common.

When you are ready to export your projects, configure them to export to a build folder at the repository root, with subdirectories named for the export platform. Keep the build folder out of version control by adding it to a top-level .gitignore file.

Version control

All repositories must be in the course organization on GitHub. Only source files should be tracked in version control: do not commit derived files nor builds.

There is one mainline branch named main or master.

Do not include files in the repository that are not used in the project.

Follow Chris Beams seven rules of a great git commit message, which are reproduced here for your convenience.

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

Beams pays particular attention to the subject line. Following these standards, the subject line finishes the sentence, “If applied, this commit will…”

If you realize that one of your commit messages needs to be updated, and you want to fix it, follow the useful guide provided by GitHub.

Every submission corresponds to a GitHub release. Name your release and the corresponding tag using semantic versioning with a major version of zero, a minor version of the iteration number, and the patch number for bugfixes. For example, your first iteration release should be tagged 0.1.0. If you discover a problem after tagging but before the deadline, you can make a new release tagged 0.1.1.

Code quality

Follow Godot Engine’s GDScript Style Guide.

Write self-documenting code and use comments sparingly.

Name variables clearly, avoiding abbreviations. For example, write character_position, not char_pos.

Commit no dead code. Scripts that have been detached from their scenes, scripts with no bodies, and methods that only pass are all dead code.

Include no editor warnings nor errors, and generate neither errors nor warnings at runtime. Do not change the editor settings to avoid this quality standard. Most warnings can be addressed with better engineering. In the rare case where using @warning_ignore is appropriate, explain the reason in source code comments.

Follow the principle Call Down, Signal Up. A node may only directly manipulate the nodes in its own tree. It must never “reach up” to its parent. This means that any call to get_parent() (including its syntactic equivalent, $..) should be considered suspect. For more information on this principle, see the Node communication article from KidsCanCode.

Asset files

All assets are in open file formats.

For audio files, use the formats described in the table below.

Content

Game designs uphold the values of the Beneficence Pledge. All content is appropriate for an ESRB Rating of E, E10+, or T.

Intellectual property and licensing

You must have a clear legal right to all the third-party work you incorporate, and you must abide by their licenses.

Track the origins and licenses of all third-party assets in your README.md file. This allows you to keep track of what is in your project so that you can audit it later.

If a license requires that a copy of the license itself be redistributed, keep a copy of that license alongside the asset in the project folder, naming it clearly.

For example, many fonts at Google Fonts are licensed under SIL Open Font License and are distributed with a file named OFL.txt that documents the terms. One such font is Roboto. Incorporating the font into the game and following this guide, you should expect to see a structure like this:

my-game/
├── README.md
└── project/
    └── ui/
        ├── Roboto-VariableFont_wdth,wght.ttf
        └── Roboto_OFL.txt

For projects that are kept internal to the class, there are no additional steps required. These projects are internal studio experiments and not intended for public display, and these steps ensure we have done due diligence should the project continue.

Public works must fully follow the licensing requirements. Godot Engine itself provides helpful documentation about how to comply with licenses, including tips that facilitate the process for Godot Engine projects.