1 of 8

Dev Intro

Intro to developing for Space Station 3D!

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 .

Using GitHub

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

The game repository is the ~~only~~ primary repository the most of the contributors will be working on. The game is made by a collection of both artists and coder, the two groups couldn't do it without each other.

The art repo is the one repo where artists ~~can get away from the coders for a bit~~ contribute source files as to make it easier for editing an art asset later. (This repo may get nested into the game repo, reducing work to export assets to the game from here.)

The server repo is where ~~know one dares to look~~ we host the central server which, as you might have guessed, handles the multiplayer networking.

Ah the infamous website repo, ~~if you can't guess this one then we're no longer friends~~ is where we develop and host our website from.

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.

Using Unity

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 current Unity version is, then find that specific version in the Unity download archives below.

Method 2:

Download Unity Hub, then open our project using the hub and it should auto-detect our Unity version and prompt a download for that version.

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.

Licensing

SS3D project licenses.

Code

All our code falls under the MIT license.

Art

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

File Naming & Organization

File Naming

When (re)naming files and folders always do so using 'PascalCase', 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

File Organization

/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:

/Assets/Art

Art assets are "external" assets, meaning they are created via an external source (outside of Unity). EX. pngs, oggs, mp4s, fbxs, etc.. Although some assets will not saved in this folder (materials, shaders, etc.) because those assets are exclusive to Unity and were not created externally (see the "Content" folder below).

Due to the nature of our project being open-source and having a community of contributors with various skills, we have segregated the Art folder by asset type, using the following sub-folders:

/Animations: 3D animation files for our 3D models.
/Fonts: font files.
/Graphics: 2D images used mostly for UI.
/Models: 3D models.
/Sound: audio files.
/Textures: 2D images and animations used as textures on 3D models in-game.

This helps reduce clutter in individual folders and also some assets are used in combination with multiple other assets in various ways.

Next we sort the art assets by . This applies for all of the above folders except Graphics and Fonts because those are mostly for UI.

Most files in the Art folder are documented in the Art Asset Contributor list currently saved on our Google Drive.

/Assets/Content

Content assets are 'internal' assets, meaning they are created within Unity itself. EX. shaders, materials, prefabs, etc..

Unlike art assets, content assets, are NOT sorted by asset type, but rather their broad usage.

/Addressables: asset data files.
/Data: Holds all the Scriptable Objects and data files that are used by scripts.
/Resources: you will see a Resources folder here in the Content folder and maybe a few floating around other places in the project. This is used to house files that specifically require to be held in a folder called resources. I think this only effects 'object type' content assets. I think it had something to do with network IDs or the tilemap or both (Broodje would know).
/Scenes: unity scene files for menus, maps, and such.
/Systems: technical content relating to game systems like, substances, UI, controls, etc.
/WorldObjects: all the prefabs and related content that make up our interactable in-game objects. This folder is sorted by !

/Assets/Editor

Editor assets do not go to built executables!

Editor assets are files exclusive to Unity editors. EX. the tilemap editor, or atmospherics editor.

/Assets/Scripts

Scripts are code files that make up our codebase. This includes things such as UI code, networking code, camera & FOV code, game systems, etc.

They are separated by two main folders, SS3D and External:

/SS3D holds all the scripts made by us, it is our codebase.
/External is where we put all the tools and frameworks we use, and that are not created by us.

/Assets/Settings

Holds all the Scriptable Settings assets, which are global settings that can be custom created.

/Assets/StreamingAssets

This is for file saved by the game, like map saves.

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

Object Type

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

Entities

In-game objects that have 'life' per-se. This includes player races, animals/monsters, robots/borgs, and even vehicles.

Items

In-game objects which can be picked up, stored on your character, or moved in a variety of ways (physics?). EX. bikehorn, bananas, guns, clothing, etc..

Furniture

In-game objects which are too large to store on your character, most of which cannot even be picked up. EX. tables, chairs, plants, machines, etc..

Structures

In-game objects similar to furniture but are nearly exclusive to the structure of the station (tilemap). EX. walls (& wall mounts), floors, plenums, wires, pipes, etc..

World

In-game objects which are 'other' objects pertaining to the world itself. EX. skyboxes or other backgrounds, character customization room, VFX & SFX, etc..

Editor

Non-game objects which are used in the Unity editors for display or other reasons. (This will likely only be used in the /Art/ subfolder, NOT the /Content/ subfolder. Reason being is we use broad Editor folder in the /Content/ folder.)