Git Clients

To get a hold of the project, you need a git client. Git is the software that manages the source. GitHub is the website that we use to host it. If you are new, GitHub Desktop is easiest for beginners.

Our Repositories

Forking the Repository

To start contributing via GitHub, first you should fork this GitHub repository, using the 'Fork' button in the upper right corner of this page. Naturally, this requires a GitHub account. You will commit your changes to your fork and then make a pull request to merge it into our repository. Learn more about pull requests here.

Over time your fork will become outdated as the main project's repository continues to be added upon. GitHub has made a pretty clear guide on how to sync your fork, to keep it up to date with the SS3D repository.

Reporting Bugs

Before reporting a bug, please check the our issues to see if the bug has already reported.

If you are unfamiliar with issues, GitHub has a helpful guide here. Use one of the templates when creating your issue, as the information it requests helps you help us help you more efficiently.

Explain the problem clearly and include any additional details to help maintainers reproduce the problem:

• Use a clear and descriptive title for the issue to identify the problem.

• Describe the steps to reproduce the problem as specifically and detailed as possible.

• Describe the behavior you observed and point out the problem with that behavior.

• Describe the expected behavior that should happen instead.

• Include pictures/videos to show the steps taken to demonstrate the problem.

• Include your game version and OS to help track if the problem is version specific.

• Include your game settings to help track if the problem is settings specific.

• If you're reporting a game crash, include a crash report with the error log. It's location depends on your operating system, so follow this official guide.

• If the problem isn't triggered by a specific action, describe what you were doing before the problem happened.

Pull Requests

Pull requests allow the maintainers to review any changes and verify they are wanted and don't break anything in the existing project. Similarly to issues, you should use the template when making a new PR and provide as much detail as possible.

• Pull requests should merge into the develop branch.

• The title and description should be clear and concise.

• If the PR is attempting to fix an issue, reference the issue number in the PR description ("Fixes #number").

• Include pictures/videos in your pull request whenever possible.

Assigning Issues

Our GitHub issues can be self-assigned using basic commands (see below). This is helpful for contributors to claim an issue without the assistance of a maintainer.

Type the following command as a comment on the issue in question. Assign me - assigns you to the issue. Unassign me - unassigns you from the issue.

Commit Messages

• Use the present imperative tense ("Add feature" not "Added feature", "Move cursor to..." not "Moves cursor to...").

• Limit the first line to 72 characters or less.

• Reference issues and pull requests liberally after the first line.

Code

All our code falls under the MIT license.

Art

All our art assets fall under the CC BY-NC-SA 4.0 license.

This page outlines the guidelines for contributing to the SS3D project. If you have any questions, feel free to ask on our discussions page or discord server.

The game itself is made in Unity and written in C#, check out our C# style guide. We use FishNet for networking.

For art contributors, read through the subpages under this page, then head over to the .

When (re)naming files and folders always do so using , this makes naming consistent which helps with organization and clarity.

✔️ Correct

LockerDoorAnimationController.file

❌ Wrong

Locker Door Animation Controller.file lockerdoor animation controller.file AnimationController - LockerDoor.file

Also, acronyms should be treated as words. For example: JanitorIdImage.file NOT JanitorIDImage.file

Downloading Unity

You will need the correct Unity version to run the project. There are two ways you can acquire it:

Method 1:

Check what our is, then find that specific version in the Unity download archives below.

Method 2:

Current Version

To avoid having to update the current version in this document every time it's updated, we will just point you to the version file instead.

Object type sorting is specific to object-related assets. Which is all assets in the Art folder and many in the Content folder.

The Assets folder on the GoogleDrive (and art repo) are organized the same as the Art folder on the game repo. First sorted by asset type, then by object type. Not all folders will have all types.

Object Types:

(The first 4 types in the list below are where 95% of common objects are kept.)

/Assets

Most of our project lives in this folder and as a result we need to keep it organized. As you may have guess the folder itself it broken up into various sub folders. Here is the ruling:

/Builds

This folder is for storing builds and their related assets like .bat files which we currently use for running the game as a developer.

/Documents

Documents is simple, it stores the basic documents for the repo.

/ProjectSettings

ProjectSettings stores all various settings and managers for the project.

Well, where do I start. To clear out and not let you disappointed, programming is hard, programming games is hard, and we also added an extra layer with networking programming. Many things we discovered while at it, which makes us rework many systems, but we learn from it which is what matters.

One thing that should be obligatory to every single programmer up to contributing to this project is to understand basic networking concepts. There’s is no game without networking.

Network Packets

Networking is all about communication. The way we communicate between machines is via network packets, which are pieces of data sent over the network. Networking games uses that, and usually we have that part done for us when we use a high-level networking framework, which is why you will rarely see that while developing basic networking code.

Host

Never think hosting is another type of network setup, it is the server and one client, at the same time, doing different things. It’s just a quick way to test your application, the only issue is that it can be misleading.

In order to network stuff we need a framework. We aren't doing it from scratch (again). We used to use Mirror but I found FishNet Networking, and I haven't used anything else since. It has free and paid features, which is lame, but we can use it at our favour.

I'll add important notes about developing with in the next sections.

Related links:

• FishNet's GitHub page

• FishNet's API documentation

Client

The client is a game instance that is connected to a server game instance, it receives all network packets the server wants to send it, so a character position is set by the server so every client sees your player in the same position.

Code that runs on the client

Logic that will only run on the client game instance. Usually in Unity game development we use attributes for defining those rules, they are little tags that go above the method declaration, which does depend a lot on the networking framework you’re using in your game.

We are using FishNet Networking, the attribute is [Client], but code that is not sent to either clients or the server is always local to that game instance, so you only use that when you want to prevent the server game instance running that code.

Client attribute

[Client]

The client attribute prevents the server from running a method.

Examples

[Client]
private void Setup()
{
    LastScreen = ScreenType.None;

    if (_canvasGroup != null)
    {
        bool foundCanvas = TryGetComponent(out CanvasGroup canvasGroup);
        _canvasGroup = foundCanvas ? canvasGroup : GameObjectCache.AddComponent<CanvasGroup>();
    }

    SetScreenState(ScreenType.Lobby, true);

    ChangeGameScreenEvent.AddListener(HandleChangeGameScreen);
    ChangeCameraEvent.AddListener(HandleChangeCamera);
}

What is a Server?

The server is an instance of the game that does all the network management, sending network packets (small portions of data) to client game instances that are connected to that server.

What will be sent to clients and what will remain on the server is on the programmer to decide, that’s what network programming is.

It guarantees every client game instance is seeing the game game, otherwise it would be analogue as seeing two different games being played in two different PCs.

Code that runs on the server

Logic that will only run on the server game instance, so any information not networked from any clients are unknown to the server, we cannot just network everything, that's a lot of information to send over the network, we are here to manage what should be networked and what should not.

All the code run in the server, will only run on the server. If we were to set a variable on the server and not replicate that logic on the client, that means the client would never know that was changed.

Server Attribute

[Server]

The Server attribute is used when we want to run methods only in the server.

Examples

/// <summary>
/// Sets a new controlling soul.
/// </summary>
[Server]
public void SetControllingSoul(Soul soul)
{
        _controllingSoul = soul;

        if (soul == null)
        {
        RemoveOwnership();
        }
        else
        {
        GiveOwnership(soul.Owner);
        }
}

[Server]
private void InitializeGamemode()
{
            // Creates an instance of the SO, to avoid using the file.
            _gamemode = Instantiate(_gamemode);

            _gamemode.OnInitialized += HandleGamemodeInitialized;
            _gamemode.OnFinished += HandleGamemodeFinalized;
            _gamemode.OnObjectiveUpdated += HandleObjectiveUpdated;

            _gamemode.InitializeGamemode();
}

Code that is called from the client to be run in the server, with the client information

Continuing the disgrace, there’s code that the client decides when to run and the server actually executes it, with the information the client gave it.

This is probably one of the most critical parts when we think about security, we sometimes we have to trust the client with what they are sending the server, so extra validation can be welcoming.

Anyways the attribute is [ServerRpc] this one has another trick at its sleeve, we have to own the object that we are trying to call the method, this can however be completed ignored by using [ServerRpc(ignoreAuthority = true)].

To guarantee you got it right, the params of the call will use data from the client, and the logic will be executed with the server’s data.

Code that is called from the server to be run on the client, with the information from the server

Usually here is where things get messy for some people, but for starters, the attribute is [ObserversRpc], RPC stands for remote-procedure-call, this one is called by the server, which means the server decides when to run it, and makes the client run it, with the information it wants.

That information is only valid for params, as the logic inside the code is run by the client, everything there only exists for the client, excepts for the method parameters sent by the server.

On the whole, naming should follow C# standards.

Network Messages

Network messages are a way to transmit data without having to worry about object relationships, they are basically global events, which anyone can subscribe and listen to. And we can create structures to send whatever we want via the network.

The downside of that is that it doesn’t support late joins, the client has to be connected in order to receive that, otherwise it would miss the message. We should only use them when we want to ask something for the server to do, without worrying about object relations.

This style guide is based on and expands upon it.

You can use whatever file editor you want, but is probably the most popular and recommended choice. It's free, has many features, and integrates well with Unity and Git.

If you're a student, we recommend getting a copy of which adds a lot of code hints and shortcuts that will significantly improve your code quality.

Our overarching goals are clarity, readability and simplicity. Also, this guide is written to keep Unity in mind.

Inspiration

This style guide is based on C# and Unity conventions, and discussions within the development team.

Automation

We recently added an file to automate the code review process, it is a file you can add to or and it will apply the formatting and style we use to your analyzers, telling you when something is out of order.

Namespaces are all PascalCase, multiple words concatenated together, without hypens ( - ) or underscores ( _ ):

Namespaces should be used for major systems, such as Atmospherics, or Electrics. Everything else should be without namespace.

BAD:

GOOD:

Delegates are written in PascalCase.

When declaring delegates, DO add the suffix EventHandler to names of delegates that are used in events.

BAD:

public delegate void Click()

GOOD:

public delegate void ClickEventHandler()

DO add the suffix Callback to names of delegates other than those used as event handlers.

BAD:

public delegate void Render()

GOOD:

public delegate void RenderCallback()

⚠️ IMPORTANT!

Using built.in C# features, such as Action, is encouraged in place of delegates.

Private fields have the _ prefix, static, const and public fields are in UpperCamelCase.

For example:

public class MyClass 
{
    public int PublicField;
    private int _packagePrivate;
    private int _myPrivate;
    protected int _myProtected;
}

BAD:

private int myPrivateVariable

GOOD:

private int _myPrivateVariable

Field Position

All fields should be at the top of the class, before any methods.

Classes are written in PascalCase. For example RadialSlider.

Interfaces should always have the prefix I, as in IOpenable.

Parameters are written in camelCase.

BAD:

GOOD:

Single character values are to be avoided except for temporary looping variables. You can also use _ for unused variables, m for and e for .

Methods are written in PascalCase. For example DoSomething().

[SyncVar(OnChange = nameof(SyncUsername))] string _username;

private void SyncUsername(string oldUsername, string newUsername, bool asServer) {}

clownBomb.OnExploded += HandleClownBombExploded;

private void HandleClownBombExploded() 
{
    Honk();
}

[Server]
public void ServerKillPlayer() {}
[Server]
public void KillPlayer() {}

[ServerRpc]
public void CmdSpawnItem(GameItems item) 
{
    SpawnItem(item);
}

[ObserversRpc]
private void RpcSpawnVisualProjectives() 
{
   _particleSystem.Play();   
}

Prefix event methods with the prefix On.

BAD:

GOOD:

In code, acronyms should be treated as words. For example:

BAD:

XMLHTTPRequest
String URL
findPostByID

GOOD:

XmlHttpRequest
String url
findPostById

A class must respect the following order, from top to bottom

• Events and delegates declaration.

• Private enums declaration.

• Private internal classes.

• Member variables.

• Properties.

• Methods.

BAD:

 public sealed class Container : NetworkActor
    {
        public event ContainerContentsHandler OnContentsChanged;

        public Vector2Int Size;
        public AttachedContainer AttachedTo { get; set; }
        
        [SyncObject]
        private readonly SyncList<StoredItem> _storedItems = new();
        
        private readonly object _modificationLock = new();
        
        public float LastModification { get; private set; }
        
        public delegate void ContainerContentsHandler(Container container, IEnumerable<Item> oldItems,IEnumerable<Item> newItems, ContainerChangeType type);

        ...

GOOD:

 public sealed class Container : NetworkActor
    {
        public event ContainerContentsHandler OnContentsChanged;
        public delegate void ContainerContentsHandler(Container container, IEnumerable<Item> oldItems,IEnumerable<Item> newItems, ContainerChangeType type);
  
        public Vector2Int Size; 
        private readonly object _modificationLock = new();
        
        [SyncObject]
        private readonly SyncList<StoredItem> _storedItems = new();
        
        public AttachedContainer AttachedTo { get; set; }
        public float LastModification { get; private set; }
   

        ...

Exactly one class, struct, enum, or interface per source file, although inner classes are encouraged where scoping appropriate.

Access level modifiers should be explicitly defined for classes, methods and member variables. This includes defining private even though C# will implicitly add it.

Use the least accessible access modifier, except for public member that is expected to be used by other classes in the future.

Fields & Variables

Prefer single declaration per line.

BAD:

string username, twitterHandle;

GOOD:

string username;
string twitterHandle;

Spacing is especially important to make code more readable.

Indentation

Indentation should be done using tabs — never spaces .

Blocks

Indentation for blocks uses tabs for optimal readability:

BAD:

for (int i = 0; i < 10; i++) 
{
  Debug.Log("index=" + i);
}

GOOD:

for (int i = 0; i < 10; i++) 
{
    Debug.Log("index=" + i);
}

Line Wraps

Indentation tab for line wraps should use 4 spaces (not the default 8):

BAD:

CoolUiWidget widget =
        someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line);

GOOD:

CoolUiWidget widget =
    someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line);

Line Length

Lines should be no longer than 100 characters long.

Vertical Spacing

There should be just one or two blank lines between methods to aid in visual clarity and organization. Whitespace within methods should separate functionality, but having too many sections in a method often means you should refactor into several methods.

All braces get their own line as it is a C# convention:

BAD:

class MyClass {
    void DoSomething() {
        if (someTest) {
          // ...
        } else {
          // ...
        }
    }
}

GOOD:

class MyClass
{
    void DoSomething()
    {
        if (someTest)
        {
          // ...
        }
        else
        {
          // ...
        }
    }
}

Conditional statements are preferred to be enclosed with braces, irrespective of the number of lines required. Some cases can be pardoned.

BAD:

if (someTest)
    doSomething();  

if (someTest) doSomethingElse();

GOOD:

if (someTest) 
{
    DoSomething();
}  

if (someTest)
{
    DoSomethingElse();
}

Use US English spelling.

BAD:

string colour = "red";

GOOD:

string color = "red";

The exception here is MonoBehaviour as that's what the class is actually called.

Whenever someone add a script implementing NetworkBehaviour, they have access to the following attributes, indicating if a given method should be server only, client only, or both :

• [Server] for server only code.

• [Client] for client only code.

• [ServerOrClient] for both.

Make sure no methods goes without an attribute in a script inheriting NetworkBehaviour. The goal is to increase readability and to generate warnings or exceptions when clients or server are attempting to call something they should not.

Methods with [ServerOrClient] attributes should stay uncommon, they make debugging harder. If possible, try to refactor the code to avoid them.

Switch-statements come with default case by default (heh). If the default case is never reached, be sure to remove it.

If the default case is an unexpected value, it is encouraged to log and return an error

BAD

switch (variable) 
{
    case 1:
        break;
    case 2:
        break;
    default:
        break;
}

GOOD

switch (variable) 
{
    case 1:
        break;
    case 2:
        break;
}

BETTER

switch (variable) 
{
    case 1:
        break;
    case 2:
        break;
    default:
        Debug.LogError("Unexpected value when...");
        return;
}

This section includes some rules of thumb for design patterns and code structure

Error handling

Avoid throwing exceptions. Instead log and error. Methods returning values should return null in addition to logging an error

BAD:

public List<Transform> FindAThing(int arg){
    ...
    if (notFound) {
        throw new NotFoundException();
    }
}

GOOD:

public List<Transform> FindAThing(int arg){
    ...
    if (notFound) {
        Debug.LogError("Thing not found");
        return null;
    }
}

Finding references

Don't use Find or in other ways refer to GameObjects by name or child index when possible. Reference by reference is less error prone and more flexible. Expect people to set the fields in the inspector and log warnings if they don't.

BAD:

private GameObject _someMember;

private void Start() {
    _someMember = GameObject.Find("ObjectName");
}

RequireComponent

Prefer RequireComponent and GetComponent over AddComponent. Having the components in the inspector let's us edit them. AddComponent limits us.

BAD:

public class : MonoBehaviour
{
    private AudioSource _audioSource;

    private void Start() {
        _audioSource = gameObject.AddCompenent<AudioSource>();
    }
}

GOOD:

[RequireComponent(typeof(AudioSource))]
public class : MonoBehaviour
{
    private AudioSource _audioSource;

    private void Start() {
        _audioSource = GetCompenent<AudioSource>();
    }
}

Properties with backing fields

Properties can be used for access control to fields, and when using backing fields they can be private and let us change them in the inspector. Consider when a fields should be public and prefer properties with backing fields.

Sometimes it's just nice to see them for debugging, even if we don't change them, so consider making more of your private fields visible.

OKAY:

public GameObject SomeMember;

BETTER:

[SerializeField] private GameObject _someMember;
public GameObject SomeMember => _someMember;

Actor is our substitute for MonoBehaviours, it optimizes and creates shortcuts for useful stuff.

transform.position = new Vector3(0, 0, 123);

Position = new Vector3(0, 0, 123);

Networking

For networked objects, instead of NetworkBehaviour, you will use NetworkActor. They work the same way as Actor.

Programming Definitions & Important notes

• Always ask the lead programmer if you're in doubt.

• Remember, we gotta network stuff.

• Use _variableName for private variables.

• Use VariableName for public, const and static variables.

• Never use underscores.

• Never use abbreviated variables, except (if any missing or you'd like to suggest one please contact the lead programmer): i, j, rb, ui, gui, id, x, y, z, args, config.

• Avoid singletons at all costs.

• Avoid numbers in variables.

• Always unsubscribe from events.

• Document everything you can, the idea is: anyone with beginner understanding of code should read and understand the code, knowledge is everything and we got to provide that to newcomers and instruct them. This is the way.

• Don't leave Debug.Logs, and always remove unused commented code.

• Do not touch other people's code, if you're not directly working with it.

A view is a controller for an user interface, it sets the parameters, controls buttons, etc. A view's existence is never known by systems.

public sealed class RoundTimeView : Actor 
{
    // add time logic
}

If we need to network a view, we can either use a direct call on a system or use network messages. Do not use the event bus's events for that.

⚠️ IMPORTANT!

Always add the postfix "View" in the name of the class for your views.

A system is a class that manages something, it should work on its own, the only exception is when it needs information about other system, but it is preferable that you do that by using events or event buses or network messages.

A system can be networked or not, for that you can inherit your class from System or NetworkSystem.

Here's a snipped of now you can declare a system that creates explosion somewhere.

public sealed class ExplosionSystem : NetworkSystem 
{
    public void CreateExplosionAt(Vector3 position, float size) 
    {
        // boom.
    }
}

It is also important that you know all the systems work with the SystemLocator class

The event bus is a design pattern, it serves the purpose of a "global event system" as it can be invoked from anyone, anywhere and can be listened by anyone, anywhere.

The implementation we use was created by the CS Framework and we use it to create new event buses. To understand further on the design pattern itself, you can read this article.

We use these events when we want something that will be used in more than one place, without having to care about object relation.

We usually want events to be fired by systems when we want to inform other objects something has happened, like a round timer being updated, a player that spawned, an object that was picked up.

public partial struct RoundTimerUpdatedEvent : IEvent 
{
    public int TimerSeconds;
}

public partial struct RoundTimerUpdatedEvent : IEvent 
{
    public int TimerSeconds;
    
    public RoundTimerUpdatedEvent(int timerSeconds) 
    {
        TimerSeconds = timerSeconds;
    }
}

Pretty straight-forward isn't it? Well, now for the usage.

RoundTimerUpdatedEvent event = new RoundTimerUpdatedEvent(30);
event.Invoke(this);

protected override void OnAwake() 
{
    base.OnAwake();
    
    RoundTimerUpdated.AddListener(HandleRoundTimerUpdated);
}

private void HandleRoundStateUpdated(ref EventContext ctx, in RoundStateUpdated e) 
{
    Debug.Log(e.TimerSeconds);
}

protected override void OnAwake() 
{
    base.OnAwake();
    
    AddHandle(RoundTimerUpdated.AddListener(HandleRoundTimerUpdated));
}

[SyncObject] private readonly SyncList<string> _readyPlayers = new();

_readyPlayers.OnChange += HandleReadyPlayersChanged;

private void HandleReadyPlayersChanged(SyncListOperation op, int index, string s, string newItem1, bool asServer)
{
    SyncReadyPlayers();
}

private void SyncReadyPlayers()
{
    ReadyPlayersChanged readyPlayersChanged = new(_readyPlayers.ToList());
    readyPlayersChanged.Invoke(this);
}

An Action is an event that depends on an object to exist.

The Action event should be used when we don't need something to be accessed globally, like a button being pressed, or when we need to listen from something from a specific object.

public class ButtonView : Actor 
{
    public event Action OnButtonPressed;
}

public event Action<int> OnNumberUpdated;
public event Action<Item> OnItemUpdated;

Using an Action

Let's imagine you have a granade in your character's hand. Pretty common sight in a Low RP server. In the code, usually we would have something like:

public class Granade : Explosive 
{
    public event Action OnPinRemoved;
    
    public void RemovePin() 
    {
        // Do pin removal logic.
    
        OnPinRemoved?.Invoke();
    }
}

The OnPinRemoved event will be used to to tell listeners that subscribed to that granade's event that the granade's pin was removed. The relevance of that OnPinRemoved event is usually for UI related purposes, or running a local animation of a granade pin flying through your screen.

Something like:

public class GranadePinAnimationView : Actor 
{
    private GranadePinAnimation _granadePinAnimation;

    private Granade _granade;
    
    protected override OnAwake() 
    {
        _granade.OnPinRemoved += HandlePinRemoved;
    }
    
    protected override OnDestroyed() 
    {
        _granade.OnPinRemoved -= HandlePinRemoved;
    }
    
    private void HandlePinRemoved() 
    {
        _granadePinAnimation.RunAnimation();
    }
}

You might even think it would be easier to call it directly, and depending on your logic it might be, but we are assuming that in this case its better to keep the classes decoupled.

All assets should meet the specified criteria when contributing to the project, and maintainers will refer back to this when reviewing GitHub PRs and direct art submissions in Discord.

General assets are categorized by 2 types in our project as you should know from our file organization. These two types, internal and external, have different criteria based on their nature.

The sub pages contained under this one will be split based on these 2 types, but we will also be adding a 3rd page to represent the importing criteria of external assets.

External Asset Criteria

The criteria used to check art assets BEFORE importing them into Unity.

This criteria specifically focuses on the details of the file as it was created in whatever external (non-Unity) program.

Many of these art assets were already check based on our criteria when they were originally submitted, but many (especially the older ones) have not. So all art assets should be double checked prior to being imported into the Unity project via a GitHub pr.

Due to the nature of different art asset types, we have different acceptance criteria for each. This includes 3d models, 3d animations, textures, graphics, and audio.

Also, each art asset type is not bound by 1 set of criteria. Because assets of the same type are used in different ways inside the project they may have different acceptance criteria based on their use.

The following subpages are based on asset types while they may have sub pages but will be based on object type.

The SystemLocator is a class used to easily find any system that has been registered on it.

It helps us avoid falling into the Singleton pattern, and does something similar to the Service Locator pattern. Also good for performance reasons, It can handle over a million calls every frame with no issues.

Using the SystemLocator

To register a new system you can call the SystemLocator.Register(this) method, it'll add that system into a dictionary of systems, preventing two of the same system from existing.

Then you can get this system from somewhere else using SystemLocator.Get<T>()

⚠️ IMPORTANT!

Note that is done automatically by classes inheriting System and NetworkedSystem. They register on Awake:

public class System : Actor
    {
        protected override void OnAwake()
        {
            base.OnAwake();
            SystemLocator.Register(this);
        }
    }

Examples

Importing Asset Criteria

The criteria used to check art assets WHILE importing them into Unity.

Art assets have different options and settings in Unity based on their file type. Also, files of the same type may have different criteria here depending on how they will be used in the project.

Dependent assets like prefabs may not function properly if the options are not correctly set on these art assets.

The following subpages are based on asset types while they may have sub pages but will be based on object type.

Internal Asset Criteria

The criteria used to check non-art assets CREATED within Unity itself.

This part focuses on those assets that are created in Unity and like .prefabs, .materials, etc.. Again these criteria may vary depending on usage.

The following subpages are based on asset types while they may have sub pages but will be based on object type.

I'll fill these subpages later, promise.

I'll fill these subpages later, promise.

I'll fill these subpages later, promise.

This is a draft to remind us we have to write this little guide.

• Avoid using Debug.Log, use Punpun logger instead. This is because we get much more relevant data using Punpun compared to Debug.Log.

• Use SystemLocator instead of the Find method from Unity when trying to get a reference. This is less prone to break and more efficient.

• To get an input, don't use Unity's built in methods, use instead our input system (put link there)

This pages contains a list of code patterns that we use in developing SS3D. We recommend you to take a look as those patterns improve the code quality, testability, reusability.

Humble object pattern

This design came from the necessity to answer the following question : How do we make code testable in a class tightly coupled with its environment ?

In our case, that's what happen in our codebase with everything inheriting from monobehaviour, or worse, from networkbehaviour. All networkbehaviour objects are tightly coupled to both Unity framework, and Fishnet framework.

To remedy to this issue, we split the object in two, one "Plain Old Class Object", containing the logic we want to test, and one object tightly coupled to our framework, handling only framework stuff.

A great introduction to this concept in the following video :

If you want to learn more about it, XunitPatterns.com goes into great details.

In our codebase, you can see this pattern in action with the Container and AttachedContainer class. The container class is the testable object containing most of the logic, the AttachedContainer class contains the framework logic, networking and Unity stuff.

(Soft) Humble object pattern

Sometimes, applying a strict humble object pattern causes more trouble than good. Duplicating code, loss of encapsulation, code difficult to read ... It's not always worth it.

We encounter many of those issues while working on the Item class. After many attempts, ending with overly complicated and hacky codes, we were not satisfied.

That's when we decided to not apply a strict humble object pattern (splitting a class in two different classes), but rather to draw some inspiration from it to come with the following set of rules :

• Keep everything in the same class.

• Separate framework and logic code in different methods.

• Make logic in method involving framework code as simple as possible, consider this method untestable.

• Write code to make it work in both framework and unit test context.

Instead of splitting in two different classes, we split our code in different methods, and/or we rewrite it so it works as well in both framework and unit test context.

Practical case, the SetContainer method of the Item class.

Command Line Args

The command line args are various symbols used to define arguments to be used by the SS3D application when it runs. The reason for it existing is to easily add Hub support for it when we eventually have it.

Here's a little example on how they look, you can find all them in the CommandLineArgs.cs file

/// <summary>
/// The "-serveronly" arg in the executable.
/// </summary>
public const string ServerOnly = "-serveronly";
/// <summary>
/// The "-host" arg in the executable.
/// </summary>
public const string Host = "-host";
/// <summary>
/// String.
/// </summary>
public const string Ip = "-ip=";
/// <summary>
/// String.
/// This is temporary, in production use, this will not exist,
/// and be replaced by the token, and then the server will get the Username.
/// </summary>
public const string Ckey = "-ckey=";
/// <summary>
/// String.
/// in production this will be sent by the Hub to the client executable.
/// </summary>
public const string AccessToken = "-token=";
/// <summary>
/// Bool.
/// Skips the intro.
/// </summary>
public const string SkipIntro = "-skipintro";
/// <summary>
/// Bool.
/// Disables the discord integration.
/// </summary>
public const string EnableDiscordIntegration = "-enablediscordintegration";

Using Application Settings window

The application settings window reflects information used on the Command Line Args, it is useful for Editor overrides and internally we use it along the command line args when using built executables.

In the project settings window, you can find the Application Settings group, where you can see all the settings related to what configurations the game will use when running.

This only contains settings related to the application use. Graphics, sound, and user settings will not be defined there.

If you're developing, you'll need at some point to build the game so you can test it with multiple clients.

You can follow here if you need help with that.

We currently have two scenes in game, include them both, and you should be fine by leaving everything else default.

Click the Build button, and select the Builds/Game folder, if you don't, the build won't work !

That's it !

Using the .bat file

First, launch a server by following instructions on the page Hosting a server.

Assuming you built the game and have a SS3D.exe file in the Builds folder, you can simply double left click on the Start SS3D Client - GhostOfBeep.bat to launch a client, with GhostOfBeep as a username.

Using the Command Line Args

Open a command prompt in your project's path to the Builds/Config, and run the following command changing the fields appropriately.

This will launch the client, replace clientUsername with your username and replace serverAddress with the desired server address, you can use localhost or 127.0.0.1 for a local server.

Using Application Settings window

You can set the Network Type to Client, the Editor Server Address to the desiredserver IP, or your local IP (127.0.0.1) if hosting from the same machine, and the Ckey to your desired Ckey.

The process of hosting a server, where you can play and have players connected to your server is possible via two paths:

Pre-launch instructions

Using the .bat file

Assuming you built the game and have a SS3D.exe file in the Builds folder, you can simply double left click on the Start SS3D Host.bat to launch a server, with john as a username.

Using the Command Line Args

To host a server outside the Unity Editor, first you have to build SS3D in the Builds folder of your SS3D project. You can then open a command prompt, move to the Builds folder and type :

start SS3D.exe -host -ckey=hostUsername -skipintro

Replace hostUsername by whatever username you want to use. Don't hit enter yet and skip to launch instructions.

Using Application Settings window

You can set the Network Type to Host, the Editor Server Address to your server IP, or your local IP (127.0.0.1) if hosting from the same machine, and the Ckey to your desired Ckey.

Launch Instructions

In the permissions.txt file, inside the Builds/Config folder. The username should have Administrator written on the same line in the permissions.txt file, otherwise it will not able to host the server. This should probably be automated eventually.

You can now hit enter or hit play depending on your case. The server will be launched and you can join with a client now.

Once started, go to server settings and click on start round like in the picture below.

Troubleshooting

start SS3D.exe -host -ckey=hostUsername -skipintro

The process of opening SS3D as server only, where you can play and have players connected to your server is possible via two paths:

Pre-launch instructions

Using the Command Line Args

To open a server outside the Unity Editor, first you have to build SS3D in the Builds folder of your SS3D project. You can then open a command prompt, move to the Builds folder and type :

start SS3D.exe -serverOnly

Using Application Settings window

You can set the Network Type to Server.

A recurrent issue we have when playing in editor is the game crashing with the exception "Port already in use". We found out that making the SS3D's folder (the whole project's folder) an exception for your firewall and antivirus is solving this issue.

We might add specific instructions here for specific firewalls and antivirus in the future, but it should be pretty straightforward.

Always check your code on host and on client

SS3D is a networked game, some of the code is running server side and some client side. Every time you add or remove something, you should check that it works well both on the host and on the clients.

Ideally, you should make tests including one host and multiple clients, at least one, but be careful, some bugs involve two clients and it would appear as working between host and client alone. Hence, try to test with two clients and one host, whenever it's possible and relevant.

Refer to the Running section to learn how to host and join a server.

Making attributes of class public

In Unity, whenever an attribute is public, it will appear in the gameObject inspector. This allows you to modify attributes during runtime in the gameObject Inspector.

In the below picture, I can modify the Inventory displayed by the inventory UI script, simply by clicking on it, and replacing the reference with the one of my choice.

This could be useful to quickly go through all inventories during the run, without having to code a special tool for it.

Making attributes public is also interesting to observe attribute changes during run time without using an actual debugger or the console. It has the advantage of not disturbing the flow of the game, and not overflowing the debug console.

Making use of the Input.GetKeyDown() function

Sometimes, what you need to debug involves critical timing, and running some logic. A classic debugger is not good enough or at best makes things really tedious.

To control when you want to get some debugging info, or run some code at the right time, what you could use is the Input.GetKeyDown() function.

This function simply returns true whenever the key of your choice is pushed. Put that in the Update loop of a monoBehaviour and you can log anything you want when you push a key, or run some logic.

    public void Update()
    {
        if (Input.GetKeyDown(KeyCode.space))
        {
            // Run some Debug.Log() or some logic
        }
    }

Here's an exemple, this little snippet of code allows me to modify a given container by one of my choosing, during run time, when I choose to. It's a simple trick but it's easy to forget about it.

    public void Update()
    {
        if (Input.GetKeyDown(KeyCode.L))
        {
            Debug.Log("updating left container");

            var container = FindObjectsOfType<AttachedContainer>()
                .Where(x => x.gameObject.name == "leftcontainer").First();
            UpdateContainer(container);
        }
    }

What's destroying my game object ?

SS3D is full of calls to the Destroy() method on game objects and as the game grows finding what's destroying a given game object will become increasingly difficult.

A simple search in your code editor, using Ctrl+f and searching through the whole solution for "Destroy(" can be enough, but it's tedious.

Here is an useful trick to find what's destorying your game object. Just add this code on any component on the game object that is destroyed. It will print in the Unity Debug console the stack of methods responsible for the call of OnDisable, and this usually allows to to trace back what's destroying your game object.

    void OnDisable()
    {
        // If object will destroy in the end of current frame...
        if (gameObject.activeInHierarchy)
        {
            Debug.LogError("Log an error with a stack trace in debug mode");
        }
    }

When needed, contributors might need to review PRs

To ease out the process, we'll walk through all the points need to be tackled when reviewing.

Check the Target branch, check the source branch

1. Check the target branch.

   • Most of the PRs should be develop, but some might be updating a feature or a preview feature, make sure the feature is not supposed to be a test nor experimental.

2. Source branch should be up-to-date with the develop branch.

   • It is not allowed to merge non up-do-date branches to develop, even if there's no merge conflicts.

Check PR's information

1. Revise the PR's textual information.

   • Make sure the title doesn't contain the [WIP] tag. If you feel the PR is completed, warn the author.

   • Make sure the PR describes clearly how that PR will change develop.

2. Make sure the known issues are present in the PR description.

   • See link 'Turn known issues into Github issues' for more info.

Check and make the tests

You can follow the instruction of the Running section to learn how to run with the different set ups of this section.

1. Revise the tests log.

   • Before continuing, it is proper to check if all the checks were passed on the tests runner.

   • If any tests have failed, warn the author.

2. Playtest in the editor.

   • Playtest all the feature in the editor, as it is the most safe way to playtest most of the time.

   • If any issues appear here, warn the author and create a small video or a very detailed comment on the PR.

3. Make a build.

   • If the build fails, warn the author and screenshot the build error message, add said screenshot in a comment on the PR.

4. Play the build as the host.

   • If any errors appear in this built version, warn the author and create a small video or a very detailed comment on the PR.

   • Note that all playtest in built executables should explore the feature as much as possible, to detect bugs as early as possible.

5. Play the build as the host and another as a client.

   • If any errors appear in this built version, warn the author and create a small video or a very detailed comment on the PR.

6. Play the build as the server and another as a client.

   • If any errors appear in this built version, warn the author and create a small video or a very detailed comment on the PR.

7. Play the build as the server and more than one as clients.

   • If any errors appear in this built version, warn the author and create a small video or a very detailed comment on the PR.

Check the file organization and naming

1. Make sure no unwanted files were committed.

   • we don't want changes that are not related to the PR.

   • Warn the author about, question why that file is being submitted.

2. Make sure the committed files follow our file naming and organization.

Check the PR content

1. Make sure no unwanted or unrelated changes are present on the PR.

   • we want PR to be concise as much as possible, changes that do not fit the description of the PR should simply not be there.

2. Make sure big PR are either :

   1. Completely new addings. It's fine for PRs to be big if they don't modify preexisting part of the code.

   2. Complete removal. If we ever need to completely remove something, it's fine if it's big.

   3. Changes very focused on one aspect : adding a particular attribute project wise, fixing a given style project wise, those are all acceptable changes.

Check the code

1. Make sure all the code follows the C# style guide.

   • This is not the best way nor it is infallible, but we still don't have any syntax linting.

2. Make sure the best architecture to your knowledge is being used.

   • Always ask why things are in that way if you feel something can be done better or don't know how it works.

3. Don't ask for micro optimization unless it's really obvious.

   • We have close to zero performance tests at this point. We don't want to over optimize at the cost of ruining readability and introducing hard bugs to solve, when the performance need is probably not even there.

Ask for documentation

1. Ask for thorough comments when necessary.

   • Insist on it especially when something is public.

2. Ask for independent documentation when a new feature is added.

   • The doc should be user oriented, it should mainly answer the question "how do I use this feature?"

   • If the contributor wants to add some technical details in it, check that it's focusing on a global overview of the feature.

   • Up to date documentation should be put here on SS3D's Gitbook.

Check any linked issues

1. Check any linked issues in the pull request.

   • If a PR links to an issue(s) to close them, check to make sure the PR meets the requirements of the issue. If for any reason parts of the issue cannot be met, make sure the reason is stated in the PR.

Turn Known Issues into Github Issues

Not all issues need to be solved in a PR. On the contrary, sometimes it's better to avoid bloating it or delaying a merge. Known issues that can be kept are the one impacting only the newly added feature, not in a fatal way. It can be optimization issue, partial feature..

Turn all known acceptable issues into Github issues for someone to solve later on.

All Good !

If you check all of these, accept the PR and warn a CentCom or a Maintainer member. If you're a CentCom or Maintainer member, you can merge the PR.

These are edit mode tests that are intended to check basic configuration of objects. These represent actions that a non technical person could check in the editor (given a basic checklist) without needing to look at any code. Examples include making sure no prefabs have missing scripts, making sure all tile prefabs are within a certain size range, all asset data references are not null etc.

Asset audits have been configured as parameterized tests, so it will be immediately clear which object is causing failures.

Note that a business rule is that test failures for prefabs should be resolved before test failures for scenes, because the scenes may be broken because the prefabs in them are broken.

Unity divides tests in two categories, play tests and editor tests. We decided to divide those tests into more subcategories. Here's a summary of the hierarchy, and you can find on the following pages a description of each of those, allowing you to choose the right category when writing a new test.

• Play tests

• Editor tests

  • Asset audit

  • Edit mode

SS3D, now with play mode tests ! Those are heavy tests, that require building the game, and, depending on the goal, they may require starting a server, launching multiple clients ...

Play mode tests architecture

Play mode tests need different setup based on what is tested . For instance, we might want to test picking up an item, for players embarking at the same time as host, or for players embarking after it. We could also test it just for host.

Manual Tests

The pages below describe a bunch of tests related to different systems implemented that a reviewer should do in order to check if everything's alright.

All tests described here should be tests that did pass at some point on the develop branch.

Please add a mention if the test you add is supposed to pass in the future but not yet.

Those tests are under the form :

SetUp : What need to be done before starting the test.

Test : What need to be done to execute the test.

Result : The expected result.

These are edit mode tests that are intended to check the behaviour of public methods within the game systems. They are restricted to editor only functionality, so some code will not function (e.g. IEvent invocation)

Clothings put in clothes slots show on the character

Should work for backpack, gloves, shoes, jumpsuit, headsets left and right, glasses, mask, PDA.

SETUP : Just spawn a human, make it naked. Spawn a random piece of cloth.

TEST : Take the cloth by left clicking it and put it in the appropriate cloth container by dragging it with left click.

RESULT : You should see the cloth displaying on the player.

Items put in hand slots show in player hands

SETUP : Just spawn a human.

TEST : Pick up a random item by left clicking it.

RESULT : Check the item is well in hand and move accordingly to the player's movements.

Dragging items out of inventory slots dump them out of inventory

SETUP : Just spawn a human. the human should have a few items on it already.

TEST : drag an item with left click and release outside of the container.

RESULT : Check the item is dropped close to the human, and the sprite is no longer showing in inventory.

Killing a player by hitting on torso

SETUP : Just have a healthy human spawn, with the AttackBodyPartByClickingIt attached. Check that the damage amount is above 0 (should be 10 to quick test it).

TEST : Press F a bunch of time while aiming with the mouse on the player torso until the player explode.

RESULT : You should see body parts flying, the camera should focus on the detached head, all body parts should disappear after a while and the head should too. After that, you're a ghost that you can control.

Killing a player by hitting on head

SETUP : Just have a healthy human spawn, with the AttackBodyPartByClickingIt attached. Check that the damage amount is above 0 (should be 10 to quick test it).

TEST : Press F a bunch of time while aiming with the mouse on the player's head until the player dies.

RESULT : You should immediately become a ghost.

Bleeding to death

SETUP : Just have a healthy human spawn, with the AttackBodyPartByClickingIt attached. Check that the damage amount is above 0 (should be 10 to quick test it).

TEST : Press F a bunch of time while aiming with the mouse on random body parts on the player.

RESULT : See that blood particles are spawning close to the body part you hit. Check that after a while, the player dies from lack of blood. Should take less than a minute if you hit a lot of time each body part.

Walking when injured

SETUP : Just have a healthy human spawn, with the AttackBodyPartByClickingIt attached. Check that the damage amount is above 0 (should be 10 to quick test it).

TEST : Press F a bunch of time while aiming with the mouse on the feet.

RESULT : See that player movement is slower with injured feet. Try to destroy completely the feet to see that the player cannot move anymore.

Loosing hands

SETUP : Just have a healthy human spawn, with the AttackBodyPartByClickingIt attached. Check that the damage amount is above 0 (should be 10 to quick test it).

TEST : Take an item in hand. Press F a bunch of time while aiming with the mouse on a hand, until you destroy it.

RESULT : See that a hand slot in the UI has disappeared, and that the player can't pick up items with its missing hand. Try to destroy the other one to check if the player can't take anything anymore. Check that the item held is dropped when the hand is destroyed.

Release Versioning

The release naming is defined by gamestate.major.minor.hotfix In which the rules are:

Automated Releases

Soon we will move to automated releases much like many of the SS13 servers and such. First they will likely start off as monthly releases but after we gain a lot of momentum we will eventually move to nightly releases.

These will be registered as hotfix releases. Devs will still be able to push manual releases at anytime for hotfixes as well.

You might wonder how to trigger an effect during an animation, how to call functions when an animation ends, even better, have your effect still trigger at the right time even if you change your animation. The answer is state machine behaviours.

To make it simple, SMBs are scripts you're going to put on states in animator controller. It calls some callback methods when entering and leaving a state.

In this page, I'll provide an example on how to set up properly an airlock, using it.

Airlock example

Say you want some lights on your airlock to turn green when opening, red when closing and black when idle.

We have the following state machine for the airlock.

During the opening state, the animator play the "opening" animation.

During the closingstate, the animator play the "closing" animation.

When selecting a state, see the "Add behaviour" option. We're going to use that to write a script to handle the airlock lights.

As said earlier, SMB's have callbacks when entering and leaving a state.

We're going to use two of them here, OnStateExit and OnStateEnter.

public override void OnStateExit(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)

public override void OnStateEnter(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)

The idea is simple : let's put our behaviour on the two states, opening and closing. When leaving a state, we know that the door is idle, so we're just going to make that call (we'll detail the ChangeColors method later).

    public override void OnStateExit(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)
    {
        ChangeColors(_idleColor, animator, stateInfo, layerIndex);
    }

Since we want to use the same script both when closing and opening the door (notice we could write two different scripts for simpler logic but harder management of files), when entering a state, we need to check in which state we're going.

Pretty simple, the code is self explanatory, we're using the data from the AnimatorStateInfo to retrieve the data we need :

/ublic override void OnStateEnter(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)
{
    if (stateInfo.IsName(Opening))
    {
        ChangeColors(_openingColor, animator, stateInfo, layerIndex);
    }
    if (stateInfo.IsName(Closing))
    {
        ChangeColors(_closingColor, animator, stateInfo, layerIndex);
    }
}

Now, let's see what's going on in the ChangeColors method.

Contrary to a classic monobehaviour, we can't define serialised field on a SMB, so if we need

to access stuff on our game object we need a simple trick. The callback from the SMB are sending back our animator component, so we have an easy reference to the game object the animator is onto. We can use that game object reference to access just any script we need, on our game object.

Here we use that to retrieve mesh renderers and skinned mesh renderers, that we put into lists on the AirlockOpener script.

Once we have them, we can do whatever we want with them, here we just modify some material colors and we modify some blend shape.

       
    private void ChangeColors(Color color, Animator animator) 
    { 
         var renderers = animator.GetComponent<AirLockOpener>().MeshesToColor;
         var skinnedRenderers = animator.GetComponent<AirLockOpener>().SkinnedMeshesToColor;
         foreach (var renderer in renderers) 
         { 
             renderer.materials[DOOR_LIGHT_MATERIAL_INDEX].color = color; 
         } 
         
         foreach (var skinnedRenderer in skinnedRenderers)
         {
            if (color == _openingColor)
            {
                skinnedRenderer.SetBlendShapeWeight(1, 100);
                skinnedRenderer.SetBlendShapeWeight(2, 0);
            }
            else if (color == _closingColor)
            {
                skinnedRenderer.SetBlendShapeWeight(1, 0);
                skinnedRenderer.SetBlendShapeWeight(2, 100);
            }
            else
            {
                skinnedRenderer.SetBlendShapeWeight(1, 0);
                skinnedRenderer.SetBlendShapeWeight(2, 0);
            }
         }

    }

We use milestones to track large achievements of development. Our GitHub Projects page tracks the individual tasks in our active milestone(s). The milestones are defined below.

Purple - indicates the milestone is completed. Green - indicates the milestone is in progress. Yellow - indicates the milestone is on GitHub but NOT in progress yet. White - indicates the milestone is only be theorized at this point and will be elaborated on in the future as we get closer to it.

Reminder that our milestones are synced with our release versioning for easy tracking, link below.

(We will add GitHub links to the name of the milestones in the list below as they get added to GitHub.)

0.0 - Rework

The rework is the first primary milestone. Its goal is to rework the structure (underlying aspects) of the game (such as networking, tilemaps, character movement, etc.), harmonize contributor guidelines and workflows, and porting over necessary systems.

0.1 - Minimal Viable Product (MVP)

The MVP is the goal to achieve a basic demo-like product to showcase a glimpse of our future game. It should include basic health & combat, crafting & construction, clothing, and shuttles.

0.2 - Alpha: Expand The Basics

When we really start to expand systems, add interactions, new content etc..

0.3 - Alpha: More Systems

Now adding less core but still crucial systems, and expanding previous systems.