GrapeJuiceCity

Installation & Setup

GitHub

Installation

1. Install GitHub Desktop.

   • If you prefer, you can install Git instead, but most students are less familiar with the commandline and prefer a GUI.

GrapeJuiceCity Repository

1. Accept the GitHub/email invitation to become a collaberator on the TimeKeepers repository.

2. In GitHub Desktop, clone the repository:

   • GitHub Desktop > File > Clone Repository... > sandint2011/TimeKeepers.

Unity

Installation

1. Install Unity Hub.

   • Unity Hub might require an update, so open it and update/restart if it asks.

   • Unity Hub might also require you to activate a license, so be sure to follow the instructions (there is a free license).

2. In Unity Hub, install the Unity Editor version 2021.3.10f1 (LTS).

   • Unity Hub > Installs > Install Editor > 2021.3.10f1 (LTS) > Install

Preferences & Settings

1. Set the Play Mode tint to red (optional but helpful).

   • Unity > Edit > Preferences... > Colors > Play Mode tint > #FFA0A0.

2. Set objects to create at origin instead of camera pivot (optional but useful).

   • Unity > Edit > Preferences... > Scene View > Create Objects at Origin > CHECK.

3. Reconfigure the editor layout as you see fit. You can drag panels around and use the Window tab to add more panels.

   • I've made a layout with most of the panels we'll use; feel free to use it.

     • Unity > Window > Layouts > Load Layout from file... > Layout.wlt.

VS Code

Installation

1. Install Visual Studio Code.

2. Install the .NET SDK.

C# & Unity Extensions

1. Install the following VS Code extensions (press Ctrl+Shift+X to open the extensions tab).

   • C#

   • C# Snippets

   • Debugger for Unity

   • Unity Code Snippets

   • Unity Snippets

   • Unity Tools

Unity Settings

1. Set Unity's default script editor to VS Code.

   • Unity > Edit > Preferences... > External Tools > External Script Editor > Visual Studio Code.

C# Coding Conventions

This is a shortened and slightly modified version of Microsoft's .NET C# coding conventions.

There is an auto-formatter set up for VS Code, so anything it automatically handles (like tabs, spacing, and newlines) is omitted from this list. Auto-formatters can only do so much, though, so some things (like naming conventions) need to be managed ourselves.

Naming Conventions

Pascal Case

Use pascal casing ("PascalCasing") when naming a class, record, or struct.

public class Player
{
}

public record Rectangle(
    float X,
    float Y,
    float Width,
    float Height
);

public struct Action
{
}

When naming an interface, use pascal casing prefixed with an I.

public interface IEnemy
{
}

Use pascal casing for all public members such as fields, properties, events, methods, and local functions.

public class Events
{
    // Public field. Properties should be preferred to public fields.
    public vool isValid;
    
    // An init-only property.
    public IEventQueue EventQueue { get; init; }
    
    // An event.
    public event Action Event Processing;
    
    // Method.
    public void StartEventProcessing()
    {
        // Local function.
        static int CountQueueItems() => EventQueue.Count;
        // ...
    }
}

When writing positional records, use pscal casing for parameters, as they're the public properties of the record.

public record Rectangle(
    float X,
    float Y,
    float Width,
    float Height
);

Camel Case

Use camel casing ("camelCasing") when naming private or internal fields..

public class Player
{
    private int baseHealth;
}

Use camel casing for method parameters.

public void setHealth(int health)
{
    // ...
}

Layout Conventions

Use the auto-formatter's layout changes whenever they're applied. If the auto-formatter has no preference, use the following conventions instead.

Write only one statement per line.

// Good.
player.resetHealth();
player.resetExperience();

// Bad.
player.ResetHealth(); player.ResetExperience();

Write only one declaration per line.

// Good.
int x;
int y;

// Bad.
int x; int y;

// Also bad.
int x, y;

Never use more than 1 blank line between code or comment lines.

// Good.
int a = 1;
int b = 2;

int c = 3;

string x = "Hello";

// Bad.
int a = 1;
int b = 2;

int c = 3;



string x = "Hello";

Separate block elements methods from each other and from fields and parameters with a blank line. Fields and properties can be grouped together, though.

// Good.
class Player
{
    public int Health { get; set; }
    public int Experience { get; set; }
    
    public void ResetHealth()
    {
        Health = 100;
    }
    
    public void ResetExperience()
    {
        Experience = 0;
    }
}

// Bad.
class Player
{
    public int Health { get; set; }
    public int Experience { get; set; }
    public void ResetHealth()
    {
        Health = 100;
    }
    public void ResetExperience()
    {
        Experience = 0;
    }
}

Do not place fields or properties between methods.

// Good.
class Player
{
    public int Health { get; set; }
    public int Experience { get; set; }
    
    public void ResetHealth()
    {
        Health = 100;
    }
    
    public void ResetExperience()
    {
        Experience = 0;
    }
}

// Bad.
class Player
{
    public int Health { get; set; }
    
    public void ResetHealth()
    {
        Health = 100;
    }
    
    public int Experience { get; set; }
    
    public void ResetExperience()
    {
        Experience = 0;
    }
}

Do not start or end blocks with blank lines.

// Good.
class Player
{
    void Ready()
    {
        health = 100;
        experience = 0;
    }
}

// Bad.
class Player
{
    
    void Ready()
    {
        
        health = 100;
        experience = 0;
    }
    
}

If continuation lines are not indented automatically, indent them one tab stop (4 spaces).

// Ideal, but too many parameters might make for a long line.
SetPosition(player.GetX(), player.GetY(), player.GetZ());

// Good.
SetPosition(
    player.GetX(),
    player.GetY(),
    player.GetZ()
);

// Bad.
SetPosition(
            player.GetX(),
            player.GetY(),
            player.GetZ()
);

Continuous lines should end their parenthesis on their original indentation, with the first of multiple parameters (if there are any) getting its own line.

// Ideal, but long lines might need breaking up.
Vector3(x, y, z);

// Good.
Vector3(
    x,
    y,
    z
);

// Bad.
Vector3(x,
    y,
    z
);

// Bad.
Vector3(x,
    y, z);

Commenting conventions.

Begin comments with a space and a capital letter.

End comments with a period.

Do not add more than 2 slashes at the start of a comment.

// Good.

///bad

Place comments on their own line, not at the end of code lines.

// Good.
Foo();

Bar(); // Bad.

Don't create formatted blocks of asterisks around comments.

// Please
// do
// this.

// Or this.

/* Please
 * don't
 * do
 * this.
 */

/* Please don't do this either. */

Strings

Concatinate strings with string interpolation, rather than concatination, unless there are no hardcoded strings being added.

// Good.
string fullName = $"{firstName}, {lastName}";

// Good, since there are only variables and no hardcoded strings.
string fullName = fullName + commaSeparator + lastName;

// Bad.
string fullName = firstName + ", " + lastName;

Data types

Implicitly typed local variables

Don't do them.

// Good.
string sentence = "This is a string.";
int number = 5;

// Bad.
var sentence = "This is a string.";
var number = 5;

Numbers

Use int over short or long unless it's absolutely necessary.

Use float over double unless it's absolutely necessary, since Unity's classes and methods generally use them (most notably Vector3).

In general, use unsigned types (like short, int, or long) over unsigned types (like byte, ushort, uint, or ulong). This is because it makes refactoring to allow signed numbers in the future easier.

Arrays

Use concise array initialization syntax in the declaration line.

// Good.
string[] letters = { "A", "B", "C" };

// Bad.
string[] letters = new string[] { "A", "B", "C" };

try-catch and using statements

When using try-catch or using statements for exception handling, do not use them to hide the error. We want things to break as loudly as possible so they're easier to debug, as we can see exactly what went wrong and where.

// Good.
try
{
    return array[index];
}
catch (System.IndexOutOfRangeException e)
{
    Debug.Log("Index out of range: {0}", index);
}

// Bad.
try
{
    return array[index];
}
catch (System.IndexOutOfRangeException e)
{
    // Do nothing and/or fail silently.
    return defaultValue;
}