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.

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.

start SS3D.exe -ip=serverAddress -ckey=clientUserName -skipintro

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

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 Unity's instructions about building 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 !

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 :

Using Application Settings window

You can set the Network Type to Server.

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.

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 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.

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.

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.

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.

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.

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)

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.

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);
            }
         }

    }