User:Harryob

Getting started with the code

Setting up your Coding Environment

Though you can use DreamMaker, and external Git software, for modifying your code and maps, all modern SS13 tooling is set up for Visual Studio Code, so it is highly recommended. You can jump to variable definitions, procs and atoms with ease.

Step 1: Downloading Visual Studio Code

Visual Studio Code is a free code editor (from Microsoft) that you can use to edit, test and publish your code to GitHub.

You can download it from https://code.visualstudio.com/ and run the installer.

Step 2: Forking the Repository

Go to https://github.com/cmss13-devs/cmss13, and at the top right, hit “Fork” - you’ll need a GitHub account for this.

Follow the prompts that come up, and you’ll have your own copy of the code on GitHub.

Step 3: Download Git

You’ll need Git installed to make any changes to the repository. Download it from https://git-scm.com/downloads.

Then, on Visual Studio Code, under the Source Control tab on the left bar - the third option down, you should be presented with the option to “Clone Repository”.

Paste the URL of your fork into the box that pops up - this should be in the format of https://github.com/[YOURUSERNAME]/cmss13. Select a folder to download the repo into, and let it run. It may take awhile.

Step 4: Download Extensions

These extensions to Visual Studio Code will allow the program to read DreamMaker code intelligently and allow you to navigate through the code faster.

You can get them by clicking on the extensions tab - probably the fourth or fifth option, it looks like three boxes with a fourth being added - and downloading all the “Recommended” extensions.

Step 5: Finishing Up

You’ve now got a complete clone of the CM-SS13 codebase on your local computer - excluding the xenomorph sprites you would see on the main server. Don’t be alarmed if you can’t see them.

Making a Change

All changes you make to the code must be done on a new branch.

A branch is another version of your codebase - made from your “master” branch - which should be identical to the “master” branch present on the main repo - which changes can be made to without affecting your “master” branch.

A “commit” is a save of your changes to the code you’ve made. Every time you “commit” your changes to the branch, you are saving all your changes made so far. All code must be “committed” before it can be sent to the main repository.

To start with making changes, you must make a new branch on your forked repository, from your master branch. Your master branch should never be committed to, and should be a clean state.

Every PR you make should have a new branch. This allows for commits you make on different branches to not affect your other branches, letting you work on multiple projects at once.

Step 1: Making a New Branch

Press Control + Shift + P to bring up the Command Pallet. This allows you to control Visual Studio Control easily, but we want the command “Create new Branch”. Type that in and press enter to run it. Give your branch a name - like new-helmet. Select which branch to make it from - that will be your master branch.

Then, switch to this branch. You can do this at the bottom of the Source Control tab, under the Branches title - you might have to click on it to show all your branches. Right click on your new branch, and select the option to switch to it.

Now, you can make whatever changes you like, and you can commit them to this branch without altering your master branch.

Step 2: Modifying the Code

Now, if you make any change to any file within the repo, Git will notice and add it to the modified files in the Source Control tab.

You can make a simple change - such as altering an item description - just to see your code changes reflected in game. To find an item, use the Search tab on the left - the magnifying glass - and type in the name or description if the item as it is in game.

Once you’ve made this change, it’ll be noticed at the top of the Source Control tab.

Step 3: Testing your Code

Press F5 - this will start your code with the debugger attached. This will automatically pause the server and tell you when an error - usually known as a runtime - occurs.

You can press Control-F5 to start without the debugger.

Then, at the bottom right of your Windows interface, click the chevron to view your hidden processes. Click on the green DreamDaemon circle, and you can see the server process that has booted up. Then, on the World tab at the top, press Join. This will log you in to the server, where you will automatically have full Admin permissions.

Find your item in game - or spawn it in with the admin game-panel - and it should have the changes you’ve made in the code. If it doesn’t- you probably didn’t save the file. Terminate the server using the stop button on Visual Studio Code or by right clicking on the DreamDaemon process and pressing Stop.

Step 4: Committing your Changes

At the top of the Source Control tab, your modified file should be under “Changes”. Hover over the file name you have modified, and press the Plus symbol - or do the same over the Changes button to “stage” your changes.

Once your changes have been “staged”, they have been selected to be committed. You can give it a commit message on the box with “Message”, and press the tick at the top to commit those changes.

Once this has been completed, you’ve committed your changes locally - but they have not been published to your GitHub fork.

Step 5: Publishing to GitHub

This is quite simple. On the Source Control tab, you should now see the “Publish Branch”. This will publish your branch, along with your changes, to your fork on GitHub. You can navigate to it on the web to see these changes.

If you make any further changes to this branch and commit them, you will see the “Sync Changes” option instead. This does the same thing - “pushing” all your changes to your fork on GitHub.

Making a Pull Request

A “pull request” is a *request* for the main repository to *pull* - or more accurately, merge - the contents of your branch into the master branch. This process allows for code to be tested and reviewed by maintainers/developers, before being merged into the master branch.

Step 1: Navigating the Web Interface

Head to your repository on GitHub - not the main CM-SS13 repo. Then, click on “master” and type in the name of your branch.

Hit “Pull Request” on the right, and it’ll bring up the Pull Request editor - automatically setting the merge as being from your branch to the master branch at the main CM-SS13 repository.

Step 2: Creating the Pull Request

Give your PR a good title - this will be the message of the commit to the main branch containing all your code.

Then, fill in the PR description, including a descriptive changelog. Put your BYOND username next to the first :cl: to ensure you are accurately credited.

Then, hit Create Pull Request (or don’t, if you’re uselessly changing one description as a test).

Step 3: Code Review

GitHub will automatically run some tests on your code, which may fail, resulting in you having to change your code. The developers will review your code, and may also request changes.

In order to carry out the changes, simply make the changes on your branch on your local repository, and press “Sync Changes”, this will automatically update the PR.

If a developer has marked your PR as a draft, you will have to mark it as being ready for review. You can do this at the bottom of the web interface on your PR.

Staying in Sync

As other PRs are merged into the repository, your branch will slowly become out of date. This will become an issue over time, as you modify code that has been changed by another recent PR, and you find conflicts that didn’t need to happen.

To avoid this, regularly go to your master branch of your fork on the web interface, and press “Fetch from Upstream”, to add all the commits recently merged to your fork.

Then, on Visual Studio Code, you can “Sync Changes” to update your local copy of the master branch.

Do this regularly to ensure you don’t fall out of date with any changes.