BeeStation Wiki - User contributions [en]

Guide to signals

2023-12-28T06:18:34Z

Itsmeowdev: Add patterns and clarify send_signal

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals '''from''' other objects! It is a common pattern to emit a signal '''from'' another object, and have the object listen to signals on itself to respond to it. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

=== Signal Patterns ===

There are many ways to utilize signals, here are some common ones:

* '''Event->Listener:''' Use a global signal to emit an 'event' occurring to anything that is listening.
* '''Component<->Parent:''' Use a signal to communicate data between a component and its parent. This avoids the bad practice of GetComponent(), and allows components to react to events from the parent. This can use combinations of other patterns, but with components rather than objects.
* '''Object->Object:''' Use a signal to inform an object of something happening to it. The listening object will register a signal to itself, if it cares about this interaction.
* '''QDELETING:''' <code>COMSIG_PARENT_QDELETING</code> is one of the most used signals, it fires when the emitter is Destroy()ing. This allows the listener to clean up any references it has to the emitter, so it can delete properly.
* '''Object->Listener:''' Use a signal to inform listeners of something happening within an object. This is used to avoid hard-coding unnecessary references. An example of this is the MOB_LOGOUT or MOB_DEATH signal.
* '''Self->Listener:''' Use a signal to react to an event from within an object inside that same object. This is used when the two events are not related, to avoid hard-coding the event response. It can also be used to react to events from within the parent type without performing a method override.

== Global Signals ==

Global signals are a special type of signal that can be emitted to listeners at any time, and can be listened to by any object. They do not require specifying where to send a signal to. This is helpful for events that may impact a large variety of objects in varying ways, or when the relationship between two events is weak but unnecessary, making hard-coding it bad practice. A good example of this is the explosion global signal. Many things care if an explosion has happened, such as the Tachyon-Doppler array, but it would not make sense to hard-code that logic into the explode proc. Hence, a global signal.

To emit a global signal, use <code>SEND_GLOBAL_SIGNAL</code>:

<pre>
SEND_GLOBAL_SIGNAL(COMSIG_GLOB_CREW_MANIFEST_UPDATE)
</pre>

Listening to a global signal requires listening to <code>SSdcs</code>, which is the subsystem responsible for signal emissions. This is because behind the scenes, <code>SEND_GLOBAL_SIGNAL</code> actually just sends a signal to <code>SSdcs</code>.

<pre>
RegisterSignal(SSdcs, COMSIG_GLOB_CREW_MANIFEST_UPDATE, PROC_REF(on_crew_manifest_update))
</pre>

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Guide to signals

2023-12-28T05:57:04Z

Itsmeowdev: Describe global signals

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals to other objects! The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

== Global Signals ==

Global signals are a special type of signal that can be emitted to listeners at any time, and can be listened to by any object. They do not require specifying where to send a signal to. This is helpful for events that may impact a large variety of objects in varying ways, or when the relationship between two events is weak but unnecessary, making hard-coding it bad practice. A good example of this is the explosion global signal. Many things care if an explosion has happened, such as the Tachyon-Doppler array, but it would not make sense to hard-code that logic into the explode proc. Hence, a global signal.

To emit a global signal, use <code>SEND_GLOBAL_SIGNAL</code>:

<pre>
SEND_GLOBAL_SIGNAL(COMSIG_GLOB_CREW_MANIFEST_UPDATE)
</pre>

Listening to a global signal requires listening to <code>SSdcs</code>, which is the subsystem responsible for signal emissions. This is because behind the scenes, <code>SEND_GLOBAL_SIGNAL</code> actually just sends a signal to <code>SSdcs</code>.

<pre>
RegisterSignal(SSdcs, COMSIG_GLOB_CREW_MANIFEST_UPDATE, PROC_REF(on_crew_manifest_update))
</pre>

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Guide to signals

2023-12-28T05:49:21Z

Itsmeowdev: /* Emitting or sending a signal */ Include emits to other objects

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals to other objects! The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Development

2023-12-19T06:35:13Z

Itsmeowdev: /* Coding */ Add guide to signals

This is an index-page for finding guides related to aspects of development and contributing to the game. Guides will be linked with a short description of what they are about.

Feel free to add to this page if you have any resources that may help aspiring developers. It is recommended you keep guides within the bounds of this wiki.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
== Resources ==
{{Contribution guides}}
=== Design ===
* Design Goals - https://github.com/BeeStation/BeeStation-Hornet/wiki/Design-Goals - The current goals and direction of the game.
=== Coding ===
* Code Standards - https://github.com/BeeStation/BeeStation-Hornet/wiki/Code-Standards - The essential guidelines that maintainers look for in a PR.

* Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq - Making a new item in the game from scratch, from environment setup to the Pull Request.

* Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels - Explains how to avoid hard deletes, a quirk of the game's garbage collection.
* [[Understanding SS13 code]] - An older guide, explaining SS13 and DM to new coders
* [[SS13 for experienced programmers]] - Another older guide, explaining SS13 and DM to experienced coders.
* [[Guide to signals]] - A guide explaining what signals are in SS13 code, and how to use them.
*Visuals - https://github.com/tgstation/tgstation/blob/master/.github/guides/VISUALS.md - Guide describing most things relating to visuals and rendering on /tg/, however most of it also applies on BeeStation.
=== Development ===
* [[Working with the database#Database Setup|Working with the database]] - Setting up a local database for testing purposes, very useful for testing persistence and reducing development time.

* [[Guide to git]] - Using git command line, as well as dealing with merge conflicts and using mapmerge/dmimerge
=== Spriting ===
* [[Guide to spriting]] - How to create sprites for the game. This is fairly outdated, however.
=== Mapping ===
* [[Guide to mapping]] - Many tips, tricks, and guidelines for creating maps.
* [[Map Merger]] - Use of mapmerge2, a vital tool for resolving map merge conflicts, as well as installing Git hooks.
* [[Guide to mapping/Exploration ruins]] - Guide explaining how to map exploration ruins.

Template:Contribution guides

2023-12-19T06:34:28Z

Itsmeowdev: Add guide to signals

{|style='background-color:#e7e7ff' width='100%'
|colspan='2' style='background-color:#d8d8ff'|<div align='center'>'''Contribution guides'''</div>
|-
|width='150' align='center' |'''General'''
|align='left' style='background-color:#f0f0ff;' |[[Development]], [[Downloading the source code|Downloading the source code / hosting a server]], [[Guide to git]], [[:Category:Game Resources|Game resources category]], [[Guide to Changelogs|Guide to changelogs]]
|-
|width='150' align='center' |'''Database (MySQL)'''
|align='left' style='background-color:#f0f0ff;' |[[Working_with_the_database#Database_Setup|Setting up the database]], [[MySQL]]
|-
|align='center' |'''Coding'''
|align='left' style='background-color:#f0f0ff;' |[[Understanding SS13 code]], [[SS13 for experienced programmers]], [[Binary flags‎]], [[Text Formatting]], [[Guide to signals]]
|-
|align='center' |'''Mapping'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to mapping]], [[Map Merger|Map merger]], [[Guide to mapping/Exploration ruins|Exploration Ruins]]
|-
|align='center' |'''Spriting'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to spriting]]
|-
|align='center' |'''Wiki'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to contributing to the wiki]], [[Wikicode]]
|}<noinclude>[[Category:templates]]</noinclude>

Guide to signals

2023-12-19T06:33:51Z

Itsmeowdev: Add categories

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so generally it is <code>src</code>, however this is not a rule. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Guide to signals

2023-12-19T06:33:05Z

Itsmeowdev: Created page with "== What is a signal? == A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen". == Why signals? == In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on..."

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so generally it is <code>src</code>, however this is not a rule. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

FullControls

2023-08-11T17:45:35Z

Itsmeowdev: /* Throwing Mode: How and Why? */ Add hold-to-throw

= BeeStation Full Controls: Why and How =
If you are a brand-new player, you might have stumbled in here by accident. You can see the basic controls if you want to get into a round immediately on the [[Starter guide#Controls|new player tutorial page]]. Otherwise, this page is meant to be a breakdown of all (probably) relevant controls. It explains the '''how''' and more importantly it explains the '''WHY'''. Read this page and use the tasks at the bottom for practice and SS13 controls will become second nature in just a round or two. You can also check out the full [[Keyboard Shortcuts|hotkeys]] page.
== Full Controls: Breakdown ==
=== Left Click: The Pickup or “Use On” Key ===
Left click is used as a “take in hand button” most of the time. If there is something you want to pick up walk up and just click on it (assuming you don’t already have something in that hand). It’s second use is that it can be used to “use on x” items in hand. Use on what?
* Use some food, drink, or medicine on yourself to eat/drink/take it.
* Use the above on other people to attempt to force them to eat/drink/take it. Don’t.
* Use a [[Guide to Combat#Ranged%20Weapons|gun]] on a person or thing to shoot them.
* Use the computer console to open the interface.
* Use your empty hand on someone (with help intent) to hug them. :)
*If someone is buckled to a chair or something, click on the chair (or whatever) to unbuckle them.
=== Right click: The Stack Popup ===
For example, you want something from a locker, but there is a big stack of items in it. You can’t see the thing you want and so you can’t click on it. What do you do? You use '''Right click''' to open a popup menu listing every “thing” on that turf (tile). Simply find the item you want and from it’s popup menu use the pick-up or drag option.
=== “Using” Items with the '''Z''' key: Why and How? ===
This is ''different'' from the '''left click''' use. You can think of this as “use my hand on this item”. If you are confused a few examples should help:
* Use it on a can of coke to open it.
* Use it on a zippo lighter to light it.
* Use it on an e-gun to swap to lethal mode.
* Use it on a piece of paper to read it.
* Use it on a [[Medical items|health scanner]] to toggle into reagent mode.
For example, how would you drink a can of coke? You must first open the can by “using” it in your hand with the '''Z''' key. This will “use your hand on it” to open the coke can. Then you click on yourself with the opened can of coke in your hand to “use“ it on yourself which makes your character drink it.
=== ALT + Click: How and why? ===
The less common use case of '''ALT + click''' is to perform specific, context sensitive actions. Examples are toggling the lock on a locker, split a stack of items, crawling into vents (as something small like a monkey or alien larva)…

It’s most common use case, however, is opening an “inventory”. The way you can think of this hotkey is like a “show/take from inside”. What you might not expect is that a lot of things are technically “inventories”. If something has something inside it and you want to reach it then '''ALT + click''' is the answer.
* Take out your ID from your PDA.
* Take out your pen from your PDA (if there is no ID in it).
* Show a toolbelt, backpack or box inventory.
* Show your coat pockets inventory.
* Take out the item you put in your heavy boots.
This hotkey can also be used to open “inventories”, like a toolbox on the floor, without having to pick them up or equip them (toolbelts, bags). In the case of an “inventory” that has a single item inside it, it just spits that one item out like in the pen from PDA example or like taking out the ID from your PDA.

Something of note however is that you don’t '''ALT + click''' “container” like things such as crates or lockers. They are simply opened by left clicking them and then taking the items directly from them or with the '''right click''' if there is big stack on them. If you are a little confused by all this, don’t worry, it will be crystal clear after a round or two.
=== Communication ===
Press the '''T''' key – to talk. Your sentences will be automatically capitalized and end with a period. Unless you use “?” or “!” or even “!!” if you really want to scream something out. The last on is usually used with “;HELP!!” to scream for said help in the global radio chat.

As shown above If you add a semicolon (;) before anything else, you'll transmit your message to the general chat radio. Use the '''Y''' key to speak on the radio without typing the semicolon prefix.

You can also speak on a department specific radio channel. The format is the same for each, just with a different letter. To speak on the medical channel, for example, type .m or #m before your message.

Use the '''T''' key to talk BUT place a * (asterisk) followed by one of the '''preset''' non-verbal actions (emotes) to use them. Most common ones are: *clap, *laugh and *scream. These will make an in-game sound! You can use *help to see all the options. Not all of them have sounds and sounds can be different depending on the species e.g., moth or lizard (stinky).

Use '''SHIFT + Middle Mouse Button -''' to point at something. This creates a message in the chat and temporarily displays an arrow over the thing you point at.

Press the '''U''' key – to talk in local out of character chat. This is special yellow text with no rune text (text over the head) only visible in the chat window. As a new player you can use this in the game to ask control related questions to the people around you. If you have such questions also try the '''mentor''' tab. Global OOC is the '''O''' key and is only usable before or after a round.
=== Click-dragging: Buckling, Searching and Resisting ===
The '''B''' key is used to “resist” things such as any grab type from another person, resisting your butt off the sofa, breaking hands cuffs (this will take a while), resisting the fire on you by stop, drop and rolling, etc.

The word ''buckle'' might be confusing here. While you are “buckled” to the sofa you can just instantly resist it. If on the other hand you are handcuffed to said sofa (or in general) the “resist” word becomes more apt.

'''Click-dragging''' yourself or a held person onto something else has a lot of uses:
* Do it with yourself onto a chair to sit on it. A bed to rest on it.
* Do it with yourself onto a table to climb up onto the table.
* Do it with a person who is handcuffed to buckle them to a bed or chair.
An important one is '''click-dragging''' yourself onto another person to open ''their'' character inventory. You can then unequip or equip items from them. Security uses this to take off handcuffs or search convicts.
=== Throwing Mode: How and Why? ===
Use the '''R''' key to '''toggle''' throw mode for '''one''' throw. Next time you click somewhere on the screen your character will THROW the item. You can also hold down '''Space''' to toggle throw mode on while it is held down.

Why would you want to throw stuff? Because it’s ''convenient''. Why walk 6 tiles to drop that hat on the table when you can just chuck it at it? Why walk to someone to hand them an item when you can just throw it '''next''' to them? Do not throw items at people. Unless you want to, in cases where you might try throwing stuff for self-defense, for example.

Will it break or something? Most items are safe to throw. The exception are items made from glass such as cups. Even if they don’t break themselves, they will spill their contents on the floor or hit thing. A common use case is to throw an open bottle of fuel at someone followed by a lit match or something to set them on fire.
=== Pulling Things with CTRL + Click: How and Why? ===
'''CTRL + click''' is used to pull a thing or person. Your hand must be empty to pull. '''H'''alt as in stop pulling with '''H'''. Why would I want to pull a thing? You can gently pull people if you want to lead them somewhere. You can pull items such as crates or anything too big to carry in your hands. Most machines can be unwrenched and pulled somewhere else.

Another tip is that you can pull an item with an empty hand. Then you can use said empty hand to pick up another item even though you are “using” it to pull an item. Usually used to transport three bulky items instead of two.
=== QoL Hotkeys ===
Press the '''E''' key to quick equip items. If an item can be “equipped”, as in placed in any slot including your inventory or any other inventories such as belts or the suit slot, it will be. For example, if you have gloves and press E you will “quick equip” them into your gloves slot. If you already have gloves they will instead go to your backpack or other valid slots. There are too many cases so just experiment with the '''E''' key on items and you will figure out the behavior.

Using '''SHIFT + B''' and '''SHIFT + T''' you can place an item in/on your backpack or toolbelt respectively. If used with an empty hand, then it will instead take the last item you placed inside the backpack/toolbelt into your hand. An engineer might use this to quickly toggle between a wrench and his empty hand when working with pipes.
=== What is the drop item ('''Q''') key used for? ===
There are items that you can pick up with your hands, but that are too big to be stored in your backpack or even the suit slot such as the combat shotgun. If you need two hands for some reason you can just drop and item on the ground as a kind of a temporary inventory extension. Don’t worry it won’t get “dirty” and no one will steal it (probably). If you find this a bit confusing don't worry it's not critical that you understand this. Just play the game and you will figure it out what I mean.
== Tasks to practice the controls ==
Here are a few suggestions for things you should do on your first round to effectively learn the controls. After all the best way to learn is by doing. In no particular order:
* Make a paper airplane and throw it.
* Smoke a cigarette.
* Drink a can of coke.
* Pull a chair into a funny spot and then sit on it.
* Climb up onto a table.
* Talk to someone and use a preset emote.
* Get a drink or a meal from the crew area and tip the server.

Starter guide

2023-08-11T17:37:05Z

Itsmeowdev: TGUI Prefs update

= [[What is SS13|What is SS13?]] =
'''Space Station 13''' is a multiplayer sandbox that has a heavy focus on player interaction. In the year 2557, the megacorporation [[Nanotrasen]] employed you as a staff [[Jobs|member]] onboard their latest state of the art [[Guide to Research and Development|research]] station. Nanotrasen claims to be researching [[plasma]], a mysterious new substance, but rumors abound that the station is little more than a [[Clown|twisted]] [[Traitor|social]] [[Assistant|experiment]]...{{Speech
|name=Tuterr, the Private Eye
|text=Hmph. Fresh off the boat from Nanotrasen's recruitment office, huh? Let me tell you something, kid. You won't last five minutes on this floating deathtrap without help. You're as likely to be left for dead in a dark maintenance tunnel riddled with bullet holes as you are to get out of here alive. Lucky for you, I'm in a helpful mood today.
|image=[[File:Generic detective.png|64px|right]]
}}
At the start of each round, each player is assigned a role onboard the station. There are many jobs, such as the [[Scientist|scientist performing research and development of new technologies]], the [[Medical Doctor|medical doctor]] trying to keep people alive, or the simple [[janitor]]. There are many ways to play. The game also randomly chooses a [[Game Mode|round type]], ranging from an all-out assault on the station by [[Nuclear Operative|nuclear operatives]], a sinister [[Blood Cult|cult sacrificing crewmembers]] to summon their [[Nar-Sie|god]], or more commonly, good ol' fashioned [[Traitor|traitors]]. It is player driven and not some procedurally generated indie game. Every round on '''Space Station 13''' is different and a completely unique experience.
== Before Playing ==
Your choices matter in SS13. They have [[Ghost|consequences]]. The [[rules]] are here to ensure that when [[How to Roleplay|drama]] and [[Guide to Combat|conflict]] happen, they happen in a way that is [[Byond the impossible|beneficial to all parties involved]]. You should read the [[rules]] before playing. If you don’t understand them all don’t worry. You can engage in the server more and more as you understand.

At a base level, don’t attack players without any reason. Role playing as an “insane person” is '''not valid'''. If you want to be extra safe (there is no reason to be this afraid though) you can avoid any kind of fight. Most rules define who, what, where and how is allowed to fight, main or kill. If you don’t fight you automatically comply with these rules. One last point: Please, remember the human. SS13 can be highly frustrating. You will be unceremoniously killed, griefed, or die to some galactic space-bug shortly before executing your master plan. Everyone is here to play a game they enjoy, so keep that in mind before you bash someone's brain in with a [[toolbox]] because they took your [[multitool]].
== Getting Help ==
If you happen to get confused about something there are several ways to resolve this. The easiest is to contact a [[mentor]]. There is almost always at least one online. Don’t be shy! They love helping new players! In the top right there is a mentor tab. You can use “mentorwho” to check if any are online. Then you can use “mentorhelp” to send your question.

In the case there are none, you can ask the players around you. It might be difficult to communicate your problem in an [[IC]] (in character) way. It might also be difficult to answer in an [[IC]] way. That is why we have the LOOC or “local out of character” button which defaults to the '''U''' key. LOOC is a special yellow text visible only in the chat window. Meaning it has no rune text (text over the head). LOOC is used to discuss [[OOC]] things. For advanced users it’s used to [[Byond the impossible|set up more complex RP scenarios]]. For beginners, like yourself, it’s used to explain controls in a literal “click this press that” way that [[IC]] does not allow.
== Setting Up ==
Download the [https://www.byond.com/download/ BYOND client]. If you are in the Discord server (you should be; it's where all the drama happens!), you can use the ?byond command in the bot-spam channel. BeeStation has two servers:
*'''The Main BeeStation Sage:''' byond://sage.beestation13.com:7878
*'''The Overflow Low-pop BeeStation Acacia:''' byond://acacia.beestation13.com:7979
To join the game, you can use the links on the website. If you are in the Discord server there is a dedicated bot-spam channel. Use the “?cs” command to ask the bot about the current round information on the main BeeStation server Sage. The bot output will include a link that you can just click. These two methods are preferred by most veteran players (mostly the latter) since you avoid interacting with the icky Byond client.

Once you are in you will see a small window with some buttons. This is either “Ready” and “Not Ready” buttons or the “Join Game!” button depending on if the round is about to start or on-going. There is also a “Create Character” button we will be using shortly.

BeeStation operates on a round based system. Every round is a new “shift” not related in any way to the past ones. The typical round length is around 1 hour and 30 minutes. This is because at that time there is a “crew transfer vote” which is basically a “are we done with this round?” vote. This is also plenty of time for things to go horribly wrong in the case of any of the [[Game Mode|major game modes]].

If you jump onto the server, you are very likely to have joined during an active round. Using the “Status” tab, you can see the current round information. Speaking of which...
=== Client Interface ===
Look at the top right of the game window. You'll see some tabs. The most important tabs are the Status and Admin tabs. The admin tab contains the “'''adminhelp”''' button, used to contact admins directly if you have a '''rules question''' or believe someone is breaking the rules. For gameplay use the mentor tab. Here is a quick break down of the tabs:
* Status: Displays important info such as your ping, the current map, pressure remaining in airtanks, etc.
* [[Admin]]: Contains buttons that allow you if any admins are online, and most importantly, to send a message directly to the admins (the '''adminhelp''' button). If no admins are online, the message will be forwarded to the admin IRC channel.
* [[Mentor]]: Explained in the “getting help” section. Contains buttons that allow you to see if any mentors are online, and allow you to ask a question directly to the mentors (the "mentorhelp" button). Mentorhelps are not forwarded like adminhelps.
* [[IC]]: Usually, won't use this. The '''Pray''' button allows you to send a message to any admins online in character meaning it's used for "communicating with the gods". Or the Notes button which has your bank ID or shows any antag objectives if you have them.
* OOC: Stands for "Out of Character". Rarely needs to be used. Various functions that are related to the game, but not something your character does. View Webmap, View tracked playtime, and View Admin Remarks are the most used verbs here.
* Preferences: Self-explanatory. Contains various options you can toggle on and off. You can also open Character and Game Preferences at any time with the corresponding buttons.

[[File:Status_tab_top.png]]

On the right side will be the chat window. And above the chat window there are some tabs like “Admin” or “Preferences”. Feel free to immediately click the blue gear in the chat window and turn on night mode. Anyway, before you can join we need to create your character.
===Character Creation===
{{Speech
|name=Tuterr, the Private Eye
|text=You're brand new here, so make sure you sign up as an Assistant. Nanotrasen usually has checks to make sure fresh meat doesn't get to be the Captain, but if you manage to end up in that position, you'll probably be just another case for me to solve.|image=[[File:Generic detective.png|64px|right]]
}}
Recommended species for new players is [[Humans|human]]. Humans don’t have any major ups or downs. Later you can play as one of the [[Races|more exotic species]]. Other than that, it’s all mostly cosmetic. Once you've finished editing your appearance, the box in the title bar should hopefully say "Saved!", verifying that your choices saved properly.

'''Job Preferences'''

The Occupations tab lets you select your job preferences when a new round is starting. You, as a new player, want to set assistant to YES. For more information about job distribution on round start [[Job selection and assignment|see here]]. Again, this only applies to round start. In the case of on-going rounds, the “Join Game!” button will just let you pick what job you want assuming there are open slots. In the case of assistants that is always.

Some jobs have different character names when you play them, such as AI, Cyborg, Clown, and Mime. You can access these name options by pressing the hamburger button (three lines) next to your character's name in the Character tab. Please keep in mind that some of these roles are affected by [[Naming Guidelines]].

'''Game Preferences'''

You can also access your Game Preferences by pressing the gear at the top of the character setup. In this menu, you can customize various sound, UI, HUD, and other preferences.

Some of the most commonly modified preferences are:

* Sound toggles, typically ambience or lobby music.
* Pixel Scaling / Scaling Method, which determines how the game scales icons. Using a pixel perfect preset that fits your screen can increase the clarity of icons.
* FPS (frames per second).
* HUD Style, which adjusts the look of your ingame HUD.
* Ghost Chat toggles, these can reduce the clutter in chat while you are dead.

'''Antagonist Preferences'''

Once you are more familiar with the game, you can also customize your antagonist preferences in the Antagonists tab. By default, they start enabled, but are locked behind playtime, so don't worry, you won't be thrust into one of these roles before you know how to play. If you're worried about this, you can also go ahead and press the Global Disable Everything button at the top for now.<gallery>
File:Character settings.PNG|Character Creation Screen
File:Occupation Screen.png|Job Preferences Screen
File:Antagonist Preferences.png|Antagonist Preferences Screen
File:Game prefences Screen.PNG|Game Preferences Window
</gallery>
== HUD & Controls ==
The biggest barrier to entry in Space Station 13 is the controls. Despite the reputation once it clicks, you'll never have an issue with it again. '''Don't let it overwhelm you!''' After a round or two of practice, you should be fine.
===HUD===
{{Speech
|name=Tuterr, the Private Eye
|text="Interface"? What the hell are you talking about, kid? "Blue buttons?" Geez, you've been here for five minutes and you're already cracking. Hmmm... *recorder crackles* Note to self - check atmospherics. Gas might be poisoned.|image=[[File:Generic detective.png|64px|right]]
}}
The top right of the screen contains the action tabs and the bottom right is the text log or chat window. This is where you can see what people are saying, what's happening around you, and chat such as OOC or adminhelps. The bar along the bottom of the screen is the input bar, but since we're on [[Keyboard_Shortcuts|Hotkey]] mode we won't need to use it. There are a few HUD elements on the main screen, so let's break them down into sections. Don't worry if you can't memorize what everything does at once. You can always come back to this guide.
<tabs>
<tab name="Hands">[[File:Hud-hands.gif]] One of the most important elements of the HUD. You have the ability to hold an item in each hand (unless an item takes up both hands, obviously). The square around one of the hands is the '''selected hand'''. If you have an '''empty''' selected hand, and click on an object, you'll pick it up/open it/use it. If '''an object is in your selected hand''' and you click on something, you'll use it on the item you're holding. (The way this works means that if you'd like to unequip your backpack, you need to click and drag the bag into your hand - if it was removed by clicking on it, you'd never be able to open the bag.)

'''If this seems confusing, don't worry - it'll be explained shortly.'''</tab>
<tab name="Inventory Buttons">These icons manage your inventory.

The backpack [[File:Hud-inventory.png]] icon can be toggled to show your worn equipment.

The belt [[File:Hud-Belt.png]], backpack [[File:Hud-Back.png]], and pocket [[File:Hud-Pocket.png]] icons are all storage locations.

The ID [[File:Hud-ID.png]] slot can hold your ID, or your PDA (which can hold your ID).</tab>
<tab name="Interact Commands">These buttons directly affect how you interact with objects.

The drop [[File:Hud-drop.png]] and throw [[File:Hud-throw.png]] icons do what the name implies. Dropping is self explanatory, but the throw button is a toggle - if it's on and you click somewhere, you'll throw the item in your hand at where you clicked. (You can also press R to enable throwing and Q to drop your held item.)

The pull [[File:Hud-pull.png]] icon only appears when dragging something, and can be pressed to stop dragging an object. [[Keyboard_Shortcuts|Hotkey]]: "H".

The internals [[File:Gmaskinternalsicon.gif]] icon can be clicked to enable/disable your internals (oxygen tank and breath mask).

The resist [[File:Hud-resist.png]] icon can be pressed to break out of grabs, restraints, and if you're on fire, is the "stop drop and roll" button. [[Keyboard_Shortcuts|Hotkey]]: "B".

The run/walk toggle [[File:Hud-walkrun.gif]] icon can be pressed to switch between running and walking. Running is faster, but walking has benefits, such as being able to walk over water without slipping - useful for when the janitor doesn't put wet floor signs down. [[Keyboard_Shortcuts|Hotkey]]: Hold "alt" to walk.

The body selector [[File:Hud-target.gif]] icon is used to choose which body part you want to target. This is used for both targeting specific sections to heal, or targeting specific sections when attacking someone. Click a limb to target it. (You can target individual arms, legs, the head, the upper torso, the groin, the eyes, or the mouth.) [[Keyboard_Shortcuts|Hotkeys]]: "numpad keys".

Last but not least is the intent selector [[File:Hud-intent.gif]] - this will be explained in detail later. It has four modes: '''Help''', '''Disarm''', '''Grab''', and '''Harm''', in clockwise order. [[Keyboard_Shortcuts|Hotkeys]]: "1-4".</tab>
<tab name="Other">The health [[File:Hud_100_percent_Health.gif]] icon and [[File:Healthdoll.gif]] doll change depending on how injured you are.

The crafting menu [[File:Craft.gif]] icon opens the crafting menu.

The speech bubble [[File:Talk_wheel.gif]] icon opens the languages menu. You won't need to use this for the tutorial.

The create area [[File:Area_edit.gif]] icon is used to create an "area", which is a more advanced topic. You won't need to worry about it for this tutorial.</tab>
<tab name="Alerts">These will only appear on the HUD if something is wrong.

[[File:Hud-oxy.gif]] '''Oxygen warning''' - The air you're breathing doesn't have enough oxygen.

[[File:Hud-pressure.gif]] '''Pressure warning''' - Pressure levels are too high (red) or too low (black). Low and high pressures can kill you.

[[File:tox_in_air.gif]] '''Toxin warning''' - You are breathing in toxic gases.

[[File:Hud-fire.png]] '''Fire warning''' - The air is hot enough to burn you.

[[File:Hud-freeze.gif]] '''Freeze warning''' - The air is cold enough to freeze you.

[[File:Hud-temp.gif]] '''Temperature warning''' - You're too cold or too hot.

[[File:Hud-hunger.gif]] '''Hunger warning''' - You're starting to get hungry. You cannot die from hunger, but the longer you go without food, the slower you will be able to run. You can also eat too much and become bloated.</tab>
</tabs>
===Controls===
[[File:Hotkeys.png|thumb|500px|[[Keyboard_Shortcuts|Keybindings]] for the hotkey mode.]]
Don’t get scared by the hotkey image. It shows ''all'' the controls and their alternatives. This might seem like a lot, but don't worry, you'll only be using a few most of the time. The control are quite elegantly designed. There are exceptions, but for the most part you will be able to anything from surgery to nuclear science with the exact same controls. You won't need to memorize 20 hotkeys.

The default control scheme is “hotkeys” set in the game preferences menu. In case it’s not working you will see the bottom-right textbox in a red color. Click anywhere in the game window and press '''Tab'''. The textbox should go white showing that you are in “hotkey” mode.
*Use the '''WASD''' keys to move around.
* Press the '''X''' key to swap your active hand. The hand system is explained below.
*Press the '''Q''' key to drop what you are currently holding in your hand on the ground.
*Press the '''T''' key to talk. Prefix what you say with a semicolon (;) to say it in the global radio channel. Use the '''M''' key for non-verbal actions like “smile” or “wave”.Use the '''U''' key for LOOC (described in Getting Help).
*Use '''left click''' on a thing to interact with it. Interact means different things based on the thing you are clicking. Use '''right click''' for a context menu (mostly used for stacks of items).
*Press the '''Z''' key with an item in hand to “use” it.
*Use '''SHIFT + click''' on anything to examine it. Your new favorite button combo. It will describe what you are looking at. As a new player you will be using this ''very often''. Use this on anything and everything.
If you just want to just jump into a round immediately the above controls should be enough for your first round. Doing a task, like, asking someone where the drink vending machine is, buying and then drinking something is a good way to start getting the hang of the controls.

It is '''necessary''' to read the '''[[FullControls|full controls page]]''' after your first (or such) round, however. You can also check out all the available [[Keyboard Shortcuts|hotkeys]].
== Gameplay Concepts ==
Before getting into anything else, it's important to note that since SS13 is such an open ended game that has other people in it, when you get in game and try to follow the guide, things may go wrong - the station might have been almost entirely consumed by a singularity, a traitor could attack you with a powerful weapon, or something no one could have predicted will kill you. '''It's important to not let death get to you!''' There are multiple ways you can be brought back into the game, so don't get frustrated if something happens.
{{Speech
|name=Tuterr, the Private Eye
|text=You know, as much as I like to rib the fresh meat, it doesn't really matter if something happens to them - Nanotrasen thinks death is a waste of money, they'll just get cloned or something. What? Oh, shit, I gotta go. *click* You, uh, didn't hear that - right, kid?
|image=[[File:Generic detective.png|64px|right]]
}}
===The Hands System===
If an item requires two hands to use, then the other hand slot will instead be labeled as “off-hand”. Why do I start by telling you this? Because only one hand can be selected at a time. Imagine yourself as a creature with one hand. You only sprout a second hand when you need to use two handed items.

Another time when you sprout an extra hand is to '''just''' hold an item. That is because your hands are also just a part of your inventory. However, think of them as an “active” part of your inventory. You place items in these “active” slots when you want to use them.

The bright box around one of your hands is the selected hand. Swap your selected hand with the '''X''' key. This is the hand that's used whenever you click on something. If it’s empty. Otherwise, you will use what you are holding in your hand on what you clicked on.

This can also cause problems with backpacks, boxes, and other containers. If you want to open a container, '''Alt + Click''' it. You can also pick it up, then switch hands and click on the container with an empty hand. Clicking on a container with an object will put it in the container. This also means that if you'd like to '''take your backpack off''', you need to click and drag the bag to an empty hand. Normal click just opens the equipped bag.

If you find this confusing, you should go check out the [[FullControls|full controls page]] already! It goes hand in hand (GET IT!?) with this explanation. If you still find it confusing, then maybe you should play your first round already because it really is not that complicated.
===[[Intent|Intents]]===
The intent selector has four modes: '''help''' [[File:Intent_Help.png]], '''disarm [[File:Intent_Disarm.png]]''', '''grab''' [[File:Intent_Grab.png]], and '''harm [[File:Intent_Harm.png]]'''. This system mostly controls how you interact with things with your bare hands. You can learn more about these uses on [[Intent|the intents page]]. It's not, however, critical that you learn this right now. When it comes to using '''things''' this system is '''much simpler then it appears'''. Using a crowbar on someone will hit them '''regardless''' of intent. Most items work like that. Instead when it comes to '''things''' there are special use cases, for example:
*While doing surgery, if you are '''not''' on help [[File:Intent_Help.png]] intent, you will intentionally botch it.
*Clicking on something next to you with a gun will shot them point blank. If, however, you are on harm '''[[File:Intent_Harm.png]]''' intent you will hit them with the weapon instead.
* Using harm '''[[File:Intent_Harm.png]]''' intent on an airlock with a welder will weld it shut instead of repair it.
You don't need to know these things right now. It's just so you understand the types of specific thing you will use intents for. The only intent related thing I want you to know for now is that clicking on people with and empty hand with help [[File:Intent_Help.png]] intent will hug them. Very important.
== Playing the Game ==
[[File:HUD_no_labels.png|thumb|489x489px|Arriving on the station.]]
{{Speech
|name=C-05-MO, the AI
|text=Hello! The automatic diagnostic and announcement system welcomes you to Space Station 13. Remember: Have a secure day.
|image=[[File:AI.gif|64px|right]]
}}
If you join a game in progress, you'll spawn on the [[Arrivals|arrival shuttle]]. You'll start buckled onto a chair. Use the '''B''' key to resist out of the chair (or click the HUD icon).
===Finding Your Way Around===
On of the hardest things for new players is learning what there is on the station and where it is. This is compounded by the fact that we have [[Maps|several different stations]] with different designs. Look out for signs on the walls. Ask the people in the hallway. Look out for lines on the floor in the case of [[webmap:FlandStation|Fland]] or [[webmap:RadStation|Rad]] station. Ask the [[Mentor|mentors]].

We live in the future! And thanks to revolutionary advancements in technology, we have an online map viewer for all [[Maps|BeeStation stations]]! Check the map you are currently on in the status page and then find the webmap link on the [[Maps|maps page]].

It is helpful not just to find your way, but to get a more complete understanding of the stations. You can notice things here that are a common trend across all stations like: [[bar]] is always next to [[kitchen]], [[atmospherics]] are always next to [[engineering]], the [[Dormitory|dorms]] always have a room for cryosleep in case you want to leave the game, and more for you to discover!

Since you've chosen [[Assistant]] as your role, you'll have no responsibilities. This means you can safely attempt to get your bearings without fear of someone telling you that you need to be doing something. Check out the [[FullControls#Tasks to practice the controls|full controls page for suggestions]]. Eventually, once you're confident in the controls, why not consider doing some [[How to Roleplay|roleplaying]]? This is a roleplay server, after all.
===Inventory Management [[File:Backpack.png]]===
Items in the game have 4 different "weight classes," tiny, small, normal, and bulky. These weight classes determine which storage slots it can fit in, and what they can't fit in. If you are wearing a jumpsuit, the two item storage slots to the rightmost of your screen are your pockets.
*These pockets can only store tiny and small items.
*Your hands are where you can grab items and interact with them.
*Your back is where you should have your backpack.
*Your backpack is your main storage space, but it can only fit a limited number of items. You can stuff tiny, small, and normal classed items into your backpack. However, normal classed items will take up more storage space than a tiny classed item.
*Your belt is where you store your toolbelt, (if you are an [[Station Engineer|engineer]]), your [[Laser Gun|gun]], or a variety of other different items, which range from swords to [[Defibrillator|defibrillators]].
* The items which you can fit in your suit storage (on the left most of your screen, below your gloves) depend on the uniform you are wearing. For example, a [[hardsuit]] would allow you to fit an oxygen tank in there, whilst an [[Armor Vest|armor vest]] would allow you to fit a [[laser gun]].
This is one of those things where there are a lot of exceptions. Simply ask around or experiment to find out all the interesting combinations of storage.
===Using Internals===
Your character starts with a [[box]]. Inside the box you will find an EpiPen. It’s used to stabilize people in [[Crit|critical]] condition. You will also find an [[emergency oxygen tank]] and a breathing mask. In a situation where there is a lack of oxygen, a viral outbreak, or some toxic gas in the air you can use this.
#Equip the mask into your mask slot [[File:Hud-Mask.png]] (press the equipment [[File:Hud-inventory.png]] icon to see it) or quickly equip with the '''E''' key.
#Place the oxygen tank into your pockets and press the [[File:Gmaskinternalsicon.gif]] button on the top left. You are now breathing from the oxygen tank.
Despite being called an emergency oxygen tank these puppies start with ~1000 kPa of pure oxygen. This, in layman’s terms, means you can breathe from one of these for about 30 minutes. You don’t have to fear running out of air in 5 minutes. The situation to use internals are not that common though. Lack of oxygen is usually accompanied by extreme temperature or pressure. The mask will not help with those. The best way to deal with things like breaches, fire or [[plasma]] fires is to run away from the affected area.
===Using suit sensors===
Every [[Nanotrasen]] [[jumpsuit]] comes with a mechanism called [[suit sensors]]. Right click on your jumpsuit and use the “adjust suit sensors mode”. It should be, by default, set to the highest level. If not, make sure to set them. I’m sure you can guess what they do by name alone. [[Medical Doctor|Medical]] and [[Security Officer|Security]] crew have access to [[Crew Monitoring Console|crew monitoring consoles]]. They can also use [[Pinpointer|pinpointers]] to locate crew. This only works if your suit sensors are on. In the unfortunate case of your early departure from this moral coil the good folk in medical possibly locate are resurrect or clone your body.
===What To Do if You Are Hurt or See Someone Hurt on the Ground?===
Go to the medbay. If you happen to see a dead or near dead person on the ground, you should take the following steps: Remember that EpiPen? Now is the time to use it. What is happening to a person in [[critical]] condition is that they are slowly suffocating. Injecting them with the EpiPen will prevent this suffocation, buying a lot of time. Then since they are hurt, they are probably bleeding. '''Do not drag them across the floor''' as this slowly kills them. Instead consult the [[FullControls|full controls]] page on how to lift a body in a fireman’s carry.
===What To Do if You Are Attacked?===
In the case that someone attacks you, you are already dead probably. If you are attacked by a [[Blood Cult|blood cultist]] using [[Blood Cult#Blood Spells|eldritch magic]], blood weapons and that has the jump on you; it’s not supposed to be a fair fight. Or a fight at all rather.

In the case where you [[Byond the impossible|are not already dead]]. The first thing you want to do is scream “HELP” in the global radio chat. Because we can’t play the game and talk, an all uppercase “help” is like a special summoning call for [[Security Officer|security]], the [[AI]], or the [[Medical doctor|medical]] crew. If you have your [[Suit sensors|sensors]] turned on you don’t have to say where you are being attacked. Once the [[Terminology#Valid/Validhunting|valid hunters]] have been summoned the next step is to run away (bravely!). Look for the main station corridor as it is a public area and has lots of space. Avoid going into areas you don’t know since you might dead-end yourself.

Once you get better acquainted with the [[rules]] you can read the [[Guide to Combat|combat guide]] (outdated; ask some security players for classes), to learn how to fight back.
===Radiation Storms===
When you hear a message stating: '''''"'''High levels of radiation detected near the station. Maintenance is best shielded from radiation.'''";''''' that means a [[Random events#Radiation Storm|radiation storm]] is coming. This message is misleading, because maintenance is the only place protected from radiation. Normally, if the heads are competent, a station-wide emergency will then be declared opening up [[maintenance]] even if you don't have access. All you have to do now is mill in [[maintenance]] until the radiation storm passes over. If you get hit by the radiation or feel sick in general head to the [[medbay]].
==Properly Leaving The Game (Cryosleep)==
Too confused? Head hurts? Mom called you to eat dinner? Whatever the reason you wish to leave the game, there is a proper way to do it. Crew and job slots are based on the number of living crew. The proper way to leave the round is to go the [[Dormitory|dorms]] and find the cryosleep pods. They are bright green. If you can’t find the dorms just ask [[Crew|someone]] (like a [[mentor]]). There are usually signs as well such as “DORMS”, “SLEEP” or “REST”. If you lay into a cryosleep pod and then log out or rather exit the game your body will be removed from the round, you will become a ghost and an empty crew an job slot will open for someone else. Speaking of ghosts...
==Death and Ghosts==
Tried to be a [[Clown|funny guy]] with the [[Traitor|wrong]] [[Changeling|person]]? Wrong [[Blood Cult|place]], wrong [[Nightmare|time]] in maintenance? Whatever the case, you are now [[dead]]. Don’t despair just yet! If the [[Antagonist|bad man]] has not completely destroyed your body and you turned your suit sensors on max there is a chance that some good [[paramedic]] will find your charred and bruised corpse and bring it to the [[medbay]] to be revived or [[Clone|cloned]].

In the meantime, move the ghost out of your body. This is spectator mode. You can communicate with other dead players. It’s fine to talk in an [[OOC]] way in Dchat. In the case you are revived you are '''not allowed''' to use any information gained while being a ghost. Anything you saw while you were alive is fair game though. Unless you are cloned that is. If you are cloned, you forget the last 15 minutes of your life.

In while being a ghost there is a chance to be prompted to become things like xenomorphs or swarmer. Sometimes these are random events and sometimes admin interference.

There is also a ghost spawner menu. From here you can spawn as certain things on [[Lavaland]]. If you choose to do this, you will no longer be able to revive or be cloned. When you spawn you are a new entity. You are unaware of your past life. For a new player a recommendation can be spawning as a [[Lavaland]] doctor. You get your own [[Lavaland]] hospital where you can freely practice [[Guide to medicine|medicine]] and [[surgery]] on monkeys as well as [[Guide to hydroponics|botany]] and [[Guide to chemistry|chemistry]].
==What Jobs to Take After Your First Round==
The best beginner jobs are ones where no one is going to come to you asking for something you don't really understand. Assistant is the best because no one expects anything at all from you. You are free to explore and play with the controls. However once you get a grip on the controls is recommended to move to a job where still no one expects anything, but that have a designated objective. The recommended assistant ''plus'' roles are:
*[[Janitor]]: People will expect nothing from you except maybe that you clean the floor.
*[[Curator]]: The library is practically abandoned. Play with board games and painting. Organize books. Get fun loot from your curator beacon.
*[[Cargo Technician|Cargo Tech]]: Move crates until you die. It is said that all SS13 journeys begin and end in cargo. This is because cargo is of vital importance to several game modes. As a CT you will get to see the flow of these rounds first hand. However, your job will still remain to be just moving crates.
After that it's time to move on to some real roles. Funnily enough, the best way to learn these roles is to sign up as an assistant again. You are going to use this role as intended and actually assist some departments. Going to the [[Head of Personnel|HoP]] or whatever place you want to learn about and asking nicely for someone to teach you is a very effective way to learn. The [[Head of Personnel|HoP]] can even give you custom job titles like "medical intern" or "brig receptionist". Job that are good for this are: [[Medical Doctor]], [[Scientist]], [[Station Engineer]]... This is also the best way to dip your toes safely into being a [[Security Officer]]. Be careful, because it's very easy to play security poorly, and [[Shitcurity|letting the power get to your head is a bad idea]].

Avoid joke roles such as the [[Clown]] or [[Mime]] at first. Many players find harassing the on board entertainment much more fun than any jokes the clown might otherwise have.

After some time, when you're confident enough in your combat abilities, you should enable antagonists within your game preferences, so that you can roll for antag when the shift starts. A good half of the game is arguably being an antag and beating everyone up. Don't be scared that you will be a bad antag. Due to the fact that you can't predict what or when it will happen everyone was a painfully obvious antag at one point. It's just how the game works. You should however avoid team antag roles. [[Blood Cult|Blood cult]], blood brothers, [[Revolutionary|revolutions]], [[Clockwork Cult|clock cultists]], [[Nuclear Operative|nuclear operatives]], [[Xenomorph|xenomoprhs]]... The most common and "safe" antag options to dip you toes in are [[Traitor]] and [[Changeling]].

File:Antagonist Preferences.png

2023-08-11T17:22:15Z

Itsmeowdev:

== Summary ==

File:Game prefences Screen.PNG

2023-08-11T17:17:12Z

Itsmeowdev: Itsmeowdev uploaded a new version of File:Game prefences Screen.PNG

== Summary ==
New Game preference screen

File:Occupation Screen.png

2023-08-11T17:14:05Z

Itsmeowdev:

File:Character settings.PNG

2023-08-11T17:11:35Z

Itsmeowdev: Itsmeowdev uploaded a new version of File:Character settings.PNG

== Summary ==
How character settings screen

Starter guide

2023-08-11T17:05:20Z

Itsmeowdev: /* Character Creation */ Text updated for tgui prefs

= [[What is SS13|What is SS13?]] =
'''Space Station 13''' is a multiplayer sandbox that has a heavy focus on player interaction. In the year 2557, the megacorporation [[Nanotrasen]] employed you as a staff [[Jobs|member]] onboard their latest state of the art [[Guide to Research and Development|research]] station. Nanotrasen claims to be researching [[plasma]], a mysterious new substance, but rumors abound that the station is little more than a [[Clown|twisted]] [[Traitor|social]] [[Assistant|experiment]]...{{Speech
|name=Tuterr, the Private Eye
|text=Hmph. Fresh off the boat from Nanotrasen's recruitment office, huh? Let me tell you something, kid. You won't last five minutes on this floating deathtrap without help. You're as likely to be left for dead in a dark maintenance tunnel riddled with bullet holes as you are to get out of here alive. Lucky for you, I'm in a helpful mood today.
|image=[[File:Generic detective.png|64px|right]]
}}
At the start of each round, each player is assigned a role onboard the station. There are many jobs, such as the [[Scientist|scientist performing research and development of new technologies]], the [[Medical Doctor|medical doctor]] trying to keep people alive, or the simple [[janitor]]. There are many ways to play. The game also randomly chooses a [[Game Mode|round type]], ranging from an all-out assault on the station by [[Nuclear Operative|nuclear operatives]], a sinister [[Blood Cult|cult sacrificing crewmembers]] to summon their [[Nar-Sie|god]], or more commonly, good ol' fashioned [[Traitor|traitors]]. It is player driven and not some procedurally generated indie game. Every round on '''Space Station 13''' is different and a completely unique experience.
== Before Playing ==
Your choices matter in SS13. They have [[Ghost|consequences]]. The [[rules]] are here to ensure that when [[How to Roleplay|drama]] and [[Guide to Combat|conflict]] happen, they happen in a way that is [[Byond the impossible|beneficial to all parties involved]]. You should read the [[rules]] before playing. If you don’t understand them all don’t worry. You can engage in the server more and more as you understand.

At a base level, don’t attack players without any reason. Role playing as an “insane person” is '''not valid'''. If you want to be extra safe (there is no reason to be this afraid though) you can avoid any kind of fight. Most rules define who, what, where and how is allowed to fight, main or kill. If you don’t fight you automatically comply with these rules. One last point: Please, remember the human. SS13 can be highly frustrating. You will be unceremoniously killed, griefed, or die to some galactic space-bug shortly before executing your master plan. Everyone is here to play a game they enjoy, so keep that in mind before you bash someone's brain in with a [[toolbox]] because they took your [[multitool]].
== Getting Help ==
If you happen to get confused about something there are several ways to resolve this. The easiest is to contact a [[mentor]]. There is almost always at least one online. Don’t be shy! They love helping new players! In the top right there is a mentor tab. You can use “mentorwho” to check if any are online. Then you can use “mentorhelp” to send your question.

In the case there are none, you can ask the players around you. It might be difficult to communicate your problem in an [[IC]] (in character) way. It might also be difficult to answer in an [[IC]] way. That is why we have the LOOC or “local out of character” button which defaults to the '''U''' key. LOOC is a special yellow text visible only in the chat window. Meaning it has no rune text (text over the head). LOOC is used to discuss [[OOC]] things. For advanced users it’s used to [[Byond the impossible|set up more complex RP scenarios]]. For beginners, like yourself, it’s used to explain controls in a literal “click this press that” way that [[IC]] does not allow.
== Setting Up ==
Download the [https://www.byond.com/download/ BYOND client]. If you are in the Discord server (you should be; it's where all the drama happens!), you can use the ?byond command in the bot-spam channel. BeeStation has two servers:
*'''The Main BeeStation Sage:''' byond://sage.beestation13.com:7878
*'''The Overflow Low-pop BeeStation Acacia:''' byond://acacia.beestation13.com:7979
To join the game, you can use the links on the website. If you are in the Discord server there is a dedicated bot-spam channel. Use the “?cs” command to ask the bot about the current round information on the main BeeStation server Sage. The bot output will include a link that you can just click. These two methods are preferred by most veteran players (mostly the latter) since you avoid interacting with the icky Byond client.

Once you are in you will see a small window with some buttons. This is either “Ready” and “Not Ready” buttons or the “Join Game!” button depending on if the round is about to start or on-going. There is also a “Create Character” button we will be using shortly.

BeeStation operates on a round based system. Every round is a new “shift” not related in any way to the past ones. The typical round length is around 1 hour and 30 minutes. This is because at that time there is a “crew transfer vote” which is basically a “are we done with this round?” vote. This is also plenty of time for things to go horribly wrong in the case of any of the [[Game Mode|major game modes]].

If you jump onto the server, you are very likely to have joined during an active round. Using the “Status” tab, you can see the current round information. Speaking of which...
=== Client Interface ===
Look at the top right of the game window. You'll see some tabs. The most important tabs are the Status and Admin tabs. The admin tab contains the “'''adminhelp”''' button, used to contact admins directly if you have a '''rules question''' or believe someone is breaking the rules. For gameplay use the mentor tab. Here is a quick break down of the tabs:
* Status: Displays important info such as your ping, the current map, pressure remaining in airtanks, etc.
* [[Admin]]: Contains buttons that allow you if any admins are online, and most importantly, to send a message directly to the admins (the '''adminhelp''' button). If no admins are online, the message will be forwarded to the admin IRC channel.
* [[Mentor]]: Explained in the “getting help” section. Contains buttons that allow you to see if any mentors are online, and allow you to ask a question directly to the mentors (the "mentorhelp" button). Mentorhelps are not forwarded like adminhelps.
* [[IC]]: Usually, won't use this. The '''Pray''' button allows you to send a message to any admins online in character meaning it's used for "communicating with the gods". Or the notes button which has your bank ID or shows any antag objectives if you have them.
* OOC: Stands for "Out of Character". Rarely needs to be used. Various functions that are related to the game, but not something your character does.
* Object: Never used.
* Preferences: Self-explanatory. Contains various options you can toggle on and off.
On the right side will be the chat window. And above the chat window there are some tabs like “Admin” or “Preferences”. Feel free to immediately click the blue gear in the chat window and turn on night mode. Anyway, before you can join we need to create your character.
===Character Creation===
{{Speech
|name=Tuterr, the Private Eye
|text=You're brand new here, so make sure you sign up as an Assistant. Nanotrasen usually has checks to make sure fresh meat doesn't get to be the Captain, but if you manage to end up in that position, you'll probably be just another case for me to solve.|image=[[File:Generic detective.png|64px|right]]
}}
Recommended species for new players is [[Humans|human]]. Humans don’t have any major ups or downs. Later you can play as one of the [[Races|more exotic species]]. Other than that, it’s all mostly cosmetic. The Occupations tab lets you select your job preferences when a new round is starting. You, as a new player, want to set assistant to YES. For more information about job distribution on round start [[Job selection and assignment|see here]]. Again, this only applies to round start. In the case of on-going rounds, the “Join Game!” button will just let you pick what job you want assuming there are open slots. In the case of assistants that is always. Once you've finished editing your appearance, the box in the title bar should hopefully say "Saved!", verifying that your choices saved properly.<gallery>
File:Character settings.PNG|Character Creation Screen
File:New Occupation screen.JPG|Job Preferences Screen
File:Game prefences Screen.PNG|Preferences Window
File:Status tab top.png|Client Tabs
</gallery>
== HUD & Controls ==
The biggest barrier to entry in Space Station 13 is the controls. Despite the reputation once it clicks, you'll never have an issue with it again. '''Don't let it overwhelm you!''' After a round or two of practice, you should be fine.
===HUD===
{{Speech
|name=Tuterr, the Private Eye
|text="Interface"? What the hell are you talking about, kid? "Blue buttons?" Geez, you've been here for five minutes and you're already cracking. Hmmm... *recorder crackles* Note to self - check atmospherics. Gas might be poisoned.|image=[[File:Generic detective.png|64px|right]]
}}
The top right of the screen contains the action tabs and the bottom right is the text log or chat window. This is where you can see what people are saying, what's happening around you, and chat such as OOC or adminhelps. The bar along the bottom of the screen is the input bar, but since we're on [[Keyboard_Shortcuts|Hotkey]] mode we won't need to use it. There are a few HUD elements on the main screen, so let's break them down into sections. Don't worry if you can't memorize what everything does at once. You can always come back to this guide.
<tabs>
<tab name="Hands">[[File:Hud-hands.gif]] One of the most important elements of the HUD. You have the ability to hold an item in each hand (unless an item takes up both hands, obviously). The square around one of the hands is the '''selected hand'''. If you have an '''empty''' selected hand, and click on an object, you'll pick it up/open it/use it. If '''an object is in your selected hand''' and you click on something, you'll use it on the item you're holding. (The way this works means that if you'd like to unequip your backpack, you need to click and drag the bag into your hand - if it was removed by clicking on it, you'd never be able to open the bag.)

'''If this seems confusing, don't worry - it'll be explained shortly.'''</tab>
<tab name="Inventory Buttons">These icons manage your inventory.

The backpack [[File:Hud-inventory.png]] icon can be toggled to show your worn equipment.

The belt [[File:Hud-Belt.png]], backpack [[File:Hud-Back.png]], and pocket [[File:Hud-Pocket.png]] icons are all storage locations.

The ID [[File:Hud-ID.png]] slot can hold your ID, or your PDA (which can hold your ID).</tab>
<tab name="Interact Commands">These buttons directly affect how you interact with objects.

The drop [[File:Hud-drop.png]] and throw [[File:Hud-throw.png]] icons do what the name implies. Dropping is self explanatory, but the throw button is a toggle - if it's on and you click somewhere, you'll throw the item in your hand at where you clicked. (You can also press R to enable throwing and Q to drop your held item.)

The pull [[File:Hud-pull.png]] icon only appears when dragging something, and can be pressed to stop dragging an object. [[Keyboard_Shortcuts|Hotkey]]: "H".

The internals [[File:Gmaskinternalsicon.gif]] icon can be clicked to enable/disable your internals (oxygen tank and breath mask).

The resist [[File:Hud-resist.png]] icon can be pressed to break out of grabs, restraints, and if you're on fire, is the "stop drop and roll" button. [[Keyboard_Shortcuts|Hotkey]]: "B".

The run/walk toggle [[File:Hud-walkrun.gif]] icon can be pressed to switch between running and walking. Running is faster, but walking has benefits, such as being able to walk over water without slipping - useful for when the janitor doesn't put wet floor signs down. [[Keyboard_Shortcuts|Hotkey]]: Hold "alt" to walk.

The body selector [[File:Hud-target.gif]] icon is used to choose which body part you want to target. This is used for both targeting specific sections to heal, or targeting specific sections when attacking someone. Click a limb to target it. (You can target individual arms, legs, the head, the upper torso, the groin, the eyes, or the mouth.) [[Keyboard_Shortcuts|Hotkeys]]: "numpad keys".

Last but not least is the intent selector [[File:Hud-intent.gif]] - this will be explained in detail later. It has four modes: '''Help''', '''Disarm''', '''Grab''', and '''Harm''', in clockwise order. [[Keyboard_Shortcuts|Hotkeys]]: "1-4".</tab>
<tab name="Other">The health [[File:Hud_100_percent_Health.gif]] icon and [[File:Healthdoll.gif]] doll change depending on how injured you are.

The crafting menu [[File:Craft.gif]] icon opens the crafting menu.

The speech bubble [[File:Talk_wheel.gif]] icon opens the languages menu. You won't need to use this for the tutorial.

The create area [[File:Area_edit.gif]] icon is used to create an "area", which is a more advanced topic. You won't need to worry about it for this tutorial.</tab>
<tab name="Alerts">These will only appear on the HUD if something is wrong.

[[File:Hud-oxy.gif]] '''Oxygen warning''' - The air you're breathing doesn't have enough oxygen.

[[File:Hud-pressure.gif]] '''Pressure warning''' - Pressure levels are too high (red) or too low (black). Low and high pressures can kill you.

[[File:tox_in_air.gif]] '''Toxin warning''' - You are breathing in toxic gases.

[[File:Hud-fire.png]] '''Fire warning''' - The air is hot enough to burn you.

[[File:Hud-freeze.gif]] '''Freeze warning''' - The air is cold enough to freeze you.

[[File:Hud-temp.gif]] '''Temperature warning''' - You're too cold or too hot.

[[File:Hud-hunger.gif]] '''Hunger warning''' - You're starting to get hungry. You cannot die from hunger, but the longer you go without food, the slower you will be able to run. You can also eat too much and become bloated.</tab>
</tabs>
===Controls===
[[File:Hotkeys.png|thumb|500px|[[Keyboard_Shortcuts|Keybindings]] for the hotkey mode.]]
Don’t get scared by the hotkey image. It shows ''all'' the controls and their alternatives. This might seem like a lot, but don't worry, you'll only be using a few most of the time. The control are quite elegantly designed. There are exceptions, but for the most part you will be able to anything from surgery to nuclear science with the exact same controls. You won't need to memorize 20 hotkeys.

The default control scheme is “hotkeys” set in the game preferences menu. In case it’s not working you will see the bottom-right textbox in a red color. Click anywhere in the game window and press '''Tab'''. The textbox should go white showing that you are in “hotkey” mode.
*Use the '''WASD''' keys to move around.
* Press the '''X''' key to swap your active hand. The hand system is explained below.
*Press the '''Q''' key to drop what you are currently holding in your hand on the ground.
*Press the '''T''' key to talk. Prefix what you say with a semicolon (;) to say it in the global radio channel. Use the '''M''' key for non-verbal actions like “smile” or “wave”.Use the '''U''' key for LOOC (described in Getting Help).
*Use '''left click''' on a thing to interact with it. Interact means different things based on the thing you are clicking. Use '''right click''' for a context menu (mostly used for stacks of items).
*Press the '''Z''' key with an item in hand to “use” it.
*Use '''SHIFT + click''' on anything to examine it. Your new favorite button combo. It will describe what you are looking at. As a new player you will be using this ''very often''. Use this on anything and everything.
If you just want to just jump into a round immediately the above controls should be enough for your first round. Doing a task, like, asking someone where the drink vending machine is, buying and then drinking something is a good way to start getting the hang of the controls.

It is '''necessary''' to read the '''[[FullControls|full controls page]]''' after your first (or such) round, however. You can also check out all the available [[Keyboard Shortcuts|hotkeys]].
== Gameplay Concepts ==
Before getting into anything else, it's important to note that since SS13 is such an open ended game that has other people in it, when you get in game and try to follow the guide, things may go wrong - the station might have been almost entirely consumed by a singularity, a traitor could attack you with a powerful weapon, or something no one could have predicted will kill you. '''It's important to not let death get to you!''' There are multiple ways you can be brought back into the game, so don't get frustrated if something happens.
{{Speech
|name=Tuterr, the Private Eye
|text=You know, as much as I like to rib the fresh meat, it doesn't really matter if something happens to them - Nanotrasen thinks death is a waste of money, they'll just get cloned or something. What? Oh, shit, I gotta go. *click* You, uh, didn't hear that - right, kid?
|image=[[File:Generic detective.png|64px|right]]
}}
===The Hands System===
If an item requires two hands to use, then the other hand slot will instead be labeled as “off-hand”. Why do I start by telling you this? Because only one hand can be selected at a time. Imagine yourself as a creature with one hand. You only sprout a second hand when you need to use two handed items.

Another time when you sprout an extra hand is to '''just''' hold an item. That is because your hands are also just a part of your inventory. However, think of them as an “active” part of your inventory. You place items in these “active” slots when you want to use them.

The bright box around one of your hands is the selected hand. Swap your selected hand with the '''X''' key. This is the hand that's used whenever you click on something. If it’s empty. Otherwise, you will use what you are holding in your hand on what you clicked on.

This can also cause problems with backpacks, boxes, and other containers. If you want to open a container, '''Alt + Click''' it. You can also pick it up, then switch hands and click on the container with an empty hand. Clicking on a container with an object will put it in the container. This also means that if you'd like to '''take your backpack off''', you need to click and drag the bag to an empty hand. Normal click just opens the equipped bag.

If you find this confusing, you should go check out the [[FullControls|full controls page]] already! It goes hand in hand (GET IT!?) with this explanation. If you still find it confusing, then maybe you should play your first round already because it really is not that complicated.
===[[Intent|Intents]]===
The intent selector has four modes: '''help''' [[File:Intent_Help.png]], '''disarm [[File:Intent_Disarm.png]]''', '''grab''' [[File:Intent_Grab.png]], and '''harm [[File:Intent_Harm.png]]'''. This system mostly controls how you interact with things with your bare hands. You can learn more about these uses on [[Intent|the intents page]]. It's not, however, critical that you learn this right now. When it comes to using '''things''' this system is '''much simpler then it appears'''. Using a crowbar on someone will hit them '''regardless''' of intent. Most items work like that. Instead when it comes to '''things''' there are special use cases, for example:
*While doing surgery, if you are '''not''' on help [[File:Intent_Help.png]] intent, you will intentionally botch it.
*Clicking on something next to you with a gun will shot them point blank. If, however, you are on harm '''[[File:Intent_Harm.png]]''' intent you will hit them with the weapon instead.
* Using harm '''[[File:Intent_Harm.png]]''' intent on an airlock with a welder will weld it shut instead of repair it.
You don't need to know these things right now. It's just so you understand the types of specific thing you will use intents for. The only intent related thing I want you to know for now is that clicking on people with and empty hand with help [[File:Intent_Help.png]] intent will hug them. Very important.
== Playing the Game ==
[[File:HUD_no_labels.png|thumb|489x489px|Arriving on the station.]]
{{Speech
|name=C-05-MO, the AI
|text=Hello! The automatic diagnostic and announcement system welcomes you to Space Station 13. Remember: Have a secure day.
|image=[[File:AI.gif|64px|right]]
}}
If you join a game in progress, you'll spawn on the [[Arrivals|arrival shuttle]]. You'll start buckled onto a chair. Use the '''B''' key to resist out of the chair (or click the HUD icon).
===Finding Your Way Around===
On of the hardest things for new players is learning what there is on the station and where it is. This is compounded by the fact that we have [[Maps|several different stations]] with different designs. Look out for signs on the walls. Ask the people in the hallway. Look out for lines on the floor in the case of [[webmap:FlandStation|Fland]] or [[webmap:RadStation|Rad]] station. Ask the [[Mentor|mentors]].

We live in the future! And thanks to revolutionary advancements in technology, we have an online map viewer for all [[Maps|BeeStation stations]]! Check the map you are currently on in the status page and then find the webmap link on the [[Maps|maps page]].

It is helpful not just to find your way, but to get a more complete understanding of the stations. You can notice things here that are a common trend across all stations like: [[bar]] is always next to [[kitchen]], [[atmospherics]] are always next to [[engineering]], the [[Dormitory|dorms]] always have a room for cryosleep in case you want to leave the game, and more for you to discover!

Since you've chosen [[Assistant]] as your role, you'll have no responsibilities. This means you can safely attempt to get your bearings without fear of someone telling you that you need to be doing something. Check out the [[FullControls#Tasks to practice the controls|full controls page for suggestions]]. Eventually, once you're confident in the controls, why not consider doing some [[How to Roleplay|roleplaying]]? This is a roleplay server, after all.
===Inventory Management [[File:Backpack.png]]===
Items in the game have 4 different "weight classes," tiny, small, normal, and bulky. These weight classes determine which storage slots it can fit in, and what they can't fit in. If you are wearing a jumpsuit, the two item storage slots to the rightmost of your screen are your pockets.
*These pockets can only store tiny and small items.
*Your hands are where you can grab items and interact with them.
*Your back is where you should have your backpack.
*Your backpack is your main storage space, but it can only fit a limited number of items. You can stuff tiny, small, and normal classed items into your backpack. However, normal classed items will take up more storage space than a tiny classed item.
*Your belt is where you store your toolbelt, (if you are an [[Station Engineer|engineer]]), your [[Laser Gun|gun]], or a variety of other different items, which range from swords to [[Defibrillator|defibrillators]].
* The items which you can fit in your suit storage (on the left most of your screen, below your gloves) depend on the uniform you are wearing. For example, a [[hardsuit]] would allow you to fit an oxygen tank in there, whilst an [[Armor Vest|armor vest]] would allow you to fit a [[laser gun]].
This is one of those things where there are a lot of exceptions. Simply ask around or experiment to find out all the interesting combinations of storage.
===Using Internals===
Your character starts with a [[box]]. Inside the box you will find an EpiPen. It’s used to stabilize people in [[Crit|critical]] condition. You will also find an [[emergency oxygen tank]] and a breathing mask. In a situation where there is a lack of oxygen, a viral outbreak, or some toxic gas in the air you can use this.
#Equip the mask into your mask slot [[File:Hud-Mask.png]] (press the equipment [[File:Hud-inventory.png]] icon to see it) or quickly equip with the '''E''' key.
#Place the oxygen tank into your pockets and press the [[File:Gmaskinternalsicon.gif]] button on the top left. You are now breathing from the oxygen tank.
Despite being called an emergency oxygen tank these puppies start with ~1000 kPa of pure oxygen. This, in layman’s terms, means you can breathe from one of these for about 30 minutes. You don’t have to fear running out of air in 5 minutes. The situation to use internals are not that common though. Lack of oxygen is usually accompanied by extreme temperature or pressure. The mask will not help with those. The best way to deal with things like breaches, fire or [[plasma]] fires is to run away from the affected area.
===Using suit sensors===
Every [[Nanotrasen]] [[jumpsuit]] comes with a mechanism called [[suit sensors]]. Right click on your jumpsuit and use the “adjust suit sensors mode”. It should be, by default, set to the highest level. If not, make sure to set them. I’m sure you can guess what they do by name alone. [[Medical Doctor|Medical]] and [[Security Officer|Security]] crew have access to [[Crew Monitoring Console|crew monitoring consoles]]. They can also use [[Pinpointer|pinpointers]] to locate crew. This only works if your suit sensors are on. In the unfortunate case of your early departure from this moral coil the good folk in medical possibly locate are resurrect or clone your body.
===What To Do if You Are Hurt or See Someone Hurt on the Ground?===
Go to the medbay. If you happen to see a dead or near dead person on the ground, you should take the following steps: Remember that EpiPen? Now is the time to use it. What is happening to a person in [[critical]] condition is that they are slowly suffocating. Injecting them with the EpiPen will prevent this suffocation, buying a lot of time. Then since they are hurt, they are probably bleeding. '''Do not drag them across the floor''' as this slowly kills them. Instead consult the [[FullControls|full controls]] page on how to lift a body in a fireman’s carry.
===What To Do if You Are Attacked?===
In the case that someone attacks you, you are already dead probably. If you are attacked by a [[Blood Cult|blood cultist]] using [[Blood Cult#Blood Spells|eldritch magic]], blood weapons and that has the jump on you; it’s not supposed to be a fair fight. Or a fight at all rather.

In the case where you [[Byond the impossible|are not already dead]]. The first thing you want to do is scream “HELP” in the global radio chat. Because we can’t play the game and talk, an all uppercase “help” is like a special summoning call for [[Security Officer|security]], the [[AI]], or the [[Medical doctor|medical]] crew. If you have your [[Suit sensors|sensors]] turned on you don’t have to say where you are being attacked. Once the [[Terminology#Valid/Validhunting|valid hunters]] have been summoned the next step is to run away (bravely!). Look for the main station corridor as it is a public area and has lots of space. Avoid going into areas you don’t know since you might dead-end yourself.

Once you get better acquainted with the [[rules]] you can read the [[Guide to Combat|combat guide]] (outdated; ask some security players for classes), to learn how to fight back.
===Radiation Storms===
When you hear a message stating: '''''"'''High levels of radiation detected near the station. Maintenance is best shielded from radiation.'''";''''' that means a [[Random events#Radiation Storm|radiation storm]] is coming. This message is misleading, because maintenance is the only place protected from radiation. Normally, if the heads are competent, a station-wide emergency will then be declared opening up [[maintenance]] even if you don't have access. All you have to do now is mill in [[maintenance]] until the radiation storm passes over. If you get hit by the radiation or feel sick in general head to the [[medbay]].
==Properly Leaving The Game (Cryosleep)==
Too confused? Head hurts? Mom called you to eat dinner? Whatever the reason you wish to leave the game, there is a proper way to do it. Crew and job slots are based on the number of living crew. The proper way to leave the round is to go the [[Dormitory|dorms]] and find the cryosleep pods. They are bright green. If you can’t find the dorms just ask [[Crew|someone]] (like a [[mentor]]). There are usually signs as well such as “DORMS”, “SLEEP” or “REST”. If you lay into a cryosleep pod and then log out or rather exit the game your body will be removed from the round, you will become a ghost and an empty crew an job slot will open for someone else. Speaking of ghosts...
==Death and Ghosts==
Tried to be a [[Clown|funny guy]] with the [[Traitor|wrong]] [[Changeling|person]]? Wrong [[Blood Cult|place]], wrong [[Nightmare|time]] in maintenance? Whatever the case, you are now [[dead]]. Don’t despair just yet! If the [[Antagonist|bad man]] has not completely destroyed your body and you turned your suit sensors on max there is a chance that some good [[paramedic]] will find your charred and bruised corpse and bring it to the [[medbay]] to be revived or [[Clone|cloned]].

In the meantime, move the ghost out of your body. This is spectator mode. You can communicate with other dead players. It’s fine to talk in an [[OOC]] way in Dchat. In the case you are revived you are '''not allowed''' to use any information gained while being a ghost. Anything you saw while you were alive is fair game though. Unless you are cloned that is. If you are cloned, you forget the last 15 minutes of your life.

In while being a ghost there is a chance to be prompted to become things like xenomorphs or swarmer. Sometimes these are random events and sometimes admin interference.

There is also a ghost spawner menu. From here you can spawn as certain things on [[Lavaland]]. If you choose to do this, you will no longer be able to revive or be cloned. When you spawn you are a new entity. You are unaware of your past life. For a new player a recommendation can be spawning as a [[Lavaland]] doctor. You get your own [[Lavaland]] hospital where you can freely practice [[Guide to medicine|medicine]] and [[surgery]] on monkeys as well as [[Guide to hydroponics|botany]] and [[Guide to chemistry|chemistry]].
==What Jobs to Take After Your First Round==
The best beginner jobs are ones where no one is going to come to you asking for something you don't really understand. Assistant is the best because no one expects anything at all from you. You are free to explore and play with the controls. However once you get a grip on the controls is recommended to move to a job where still no one expects anything, but that have a designated objective. The recommended assistant ''plus'' roles are:
*[[Janitor]]: People will expect nothing from you except maybe that you clean the floor.
*[[Curator]]: The library is practically abandoned. Play with board games and painting. Organize books. Get fun loot from your curator beacon.
*[[Cargo Technician|Cargo Tech]]: Move crates until you die. It is said that all SS13 journeys begin and end in cargo. This is because cargo is of vital importance to several game modes. As a CT you will get to see the flow of these rounds first hand. However, your job will still remain to be just moving crates.
After that it's time to move on to some real roles. Funnily enough, the best way to learn these roles is to sign up as an assistant again. You are going to use this role as intended and actually assist some departments. Going to the [[Head of Personnel|HoP]] or whatever place you want to learn about and asking nicely for someone to teach you is a very effective way to learn. The [[Head of Personnel|HoP]] can even give you custom job titles like "medical intern" or "brig receptionist". Job that are good for this are: [[Medical Doctor]], [[Scientist]], [[Station Engineer]]... This is also the best way to dip your toes safely into being a [[Security Officer]]. Be careful, because it's very easy to play security poorly, and [[Shitcurity|letting the power get to your head is a bad idea]].

Avoid joke roles such as the [[Clown]] or [[Mime]] at first. Many players find harassing the on board entertainment much more fun than any jokes the clown might otherwise have.

After some time, when you're confident enough in your combat abilities, you should enable antagonists within your game preferences, so that you can roll for antag when the shift starts. A good half of the game is arguably being an antag and beating everyone up. Don't be scared that you will be a bad antag. Due to the fact that you can't predict what or when it will happen everyone was a painfully obvious antag at one point. It's just how the game works. You should however avoid team antag roles. [[Blood Cult|Blood cult]], blood brothers, [[Revolutionary|revolutions]], [[Clockwork Cult|clock cultists]], [[Nuclear Operative|nuclear operatives]], [[Xenomorph|xenomoprhs]]... The most common and "safe" antag options to dip you toes in are [[Traitor]] and [[Changeling]].

Starter guide

2023-06-25T06:48:47Z

Itsmeowdev: /* Controls */ Add TGUI say keys

= [[What is SS13|What is SS13?]] =
'''Space Station 13''' is a multiplayer sandbox that has a heavy focus on player interaction. In the year 2557, the megacorporation [[Nanotrasen]] employed you as a staff [[Jobs|member]] onboard their latest state of the art [[Guide to Research and Development|research]] station. Nanotrasen claims to be researching [[plasma]], a mysterious new substance, but rumors abound that the station is little more than a [[Clown|twisted]] [[Traitor|social]] [[Assistant|experiment]]...{{Speech
|name=Tuterr, the Private Eye
|text=Hmph. Fresh off the boat from Nanotrasen's recruitment office, huh? Let me tell you something, kid. You won't last five minutes on this floating deathtrap without help. You're as likely to be left for dead in a dark maintenance tunnel riddled with bullet holes as you are to get out of here alive. Lucky for you, I'm in a helpful mood today.
|image=[[File:Generic detective.png|64px|right]]
}}
At the start of each round, each player is assigned a role onboard the station. There are many jobs, such as the [[Scientist|scientist performing research and development of new technologies]], the [[Medical Doctor|medical doctor]] trying to keep people alive, or the simple [[janitor]]. There are many ways to play. The game also randomly chooses a [[Game Mode|round type]], ranging from an all-out assault on the station by [[Nuclear Operative|nuclear operatives]], a sinister [[Blood Cult|cult sacrificing crewmembers]] to summon their [[Nar-Sie|god]], or more commonly, good ol' fashioned [[Traitor|traitors]]. It is player driven and not some procedurally generated indie game. Every round on '''Space Station 13''' is different and a completely unique experience.
== Before Playing ==
Your choices matter in SS13. They have [[Ghost|consequences]]. The [[rules]] are here to ensure that when [[How to Roleplay|drama]] and [[Guide to Combat|conflict]] happen, they happen in a way that is [[Byond the impossible|beneficial to all parties involved]]. You should read the [[rules]] before playing. If you don’t understand them all don’t worry. You can engage in the server more and more as you understand.

At a base level don’t attack players without any reason. Role playing as an “insane person” is '''not valid'''. If you want to be extra safe (there is no reason to be this afraid though) you can avoid any kind of fight. Most rules define who, what, where and how is allowed to fight, main or kill. If you don’t fight you automatically comply with these rules. One last point: Please, remember the human. SS13 can be highly frustrating, you will be unceremoniously killed, griefed, or die to some galactic space-bug shortly before executing your master plan. Everyone is here to play a game they enjoy, so keep that in mind before you bash someone's brain in with a [[toolbox]] because they took your [[multitool]].
== Getting Help ==
If you happen to get confused about something there are several ways to resolve this. The easiest is to contact a [[mentor]]. There is almost always at least one online. Don’t be shy! They love helping new players! In the top right there is a mentor tab. You can use “mentorwho” to check if any are online. Then you can use “mentorhelp” to send your question.

In the case there are none you can ask the players around you. It might be difficult to communicate your problem in an [[IC]] (in character) way. It might also be difficult to answer in an [[IC]] way. That is why we have the LOOC or “local out of character” button which defaults to the '''U''' key. LOOC is a special yellow text visible only in the chat window. Meaning it has no rune text (text over the head). LOOC is used to discuss [[OOC]] things. For advanced users it’s used to [[Byond the impossible|set up more complex RP scenarios]]. For beginners, like yourself, it’s used to explain controls in a literal “click this press that” way that [[IC]] does not allow.
== Setting Up ==
Download the [https://www.byond.com/download/ BYOND client]. If you are in the Discord server, you can use the ?byond command in the bot spam window. BeeStation has two servers:
*'''The Main BeeStation Sage:''' byond://sage.beestation13.com:7878
*'''The Overflow Low-pop BeeStation Acacia:''' byond://acacia.beestation13.com:7979
To join the game, you can use the links on the website. If you are in the Discord server there is a dedicated bot-spam channel. Use the “?cs” command to ask the bot about the current round information on the main BeeStation server Sage. The bot output will include a link that you can just click. These two methods are preferred by most veteran players (mostly the latter) since you avoid interacting with the icky Byond client.

Once you are in you will see a small window with some buttons. This is either “Ready” and “Not Ready” buttons or the “Join Game!” button depending on if the round is about to start or on-going. There is also a “Create Character” button we will be using shortly.

BeeStation operates on a round based system. Every round is a new “shift” not related in any way to the past ones. The typical round length is around 1:30 minutes. This is because at that time there is a “crew transfer vote” which is basically a “are we done with this round?” vote. This is also plenty of time for things to go horribly wrong in the case of any of the [[Game Mode|major game modes]].

If you jump onto the server, you are very likely to have joined during an active round. Using the “Status” tab, you can see the current round information. Speaking of which...
=== Client Interface ===
Look at the top right of the game window. You'll see some tabs. The most important tabs are the Status and Admin tabs. The admin tab contains the “'''adminhelp”''' button, used to contact admins directly if you have a '''rules question''' or believe someone is breaking the rules. For gameplay use the mentor tab. Here is a quick break down of the tabs:
* Status: Displays important info such as your ping, the current map, pressure remaining in airtanks, etc.
* [[Admin]]: Contains buttons that allow you if any admins are online, and most importantly, to send a message directly to the admins (the '''Adminhelp''' button). If no admins are online, the message will be forwarded to the admin IRC channel.
* [[Mentor]]: Explained in the “getting help” section. Contains buttons that allow you to see if any mentors are online, and allow you to ask a question directly to the mentors (the "mentorhelp" button). Mentorhelps are not forwarded like adminhelps.
* [[IC]]: Usually, won't use this. The '''Pray''' button allows you to send a message to any admins online in character - often used for "communicating with the gods". Or the notes button which will you bank ID or show any antag objectives if you have them.
* OOC: Stands for "Out of Character". Rarely needs to be used. Various functions that are related to the game, but not something your character does.
* Object: Never used.
* Preferences: Self-explanatory. Contains various options you can toggle on and off.
On the right side will be the chat window. And above the chat window there are some tabs like “Admin” or “Preferences”. Feel free to immediately click the blue gear in the chat window and turn on night mode. Anyway, before you can join we need to create your character.
===Character Creation===
{{Speech
|name=Tuterr, the Private Eye
|text=You're brand new here, so make sure you sign up as an Assistant. Nanotrasen usually has checks to make sure fresh meat doesn't get to be the Captain, but if you manage to end up in that position, you'll probably be just another case for me to solve.|image=[[File:Generic detective.png|64px|right]]
}}
Recommended species for new players is [[Humans|human]]. Humans don’t have any major ups or downs. Later you can play as one of the [[Races|more exotic species]]. Other than that, it’s all mostly cosmetic. The “occupation preference” button declares occupation preferences when a new round is starting. More info on that here. You, as a new player, want to set assistant to YES. For more information about job distribution on round start [[Job selection and assignment|see here]]. Again, this only applies to round start. In the case of on-going rounds, the “Join Game!” button will just let you pick what job you want assuming there are open slots. In the case of assistants that is always, however. Once you've finished editing your appearance, be sure to press the '''Save Setup''' button at the bottom of the window.<gallery>
File:Character settings.PNG|Character Creation Screen
File:New Occupation screen.JPG|Job Preferences Screen
File:Game prefences Screen.PNG|Preferences Window
File:Status tab top.png|Client Tabs
</gallery>
== HUD & Controls ==
The biggest barrier to entry in Space Station 13 is the controls. Despite the reputation once it clicks, you'll never have an issue with it again. '''Don't let it overwhelm you!''' After a round or two of practice, you should be fine.
===HUD===
{{Speech
|name=Tuterr, the Private Eye
|text="Interface"? What the hell are you talking about, kid? "Blue buttons?" Geez, you've been here for five minutes and you're already cracking. Hmmm... *recorder crackles* Note to self - check atmospherics. Gas might be poisoned.|image=[[File:Generic detective.png|64px|right]]
}}

The top right of the screen contains the action tabs and the bottom right is the text log or chat window. This is where you can see what people are saying, what's happening around you, and chat such as OOC or adminhelps. The bar along the bottom of the screen is the input bar, but since we're on [[Keyboard_Shortcuts|Hotkey]] mode we won't need to use it. There are a few HUD elements on the main screen, so let's break them down into sections. Don't worry if you can't memorize what everything does at once. You can always come back to this guide.
<tabs>
<tab name="Hands">[[File:Hud-hands.gif]] One of the most important elements of the HUD. You have the ability to hold an item in each hand (unless an item takes up both hands, obviously). The square around one of the hands is the '''selected hand'''. If you have an '''empty''' selected hand, and click on an object, you'll pick it up/open it/use it. If '''an object is in your selected hand''' and you click on something, you'll use it on the item you're holding. (The way this works means that if you'd like to unequip your backpack, you need to click and drag the bag into your hand - if it was removed by clicking on it, you'd never be able to open the bag.)

'''If this seems confusing, don't worry - it'll be explained shortly.'''</tab>
<tab name="Inventory Buttons">These icons manage your inventory.

The backpack [[File:Hud-inventory.png]] icon can be toggled to show your worn equipment.

The belt [[File:Hud-Belt.png]], backpack [[File:Hud-Back.png]], and pocket [[File:Hud-Pocket.png]] icons are all storage locations.

The ID [[File:Hud-ID.png]] slot can hold your ID, or your PDA (which can hold your ID).</tab>
<tab name="Interact Commands">These buttons directly affect how you interact with objects.

The drop [[File:Hud-drop.png]] and throw [[File:Hud-throw.png]] icons do what the name implies. Dropping is self explanatory, but the throw button is a toggle - if it's on and you click somewhere, you'll throw the item in your hand at where you clicked. (You can also press R to enable throwing and Q to drop your held item.)

The pull [[File:Hud-pull.png]] icon only appears when dragging something, and can be pressed to stop dragging an object. [[Keyboard_Shortcuts|Hotkey]]: "H".

The internals [[File:Gmaskinternalsicon.gif]] icon can be clicked to enable/disable your internals (oxygen tank and breath mask).

The resist [[File:Hud-resist.png]] icon can be pressed to break out of grabs, restraints, and if you're on fire, is the "stop drop and roll" button. [[Keyboard_Shortcuts|Hotkey]]: "B".

The run/walk toggle [[File:Hud-walkrun.gif]] icon can be pressed to switch between running and walking. Running is faster, but walking has benefits, such as being able to walk over water without slipping - useful for when the janitor doesn't put wet floor signs down. [[Keyboard_Shortcuts|Hotkey]]: Hold "alt" to walk.

The body selector [[File:Hud-target.gif]] icon is used to choose which body part you want to target. This is used for both targeting specific sections to heal, or targeting specific sections when attacking someone. Click a limb to target it. (You can target individual arms, legs, the head, the upper torso, the groin, the eyes, or the mouth.) [[Keyboard_Shortcuts|Hotkeys]]: "numpad keys".

Last but not least is the intent selector [[File:Hud-intent.gif]] - this will be explained in detail later. It has four modes: '''Help''', '''Disarm''', '''Grab''', and '''Harm''', in clockwise order. [[Keyboard_Shortcuts|Hotkeys]]: "1-4".</tab>
<tab name="Other">The health [[File:Hud_100_percent_Health.gif]] icon and [[File:Healthdoll.gif]] doll change depending on how injured you are.

The crafting menu [[File:Craft.gif]] icon opens the crafting menu.

The speech bubble [[File:Talk_wheel.gif]] icon opens the languages menu. You won't need to use this for the tutorial.

The create area [[File:Area_edit.gif]] icon is used to create an "area", which is a more advanced topic. You won't need to worry about it for this tutorial.</tab>
<tab name="Alerts">These will only appear on the HUD if something is wrong.

[[File:Hud-oxy.gif]] '''Oxygen warning''' - The air you're breathing doesn't have enough oxygen.

[[File:Hud-pressure.gif]] '''Pressure warning''' - Pressure levels are too high (red) or too low (black). Low and high pressures can kill you.

[[File:tox_in_air.gif]] '''Toxin warning''' - You are breathing in toxic gases.

[[File:Hud-fire.png]] '''Fire warning''' - The air is hot enough to burn you.

[[File:Hud-freeze.gif]] '''Freeze warning''' - The air is cold enough to freeze you.

[[File:Hud-temp.gif]] '''Temperature warning''' - You're too cold or too hot.

[[File:Hud-hunger.gif]] '''Hunger warning''' - You're starting to get hungry. You cannot die from hunger, but the longer you go without food, the slower you will be able to run. You can also eat too much and become bloated.</tab>
</tabs>
===Controls===
[[File:Hotkeys.png|thumb|500px|[[Keyboard_Shortcuts|Keybindings]] for the hotkey mode.]]
Don’t get scared by the hotkey image. It shows ''all'' the controls and their alternatives. This might seem like a lot, but don't worry, you'll only be using a few most of the time. The control are quite elegantly designed. There are exceptions, but for the most part you will be able to anything from surgery to nuclear science with the exact same controls.

The default control scheme is “hotkeys” set in the game preferences menu. In case it’s not working you will see the bottom-right textbox in a red color. Click anywhere in the game window and press '''Tab'''. The textbox should go white showing that you are in “hotkey” mode.
*Use the '''WASD''' keys to move around.
* Press the '''X''' key to swap your active hand. The hand system is explained below.
*Press the '''Q''' key to drop what you are currently holding in your hand on the ground.
*Press the '''T''' key to talk. Prefix what you say with a semicolon (;) to say it in the global radio channel. Use the '''M''' key for non-verbal actions like “smile” or “wave”. Use the '''O''' key for OOC chat. Use the '''U''' key for LOOC (Local Out-Of-Character, a type of OOC isolated to those within your view that works in-round). Use the '''Y''' key to speak on the radio without typing the ''';''' prefix.
*Use '''left click''' on a thing to interact with it. Interact means different things based on the thing you are clicking. Use '''right click''' for a context menu (mostly used for stacks of items).
*Press the '''Z''' key with an item in hand to “use” it.
*Use '''SHIFT + click''' on anything to examine it. Your new favorite button combo. It will describe what you are looking at. As a new player you will be using this ''very often''.
If you just want to just jump into a round immediately the above controls should be enough for your first round. Doing a task like asking someone where the drink vending machine is, buying and then drinking something.

If you are not as impatient skim the '''[[FullControls|full controls page here]]'''. You can also check out all the available [[Keyboard Shortcuts|hotkeys]].
== Gameplay Concepts ==
Before getting into anything else, it's important to note that since SS13 is such an open ended game that has other people in it, when you get in game and try to follow the guide, things may go wrong - the station might have been almost entirely consumed by a singularity, a traitor could attack you with a powerful weapon, or something no one could have predicted will kill you. '''It's important to not let death get to you!''' There are multiple ways you can be brought back into the game, so don't get frustrated if something happens.
{{Speech
|name=Tuterr, the Private Eye
|text=You know, as much as I like to rib the fresh meat, it doesn't really matter if something happens to them - Nanotrasen thinks death is a waste of money, they'll just get cloned or something. What? Oh, shit, I gotta go. *click* You, uh, didn't hear that - right, kid?
|image=[[File:Generic detective.png|64px|right]]
}}
===The Hands System===
If an item requires two hands to use, then the other hand slot will instead be labeled as “off-hand”. Why do I start by telling you this? Because only one hand can be selected at a time. Imagine yourself as a creature with one hand. You only sprout a second hand when you need to use two handed items.

Another time when you sprout an extra hand is to JUST hold an item. That is because your hands are also just a part of your inventory. However, think of them as an “active” part of your inventory. You place items in these “active” slots when you want to use them.

The bright box around one of your hands is the selected hand. Swap your selected hand with the '''X''' key. This is the hand that's used whenever you click on something. If it’s empty. Otherwise, you will use what you are holding in your hand on what you clicked on.

This can also cause problems with backpacks, boxes, and other containers. If you want to open a container, '''Alt + Click''' it. You can also pick it up, then switch hands and click on the container with an empty hand. Clicking on a container with an object will put it in the container. This also means that if you'd like to '''take your backpack off''', you need to click and drag the bag to an empty hand - a normal click just opens the equipped bag.

If you find this confusing, you should go check out the full controls page. It goes hand in hand (GET IT!?) with this explanation. If you still find it confusing, then maybe you should play your first round already because it really is not that complicated.
===[[Intent|Intents]]===
The intent selector has four modes: '''help''' [[File:Intent_Help.png]], '''disarm [[File:Intent_Disarm.png]]''', '''grab''' [[File:Intent_Grab.png]], and '''harm [[File:Intent_Harm.png]]'''. This system mostly controls how you interact with this your bare hands. You can learn more about these uses on [[Intent|the intents page]]. It's not, however, critical that you learn this right now. When it comes to using '''things''' this system is much simpler then it appears. Using a crowbar on someone will hit them '''regardless''' of intent. Most items work like that. Instead when it comes to '''things''' there are special use cases, for example:
*While doing surgery, if you are '''not''' on help [[File:Intent_Help.png]] intent, you will intentionally botch it.
*Clicking on something next to you with a gun will shot them point blank. If, however, you are on harm '''[[File:Intent_Harm.png]]''' intent you will hit them with the weapon instead.
* Using harm '''[[File:Intent_Harm.png]]''' intent on an airlock with a welder will weld it shut instead of repair it.
You don't need to know these things know. It's just so you understand the types of specific thing you will use intents for. These exceptions are not important to memorize. The only intent related thing I want you to know for now is that clicking on people with and empty hand with help [[File:Intent_Help.png]] intent will hug them.
== Playing the Game ==
[[File:HUD_no_labels.png|thumb|489x489px|Arriving on the station.]]
{{Speech
|name=C-05-MO, the AI
|text=Hello! The automatic diagnostic and announcement system welcomes you to Space Station 13. Remember: Have a secure day.
|image=[[File:AI.gif|64px|right]]
}}
If you join a game in progress, you'll spawn on the [[Arrivals|arrival shuttle]]. (You'll start buckled onto a chair. Use the '''B''' key to resist out of the chair).
===Finding Your Way Around===
On of the hardest things for new players is learning what there is on the station and where it is. This is compounded by the fact that we have [[Maps|several different stations]] with different designs. Look out for signs on the walls. Ask the people in the hallway. Look out for lines on the floor in the case of [[webmap:FlandStation|Fland]] or [[webmap:RadStation|Rad]] station. Ask the [[Mentor|mentors]].

We live in the future! And thanks to revolutionary advancements in technology, we have an online map viewer for all [[Maps|BeeStation stations]]! Check the map you are currently on in the status page and then find the webmap link on the [[Maps|maps page]].

It is helpful not just to find your way, but to get a more complete understanding of the stations. You can notice thigs here that are a common trend across all stations like: [[bar]] is always next to [[kitchen]], [[atmospherics]] are always next to [[engineering]], the [[Dormitory|dorms]] always have a room for cryo sleep in case you want to leave the game, and more for you to discover!

Since you've chosen [[Assistant]] as your role, you'll have no responsibilities. This means you can safely attempt to get your bearings without fear of someone telling you that you need to be doing something. Check out the [[FullControls#Tasks to practice the controls|full controls page for suggestions]]. Eventualy, once you're confident in the controls, why not consider doing some [[How to Roleplay|roleplaying]]? This is a roleplay server, after all.
===Inventory Management [[File:Backpack.png]]===
Items in the game have 4 different "weight classes," tiny, small, normal, and bulky. These weight classes determine which storage slots it can fit in, and what they can't fit in. If you are wearing a jumpsuit, the two item storage slots to the rightmost of your screen are your pockets.
*These pockets can only store tiny and small items.
*Your hands are where you can grab items and interact with them.
*Your back is where you should have your backpack.
*Your backpack is your main storage space, but it can only fit a limited number of items. You can stuff tiny, small, and normal classed items into your backpack. However, normal classed items will take up more storage space than a tiny classed item.
*Your belt is where you store your toolbelt, (if you are an [[Station Engineer|engineer]]), your [[Laser Gun|gun]], or a variety of other different items, which range from swords to [[Defibrillator|defibrillators]].
* The items which you can fit in your suit storage (on the left most of your screen, below your gloves) depend on the uniform you are wearing. For example, a [[hardsuit]] would allow you to fit an oxygen tank in there, whilst an [[Armor Vest|armor vest]] would allow you to fit a [[laser gun]].
This is one of those things where there are a lot of exceptions. Simply ask around or experiment to find out all the interesting combinations of storage.
===Using Internals===
Your character starts with a [[box]]. Inside the box you will find an EpiPen. It’s used to stabilize people in [[Crit|critical]] condition. You will also find an [[emergency oxygen tank]] and a breathing mask. In a situation where there is a lack of oxygen, a viral outbreak, or some toxic gas in the air you can use this.
#Equip the mask into your mask slot [[File:Hud-Mask.png]] (press the equipment [[File:Hud-inventory.png]] icon to see it) or quickly equip with the '''E''' key.
#Place the oxygen tank into your pockets and press the [[File:Gmaskinternalsicon.gif]] button on the top left. You are now breathing from the oxygen tank.
Despite being called an emergency oxygen tank these puppies start with ~1000 kPa of pure oxygen. This, in layman’s terms, means you can breathe from one of these for about 30 minutes. You don’t have to fear running out of air in 5 minutes. The situation to use internals are not that common though. Lack of oxygen is usually accompanied by extreme temperature or pressure. The mask will not help with those. The best way to deal with things like breaches, fire or [[plasma]] fires is to run away from the affected area.
===Using suit sensors===
Every [[Nanotrasen]] [[jumpsuit]] comes with a mechanism called [[suit sensors]]. Right click on your jumpsuit and use the “adjust suit sensors mode”. It should be, by default, set to the highest level. If not, make sure to set them. I’m sure you can guess what they do by name alone. [[Medical Doctor|Medical]] and [[Security Officer|Security]] crew have access to [[Crew Monitoring Console|crew monitoring consoles]]. They can also use [[Pinpointer|pinpointers]] to locate crew. This only works if your suit sensors are on. In the unfortunate case of your early departure from this moral coil the good folk in medical possibly locate are resurrect or clone your body.
===What To Do if You Are Hurt or See Someone Hurt on the Ground?===
Go to the medbay. If you happen to see a dead or near dead person on the ground, you should take the following steps: Remember that EpiPen? Now is the time to use it. What is happening to a person in [[critical]] condition is that they are slowly suffocating. Injecting them with the EpiPen will prevent this suffocation, buying a lot of time. Then since they are hurt, they are probably bleeding. '''Do not drag them across the floor''' as this slowly kills them. Instead consult the [[FullControls|full controls]] page on how to lift a body in a fireman’s carry.
===What To Do if You Are Attacked?===
In the case that someone attacks you, you are already dead probably. If you are attacked by a [[Blood Cult|blood cultist]] using [[Blood Cult#Blood Spells|eldritch magic]], blood weapons and that has the jump on you; it’s not supposed to be a fair fight. Or a fight at all rather.

In the case where you [[Byond the impossible|are not already dead]]. The first thing you want to do is scream “HELP” in the global radio chat. Because we can’t play the game and talk, an all uppercase “help” is like a special summoning call for [[Security Officer|security]], the [[AI]], or the [[Medical doctor|medical]] crew. If you have your [[Suit sensors|sensors]] turned on you don’t have to say where you are being attacked. Once the [[Terminology#Valid/Validhunting|valid hunters]] have been summoned the next step is to run away (bravely!). Look for the main station corridor as it is a public area and has lots of space. Avoid going into areas you don’t know since you might dead-end yourself.

Once you get better acquainted with the [[rules]] you can read the [[Guide to Combat|combat guide]] (outdated; ask some security players for classes), to learn how to fight back.
===Radiation Storms===
When you hear a message stating: '''''"'''High levels of radiation detected near the station. Maintenance is best shielded from radiation.'''";''''' that means a [[Random events#Radiation Storm|radiation storm]] is coming. Normally, if the heads are competent, a station-wide emergency will then be declared opening up [[maintenance]] even if you don't have access. All you have to do now is mill in [[maintenance]] until the radiation storm passes over. If you get hit by the radiation or feel sick in general head to the [[medbay]].
==Properly Leaving The Game (Cryosleep)==
Too confused? Head hurts? Mom called you to eat dinner? Whatever the reason you wish to leave the game, there is a proper way to do it. Crew and job slots are based on the number of living crew. The proper way to leave the round is to go the [[Dormitory|dorms]] and find the cryosleep pods. They are bright green. If you can’t find the dorms just ask [[Crew|someone]] (like a [[mentor]]). There are usually signs as well such as “DORMS”, “SLEEP” or “REST”. If you lay into a cryosleep pod and then log out or rather exit the game your body will be removed from the round, you will become a ghost and an empty crew an job slot will open for someone else. Speaking of ghosts...
==Death and Ghosts==
Tried to be a [[Clown|funny guy]] with the [[Traitor|wrong]] [[Changeling|person]]? Wrong [[Blood Cult|place]], wrong [[Nightmare|time]] in maintenance? Whatever the case, you are now [[dead]]. Don’t despair just yet! If the [[Antagonist|bad man]] has not completely destroyed your body and you turned your suit sensors on max there is a chance that some good [[paramedic]] will find your charred and bruised corpse and bring it to the [[medbay]] to be revived or [[Clone|cloned]].

In the meantime, move the ghost out of your body. This is spectator mode. You can communicate with other dead players. It’s fine to talk in an [[OOC]] way in Dchat. In the case you are revived you are '''not allowed''' to use any information gained while being a ghost. Anything you saw while you were alive is fair game though. Unless you are cloned that is. If you are cloned, you forget the last 15 minutes of your life.

In while being a ghost there is a chance to be prompted to become things like xenomorphs or swarmer. Sometimes these are random events and sometimes admin interference.

There is also a ghost spawner menu. From here you can spawn as certain things on [[Lavaland]]. If you choose to do this, you will no longer be able to revive or be cloned. When you spawn you are a new entity. You are unaware of your past life. For a new player a recommendation can be spawning as a [[Lavaland]] doctor. You get your own [[Lavaland]] hospital where you can freely practice [[Guide to medicine|medicine]] and [[surgery]] on monkeys as well as [[Guide to hydroponics|botany]] and [[Guide to chemistry|chemistry]].

SS13 is such an open-ended game that has other people in it, when you get in game and try to follow the guide, things may go wrong. The station might have been almost entirely consumed by a singularity, a traitor could attack you with a powerful weapon, or something no one could have predicted will kill you. '''It's important to not let death get to you.''' There are multiple ways you can be brought back into the game. Don't get frustrated if something undesirable happens.
==What Jobs to Take After Your First Round==
The best beginner jobs are ones where no one is going to come to you asking for something you don't really understand. assistant is the best because no one expects anything at all from you. You are free to explore and play with the controls. However once you get a grip on the controls is recommended to move to a job where still no one expects anything, but that have a designated objective. The recommended assistant ''plus'' roles are:
*[[Janitor]]: People will expect nothing from you except maybe that you clean the floor.
*[[Curator]]: The library is practically abandoned. Play with board games and painting. Organize books. Get fun loot from your curator beacon.
*[[Cargo Technician|Cargo Tech]]: Move crates until you die. It is said that all SS13 journeys begin and end in cargo. This is because cargo is of vital importance to several game modes. As a CT you will get to see the flow of these rounds first hand. However, your job will still remain to be just moving crates.
After that it's time to move on to some real roles. Funnily enough, the best way to learn these roles is to sign up as an assistant again. You are going to use this role as intended and actually assist some departments. Going to the [[Head of Personnel|HoP]] or whatever place you want to learn about and asking nicely for someone to teach you is a very effective way to learn. The [[Head of Personnel|HoP]] can even give you custom job titles like "medical intern" or "brig receptionist". Job that are good for this are: [[Medical Doctor]], [[Scientist]], [[Station Engineer]]... This is also the best way to dip your toes safely into being a [[Security Officer]]. Be careful, because it's very easy to play security poorly, and [[Shitcurity|letting the power get to your head is a bad idea]].

Avoid joke roles such as the [[Clown]] or [[Mime]] at first. Many players find harassing the on board entertainment much more fun than any jokes the clown might otherwise have.

After some time, when you're confident enough in your combat abilities, you should enable antagonists within your game preferences, so that you can roll for antag when the shift starts. A good half of the game is arguably being an antag and beating everyone up. Don't be scared that you will be a bad antag. Due to the fact that you can't predict what or when it will happen everyone was a painfully obvious antag at one point. It's just how the game works. You should however avoid team antag roles. [[Blood Cult|Blood cult]], blood brothers, [[Revolutionary|revolutions]], [[Clockwork Cult|clock cultists]], [[Nuclear Operative|nuclear operatives]], [[Xenomorph|xenomoprhs]]... The most common and "safe" antag options to dip you toes in are [[Traitor]] and [[Changeling]].

Slaughter Demon

2023-06-16T06:56:51Z

Itsmeowdev: /* JAUNT KILLING */ BAD

{{JobPageHeader
|headerbgcolor = black
|headerfontcolor = white
|stafftype = INFERNAL
|imagebgcolor = #901010
|img_generic =
|img = Slaughterdemon.png
|jobtitle = Demon
|access = WHERE EVER BLOOD IS ON THE FLOOR.
|additional = WHERE EVER MERE MORTALS MAY COWER!
|difficulty = EASY!
|superior = '''FRAIL, SOULFLINGING DEVILS!!'''
|duties = KILL EVERYTHING!
|guides = THIS '''IS''' THE GUIDE, STUPID MEATBAG!
|quote = The blood begins to bubble...
}}
{{Speech
|name=Slaugh T. Deeman, Infernal Employee of the Month
|text='''YOU WANT TO LEARN ABOUT SLAUGHTER DEMONS? I'LL TELL YOU THINGS THAT WOULD MAKE THE CODEX GIGAS LOOK LIKE THE BIBLE!!'''
|image=[[File:Slaughterdemon.png|64px|right]]
}}
==DADDY'S HOME==
I AM HERE! I HAVE TWO OBJECTIVES, SO LISTEN CLOSELY HUMANS!
* ONE, KILL WHOEVER SUMMONED ME
* AND TWO, KILL EVERYONE ELSE! RUN, PUNY MORTALS!
==WAHHH I'M A DEMON AND I'M KILLING ALL THESE HUMANS WITHOUT A SECOND THOUGHT WHAT DO I DO==
WHAT A TIME TO BE ALIVE! JUST SIT BACK AND ENJOY THE KILLING BECAUSE NOBODY ELSE WILL. HERE'S A COUPLE THINGS TO KEEP IN MIND THOUGH, DEMON TO DEMON.
===HIERARCHY===
IT GOES LIKE THIS
*SATAN
*DEVILS
*DEMON KING, [[Megafauna#Bubblegum|BUBBLEGUM]]
*DEMONS
*IMPS
*STUPID GOOBALLS WE CALL HUMANS
MY FELLOW DEMONS, PLEASE DO NOT KILL DEVILS BECAUSE SATAN WILL SMITE YOU REAL FAST AS SOON AS THE DEVIL SNITCHES ON YOU IN THE UNDERWORLD
===BLOOD JAUNTING===
SPREADING BLOOD ALL THROUGH THE HALLWAYS (DRAGGING A CORPSE WHILE SLASHING IT) WILL HELP YOU IN THE LONG RUN, TRUST ME. HAVING THE ABILITY TO TELEPORT ANYWHERE PROVES TO BE PRETTY USEFUL.
===CORPSE FEEDING===
NO SHAME ON TAKING A BITE ONCE YOU DRAG THEM TO HELL, MY FRIEND. IT'S YOUR ONLY WAY OF HEALING, SHORT OF A HUMAN PATCHING YOU UP. NOT ONLY IS A HUMAN GIVING YOU MEDICAL HELP A DISGRACE TO ALL DEMONKIND, BUT IF YOU EVEN ADMIT THAT YOU'RE CLOSE TO DYING THEY'LL PROBABLY JUST KILL YOU ANYWAY, YOU STUPID IDIOT DEMON.
===JAUNT KILLING===
WE ARE SLOW, OKAY? IT TURNS OUT HAVING A SUIT OF INFERNAL ARMOR GLUED TO US IS PRETTY HEAVY. LUCKILY, YOU CAN GET SOME PRETTY EASY KILLS JUMPING OUT OF BLOOD AS THE BLOOD WILL GIVE YOU A SPEED BOOST. FANTASTIC COMBO, JUMP OUT OF BLOOD, ATTACK, TRY TO GET IN A FEW, AND THEN RETREAT TO THE BLOOD FOR ANOTHER SPEED ATTACK. '''REALLY THE ONLY WAY YOU'RE REALISTICALLY GOING TO STOP A SHOTGUN, SO PRACTICE MAKES PERFECT'''
==WAHHH DEMONS ARE KILLING MY FRIENDS AND I'M ONLY A STUPID HUMAN WHAT DO I DO==
GEE, I DON'T KNOW HUMAN, MAYBE SPACING YOURSELF WOULD WORK? OR MAYBE PRE-EMPTIVELY SPREADING YOUR BLOOD ALL DOWN THE HALLWAYS SO I DON'T HAVE TO FOR YOU WOULD BE GREAT AT STOPPING DEMONS, YES!
===DEMONS LOVE BLOOD===
I NEED BLOOD TO JAUNT AROUND THE STATION AND KEEP MY KILL TO NOT KILLING RATIO EXTREMELY HIGH. DON'T REMOVE MY BLOOD, I MEAN IT. THAT WOULD INCUR MY IRE AND THEN I'D HAVE TO KILL SOMEONE ELSE TO GET MORE BLOOD.
===DEMONS LOVE EATING CORPSES===
WHOEVER THAT RIVER STYX GUY IS, HE'S A REAL DAMN CHEAT BECAUSE I CAN TAKE YOU RIGHT TO HELL WITH NO FEE. DRAGGING A DEAD HUMAN (THE LIVE ONES DON'T USUALLY WANT TO GO!) RIGHT TO THE UNDERWORLD IS MY BREAD AND BUTTER! AND I LITERALLY MEAN THAT BECAUSE I THEN FEAST ON THEIR CORPSE AND HEAL RIGHT BACK UP!
===DEMONS HATE SHOTGUNS===
IF SILVER BULLETS KILLED WEREWOLVES (THEY DON'T, STOP TRYING) THEN SHOTGUNS WOULD BE THE SILVER BULLET EQUIVALENT OF SLAUGHTER DEMONS. DEMONS, STAY AWAY FROM THEM, YOU WILL GET BLASTED BACK TO TARTARUS.
===DEMONS HATE LAUGHTER DEMONS===
I MEAN ATTACKING THEM WOULD BE SOME PRETTY HIGH LEVELS OF DEMONIC HERESY BUT MY GOD PLEASE INSULT THEM FOR THEIR PRIMAL STUPIDITY. EVEN YOU, HUMANS! THEY DON'T EVEN KILL HUMANS, JUST TAKE THEM TO THEIR HUGBOX DIMENSION! I DON'T EVEN KNOW WHAT THAT IS AND IT'S REALLY UNSETTLING AND '''THIS CONVERSATION IS OVER!!'''
==RELEVANT CODE CHANGES==
I'LL GET BACK TO YOU ON THIS ONE, VERY BUSY WITH KILLING PEOPLE AT THE MOMENT.

{{Jobs}}
[[Category: Jobs]]

Downloading the source code

2023-06-07T23:26:49Z

Itsmeowdev: /* Tips for Using the Server for Sandboxing */ Add more tips

== Download and License ==
This page contains the information and steps needed to download the latest version of the code, compile it and host your own server. The BeeStation source code is under [https://www.gnu.org/licenses/agpl-3.0.html GNU AGPL v3 license] and the assets are [https://freedomdefined.org/Licenses/CC-BY-SA CC-BY-SA]. We use GitHub to host our project. A zip download is available here: [https://github.com/BeeStation/BeeStation-Hornet '''DOWNLOAD'''] (Press Code -> '''Download''' ZIP) If you don't want to download 30MB of data every time an update is made, you can [[Guide to git|follow this guide]] to set up and use Git.
== Hosting Your Server ==
To get a simple server running first
* Download the source code as explained above.
* Run '''BUILD.bat''' and wait (1-3 minutes) until it's complies. You should see file with an orange icon called "beestation.dmb."
* Open Dream Daemon located in your BYOND install directory.
* Select the "..." in the lower right corner and select the file "beestation.dmb".
*Set the Security to "Trusted", to avoid excessive prompts from Dream Daemon. Only do this if you can verify that the source you have is official and safe - it is unlikely to be untrustworthy, but keep it in mind when working with any projects.
* Click the "GO" button and wait until it changes to a red "STOP" button. Starting the server usually takes between 1 and 5 minutes. It is fully started once you can normally interact with Dream Daemon and a byond://xxx.xxx.xxx.xxx:xxxxx link is present at the bottom.
* Click the yellow arrow button join
* Left click the (byond://xxx.xxx.xxx.xxx:xxxxx) link to copy it to clipboard and then paste it to your friends so they can join.
== Setting Up the Database ==
See [[working with the database]] guide. This is not required if you are just planing locally sandboxing for the purposes of testing.
== Tips for Using the Server for Sandboxing ==
* There is a secret menu in the adminbus panel that lets you fully power all areas and the SMES.
* If your hotkeys don’t work, try going into preferences and resetting to default.

* If you want to spawn something, use the Spawn command in the textbox. Just type the item name or what you think the name is and a menu will pop up with all the things in the game with that word in their name. For example: Spawn “spare” - will show a menu from where you can spawn the spare Capitan’s ID. Another use is Spawn “trit” - which will spawn a full Tritium canister if you want to test maxcaps.

* Right click on a tile and use “Jump to turf” to teleport.
* If all the extra tabs and options are distracting, you can use the deadmin command to become a normal player. You can readmin at any time.
*Hit Debug -> Debug-verbs Enable to get more verbs on the player's right click menu.
*With debug verbs on, you can use the Select equipment verb on yourself to equip the Debug outfit, which has loads of useful tools and items.
== FAQ and Troubleshooting ==
==== "I did not change anything, but the code does not work anymore!" ====
This is likely due to corrupted files.
To fix this, you need to:
*Re-download everything
*Copy over your config and data folder
*Clean compile
If you're using git reset hard against the BeeStation upstream master branch and then recompile.
==== Do I need to for a BYOND membership to make my server visible? ====
You '''DO NOT NEED''' to pay for membership to make your server visible on byond.com! To make your server show up [[beerepo:blob/master/config/config.txt#L26|change this hub config option]].

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Downloading the source code

2023-06-07T23:24:50Z

Itsmeowdev: Add note about Trusted

== Download and License ==
This page contains the information and steps needed to download the latest version of the code, compile it and host your own server. The BeeStation source code is under [https://www.gnu.org/licenses/agpl-3.0.html GNU AGPL v3 license] and the assets are [https://freedomdefined.org/Licenses/CC-BY-SA CC-BY-SA]. We use GitHub to host our project. A zip download is available here: [https://github.com/BeeStation/BeeStation-Hornet '''DOWNLOAD'''] (Press Code -> '''Download''' ZIP) If you don't want to download 30MB of data every time an update is made, you can [[Guide to git|follow this guide]] to set up and use Git.
== Hosting Your Server ==
To get a simple server running first
* Download the source code as explained above.
* Run '''BUILD.bat''' and wait (1-3 minutes) until it's complies. You should see file with an orange icon called "beestation.dmb."
* Open Dream Daemon located in your BYOND install directory.
* Select the "..." in the lower right corner and select the file "beestation.dmb".
*Set the Security to "Trusted", to avoid excessive prompts from Dream Daemon. Only do this if you can verify that the source you have is official and safe - it is unlikely to be untrustworthy, but keep it in mind when working with any projects.
* Click the "GO" button and wait until it changes to a red "STOP" button. Starting the server usually takes between 1 and 5 minutes. It is fully started once you can normally interact with Dream Daemon and a byond://xxx.xxx.xxx.xxx:xxxxx link is present at the bottom.
* Click the yellow arrow button join
* Left click the (byond://xxx.xxx.xxx.xxx:xxxxx) link to copy it to clipboard and then paste it to your friends so they can join.
== Setting Up the Database ==
See [[working with the database]] guide. This is not required if you are just planing locally sandboxing for the purposes of testing.
== Tips for Using the Server for Sandboxing ==
* There is a secret menu in the adminbus panel that lets you fully power all areas and the SMES.
* If your hotkeys don’t work, try going into preferences and resetting to default.

* If you want to spawn something, use the Spawn command in the textbox. Just type the item name or what you think the name is and a menu will pop up with all the things in the game with that word in their name. For example: Spawn “spare” - will show a menu from where you can spawn the spare Capitan’s ID. Another use is Spawn “trit” - which will spawn a full Tritium canister if you want to test maxcaps.

* Right click on a tile and use “Jump to turf” to teleport.
* If all the extra tabs and options are distracting, you can use the deadmin command to become a normal player. You can readmin at any time.
== FAQ and Troubleshooting ==
==== "I did not change anything, but the code does not work anymore!" ====
This is likely due to corrupted files.
To fix this, you need to:
*Re-download everything
*Copy over your config and data folder
*Clean compile
If you're using git reset hard against the BeeStation upstream master branch and then recompile.
==== Do I need to for a BYOND membership to make my server visible? ====
You '''DO NOT NEED''' to pay for membership to make your server visible on byond.com! To make your server show up [[beerepo:blob/master/config/config.txt#L26|change this hub config option]].

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Guide to git

2023-04-16T06:23:08Z

Itsmeowdev: Fix GitKraken grammar

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "email here"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

Name can just be your GitHub username or something else, doesn’t matter.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. GitHub will also provide you with a private email, if you don't have any type of "business" email, it is recommended to use this.

For more details on commit email privacy, read [https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address GitHub's guide].


== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.

For more info, see [[Map Merger]].
=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.
=GitKraken=
==How to update your branch from master==
{| class="wikitable"
|+
!images
! width="400px" | instruction
|-
|[[File:Gitkrakenpage1.png|frameless|500x500px|center]]
|
* Go to your master branch (on GitHub), and sync it to up-to-date
|-
|[[File:Gitkraken-updateyourmaster.png|center|frameless|400x400px]]
|
* Pull your master (local) from your master (remote GitHub)
|-
|[[File:Gitkraken-dragyourmaster.png|center|frameless|400x400px]]
|
* Drag your master onto a branch where you need to update
|-
|[[File:Gitkrakenmerge2.png|center|frameless|444x444px]]
|
* if it’s not compatible, a merge-conflict will occur. Click the file in the issue. It’s not <code>"Mark resolved"</code>.
|-
|[[File:Gitkrakenconflictslist.png|center|frameless|500x500px]]
|
* (1): click these lines, then it will be the bottom window (2). clicking a line will transfer only one line. clicking a check-box will transfer the whole lines. (the example clicked different lines to let you recognise it’s possible to put different lines, but you won’t really do that in this way. There’s no reason to transfer lines like this)
<blockquote>NOTE:
My suggestion for handling this is to transfer all lines from both of these, and compare how the new logic is different.

in this image, the conflict is only 3 lines, so just transferring a single line would be enough, but when it’s massive, comparing all lines is important.</blockquote>
* (2): the result of your merge-confliction resolve.
* (3): The list of where merge-confliction occurs.
* (4): click this once it’s done
click (4) once the merge resolve is done.
|-
|[[File:Gitkrakenmerge.png|center|frameless|429x429px]]
|Now commit your changes.
|}
Q. How can I resolve the map conflicts?

A. See [[Map Merger]]
{{Contribution guides}}

Guide to git

2023-04-16T03:37:40Z

Itsmeowdev: /* The Setup */ Remove protected email notice

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "email here"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

Name can just be your GitHub username or something else, doesn’t matter.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. GitHub will also provide you with a private email, if you don't have any type of "business" email, it is recommended to use this.

For more details on commit email privacy, read [https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address GitHub's guide].


== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.

For more info, see [[Map Merger]].
=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.
{{Contribution guides}}

Development

2023-03-30T10:21:19Z

Itsmeowdev: /* Mapping */ Rewrite guide to mapping desc

This is an index-page for finding guides related to aspects of development and contributing to the game. Guides will be linked with a short description of what they are about.

Feel free to add to this page if you have any resources that may help aspiring developers. It is recommended you keep guides within the bounds of this wiki.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
== Resources ==
{{Contribution guides}}
=== Design ===
* Design Goals - https://github.com/BeeStation/BeeStation-Hornet/wiki/Design-Goals - The current goals and direction of the game.
=== Coding ===
* Code Standards - https://github.com/BeeStation/BeeStation-Hornet/wiki/Code-Standards - The essential guidelines that maintainers look for in a PR.

* Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq - Making a new item in the game from scratch, from environment setup to the Pull Request.

* Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels - Explains how to avoid hard deletes, a quirk of the game's garbage collection.
* [[Understanding SS13 code]] - An older guide, explaining SS13 and DM to new coders
* [[SS13 for experienced programmers]] - Another older guide, explaining SS13 and DM to experienced coders.
*Visuals - https://github.com/tgstation/tgstation/blob/master/.github/guides/VISUALS.md - Guide describing most things relating to visuals and rendering on /tg/, however most of it also applies on BeeStation.
=== Development ===
* [[Working with the database#Database Setup|Working with the database]] - Setting up a local database for testing purposes, very useful for testing persistence and reducing development time.

* [[Guide to git]] - Using git command line, as well as dealing with merge conflicts and using mapmerge/dmimerge
=== Spriting ===
* [[Guide to spriting]] - How to create sprites for the game. This is fairly outdated, however.
=== Mapping ===
* [[Guide to mapping]] - Many tips, tricks, and guidelines for creating maps.
* [[Map Merger]] - Use of mapmerge2, a vital tool for resolving map merge conflicts, as well as installing Git hooks.
* [[Guide to mapping/Exploration ruins]] - Guide explaining how to map exploration ruins.

Development

2023-03-29T03:40:33Z

Itsmeowdev: /* Coding */ Add /tg/ visuals guide

This is an index-page for finding guides related to aspects of development and contributing to the game. Guides will be linked with a short description of what they are about.

Feel free to add to this page if you have any resources that may help aspiring developers. It is recommended you keep guides within the bounds of this wiki.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
== Resources ==
{{Contribution guides}}
=== Design ===
* Design Goals - https://github.com/BeeStation/BeeStation-Hornet/wiki/Design-Goals - The current goals and direction of the game.
=== Coding ===
* Code Standards - https://github.com/BeeStation/BeeStation-Hornet/wiki/Code-Standards - The essential guidelines that maintainers look for in a PR.

* Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq - Making a new item in the game from scratch, from environment setup to the Pull Request.

* Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels - Explains how to avoid hard deletes, a quirk of the game's garbage collection.
* [[Understanding SS13 code]] - An older guide, explaining SS13 and DM to new coders
* [[SS13 for experienced programmers]] - Another older guide, explaining SS13 and DM to experienced coders.
*Visuals - https://github.com/tgstation/tgstation/blob/master/.github/guides/VISUALS.md - Guide describing most things relating to visuals and rendering on /tg/, however most of it also applies on BeeStation.
=== Development ===
* [[Working with the database#Database Setup|Working with the database]] - Setting up a local database for testing purposes, very useful for testing persistence and reducing development time.

* [[Guide to git]] - Using git command line, as well as dealing with merge conflicts and using mapmerge/dmimerge
=== Spriting ===
* [[Guide to spriting]] - How to create sprites for the game. This is fairly outdated, however.
=== Mapping ===
* [[Guide to mapping]] - Fairly outdated guide on how to make maps, although some of its content may be useful.
* [[Map Merger]] - Use of mapmerge2, a vital tool for resolving map merge conflicts, as well as installing Git hooks.
* [[Guide to mapping/Exploration ruins]] - Guide explaining how to map exploration ruins.

Guide to git

2023-03-29T03:30:45Z

Itsmeowdev: Add contribution guides index

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "[/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>]"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

Name can just be your GitHub username or something else, doesn’t matter.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. GitHub will also provide you with a private email, if you don't have any type of "business" email, it is recommended to use this.

For more details on commit email privacy, read [https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address GitHub's guide].


== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.

For more info, see [[Map Merger]].
=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

{{Contribution guides}}

Working with the database

2023-03-29T03:30:25Z

Itsmeowdev: Add contribution guides index

= Database Setup =
When developing, it is useful to have a local database set up, for a variety of reasons.

This guide is a walk through for local testing database installation, however it will work for a production deployment so long as secure passwords are used and firewall settings protect the database from external connection.

Since savefiles no longer store character info, your character and preferences will reset between each startup. This can be problematic in adding a lot of time to the development and testing cycle. As such, it’s useful to set one up. This is a guide on how to do so.


== Setup MariaDB (Windows) ==
Download and install [[mariadb:|MariaDB Community Server]] for your operating system. Be sure to install the following components:
* Database Instance
* Client Programs
* HeidiSQL
[[File:Db_setup-6ce6ffea237bf219c2b91d392f48b2099b7930ae.png|thumb|none|alt=image|452x452px]]
Set a root password, something you will remember. It doesn’t need to be properly secure if it's for local testing, since you won’t be storing anything or hosting it publicly. Do '''not''' enable remote access for root.
[[File:Db_setup-559f5ff4e926edda40dd87a6274c774a6b9772e0.png|thumb|none|alt=image|449x449px]]
Install it as a service, with networking enabled. The default settings are fine. This means it will run 24/7 in the background. You can manage this in the Windows Services viewer.

[[File:Db_setup-A055e14a687b49ba5d723e90d6bbcfcae2958296.png|image]] [[File:Db_setup-d327ef8463bef045b46b8aac0848e9303d50b19d.png|image]]

Open HeidiSQL, Click on new to create a new session, check prompt for credentials and leave the rest as default.
[[File:Db_setup-5268ec389c6fcf8f2ff1aa84a382090c1e5278ae.png|thumb|none|alt=image|632x632px]]
Click save, then click open and enter in root for the username and the password you setup during the installation.
[[File:Db_setup-f8c2d10d5769c57f387e0eadf1c6e67842814ac3.png|thumb|none|alt=image|638x638px]]
Right click on the server entry in the left side plane (the area with <code>information_schema</code>, <code>mysql</code>, etc) (the server entry will be the first one) and go to <code>Create new -> Database</code>
[[File:Db_setup-245204aa1d0f17218e2eb1f4a0dd4a2432696ae6.png|thumb|none|alt=image|484x484px]]
You can name it anything at this step. The default config is <code>ss13beedb</code>, so go ahead and use that. Don’t name it <code>test</code>, or you will have security issues.
[[File:Db_setup-598a1178e842219e1b0ae9dc12f2ef27aafbf2de.png|thumb|none|alt=image|319x319px]]
Select the database you just created and then go to <code>File -> Open SQL File</code> and open the file <code>beestation_schema.sql</code> file located at <code>SQL/beestation_schema.sql</code>. You can also find it [[beereporaw:master/SQL/beestation_schema.sql|here]], but it may be newer than the version you are using. If it asks you to auto-detect, hit Yes. Ignore any “access violation” errors, the import works anyway.
[[File:Db_setup-f0f38f6cd445af32da096c835d2492727b091f3f.png|thumb|none|alt=image|484x484px]] [[File:Db_setup-B8634fc2985464e926572ac826faa7b4379f3653.png|thumb|none|alt=image|486x486px]]
Press the blue play icon in the topic bar of icon hieroglyphs and pray. If the schema imported correctly you should have no errors in the message box on the bottom.
[[File:Db_setup-5f7d15719bbacab5f759e2905d421f60c246f95a.png|thumb|none|alt=image|718x718px]]
Create a new user account for the server by going to <code>Tools -> User Manager</code>.
* '''Username:''' Anything, but <code>ss13dbuser</code> is the default
* '''Password:''' Any string of random text, you don’t need to remember it, just paste it into your database config. You can randomly generate one by pressing the arrow on the password field. Be sure to copy it.
* '''From host:''' <code>127.0.0.1</code>
* '''Permissions:''' Press “Add object”, select the database you created. Under the new object, add:
** <code>SELECT</code>
** <code>DELETE</code>
** <code>INSERT</code>
** <code>UPDATE</code>
[[File:Db_setup-f125cfa6a81217aa0b33ed0431b69c626303a671.png|thumb|none|alt=image|414x414px]]

== Update dbconfig ==
Now, on your local copy of the repository, open [[beerepo:blob/master/config/dbconfig.txt|config/dbconfig.txt]] in a text editor.

Set the following:
* Uncomment <code>SQL_ENABLED</code> by removing the <code>#</code> in front of it.
* <code>ADDRESS 127.0.0.1</code>
* <code>PORT 3306</code>
* <code>FEEDBACK_DATABASE ss13beedb</code> (or whatever you set)
* <code>FEEDBACK_LOGIN ss13dbuser</code> (or whatever you set)
* <code>FEEDBACK_PASSWORD password</code> (replace with the password you set for the created user)
[[File:Db_setup-dc58b4506df7c115cf8edfa191804ceba96802e5.png|thumb|none|alt=image|653x653px]]

== Skip Worktree ==
Now, on git, this will create tracked changes that you don’t want to commit to any future PRs. So you need to tell git to not process any changes in the file. If you use git command line, this is trivial.

Run <code>git update-index --skip-worktree config/dbconfig.txt</code>. Git will now ignore changes to this file locally. If you wish to undo this at any point, run <code>git update-index --no-skip-worktree config/dbconfig.txt</code>.
[[File:Db_setup-1681618ba8cc443a13696a952af5c720c44a54c3.png|thumb|none|alt=image|743x743px]]
If you do not use command line, you should still be able to accomplish this somehow, google the equivalent for whatever tool you use.
= Other database options =
== Database based banning ==
Offers temporary jobbans, admin bans, cross-server bans, keeps bans logged even after they've expired or were unbanned, and allows for the use of the off-server ban log.

To enable database based banning:
* Open config/config.txt
* Add a # in front of BAN_LEGACY_SYSTEM, so the line looks like "#BAN_LEGACY_SYSTEM"
* Done. Note that any legacy bans are no longer enforced once this is done! So it's a good idea to do it when you're starting up.
== Database based administration ==
Offers a changelog for changes done to admins, which increases accountability (adding/removing admins, adding/removing permissions, changing ranks); allows admins with +PERMISSIONS to edit other admins' permissions ingame, meaning they don't need remote desktop access to edit admins; Allows for custom ranks, with permissions not being tied to ranks, offering a better ability for the removal or addition of permissions to certain admins, if they need to be punished, or need extra permissions. Enabling this can be done any time, it's just a bit tedious the first time you do it, if you don't have direct access to the database.

To enable database based administration:
* Open config/config.txt
* Add a # in front of ADMIN_LEGACY_SYSTEM, so the line looks like "#ADMIN_LEGACY_SYSTEM"
* Do the steps described in [[Working with the database#Adding your first admin|Adding your first admin]].
* Done. Note that anyone in admins.txt lost admin status, including you! So do the step above! You can repeat it for everyone, as it's a lot easier to do that and just correct permissions with the ingame panel called 'permissions panel'.
* If your database ever dies, your server will revert to the old admin system, so it is a good idea to have admins.txt and admin_ranks.txt set up with some admins too, just so the loss of the database doesn't completely destroy everything.
If you need more help, ask in Discord.

{{Contribution guides}}

Development

2023-03-29T03:29:46Z

Itsmeowdev: Add contribution guides index

This is an index-page for finding guides related to aspects of development and contributing to the game. Guides will be linked with a short description of what they are about.

Feel free to add to this page if you have any resources that may help aspiring developers. It is recommended you keep guides within the bounds of this wiki.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki

== Resources ==

{{Contribution guides}}

=== Design ===

* Design Goals - https://github.com/BeeStation/BeeStation-Hornet/wiki/Design-Goals - The current goals and direction of the game.

=== Coding ===

* Code Standards - https://github.com/BeeStation/BeeStation-Hornet/wiki/Code-Standards - The essential guidelines that maintainers look for in a PR.

* Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq - Making a new item in the game from scratch, from environment setup to the Pull Request.

* Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels - Explains how to avoid hard deletes, a quirk of the game's garbage collection.
* [[Understanding SS13 code]] - An older guide, explaining SS13 and DM to new coders
* [[SS13 for experienced programmers]] - Another older guide, explaining SS13 and DM to experienced coders.

=== Development ===

* [[Working with the database#Database Setup|Working with the database]] - Setting up a local database for testing purposes, very useful for testing persistence and reducing development time.

* [[Guide to git]] - Using git command line, as well as dealing with merge conflicts and using mapmerge/dmimerge

=== Spriting ===

* [[Guide to spriting]] - How to create sprites for the game. This is fairly outdated, however.

=== Mapping ===

* [[Guide to mapping]] - Fairly outdated guide on how to make maps, although some of its content may be useful.
* [[Map Merger]] - Use of mapmerge2, a vital tool for resolving map merge conflicts, as well as installing Git hooks.
* [[Guide to mapping/Exploration ruins]] - Guide explaining how to map exploration ruins.

Development

2023-03-29T03:28:07Z

Itsmeowdev: Update entirely

This is an index-page for finding guides related to aspects of development and contributing to the game. Guides will be linked with a short description of what they are about.

Feel free to add to this page if you have any resources that may help aspiring developers. It is recommended you keep guides within the bounds of this wiki.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
== Resources ==
=== Design ===

* Design Goals - https://github.com/BeeStation/BeeStation-Hornet/wiki/Design-Goals - The current goals and direction of the game.

=== Coding ===

* Code Standards - https://github.com/BeeStation/BeeStation-Hornet/wiki/Code-Standards - The essential guidelines that maintainers look for in a PR.

* Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq - Making a new item in the game from scratch, from environment setup to the Pull Request.

* Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels - Explains how to avoid hard deletes, a quirk of the game's garbage collection.
* [[Understanding SS13 code]] - An older guide, explaining SS13 and DM to new coders
* [[SS13 for experienced programmers]] - Another older guide, explaining SS13 and DM to experienced coders.

=== Development ===

* [[Working with the database#Database Setup|Working with the database]] - Setting up a local database for testing purposes, very useful for testing persistence and reducing development time.

* [[Guide to git]] - Using git command line, as well as dealing with merge conflicts and using mapmerge/dmimerge

=== Spriting ===

* [[Guide to spriting]] - How to create sprites for the game. This is fairly outdated, however.

=== Mapping ===

* [[Guide to mapping]] - Fairly outdated guide on how to make maps, although some of its content may be useful.
* [[Map Merger]] - Use of mapmerge2, a vital tool for resolving map merge conflicts, as well as installing Git hooks.
* [[Guide to mapping/Exploration ruins]] - Guide explaining how to map exploration ruins.

Template:Contribution guides

2023-03-29T03:26:53Z

Itsmeowdev: Update the index

{|style='background-color:#e7e7ff' width='100%'
|colspan='2' style='background-color:#d8d8ff'|<div align='center'>'''Contribution guides'''</div>
|-
|width='150' align='center' |'''General'''
|align='left' style='background-color:#f0f0ff;' |[[Development]], [[Downloading the source code|Downloading the source code / hosting a server]], [[Guide to git]], [[:Category:Game Resources|Game resources category]], [[Guide to Changelogs|Guide to changelogs]]
|-
|width='150' align='center' |'''Database (MySQL)'''
|align='left' style='background-color:#f0f0ff;' |[[Working_with_the_database#Database_Setup|Setting up the database]], [[MySQL]]
|-
|align='center' |'''Coding'''
|align='left' style='background-color:#f0f0ff;' |[[Understanding SS13 code]], [[SS13 for experienced programmers]], [[Binary flags‎]], [[Text Formatting]]
|-
|align='center' |'''Mapping'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to mapping]], [[Map Merger|Map merger]], [[Guide to mapping/Exploration ruins|Exploration Ruins]]
|-
|align='center' |'''Spriting'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to spriting]]
|-
|align='center' |'''Wiki'''
|align='left' style='background-color:#f0f0ff;' |[[Guide to contributing to the wiki]], [[Wikicode]]
|}<noinclude>[[Category:templates]]</noinclude>

Terminology

2023-03-29T03:25:08Z

Itsmeowdev: Remove game resources category

{{Speech
|name=Speaks-His-Mind the Maintenance Dweller
|text=SSSo, lassst I heard the AI wasss helping the Redssshirts in sssome operation to robussst sssome sssort of cult in Aft Maintenance. I sssuggessst you ssstay clear of there, ssstranger. I wouldn't want to be on the wrong end of a ssstunbaton, no no...
|image=[[File:Lizardman.png|64px|right]]
}}

A big bad list of common terminology and slang commonly used by resident Spacemen (players).
===[[Administrators|Admin]]===
The people who run the server. Have a variety of power-abuse buttons to keep the game from being fun.
===Adminhelp/Ahelp===
A command which lets you send a message to the [[Administrators|admins]]. Can be accessed by typing Adminhelp in game or by pressing <code>F1</code>.

Use this (instead of the OOC-channel) if you think someone is griefing or if you otherwise have something to ask the admins about.

These can include questions about etiquette, the rules, or in-game procedures such as the starting the engine, etc.

It should be noted that even when no admins are online, any messages sent in adminhelp are logged.
===Additional Access===
Under certain circumstances, such as a low server population, admin-toggled, or simply set in the server configuration by the host, jobs may be granted additional access when they join the round.
===Aft===
Nautical term. It means the back of a ship, or in our case, south.
===[[AI]]===
The Artificial Intelligence, the station's computer which can access machinery on the station.
===[[Analyzer]]===
Most often refers to [[Health Analyzer]]s, but can also refer to [[Analyzer|Atmospheric Analyzers]], [[Botanist|Botany]]'s Plant Analyzers, or [[Scientist|Research & Development]]'s Destructive Analyzer.
===Anomaly===
A kind of [[random event#Anomalies]] announced over comms that can cause station damage if not dealt with in time.
===Antag===
Antagonist. The "opponent", "enemy". Every [[Game_modes|Game Mode]] (except extended and secret extended) has at least one.
===[[APC]]===
The Area Power Controller, a square box on the wall that provides power to the room and is the purview of [[Station Engineer]]s.
===[[Asimov]]===
The default laws that the [[AI]]s and therefore the [[Cyborg]]s are held to. Taken from [https://en.wikipedia.org/wiki/Isaac_Asimov Isaac Asimov]'s short stories and the [https://en.wikipedia.org/wiki/Three_Laws_of_Robotics Three Laws of Robotics].

Basically makes robots follow orders and unable to harm people.
===[[Atmos]]===
Either an [[Atmospheric Technician]] (which are also commonly known as Atmos Tech) or the [[Atmospherics]] area itself which deals with the air supply.
===Ayys/Ayyliens===
An [[Abductor]], not to be confused with a [[Xenomorph]].
===Badmin===
Bad Admin, refers to an admin who abuses their powers.
===Ban===
Blocking a person from access to the SS13 server for a period of time. This can happen if a person is not obeying the given [[rules]].

Read the [[guide to evading getting banned]] for further guidelines.
===[[Beepsky|Beepsky/Officer Beepsky]]===
A [[Securitron]] that starts in Security. Will chase, stun, and handcuff anyone set to be arrested in the [[security records]].
===[[Blob]]===
Can refer to the Blob game mode, or the Blob that spawns in Blob mode and sometimes in random events.

A big green jelly thing that spreads quickly, causes enormous damage, beats the shit out of people and is weak to fire.
===Bolt/Bolted===
A feature of [[Airlock]]s. When the bolts are dropped, the door cannot move from its current position, be it open or closed. They can be lifted by the AI or [[hacking]] the airlock.
===[[Borg]]===
A [[Cyborg]].
===[[Borging]]===
Making a Cyborg out of someone. Done in [[Robotics]] usually.
===Braindead===
Refers to a player who has logged off or been disconnected. Examining a braindead character reveals the message; "They have a blank, absent-minded stare and appears completely unresponsive to anything. They may snap out of it soon."

While these players are not in-game, they should generally be left alone (or preferably dragged somewhere safe) The rules still apply to braindead characters.

'''NOTE: This person can still come back to the game!''' Who knows, maybe their computer just crashed for a minute.
===[[Bridge]]===
The command center of the ship where the heads start. Found in the center of the station.
===[[Brig]]===
An area of the station north of the Bridge and just under Security Office where people are held by [[shitcurity|security]] after being arrested.
===Bwoink===
Receiving an Admin PM, named after the sound effect played when an admin PMs you.
===[[BYOND]]===
The shitty, [[Lagtime|laggy]] platform SS13 was coded on. You need it to be able to play the game, unfortunately.
===[[Cargo]]===
A shortened version of either the cargo bay, or the whole of the supply section, not including mining dock and mining outpost.
===Catatonic===
A player who has ghosted while alive, disabling them from returning to play. When such a player is examined, it gives a message stating there is no hope of recovery.

These people are as considered corpses and can be taken to the [[Morgue]] or [[Kitchen]].
===[[CE]]===
The Chief Engineer.
===[[CentCom]]===
Short for "Central Command", the administration branch of Nanotrasen which runs SS13. Will periodically send messages to the station which are usually of debatable usefulness.

Also refers to the area the Emergency [[Escape Shuttle]] goes to when it leaves SS13.
===[[Cloning|Clone/Cloning]]===
To revive someone back to life through cloning their dead body, usually done in [[Genetics]].
===[[CMO]]===
The Chief Medical Officer.
===[[CO2]]===
Carbon Dioxide, an invisible gas kept in black canisters. Will knock you out and suffocate you.
A small trace amount of it makes up breathable air.
===Comdom===
A derogatory name for an incompetent and abusive [[Captain]].
===Corporate===
A lawset for the [[AI]], which makes it a ruthless profits-maximizing, efficiency-enforcing machine.
===Crew===
This is everybody on [[Space Station 13]] that is not a [[Syndicate]], [[Wizard]], [[xenos|Alien]], or whatever.

Typically what they do is get the station into shape, like setting up the [[Station_Engineer|singularity]] and [[Quartermaster|ordering supplies]]. Oh, and beating the shit out of the other groups of players, of course!
===[[Crit]]===
To be in a critical state. At this point, your character has lost consciousness and will slowly die from lack of oxygen.
===[[Cryo]]===
The big green glass things in Medbay. Putting dying people in here can save them.
===Cuban Pete===
''They call me Cuban Pete, I'm the king of the rhumba beat.''

''When I play my maracas I go''

''Chick chicky boom, chick chicky boom''

A notorious griefer who applied the bomb-making knowledge of a mysterious first scientist mentor who had invented ludicrous sized bombs. The station was turned into nearly dust every round he was on, antagonist or not. Because of him there was a bombcap hardcoded into the game.
===[[Cult]]===
Refers to either the [[Cult]] game mode, or the cultists within.
===Deadchat===
A chat channel dead/observing players speak on using the say command. Can only be seen by other dead/observing players. Deadchat is mostly considered to be out-of-character, and here you are allowed to talk about anything happening in the round (unlike in the [[OOC#OOC_channel|OOC channel]]).

Note that what you learn here is forgotten by your character if you're revived.
===Deadmin===
Most commonly read as dead-min (as in dead admin), but actually stands for de-admin, meaning the action of removing administrative powers from an [[Administrators|administrator]].
===Disk===
Infrequently a science or genetics research disk, but most often refers to the [[Nuclear Authentication Disk]], used in [[nuke|Nuclear Mode]]. If you are the [[captain]], guard it with your life.

If you are a traitor with it as your objective, GET DAT FUKKEN DISK.
===Donk/Bangin' Donk===
[https://www.youtube.com/watch?v=ckMvj1piK58 wait wait hold on, you know what you wanna do with that right? you wanna put a bangin' donk on it]
===Drone===
Either a type of [[alien]] or a [[Drone|player-controlled repair bot]].
===Electrified/Shocked===
Another feature of [[Airlock]]s. If an electrified airlock is touched by someone without insulated gloves, they will receive an electric shock, taking damage and being stunned for some time.

The AI and airlock hacking can activate or disable electrification. Some grilles are also electrified -- cutting a cable without wearing insulated gloves will also electrify you.
===[[Emag]]===
Another name for the [[Syndicate_Items#Cryptographic_Sequencer|Cryptographic Sequencer]] traitor item, which permanently opens doors and has myriad other uses.
===Emagged/Emaged===
Used either as a verb to describe the action of using an [[emag]] on something, or as an adjective to describe an object that someone has used an emag on.
===[[Emoji]]===
A.K.A. smileys, except smile is not mandatory. [[Emoji cheat sheet|Learn them all!]]
===[[Engine]]===
The large area in the south of the station that is used to start and contain a gravitational singularity that provides power to the station.
===ERP===
Erotic Role Play (ERP) is the action of when a player or players engages in roleplaying that is erotic in nature.

An inherently controversial subject, people's reactions to ERP ranges from upset and rage to taking off one's clothes and joining to [[Rules|ding dong bannu]].
===[[EVA]]===
A room just southwest of the Security wing where space suits, magboots, jetpacks and the RCD are kept. Stands for Extra-Vehicular Activity.
===Fore===
Nautical term. It means the front of a ship, or in our case, north.
===[[Ghost]]===
Refers to a command you can type when you have died to become a ghost, and to the actual ghosts themselves.

Ghosts can speak on deadchat, move around the station freely, see everything, and can't interact with anything meaningful.

They are used to observe the game after you have died. Cannot be seen directly by living players unless something is very wrong.
===Gibs===
The bloody, torn apart remnants of a former living being. Created by people and monkeys exploding. A cyborg that blows up has its own version of gibs: robot debris.

To gib something is to turn it into gibs, usually by a [[guide to toxins|bomb]] or the Chef's machine that turns people into meat, the [[Gibber]].
===Gimmick===
Can refer to a player gimmick or a gimmick round. Basically a round or player which plays with a certain "theme".

Can be amusing once or twice but doing this regularly runs it into the ground very quickly.
===Goofball===
Refers to the [[Tesla Engine]] and specifically its energy balls, named for its coder.
===Grayshirt/Grays===
[[Assistant]]s, named after their signature gray uniform. Not to be confused with ayyliens. AKA grayshits. AKA,
===Graytide===
Originated from a bug in the job selection system, causing the majority of the crew to be roundstart [[Assistant]]s, dressed in gray. This resulted in swarms of Assistants storming the Brig and antagonize [[security]]. Now the word refers to any griefy behavior of that bent.
===[[Greentext]]===
An alternate way of describing a victory as an antagonist. Derived from the green text used for 'success'.
===Grief===
A.K.A. Griefing/Griefer/Griffed/Griff/Griffon/Gruffer/Grover/Shitler/Chucklefuck/(Pulling a) Cuban Pete.

Intentionally ruining the game for others without the metagame pardon of being an antagonist.

Note that this is subjective and up to the admin's interpretation, not yours. Report this using adminhelp to keep the servers tidy!
===Gulag===
The Russian term for the [[Labor Camp]].
===[[Hacking]]===
The act of breaking the security measures on equipment such as Airlocks or APCs by illicit means.
===[[Hand of God|HoG]]===
Abbreviation for the [[Hand of God]] game mode.
===Heads===
The station's [[Chain_of_Command|Heads of Staff]], each in command of a department. They are also the targets of a [[revolution]].
===Honk/Hunke===
[[clown|hh-ho-ooonn-nk-kkk ww-hhh-yy i-iss-s see-ccu-uur-rrttt-yy bb-eeaa-tt-iinn-gg m-mme-ee hh-hoo-oon-nnk-kk]]
===[[Head of Personnel|HoP]]===
[[Head of Personnel]]. Should assign jobs and shit, but usually ends up giving himself Captain-level access, ignoring his job, and acting like a supercop in an [[The Owl|owl costume]].
===[[Head of Security|HoS]]===
The [[Head of Security]].
===Hulk===
Used to refer to the [[genetics|superpower]] or a person in possession of it. People with the Hulk gene turn green and become super strong, being able to punch through walls, windows, and other fixtures. Hurts like hell if one hits you. Hulks are an exception to some killing rules (see the [[Rules]] for details)
===Husk===
A corpse which has turned into a gray, ugly... mummified thing.

This has either happened by extreme heat (fire), extreme cold (space) or liquid suckification (changeling sucked their juices/DNA out). Not a nice thing to witness at first, but you get used to it.
===Hypo===
[[High-risk_items#Hypospray|Hypospray]].
===IC===
In Character. Stuff that is happening in the game.
===[[IC in OOC]]===
The act of describing anything happening in the game over the [[OOC]] channel. The rule of thumb is '''if a person not involved in the incident or not observing the game can still tell what's going on''', it's [[OOC|IC in OOC]]. Usually comes with a chastising and a thousand mini-mods squawking out "ICKY OCKY!!!" but excessive use results in a ban. (See the [[OOC]] page for details)
===[[Internals]]===
Usually an [[oxygen tank]] of some sort and a [[gas mask]]. Basically any worn item that lets you breathe when you otherwise can't.
===Internals Box===
That box which comes in a spawned player's backpack containing a transparent breath mask, one emergency-sized tank of pure oxygen and an epinehrine medipen.

A great place to keep things you don't access a lot but want to keep on you.
===Job Ban===
Similar to a [[Terminology#Ban|Ban]], except in this case you'll be prevented from playing a specific role, such as a [[gang|team-based antagonist]] or a [[Head of Security|head of staff]]. You may even get banned from playing an entire [[Science|department]] if you demonstrate an inability to follow the [[rules]].
===[[Random_events#Space_Vines|Kudzu]]===
Space vines. Can start growing randomly or be planted.
===Lag/Space Lag/Spacetime Distortions===
Concept common to almost all online gaming. Not worth explaining in depth here - basically it's the server (server-side lag) or your own computer (client-side lag) being slow and causing gaps between you doing stuff and it actually happening to grow. Sometimes referred as 'time warp' or something similar when players are in character.
===Lathe===
Short for the [[Autolathe]], located in [[Cargo]]. Could also be [[Protolathe]], located in [[R&D Lab]].
===[[Asimov|Law/Laws]]===
Rules which the [[AI]] and [[Cyborg]]s must follow. Are somewhat open to interpretation by the player, but the majority consensus and badmin rulings are what really count. May be modified or changed at an [[AI Upload|AI Upload Terminal]] using various modules, wiped back to the basic three using the Reset Module, or purged entirely with the Purge Module. Note that core modules cannot be removed by the standard reset module.
===[[Ling]]===
A [[Changeling]].
===[[Malf]]===
Short for malfunction. Can refer to either the [http://nanotrasen.com/wiki/index.php/Game_Mode#AI_Malfunction|AI Malfunction game mode], or to describe the AI in said mode.
===[[Mass Driver]]===
Computer or switch operated devices found in Toxins, the Chapel and arrivals Disposals.

Any objects on them when they are activated will be thrown forward at high speed, either into the bomb testing area (Toxins) or space (Chapel).
===Mini-mod===
Those players without admin or mod powers or responsibilities who chastise other players and list server rule infractions incessantly. They should be ignored.
===[[MMI]]===
A Man-Machine-Interface. Essentially player-cyborg-interface. A [[cyborg]] has one inside it. Enables the brain to speak and see.

Put a brain into an empty MMI, insert the whole thing into an empty [[cyborg]] and you can bring it back to life!
===Mod===
Could be used to refer to Moderator, the rank, or any admin.
===Murderboning===
Going on a killing spree.
===[[N2]]===
Nitrogen, an invisible gas kept in red canisters. Mostly useless but makes up a certain percentage of breathable air. Not to be confused with chemical reagent nitrogen from chemistry.
===[[N2O]]===
Nitrous Oxide, also known as laughing gas or anesthetic. White gas kept in red canisters with a white stripe, that will knock you out and suffocate you at high enough concentrations.
===[[Nanotrasen]]===
The autonomous super-corporation that built and operates the station, according to the [[backstory]].

Common misspellings include NanoTrasen, Nanotressen, Nanotransen, Nanotracer, and You Know That Fucking Company We Work For. (See CentCom for the difference between Nanotrasen and CentCom)
===Nar-Sie/Nar-Nar===
The eldritch deity whom [[cultists]] serve and often wish to summon.
===Notes===
A command which displays "'''Notes'''" kept in your character's memory, which you add with the "'''Add-Note'''" command. Some notes are automatically added depending on the circumstances, such as [[Revolution|revolutionaries]] having the list of rev members memorized, [[Syndicate]] leaders having the nuclear bomb code memorized, or the time of your death. Also refers to the top secret notes [[admin]]s keep on players, usually if they get banned.
===[[Nuke]]===
Can refer to either the [[Game Mode#Nuclear Emergency|Nuclear game mode]] (also known as Syndicate), or the Nuclear Fission Explosive used in said mode.
===[[O2]]===
[[Oxygen]]. Invisible gas usually kept in blue and white [[Canister]]s. Vital for reasons that you should already know, but deadly for reasons you [https://en.wikipedia.org/wiki/Oxygen_toxicity may not].
===One-Human(ed)===
Referring to a custom AI law that designates only one member of the crew as a human. Usually accompanied with an order to purge "non-humans."
===[[OOC]]===
The blue bolded chat channel which is shown to all players. Don't use this to talk about anything going on in the game (until right at the end of the game generally).

Might get switched off occasionally if it gets too idiotic. You can toggle the visibility of the ooc channel by using the corresponding command.
===[[OOC in IC]]===
The inverse of the much more common [[IC in OOC]]. Whenever a game mechanic, metafeature, or player-to-player conversation is referenced in the say or emote channels.

Heavily frowned upon as it ruins MY IMMERSIONNNN!

Talking ((Like this)) is still OOC in IC.
===Ops/Operatives===
Short for [[nuke ops]]. Generally heard over the radio shortly before the station goes boom.
===ORM===
Short for the Ore Redemption Machine, which is used to turn the materials miners bring into usable sheets, typically used by science. Often found at Cargo or Science for this very reason.
===Paladin===
A lawset for the [[AI]], your stereotypical white-knight good-guy role.
===Parapen===
The [[Sleepy Pen]] was previously called Parapen, short for Paralysis Pen.
===[[PDA]]===
Short for Personal Digital Assistant, a [[PDA|handheld device]] that acts as a pager, flashlight and other useful functions, depending on what cartridge is inserted.
===[[Perma|Perma/Permabrig]]===
The [[Prison Wing]] in the fore section of security, where prisoners are kept permanently.
===[[Plasma]]===
A.K.A. [[Plasma|Biotoxin]]. Purple gas kept in orange canisters. Poisonous and flammable.

Research into uses and properties of plasma is the station's prime reason for existence, according to the [[backstory]].
===Port===
Nautical term. It means the side of a ship on the left when one is facing forward, or in our case, west.

If you're the kind of person who likes mnemonic devices, it's useful to remember that ''PORT'' has the same number of letters as ''LEFT''.
===[[QM]]===
Usually refers to the [[Quartermaster]], but can also mean the [[Cargo Bay]] or the people who [[Cargo Technician|work there]].
===[[R&D|RnD/R&D]]===
Refers to [[Guide_to_Research_and_Development|Research and Development]], or the [[R&D|Laboratory]] that carries it out.
===[[Radio]]===
Normally refers to the headset on your head which can be used with the command '<code>say ";help that traitor is griefing me"</code>', for example. Can also refer to station bounced radios and intercoms. Shows up as green text with a symbol and frequency appended to it. Additional department-specific radios also exsist. To use the equipped department radio's default department frequency use '<code>say ".h Hello Department!"</code>'. (See [[Radio]] for details or how to use the radio when it has multiple department frequencies available)
===[[RCD]]===
[[Rapid Construction Device]]. A piece of equipment that can quickly make and break floors, regular walls, and airlocks.
===[[Research Director|RD]]===
The [[Research Director]].
===Records===
Comes in two flavors, [[Computers|Security and Medical]], both accessible from terminals with red or white screens, respectively.

Medical Records are mostly useless and thus mostly unused, but Security Records contain useful fingerprint information and can be used to have [[Beepsky]] arrest people on sight.
===Redshirt===
[[Security Officer]]s, named for their signature red uniforms and tendency to die at the hands of everything.
===Redtext===
An alternate way of describing a loss as an antagonist. Derived from the red text used for 'fail'.
===Report/Centcom Report/Traitor Report===
A document printed out from communications consoles at the start of most [[Game Mode|game modes]]. Lists who might be the traitor and what might be their targets.

Inaccurate to the point where it's usually false. Do not treat this report as proof of anything.
===[[Rev]]===
Could refer to the game mode [[Game_Modes#Revolution|Revolution]], a member of the Revolution in said game mode, or a [[Revenant]].
===Revhead===
One of the leaders of the revolution in [[Game_Modes#Revolution|Revolution]] game mode.
===[[Robusting|Robust/Robusting]]===
The game's ROBUST COMBAT SYSTEM. To robust someone is to beat the shit out of them or at least win in a fight.

The definition of what exactly makes a crewmember robust varies from person to person, but it's almost universally agreed to mean being skilled despite the inherently clunky interface.
===[[RP]]===
(MY IMMERSION) "Role Play". Basically acting within the mental/emotional confines of your in-game character and not yourself. This is encouraged on our MRP server.
===[[Shitcurity]]===
A derogatory term for [[Security Officer]]s who are abusive, incompetent or generally shit. Can usually be heard shouted by the guy who just got arrested.
===[[Shuttle]]===
Most of the time refers to the Emergency [[Escape Shuttle]] which shows up at the end of the round in the northwest of the station. Can also refer to the Arrival Shuttle (where you start if you join late), the [[syndicate]] or [[wizard]] shuttle (which you'll rarely see, if ever), the Supply Shuttle (which brings items to the [[Quartermaster|Cargo Bay]]), or the mining and prison shuttles (which move people between the mining and prison stations, respectively).
===[[Signal]]===
A beep sent from a Remote Signalling Device. "Default Signal" is used to refer to the default setting of the devices, which is Frequency 147.9, Code 30.

Randomly signaling the default frequency/code is a good idea, and will cause nothing bad to happen ever.
===Silicon===
A term for [[AI]] or [[cyborg]] players, contrast with "human."
===[[Singulo|Singulo/Singuloth/Sing]]===
The [[Singularity|gravitational singularity]], what is essentially a black hole that emits radiation, this radiation is converted to power. It '''should''' be contained with a shield, if it isn't, don't stop to take in the view, get those legs moving.
===[[Shadowlings|Slings]]===
[[Shadowling]]s, one of the station's many antagonist types.
===Space Wind===
Shifts in air pressure that can cause players and items they're dragging to be knocked into space.
===Spacing===
The act of forcing or throwing someone out an airlock into space, usually for [[Traitor|malicious purposes]].
===[[SS13]]===
[[Space Station 13]]. Generally used to refer to the game rather than the actual station.
===SSD===
Stands for Space Sleep Disorder or Sudden Sleep Disorder. An in-character explanation for someone that has disconnected or has gone AFK.
===Starboard===
Nautical term. It means the side of a ship on the right when one is facing forward, or in our case, east.
===[[Supermatter|SM]]===
The [[Supermatter]].
===[[Syndie|Syndie/Synd]]===
Can refer to the organization known as the [[Syndicate]], a coalition of companies that execs their hate of [[Nanotrasen]], according to the [[backstory]], or to raid groups and operatives of said coalition. [[Traitor|Traitors]], traitor [[Cyborg]]s and traitor [[AI|AIs]] are Syndicate affiliates and [[Game Mode#Nuclear Emergency|Nuclear mode's]] premise revolves around a direct Syndicate attack. Ingame, they have randomized company names that usually look something like "GeoDyne West Operative #2" or "Waffle Co. Czar" and there are usually at least two of them and up to six. They also have access to a lot of special syndicate gear.
===Tabling===
The act of grabbing someone then clicking a table to instantly knock them down on it, usually followed by a toolbox in the skull or being stripped.
===[[Tele]]===
While usually referring to the [[Hand Teleporter]], it could also be referring to the full-fledged [[Teleporter]] in the [[Teleporter|Teleporter Room]]. Most people have no idea how to use it.
===Tesla===
The [[Tesla Engine]]. An alternative engine that [[Engineering]] can build. Also commonly referred to as the "goofball", so named for the programmer who created it.
===Testmerge===
Trying out new features or significant changes usually means temporarily merging that feature into the server in order to gather bug reports and feedback
===[[Tcomms|Tcomms/Telecomms]]===
[[Telecommunications]], the room holding servers that allows headsets to work. Does not affect [[Intercom]]s or [[Station Bounced Radio]]s.
===[[Thermals]]===
[[Optical Thermal Scanners]]. Green glasses which let you see people through walls and in the dark. The only thing they can't see through is hiding in closets. Generally not available to the crew.
===[[Toxins]]===
That section of the station east of [[Medbay]], better called the [[Research Division]] containing [[Guide to research and development|Research and Development]], [[Xenobiology]], the [[Toxins Lab]] and the [[Research Director]]'s office.

It is very rarely not filled with fire, hot gas, poisonous vapors, blood, acid, foam of all kinds and dangers, or the aftermath of all this destruction.
===[[Traitor]]===
Used to refer to the [[Game Mode|mode]] or an actual [[Traitor]] (assigned by the game mode or by admins).
===TraitorChan===
Used to refer to the [[Game_Mode#Traitor.2BChangeling|game mode]], a combination of [[Traitor]] and [[Changeling]].
===Valid/Validhunting===
Adjective: Someone who can be killed per the [[Rules]], usually on grounds of being a loud traitor. Verb: The act of deliberately seeking out and/or killing a valid individual. An inherently controversial subject.
===Voice in Your Head===
A subtle, in-character message from an admin.
===Vote===
A command which lets you call a vote to restart the game or change the game mode (which will restart the game anyway), or a request by other players indicating that the command should be typed. Calling votes when an unruined game is in progress for any reason is looked down upon, but it's not like votes work when the game really is ruined either. All votes are liable to being canceled by admins.
===VOX===
The audio announcement system that the [[AI]] will use to <s>curse at</s> send messages to the crew.
===WGW===
The legendary tale of [[Woody's Got Wood]]. The book obtained from the library. This vile tome is highly forbidden, and someone will eventually print it to spam over the radio any chance they get. Doing so will usually result in a station-wide manhunt, or the admin spawning a Space Carp named "Video Games" outside your hidey hole.
===[[Wormhole]]===
A black swirly portal that shows up during the Space-Time Anomaly random event or the verb used when thrown through a wormhole by an aggressor or your own stupidity. Anything coming into contact with a wormhole will be teleported to a random area on or off the station. They can be fairly dangerous or cause temporary blockades. Not to be confused with portals made from the Handheld Teleporter, which are blue or (more rarely) orange.
===[[Xeno]]===
Can refer to [[Aliens]], or [[Xenobiology]].
===[[Wizard]]===
Usually refers to the [[Wizard]] game mode, or a Wizard player who has access to a number of spells and will probably wreck your shit on sight or die in the first 12 seconds of a Wizard game.
===Z-Level===
Another area/map which the game consists of. Gameplay-wise, it's just a level.

Z-levels are areas you randomly spawn into when you go over the edge of an area. Part of BYOND's functionality. For example, the station, DJ station, Central Command and the [[Derelict]] are all on different Z-levels.
[[Category:Guides]]

Frequently Asked Questions

2023-03-29T03:22:24Z

Itsmeowdev: Remove game resources category

== [[What is SS13]] ==
Space Station 13 is a 2D multiplayer game, made on the BYOND engine. At a glance it looks like crap, but give it a few rounds and you'll realize just how frustratingly fun it can be.
== I'm new, where do I learn how to play? ==
Check the [[New Players]] and [[Starter guide]] pages.
== What does this word mean? ==
Check the [[Terminology]], you might find it there. Otherwise ask [[Talk:Frequently Asked Questions|here]].
== I read all the tutorials but don't know how to... ==
If it's something job specific you should check the [[Jobs]] page, if it's something about game modes (Traitor, Wizard, Cult), see the [[Game modes]] page, otherwise do a search on the wiki.

If you're smart and have already done all of those before coming here, then just [[adminhelp]] (press F1 or just type 'adminhelp' and your message) it in-game. Simply click the on adminhelp where the verbs are listed or type it into the text box in the bottom, click it and write the question in there. Try to be polite, it doesn't hurt anyone. You can also ask on [[Community|IRC]].
== I grabbed someone, how do I drop them? ==
Hit the 'stop pulling' command button. It appears when you are grabbing something and disappears when you aren't. See [[Keyboard_Shortcuts|Keyboard Shortcuts]].
== How do I remove the backpack, utility belt, etc? ==
You click on it and drag it to your empty hand.
== I'm being attacked by another player. What do? ==
You are either the victim of a traitor/some other round related character, you've really pissed the person off, or you're being griefed for no reason. If you're not sure about why you're being attacked. [[Adminhelp]] (press F1 or just type 'adminhelp' and your message) it. To reply to the administrator that responds, click the underlined portion of the message, and enter your response. Action will be taken on the matter, and the admins will look into the situation.
== How do I give an item to someone / pickpocket / dress someone up? ==
Stand next to them, click & drag their character onto yours, a list of their stuff appears, click on one of their items to take it off. Or, if you have an item in your active hand, click on the slot where you wish to put the item.
== How do I commit suicide? ==
Press "tab" until the bottom bar is red (means hotkey mode is disabled). Type 'suicide' in that red bar and hit enter. You will get a "yes or no" prompt. Clicking "yes" will make you commit suicide with the item in your activate hand. Remember that you cannot be cloned if you suicide! Suicide is considered an action which says that you don't want to play this round anymore. As such it is an [[Out of Character|OOC]] action.
== How do I eat something? ==
As with most items, pick up the food with an empty hand and then click on your character. Make sure you're on "Help Intent" other wise you might end up smashing yourself with food.
Also if you are wearing a mask (internals, gas mask etc) you will have to remove it before you can eat.
== How do I buckle/unbuckle on a chair? ==
Click and drag your character onto the chair. To unbuckle, click on the chair you are buckled to with an empty hand or "[[Keyboard_Shortcuts|resist]]". A HUD icon of a chair is also clickable to make you unbuckle. You unbuckle others by clicking the object they are buckled to.
== Why can't I play as some jobs? ==
New players are forbidden from taking jobs with are vital to normal round progression until they've been on the server for long enough. This is to avoid an inexperienced player choosing to be the Captain or AI and messing up the round for everyone.
== I got chosen as a traitor, cultist, wizard, etc. and I know I'm not ready! HELP! ==
None of these require your immediate attention. Take it slowly, open the wiki, skim through the article about your assignment and proceed to do it as best as you can. If you need additional help, ask an admin for advice through adminhelp (press F1 or just type 'adminhelp' and your message).
== Where can I go to get map files to host a server? ==
See here [[Downloading the source code]] or click the 'Host a server' link on the left.
== I have another question, where do I ask? ==
You can adminhelp it (press F1 or just type 'adminhelp' and your message) in-game, or use the OOC-command in-game to talk to players about general questions (but don't talk in OOC about anything going on in current round), or ask in the [https://tgstation13.org/phpBB/viewforum.php?f=60 discord] "help" channel, or on the [https://tgstation13.org/phpBB/ forums].
== Is BYOND/SS13 Ressources or Network intensive ? I can't seem to connect to the servers from Europe, with a recent computer. ==
When you first connect, you need to download the 30MB or so resource file from the server. This is the bulk of network activity and can take a while. Once downloaded, the game does not take much network to run. In terms of PC performance, byond itself is mostly just a front-end to the game with very little work being done on it, so you should be able to run SS13 on essentially any computer made in this millennium. It is however very resource intensive on the server side, generally requiring a full modern CPU core to itself. This is however only important if you wish to run your own server. See this thread for more help on the connecting issue: [https://tgstation13.org/phpBB/viewtopic.php?f=2&t=3678&p=90057#p90040 Unable to Connect]. Make a post if you aren't able to connect.
[[Category:Guides]]

Job selection and assignment

2023-03-29T03:22:10Z

Itsmeowdev: Remove game resources category

{{Speech
|name=Maximilian Vanderbilt, the CentCom Official
|text=NanoTrasen Central Command has selected your job assignment for this shift. I hope you are happy with what you have been so graciously provided with, 'cause you're gonna be here awhile.
|image=[[File:Centcomofficial.png|64px|right]]
}}

== Preference Ranks ==
In the job selection window of your character setup you can select how much you would like to play as a job.

There are six levels of priority:
*[High]
*[Medium]
*[Low]
*[Never]
*Banned
*Young
You can only select one job as '''high''', the other ranks do not have limits. Banned is shown to players who were banned from playing the job (received a job ban). Players who are job banned cannot spawn as that job, they can however appeal the job ban on the [[Community|forums]]. Jobs a player is banned from will show as [BANNED] no matter if it's a temporary job ban of a permanent one. Jobs the player is too young to play are jobs, which require a player to have played a certain number of days as other roles, before they are unlocked. Security jobs, head positions and silicon positions are usually the jobs that have this enabled. A [IN x DAYS] message will appear if you are too young to play a certain job, indicating how many more days need to pass before you can spawn as that job. You can still get the job by visiting the [[Head of Personnel]] though, or by being [[Cyborg|borged]] or stuffed into an [[AI]]. Finally, [NON-HUMAN] will appear by some jobs if your character is a [[lizardperson]], as lizards are prohibited from taking [[Head of Staff]] roles.
== Antagonist Assignment ==
Before jobs are assigned, the game will decide who the round antagonists are. A player who would normally have spawned as Security will spawn as a different job instead if they are selected as Antagonist.

This means you can have Security jobs on HIGH without having to worry about never getting antagonist roles.
== How Jobs are Assigned ==
Once the game is about to start, jobs are assigned to players.
=== Pre-emptive Assignment ===
*Assistants are assigned
*One head is selected
*The AI is selected
=== High Selection ===
Loops through a list of all players (randomized), if the player has a job set to high, and it has open slots, they receive it.
=== Middle Selection ===
Loops through a list of the remaining players, if the player has a job set to medium, he receives it.
=== Low Selection ===
Loops through a list of the remaining players, if the player has a job set to low, he receives it.
=== Post Selection ===
Any player who was not assigned a job spawns as a random job from the (probably small) pool of remaining empty jobs. This depends on what they selected in their character setup's occupation page (there is a toggle at the bottom).
== Tips for Job Selection ==
As you can see, people who have a job set to high are far, far more likely to get the job, since if there is only one slot available for a job - like [[Head of Security|HoS]] - and there is one person who sets that job to high and 20 people who set it to medium, the one person who set it to high will always get the job.
*Have your favorite job set to high, if you have two favorites or more, set one of them to high, do not have all three set to medium as you will very likely not get them - especially if the jobs have very few slots available.
== Available Slots ==
This is a list of the number of slots available on station. This does not count reassignments done by the [[Head of Personnel]]. The [[AI]] and [[Cyborg]] cannot be late-joiners. The default player age restriction is shown in brackets (restrictions don't apply for all servers).
* [[Assistant]]: 5 (Unlimited if no other jobs are available, anyone who sets their role to Assistant in preferences is guaranteed the role if the round is just starting)
* [[Bartender]]: 1
* [[Chef]]: 1
* [[Botanist]]: 3
* [[Quartermaster]]: 1
* [[Cargo Technician]]: 2
* [[Shaft Miner]]: 3
* [[Clown]]: 1
* [[Mime]]: 1
* [[Janitor]]: 1
* [[Curator]]: 1
* [[Lawyer]]: 2
* [[Chaplain]]: 1
* [[Station Engineer]]: 5
* [[Atmospheric Technician]]: 3
* [[Roboticist]]: 2
* [[Medical Doctor]]: 5
* [[Chemist]]: 2
* [[Geneticist]]: 2
* [[Virologist]]: 1
* [[Scientist]]: 5
* [[Warden]]: 1 (min 7 day player age)
* [[Detective]]: 1 (min 7 day player age)
* [[Security Officer]]: Scales with population; Minimum 5 (min 7 day player age)
* [[Chief Medical Officer]]: 1 (min 7 day player age)
* [[Chief Engineer]]: 1 (min 7 day player age)
* [[Research Director]]: 1 (min 7 day player age)
* [[Head of Personnel]]: 1 (min 10 day player age)
* [[Head of Security]]: 1 (min 14 day player age)
* [[Captain]]: 1 (min 14 day player age)
* [[Cyborg]]: 1 (available at round start only) (min 21 day player age)
* [[AI]]: 1 (available at round start only) (min 30 day player age)
[[Category:Guides]]

Guide to git

2023-03-29T03:20:37Z

Itsmeowdev: Add Map Merger page link

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "[/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>]"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

Name can just be your GitHub username or something else, doesn’t matter.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. GitHub will also provide you with a private email, if you don't have any type of "business" email, it is recommended to use this.

For more details on commit email privacy, read [https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address GitHub's guide].


== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.

For more info, see [[Map Merger]].
=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

Map Merger

2023-03-29T03:19:29Z

Itsmeowdev: Latest from TG (Licensed CC-BY-NC-SA 4.0)

BeeStation uses a tool called the '''Map Merger''' to make map changes easier for maintainers to review and less likely to conflict with map changes made by others.

There are a few ways of running the tool. If you have trouble or need help, ask in the Discord.

'''Summary''': for best results, open the <code>tools/hooks/</code> folder and double-click <code>Install.bat</code> to install the hooks, which will handle things automatically.
==TGM format conversion ==
The "map merge" operation describes the process of converting a map file written by the DreamMaker map editor to:
#Use a format more amenable to Git's conflict resolution, called "TGM" and originally developed by Remie. The TGM map format is like the standard Dream Maker map format, but arranged differently, meaning Dream Maker is able to open TGM maps.
#Keep the size of the difference between the old version and the new version of the map as small as possible.
This is accomplished by referencing the changed version of the map against the old version stored in the Git history.
=== Use as a Git hook (recommended)===
#'''Install the hook''': Open the <code>tools/hooks/</code> folder and double-click <code>Install.bat</code>
#*Linux users: run <code>tools/hooks/install.sh</code>
Once complete, the map merger will run '''automatically''' every time you commit in Git. The console log can be reviewed if there are any errors.
===Or: Run manually before committing===
You can also manually run a .bat file just before each time you commit:
#Ensure you have saved all your changes
#Open the <code>tools/mapmerge2/</code> folder and double-click <code>Run Before Committing.bat</code>
#Commit
===If you forgot to map merge===
For first-time contributors who committed map edits without map merging, a script is available to automatically commit a fix to your PR branch:
#Ensure you have no unsaved changes
# Open the <code>tools/mapmerge2/</code> folder and double-click <code>I Forgot To Map Merge.bat</code>
#Push your branch
==Automatic conflict resolver==
We also have a rudimentary conflict resolver to cover some cases that the TGM conversion couldn't prevent.

When run, the console output will indicate whether further manual action is needed, including conflicting coordinates.
=== Use as a Git hook===
#'''Install the hook''': Open the <code>tools/hooks/</code> folder and double-click <code>Install.bat</code>
#*Linux users: run <code>tools/hooks/install.sh</code>
Once complete, the conflict resolver will run '''automatically''' every time you merge in Git.
===Or: Resolve conflicts on an in-progress merge===
If you are using a Git GUI which does not run the hook on merge, you can also run the conflict resolver on an in-progress merge by request:
#Open the <code>tools/mapmerge2/</code> folder and double-click <code>Resolve Map Conflicts.bat</code>
#*Linux users: run <code>tools/hooks/dmm.merge --posthoc</code>
Note that to use this, you must merge your updated local master branch into the branch with conflicts so that your Git GUI reports a conflict on the map file.

{{Contribution guides}}

Guide to git

2023-03-29T02:50:39Z

Itsmeowdev: /* The Setup */ Email privacy

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "youremail@example.com"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

Name can just be your GitHub username or something else, doesn’t matter.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. GitHub will also provide you with a private email, if you don't have any type of "business" email, it is recommended to use this.

For more details on commit email privacy, read [https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address GitHub's guide].



== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.


=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

Guide to git

2023-03-29T02:48:37Z

Itsmeowdev: /* The Setup */ Email moment

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "youremail@example.com"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. Name can just be your GitHub username or something else, doesn’t matter.



== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.


=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

Guide to git

2023-03-29T02:47:51Z

Itsmeowdev: /* The Setup */ Fix git link

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [[git:|git-scm]]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "[/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>]"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. Name can just be your GitHub username or something else, doesn’t matter.



== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.


=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

Development

2023-03-27T21:27:37Z

Itsmeowdev: Add git guide

Feel free to add to this page if you have any resources that may help aspiring developers.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
=== Resources ===
==== Design ====
==== Coding ====
Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq

Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels

Local database setup - [[Working with the database#Database Setup|Working with the database]]

Using version control / git - [[Guide to git]]
==== Spriting ====
Guide to spriting - [[Guide to spriting]]
==== Mapping ====
Guide to mapping - [[Guide to mapping]]

Guide to git

2023-03-27T21:25:48Z

Itsmeowdev: Remove links

= Git Command Line =
Many are drawn to GUI versions of Git, such as GitHub Desktop, GitKraken, and VSCode’s Git integration. However, I believe this is more of a hindrance than a help. If you’re just making mapping or sprite PRs, sure, maybe you can get along just fine with GitHub Desktop. However, these tools lack the expansive features of the command line and are harder to get help with. Command line is far more google-able if you have problems and I highly recommend it. Far more people will be able to assist you if you are using command line than an GUI tool.


== The Setup ==
Download and install [git:|git-scm]. You should probably set it up to use the shell of your choice (I use command line on Windows Terminal), or if you prefer Git Bash, use that. Do note that installing it to your system PATH is very useful if you want to use VSCode’s builtin terminal.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly.

<code>git config --global user.name "Name Here"</code> <code>git config --global user.email "[/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>]"</code>

Often times the default can expose personal information. So be ''sure'' to set this.

As long as the email you put is added to your GitHub account it will work fine and show your icon on commits. Name can just be your GitHub username or something else, doesn’t matter.


== Git Terms Cheat-Sheet ==
'''HEAD:''' Term for the current location on the “commit tree”, basically your current location in history.

'''Detached HEAD:''' A state the client can be in, where the history is at a specific point in time, but not attached to a branch. Committing changes is not possible unless the HEAD is re-attached by checking out a branch.

'''Staging:''' an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.

'''Commit:''' a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time

'''Branch:''' A collection of commits in one big chain, that can split off at any time

'''Merge:''' Joining two branches

'''Remote:''' A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol

'''Upstream:''' The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo


== Git Commands Cheat-Sheet ==
<code>git clone (github link)</code> downloads the linked repository into a folder at the current location.

<code>git pull remotename branchname</code> runs <code>git fetch remotename</code> and then <code>git merge remotename/branchname</code>

<code>git fetch remotename</code> gets all the new commits from remote


=== Merging Strategies ===
<code>git merge branchname</code> Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:
* Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
* Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
* Rebase: this is its own command, <code>git rebase branchname</code> This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
<code>git reset commitsha (or branchname)</code> - Sets the current HEAD to the commit listed OR the branchname listed. If you specify –hard, it will update the local filesystem to match this, if you don’t specify or put –soft, it only updates this in git, keeping your file changes intact

<code>git checkout commitsha (or branchname)</code> - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

<code>git branch (branchname)</code> creates a new branch with the current commit history of the branch you are on

<code>git branch -d (branchname)</code> deletes branch with said name

<code>git add (filepath)</code> adds the file to “staging”

<code>git restore --staged (filepath)</code> removes the file from “staging”

<code>git status</code> View what is staged, what is not, also view what branch/commit you are on. VERY useful.

<code>git add .</code> Add ALL local filesystem changes to staging

<code>git checkout -- .</code> Undo all local changes, get rid of them

<code>git checkout HEAD .</code> The same as above but stricter, if it doesn’t work

<code>git checkout HEAD (or --) filepath</code> resets that file to the last commit on your filesystem

<code>git commit -m "Commit message"</code> creates a commit with the current staged changes and adds it to the branch

<code>git push remotename branchname</code> pushes the current local branch to remotename/branchname

<code>git remote add (remotename) (github link)</code> creates a remotename with a github repo so you can push/pull from it

<code>git push -u remotename branchname</code> OR <code>git pull --set-upstream remotename branchname</code> sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type <code>git push</code> or <code>git pull</code> without having to specify the remote or branch.

<code>git reset HEAD~(number)</code> resets current HEAD X commits backwards in the commit history

<code>git checkout HEAD~(number)</code> temporarily rewinds and detaches HEAD X commits back in history

<code>git log</code> show the commit history (q to exit)

<code>git diff HEAD</code> show all the changes you have made locally that are not committed (q to exit)


== Merge Conflicts ==
Merge conflicts can look intimidating, but they aren’t in reality (unless you don’t know how to code).

When two commits change the same part of the same file, git tries to merge them, but can’t, since it would probably break the code if it guessed.

Instead, it lets you do it yourself.

It writes into the file what looks like this
<pre><<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha</pre>
It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Here is an example.
<pre>/proc/main()
var/the_variable = GLOB.the_var
<<<<<<<<<<<<<<<<<< HEAD
if(variable?.test())
=================
if(the_variable.test()
>>>>>>>>>>>>>>>>>> commitsha
do_something()</pre>
This would most likely be merged into this:
<pre>/proc/main()
var/the_variable = GLOB.the_var
if(the_variable?.test()
do_something()</pre>
The inferred history here is the variable was named <code>variable</code>, and the current branch changed it to <code>the_variable</code>. However, another branch added the <code>?.</code> operator to the proccall. When this change was merged in, Git noticed an unexpected change to the variable name and placed a merge conflict. Making sense now? The way to merge it is applying both changes as intended.


=== Mapping Conflicts ===
DMM files are impossible to merge via text, so we have tooling in the repository to automatically merge them.

Run <code>tools/mapmerge2/Resolve Map Conflicts</code>

If there are any conflicting tiles, you will be prompted to fix it in your map editor, then you can continue by committing the changes.


=== Icon Conflicts ===
DMI files contain multiple images, making merge conflicts ''always'' happen if the file is updated by two branches. This means solving them is relatively trivial but can be time consuming. So there’s a tool for it.

Run <code>tools/dmi/Resolve Icon Conflicts</code>


=== Automatic Merge Conflict Resolution ===
Also, perk of using command line, if you want git to '''AUTO MERGE DMI and DMM''', as well as auto-cleanup your maps on commit, just run <code>tools/hooks/Install</code>. No need to run them manually anymore, they will run automatically if you merge or commit.


== Making a basic PR with command line ==
First, you’ll need to clone the repository:

<code>git clone <nowiki>https://github.com/BeeStation/BeeStation-Hornet/</nowiki></code>

Then, change directories into the repository with <code>cd</code>.

You will now need to create a branch for your changes, using the master branch for PRs is bad practice.

<code>git branch my-pr-that-does-something</code>

Now the branch is created, but you need to “check it out”, or switch to it:

<code>git checkout my-pr-that-does-something</code>

Make any changes in VSCode. When you’re done, run:

<code>git status</code>

Notice what files now have “unstaged changes”. Any files you do NOT want changes in, run

<code>git checkout HEAD (filepath)</code>

This will delete unwanted changes on your local filesystem.

Any files you DO want to PR changes to, run

<code>git add (filepath)</code>, or if you want to add all files, use <code>.</code> as the filepath.

Now run <code>git status</code>, and confirm all the changes you want are staged.

Now you’re ready to commit. Run:

<code>git commit -m "Put a summary of your changes here"</code>

This will create a commit and add it to the current branch. Run <code>git log</code> to see the commit history. You can exit with <code>q</code> and navigate with arrows.

That worked, so now you just need to push the changes to your fork of the repository. So go on GitHub and press the fork button on the top right of BeeStation-Hornet, and you’ll be taken to your new fork repository. You need to add this as a remote on your local client.

<code>git remote add fork <nowiki>https://github.com/(your</nowiki> GitHub username)/BeeStation-Hornet/</code> (change this to your fork’s link)

Then, you can push to a branch on your fork.

<code>git push -u fork my-pr-that-does-something</code> - The <code>-u</code> here tells Git to save that this is the path to remote. This means that when you run <code>git push</code> without passing a remote or branchname, it will know where to push the next time. The same applies to <code>git pull</code>.

Done! Now go to your fork on GitHub and refresh, you’ll see something like “changes have recently been pushed to branch my-pr-that-does-something” with a big “Open pull request” button. Press that and make sure it’s going to the main repository. You can also do this manually from the Pull Requests tab on your fork.

Downloading the source code

2023-03-27T21:24:30Z

Itsmeowdev: /* Downloading */ Add note on how to download zip

This page contains the information and steps needed to download the latest version of the code, compile it and host your own server.
== Licensing ==
The BeeStation source code is under [https://www.gnu.org/licenses/agpl-3.0.html GNU AGPL v3 license] and the assets are [https://freedomdefined.org/Licenses/CC-BY-SA CC-BY-SA].
== Downloading ==
We use GitHub to host our project.

A zip download is available here: [https://github.com/BeeStation/BeeStation-Hornet] (Press Code -> Download ZIP)

If you don't want to download 30MB of data every time an update is made, you can [[Guide to git|follow this guide]] to set up and use Git.
== "I did not change anything, but the code does not work anymore!" ==
This is likely due to corrupted files.
To fix this, you need to:
*Re-download everything
*Copy over your config folder and the data folder
*Clean compile
If you're using git reset hard against the BeeStation upstream master branch and then recompile
== Hosting a server ==
To get a simple server running first
* Download the source code as explained [[Downloading_the_source_code#Downloading|above]]
* Run '''BUILD.bat'''
* Wait until it compiles. Once it does a new file "beestation.dmb" will be created in the same folder where "beestation.dme" is. The dmb file has an orange icon. Compile time usually takes between 1 and 3 minutes, depending on your computer.
* Open dream daemon (Win7: start menu > all programs > BYOND > Dream Daemon; Win8/10: start > type Dream Daemon > Dream Daemon)
* Select the "..." in the lower right corner and select the file "beestation.dmb".
* Click the "GO" button and wait until it changes to a red "stop" button. Starting the server usually takes between 1 and 5 minutes. It is fully started once you can normally interact with Dream Daemon and a byond://xxx.xxx.xxx.xxx:xxxxx link is present at the bottom.
* Click the yellow button (former "...") to auto-join
* Left click the link (byond://xxx.xxx.xxx.xxx:xxxxx) to copy it to clipboard
* Paste the link (ctrl+v) to your friends so they can join.
== Making your server visible on byond.com ==
You '''DO NOT NEED''' to pay for membership to make your server visible on byond.com!

To make your server show up, edit the hub config option https://github.com/BeeStation/BeeStation-Hornet/blob/master/config/config.txt#L26
== Setting up the database ==
'''See [[Working with the database]].'''

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Downloading the source code

2023-03-27T21:23:55Z

Itsmeowdev: Update database link and git guide link

This page contains the information and steps needed to download the latest version of the code, compile it and host your own server.
== Licensing ==
The BeeStation source code is under [https://www.gnu.org/licenses/agpl-3.0.html GNU AGPL v3 license] and the assets are [https://freedomdefined.org/Licenses/CC-BY-SA CC-BY-SA].
== Downloading ==
We use GitHub to host our project.

A zip download is available here: [https://github.com/BeeStation/BeeStation-Hornet]

If you don't want to download 30MB of data every time an update is made, you can [[Guide to git|follow this guide]] to set up and use Git.
== "I did not change anything, but the code does not work anymore!" ==
This is likely due to corrupted files.
To fix this, you need to:
*Re-download everything
*Copy over your config folder and the data folder
*Clean compile
If you're using git reset hard against the BeeStation upstream master branch and then recompile
== Hosting a server ==
To get a simple server running first
* Download the source code as explained [[Downloading_the_source_code#Downloading|above]]
* Run '''BUILD.bat'''
* Wait until it compiles. Once it does a new file "beestation.dmb" will be created in the same folder where "beestation.dme" is. The dmb file has an orange icon. Compile time usually takes between 1 and 3 minutes, depending on your computer.
* Open dream daemon (Win7: start menu > all programs > BYOND > Dream Daemon; Win8/10: start > type Dream Daemon > Dream Daemon)
* Select the "..." in the lower right corner and select the file "beestation.dmb".
* Click the "GO" button and wait until it changes to a red "stop" button. Starting the server usually takes between 1 and 5 minutes. It is fully started once you can normally interact with Dream Daemon and a byond://xxx.xxx.xxx.xxx:xxxxx link is present at the bottom.
* Click the yellow button (former "...") to auto-join
* Left click the link (byond://xxx.xxx.xxx.xxx:xxxxx) to copy it to clipboard
* Paste the link (ctrl+v) to your friends so they can join.
== Making your server visible on byond.com ==
You '''DO NOT NEED''' to pay for membership to make your server visible on byond.com!

To make your server show up, edit the hub config option https://github.com/BeeStation/BeeStation-Hornet/blob/master/config/config.txt#L26
== Setting up the database ==
'''See [[Working with the database]].'''

{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]

Talk:Setting up git

2023-03-27T21:17:57Z

Itsmeowdev: Itsmeowdev moved page Talk:Setting up git to Talk:Guide to git: More accurate to new content

#REDIRECT [[Talk:Guide to git]]

Talk:Guide to git

2023-03-27T21:17:57Z

Itsmeowdev: Itsmeowdev moved page Talk:Setting up git to Talk:Guide to git: More accurate to new content

== Step 5 ==
it needs editing to inform the user of what actually needs to be done. you need to fork the /tg/ repo to create your own, but if you already have an old repo under that name then it doesn't work very well, and git gets unhappy about it, refusing to let you use Remote in tortoisegit.
the fix for this is to fork the repo to have your own, but take the /tg/station repo link instead of your own.

Setting up git

2023-03-27T21:17:57Z

Itsmeowdev: Itsmeowdev moved page Setting up git to Guide to git: More accurate to new content

#REDIRECT [[Guide to git]]

Guide to git

2023-03-27T21:17:57Z

Itsmeowdev: Itsmeowdev moved page Setting up git to Guide to git: More accurate to new content

'''WARNING: This guide is heavily outdated, and if you follow it, it's likely nobody will be able to help you if things go wrong.'''

Follow this guide and use GitKraken instead: https://forums.yogstation.net/index.php?threads/release-the-gitkraken-how-to-make-your-first-pull-request.15099/

----

This guide uses TortoiseGIT. While there are other programs out there, this one is the most commonly used. This guide is for Windows only.
TortoiseGIT is a simple enough program but other clients or the git command line are recommended once you are familiar with the basics.

It's recommended if you don't want to read this that you just watch this video:https://www.youtube.com/watch?v=ZDR433b0HJY

Some further videos that are recommended watching for any git user:

https://www.youtube.com/watch?v=MYP56QJpDr4 - Git from bits up

https://www.youtube.com/watch?v=4XpnKHJAok8 - Linus Torvalds (yes that linus) on git

== If you are having trouble ==
Watch this video guide if you are having difficulty with any step below. [http://www.youtube.com/watch?v=Z5tTCo6IHLg]
If you have further problems, contact someone on [[Community|#coderbus]]

== Step 1 - Install Git ==

* Go here: http://git-scm.com/downloads
* Download the Windows Git program.
* It should look something like 'Git-1.7.11-preview20120620.exe'
* Install it and leave everything on default (just keep clicking next).
* Wait till the installer has finished.
* Step 1 over!

== Step 2 - Register on Github ==

* Head over here: https://github.com/
* Click '''Signup and Pricing''' in the top right-hand corner.
* Click the ''Create free account button'''.
* Create an account with your username and email.
* Done!

== Step 3 - Configure Git ==

'''OPTIONAL!'''

* Head here: https://help.github.com/articles/set-up-git/#setting-up-git
* Follow the guide above from steps 2 to 4, you can install Git for Windows if you want however it's not recommended
* Now you have Git all setup, but if you're command line illiterate like me, you'll wanna have some fancy graphics!

== Step 4 - TortoiseGit ==

* Go here: http://code.google.com/p/tortoisegit/wiki/Download
* Download the right TortoiseGit for your system.
* When installing, click '''OpenSSH''' rather than TortoisePLink
* Finish installing.

== Step 5 - Forking Code ==

* Head over to: https://github.com/tgstation/tgstation
* Click the '''Fork''' button in the top right corner.
* The page you'll be directed to is now your fork. You'll be pushing updates here, and making pull requests to have them merged the main (master) repository.
* Copy the HTTP URL. It's next to the '''HTTP''' '''GIT''' and '''Git Read-Only''' buttons. It'll look something like: https://github.com/NAME/tgstation

== Step 6 - Downloading the Code ==

* Find a computer folder where you don't mind the code sitting.
* Right click and choose '''Git Clone...'''
* The URL field should be filled with the URL of your Fork. If not, paste it in.
* Click Next and watch flying tortoises bring you your code.

== Step 7 - Setting up TortoiseGit ==

* Right click '''on the folder that was created''' (usually called tgstation13), and go to '''TortoiseGit''' and then click on '''Settings'''.
* Click on '''Remote''' under '''Git'''.
* There should be one thing on the list of remotes, with the name: '''origin'''.
* You're now adding the main repository as a source you can pull updates from.
* In the '''Remote''' box type in '''upstream'''.
* In the '''URL:''' box put: https://github.com/tgstation/tgstation.git
* Click '''Add New/Save'''.
* Click '''Ok'''.
* Almost done!

== Step 8 - Updating your Repo ==

* Updating your repo with the master should be done before trying anything.
* Right-click the folder your repo is in and select '''TortoiseGit''' then '''Pull'''.
* Click the radial button next to '''Remote''' and make sure '''upstream''' (or whatever you called it) is selected next to it.
* The '''remote branch''' should be set to '''master'''.
* Then click '''Ok'''. This will pull the latest changes from the master repo.

== Step 9 - Making a Branch ==
* '''Branching your repo is very important for organising your commits, you should have a different branch for each unrelated code change (e.g. if you wanted to make some new sprites for one item and change the properties of another these should be in seperate branches), as Pull requests work off branches rather than commits this will allow you to make a seperate Pull Request per change. Doing this streamlines the whole process and will save everyone a bunch of headaches.'''
* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Create Branch...'''
* Type in your new branch name
* (Optional) Tick '''Switch to new branch'''
* Press '''Okay''' and your new branch is created

To switch between Branches:
* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Switch/Checkout...'''
* Choose your Branch then press '''Okay'''

== Step 10 - Making a Commit ==

* A commit is confirmed change of the files in your repo, it's how you make changes permanently to the files in your repo, so try not to commit without making sure it works (though subsequent commits can fix it).
* As said before, you should use different branches to separate your commits/changes. Don't commit to master. It should be clean, so you can fall back on it if needed.
* To make your commits, you need to edit the files using BYOND's inbuilt editing tools. Make sure to [[Coding Standards|follow coding standards]] when making your changes! When you're finished, right click the folder you're working with and choose '''Git Commit -> "[Your Branch Name]"''' (Example: Git Commit -> "My_First_Branch")
* You can then select only the files you want to be committed by ticking or unticking them. You should also write a detailed commit summary, detailing what happened in that commit.
* Click '''Ok''' and the commit will be committed to your local repo!

== Step 11 - Making a Pull Request ==

* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Push...'''
* Set '''Local''' and '''Remote''' to the name of the branch you committed before. (e.g. My_First_Branch)
* Under Destination, set Remote: to '''origin'''.
* Click '''Ok'''. This'll upload your changes to your remote repo (the one on GitHub).
* Head to your GitHub repo e.g https://github.com/NAME/tgstation13.git
* Click '''Pull Request''' at the top right.
* [[Getting_Your_Pull_Accepted|Give this a quick read.]]
* Fill out a summary and then create the pull request.
* You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
* Optionally, view step 13 for a guide on cleaner commit logs, '''cleaner commits help maintainers review!'''

== Step 12 - Checking Out Github PRs Locally (Optional) ==
*'''This is a must for maintainers who need to easily test other people's code!'''
*Locate the section for your Github remote in the .git/config file. Note that it is hidden by default. It looks like this:

:[remote "upstream"]
::fetch = +refs/heads/*:refs/remotes/upstream/*
::url = https://github.com/tgstation/tgstation.git

*Now add the following line:
::fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

*Fetch from the upstream remote.
*To check out a particular pull request, use Switch/Checkout and select the branch from the drop-down list.

=== Git command line verison ===

No editing of the git config file needed, just do git fetch <remote> pull/<pr>/head:target_branch usually something like git fetch upstream pull/26271/head:pr-26271.

Then you can checkout the target_branch

== Step 13 - Clean commits (Optional) ==
*'''This is a guide specifically for TortoiseGit, our recommended client'''
* Your commit logs are filthy, full of one or two line commits that fix an error that makes you look bad, and the commit is called "Whoops" or "oops"
* Navigate to your '''local version of the branch'''
* Ensure it is up to date with the '''remote'''
* Go to '''Show log'''
* Select all the commits associated with this change or PR
* Right click and choose '''Combine to one commit'''
* This will open up the standard commit interface for TortoiseGit, with the commit logs of the selected commits merged together
* Perform the normal routine for a commit
* Go to '''push''' your branch to the '''remote branch'''
* Ensure '''Force Overwrite Existing Branch (may discard changes)''' is selected to make sure the PR/Remote updates to contain just this squashed commit

{{Contribution guides}}
[[Category:Game Resources]] [[Category:Guides]]

Development

2023-03-27T21:05:42Z

Itsmeowdev: /* Coding */ Add local DB setup

Feel free to add to this page if you have any resources that may help aspiring developers.

For design direction and coding guidelines, see https://github.com/BeeStation/BeeStation-Hornet/wiki
=== Resources ===
==== Design ====
==== Coding ====
Guide to coding - https://hackmd.io/@BdkEQ8tISgW8Pbn2OquQxQ/B1SeqStVq

Guide to hard-dels - https://hackmd.io/@PowerfulBacon/guide_to_harddels

Local database setup - [[Working with the database#Database Setup|Working with the database]]
==== Spriting ====
Guide to spriting - [[Guide to spriting]]
==== Mapping ====
Guide to mapping - [[Guide to mapping]]

Working with the database

2023-03-27T21:04:17Z

Itsmeowdev: /* Setup MariaDB (Windows) */ Size up images

Working with the database

2023-03-27T20:59:51Z

Itsmeowdev: Remove captions

= Database Setup =

When developing, it is useful to have a local database set up, for a variety of reasons.

This guide is a walk through for local testing database installation, however it will work for a production deployment so long as secure passwords are used and firewall settings protect the database from external connection.

Since savefiles no longer store character info, your character and preferences will reset between each startup. This can be problematic in adding a lot of time to the development and testing cycle. As such, it’s useful to set one up. This is a guide on how to do so.


== Setup MariaDB (Windows) ==

Download and install [[mariadb:|MariaDB Community Server]] for your operating system. Be sure to install the following components:

* Database Instance
* Client Programs
* HeidiSQL

[[File:Db_setup-6ce6ffea237bf219c2b91d392f48b2099b7930ae.png|thumb|none|alt=image]]

Set a root password, something you will remember. It doesn’t need to be properly secure if it's for local testing, since you won’t be storing anything or hosting it publicly. Do '''not''' enable remote access for root.

[[File:Db_setup-559f5ff4e926edda40dd87a6274c774a6b9772e0.png|thumb|none|alt=image]]

Install it as a service, with networking enabled. The default settings are fine. This means it will run 24/7 in the background. You can manage this in the Windows Services viewer.

[[File:Db_setup-A055e14a687b49ba5d723e90d6bbcfcae2958296.png|image]] [[File:Db_setup-d327ef8463bef045b46b8aac0848e9303d50b19d.png|image]]

Open HeidiSQL, Click on new to create a new session, check prompt for credentials and leave the rest as default.

[[File:Db_setup-5268ec389c6fcf8f2ff1aa84a382090c1e5278ae.png|thumb|none|alt=image]]

Click save, then click open and enter in root for the username and the password you setup during the installation.

[[File:Db_setup-f8c2d10d5769c57f387e0eadf1c6e67842814ac3.png|thumb|none|alt=image]]

Right click on the server entry in the left side plane (the area with <code>information_schema</code>, <code>mysql</code>, etc) (the server entry will be the first one) and go to <code>Create new -> Database</code>

[[File:Db_setup-245204aa1d0f17218e2eb1f4a0dd4a2432696ae6.png|thumb|none|alt=image]]

You can name it anything at this step. The default config is <code>ss13beedb</code>, so go ahead and use that. Don’t name it <code>test</code>, or you will have security issues.

[[File:Db_setup-598a1178e842219e1b0ae9dc12f2ef27aafbf2de.png|thumb|none|alt=image]]

Select the database you just created and then go to <code>File -> Open SQL File</code> and open the file <code>beestation_schema.sql</code> file located at <code>SQL/beestation_schema.sql</code>. You can also find it [[beereporaw:master/SQL/beestation_schema.sql|here]], but it may be newer than the version you are using. If it asks you to auto-detect, hit Yes. Ignore any “access violation” errors, the import works anyway.

[[File:Db_setup-f0f38f6cd445af32da096c835d2492727b091f3f.png|thumb|none|alt=image]] [[File:Db_setup-B8634fc2985464e926572ac826faa7b4379f3653.png|thumb|none|alt=image]]

Press the blue play icon in the topic bar of icon hieroglyphs and pray. If the schema imported correctly you should have no errors in the message box on the bottom.

[[File:Db_setup-5f7d15719bbacab5f759e2905d421f60c246f95a.png|thumb|none|alt=image]]

Create a new user account for the server by going to <code>Tools -> User Manager</code>.

* '''Username:''' Anything, but <code>ss13dbuser</code> is the default
* '''Password:''' Any string of random text, you don’t need to remember it, just paste it into your database config. You can randomly generate one by pressing the arrow on the password field. Be sure to copy it.
* '''From host:''' <code>127.0.0.1</code>
* '''Permissions:''' Press “Add object”, select the database you created. Under the new object, add:
** <code>SELECT</code>
** <code>DELETE</code>
** <code>INSERT</code>
** <code>UPDATE</code>

[[File:Db_setup-f125cfa6a81217aa0b33ed0431b69c626303a671.png|thumb|none|alt=image]]


== Update dbconfig ==

Now, on your local copy of the repository, open [[beerepo:blob/master/config/dbconfig.txt|config/dbconfig.txt]] in a text editor.

Set the following:

* Uncomment <code>SQL_ENABLED</code> by removing the <code>#</code> in front of it.
* <code>ADDRESS 127.0.0.1</code>
* <code>PORT 3306</code>
* <code>FEEDBACK_DATABASE ss13beedb</code> (or whatever you set)
* <code>FEEDBACK_LOGIN ss13dbuser</code> (or whatever you set)
* <code>FEEDBACK_PASSWORD password</code> (replace with the password you set for the created user)

[[File:Db_setup-dc58b4506df7c115cf8edfa191804ceba96802e5.png|thumb|none|alt=image]]


== Skip Worktree ==

Now, on git, this will create tracked changes that you don’t want to commit to any future PRs. So you need to tell git to not process any changes in the file. If you use git command line, this is trivial.

Run <code>git update-index --skip-worktree config/dbconfig.txt</code>. Git will now ignore changes to this file locally. If you wish to undo this at any point, run <code>git update-index --no-skip-worktree config/dbconfig.txt</code>.

[[File:Db_setup-1681618ba8cc443a13696a952af5c720c44a54c3.png|thumb|none|alt=image]]

If you do not use command line, you should still be able to accomplish this somehow, google the equivalent for whatever tool you use.

= Other database options =

== Database based banning ==
Offers temporary jobbans, admin bans, cross-server bans, keeps bans logged even after they've expired or were unbanned, and allows for the use of the off-server ban log.

To enable database based banning:
* Open config/config.txt
* Add a # in front of BAN_LEGACY_SYSTEM, so the line looks like "#BAN_LEGACY_SYSTEM"
* Done. Note that any legacy bans are no longer enforced once this is done! So it's a good idea to do it when you're starting up.

== Database based administration ==
Offers a changelog for changes done to admins, which increases accountability (adding/removing admins, adding/removing permissions, changing ranks); allows admins with +PERMISSIONS to edit other admins' permissions ingame, meaning they don't need remote desktop access to edit admins; Allows for custom ranks, with permissions not being tied to ranks, offering a better ability for the removal or addition of permissions to certain admins, if they need to be punished, or need extra permissions. Enabling this can be done any time, it's just a bit tedious the first time you do it, if you don't have direct access to the database.

To enable database based administration:
* Open config/config.txt
* Add a # in front of ADMIN_LEGACY_SYSTEM, so the line looks like "#ADMIN_LEGACY_SYSTEM"
* Do the steps described in [[Working with the database#Adding your first admin|Adding your first admin]].
* Done. Note that anyone in admins.txt lost admin status, including you! So do the step above! You can repeat it for everyone, as it's a lot easier to do that and just correct permissions with the ingame panel called 'permissions panel'.
* If your database ever dies, your server will revert to the old admin system, so it is a good idea to have admins.txt and admin_ranks.txt set up with some admins too, just so the loss of the database doesn't completely destroy everything.
If you need more help contact [[Community|#coderbus]].

Working with the database

2023-03-27T20:54:20Z

Itsmeowdev: Created page with "= Database Setup = When developing, it is useful to have a local database set up, for a variety of reasons. This guide is a walk through for local testing database installation, however it will work for a production deployment so long as secure passwords are used and firewall settings protect the database from external connection. Since savefiles no longer store character info, your character and preferences will reset between each startup. This can be problematic in..."

= Database Setup =

When developing, it is useful to have a local database set up, for a variety of reasons.

This guide is a walk through for local testing database installation, however it will work for a production deployment so long as secure passwords are used and firewall settings protect the database from external connection.

Since savefiles no longer store character info, your character and preferences will reset between each startup. This can be problematic in adding a lot of time to the development and testing cycle. As such, it’s useful to set one up. This is a guide on how to do so.


== Setup MariaDB (Windows) ==

Download and install [[mariadb:|MariaDB Community Server]] for your operating system. Be sure to install the following components:

* Database Instance
* Client Programs
* HeidiSQL

[[File:Db_setup-6ce6ffea237bf219c2b91d392f48b2099b7930ae.png|thumb|none|alt=image|image]]

Set a root password, something you will remember. It doesn’t need to be properly secure if it's for local testing, since you won’t be storing anything or hosting it publicly. Do '''not''' enable remote access for root.

[[File:Db_setup-559f5ff4e926edda40dd87a6274c774a6b9772e0.png|thumb|none|alt=image|image]]

Install it as a service, with networking enabled. The default settings are fine. This means it will run 24/7 in the background. You can manage this in the Windows Services viewer.

[[File:Db_setup-A055e14a687b49ba5d723e90d6bbcfcae2958296.png|image]] [[File:Db_setup-d327ef8463bef045b46b8aac0848e9303d50b19d.png|image]]

Open HeidiSQL, Click on new to create a new session, check prompt for credentials and leave the rest as default.

[[File:Db_setup-5268ec389c6fcf8f2ff1aa84a382090c1e5278ae.png|thumb|none|alt=image|image]]

Click save, then click open and enter in root for the username and the password you setup during the installation.

[[File:Db_setup-f8c2d10d5769c57f387e0eadf1c6e67842814ac3.png|thumb|none|alt=image|image]]

Right click on the server entry in the left side plane (the area with <code>information_schema</code>, <code>mysql</code>, etc) (the server entry will be the first one) and go to <code>Create new -> Database</code>

[[File:Db_setup-245204aa1d0f17218e2eb1f4a0dd4a2432696ae6.png|thumb|none|alt=image|image]]

You can name it anything at this step. The default config is <code>ss13beedb</code>, so go ahead and use that. Don’t name it <code>test</code>, or you will have security issues.

[[File:Db_setup-598a1178e842219e1b0ae9dc12f2ef27aafbf2de.png|thumb|none|alt=image|image]]

Select the database you just created and then go to <code>File -> Open SQL File</code> and open the file <code>beestation_schema.sql</code> file located at <code>SQL/beestation_schema.sql</code>. You can also find it [[beereporaw:master/SQL/beestation_schema.sql|here]], but it may be newer than the version you are using. If it asks you to auto-detect, hit Yes. Ignore any “access violation” errors, the import works anyway.

[[File:Db_setup-f0f38f6cd445af32da096c835d2492727b091f3f.png|image]] [[File:Db_setup-B8634fc2985464e926572ac826faa7b4379f3653.png|image]]

Press the blue play icon in the topic bar of icon hieroglyphs and pray. If the schema imported correctly you should have no errors in the message box on the bottom.

[[File:Db_setup-5f7d15719bbacab5f759e2905d421f60c246f95a.png|thumb|none|alt=image|image]]

Create a new user account for the server by going to <code>Tools -> User Manager</code>.

* '''Username:''' Anything, but <code>ss13dbuser</code> is the default
* '''Password:''' Any string of random text, you don’t need to remember it, just paste it into your database config. You can randomly generate one by pressing the arrow on the password field. Be sure to copy it.
* '''From host:''' <code>127.0.0.1</code>
* '''Permissions:''' Press “Add object”, select the database you created. Under the new object, add:
** <code>SELECT</code>
** <code>DELETE</code>
** <code>INSERT</code>
** <code>UPDATE</code>

[[File:Db_setup-f125cfa6a81217aa0b33ed0431b69c626303a671.png|thumb|none|alt=image|image]]


== Update dbconfig ==

Now, on your local copy of the repository, open [[beerepo:blob/master/config/dbconfig.txt|config/dbconfig.txt]] in a text editor.

Set the following:

* Uncomment <code>SQL_ENABLED</code> by removing the <code>#</code> in front of it.
* <code>ADDRESS 127.0.0.1</code>
* <code>PORT 3306</code>
* <code>FEEDBACK_DATABASE ss13beedb</code> (or whatever you set)
* <code>FEEDBACK_LOGIN ss13dbuser</code> (or whatever you set)
* <code>FEEDBACK_PASSWORD password</code> (replace with the password you set for the created user)

[[File:Db_setup-dc58b4506df7c115cf8edfa191804ceba96802e5.png|thumb|none|alt=image|image]]


== Skip Worktree ==

Now, on git, this will create tracked changes that you don’t want to commit to any future PRs. So you need to tell git to not process any changes in the file. If you use git command line, this is trivial.

Run <code>git update-index --skip-worktree config/dbconfig.txt</code>. Git will now ignore changes to this file locally. If you wish to undo this at any point, run <code>git update-index --no-skip-worktree config/dbconfig.txt</code>.

[[File:Db_setup-1681618ba8cc443a13696a952af5c720c44a54c3.png|thumb|none|alt=image|image]]

If you do not use command line, you should still be able to accomplish this somehow, google the equivalent for whatever tool you use.

= Other database options =

== Database based banning ==
Offers temporary jobbans, admin bans, cross-server bans, keeps bans logged even after they've expired or were unbanned, and allows for the use of the off-server ban log.

To enable database based banning:
* Open config/config.txt
* Add a # in front of BAN_LEGACY_SYSTEM, so the line looks like "#BAN_LEGACY_SYSTEM"
* Done. Note that any legacy bans are no longer enforced once this is done! So it's a good idea to do it when you're starting up.

== Database based administration ==
Offers a changelog for changes done to admins, which increases accountability (adding/removing admins, adding/removing permissions, changing ranks); allows admins with +PERMISSIONS to edit other admins' permissions ingame, meaning they don't need remote desktop access to edit admins; Allows for custom ranks, with permissions not being tied to ranks, offering a better ability for the removal or addition of permissions to certain admins, if they need to be punished, or need extra permissions. Enabling this can be done any time, it's just a bit tedious the first time you do it, if you don't have direct access to the database.

To enable database based administration:
* Open config/config.txt
* Add a # in front of ADMIN_LEGACY_SYSTEM, so the line looks like "#ADMIN_LEGACY_SYSTEM"
* Do the steps described in [[Working with the database#Adding your first admin|Adding your first admin]].
* Done. Note that anyone in admins.txt lost admin status, including you! So do the step above! You can repeat it for everyone, as it's a lot easier to do that and just correct permissions with the ingame panel called 'permissions panel'.
* If your database ever dies, your server will revert to the old admin system, so it is a good idea to have admins.txt and admin_ranks.txt set up with some admins too, just so the loss of the database doesn't completely destroy everything.
If you need more help contact [[Community|#coderbus]].

File:Db setup-f125cfa6a81217aa0b33ed0431b69c626303a671.png

2023-03-27T20:32:47Z

Itsmeowdev:

File:Db setup-f8c2d10d5769c57f387e0eadf1c6e67842814ac3.png

2023-03-27T20:32:37Z

Itsmeowdev:

File:Db setup-f0f38f6cd445af32da096c835d2492727b091f3f.png

2023-03-27T20:32:23Z

Itsmeowdev: