Редактирование: SS13 for experienced programmers (раздел)

== Syntax ==

*Semicolons at the end are not mandatory,
*Loop, proc, object, variable etc. spans are determined by indentations (similar to Python, see examples below)
  /obj
    var
      i1
      i2
      i3
is the same as 
  /obj
    var/i1
    var/i2
    var/i3
which is inturn the same as
  /obj/var/i1
  /obj/var/i2
  /obj/var/i3

For this project use the following layout. (This layout makes searching for variable and proc definitions easier.)
  /obj
    var/i1
    var/i2
    var/i3
  /obj/proc/test()
    var/a = 5
    return a + i1    
  /obj/del()
    return i1

*This guide uses the word 'object' for any defined type (see [[#Variable types|Variable types]]) and the word 'obj' for derivatives of atom/obj, which are all objects which can be placed on the map.
*This guide uses the word 'AI controlled' for behavior to do with an [[AI]] player controlling an item. The term 'Game controlled' is used when refering to behavior which the script itself determins (Usually called AI controlled creatures or NPCs)
*All things are inherited from parent objects. If a variable is defined in /obj/item, it doesn't need to be (actually can't be) redefined in /obj/item/weapon.

=== [http://www.byond.com/members/?command=reference&path=var Variables] ===
Variables are very general, Byond makes no difference in the declaration of strings, integers, etc. (Similar to PHP)

==== [http://www.byond.com/members/?command=reference&path=var Predefined variables] ====
There is a lot of predefined variables for objects in BYOND, but the most important are:
*'''[http://www.byond.com/members/?command=reference&path=proc%2Fvar%2Fsrc src]''' - a variable equal to the object containing the proc or verb. It is defined to have the same type as that object. (Similar to "this" in Java or C++)
*'''[http://www.byond.com/members/?command=reference&path=proc%2Fvar%2Fusr usr]''' - a mob variable (var/mob/usr) containing the mob of the player who executed the current verb, or whose action ultimately called the current proc. '''A good rule of thumb is to never put usr in a proc.''' If src would not be the correct choice, it is better to send another argument to your proc with the information it needs.
*'''[http://www.byond.com/members/?command=reference&path=proc%2Fvar%2Fargs args]''' - a list of the arguments passed to the proc or verb.
*'''[http://www.byond.com/members/?command=reference&path=datum%2Fvar%2Fvars vars]''' - a list of object variables. If the variable name is used as an index into the list, the value of that variable is accessed.

For more SS13 specific variables see [[#SS13 common variable meanings|SS13 common variable meanings]]

==== Variable definition ====

=====Basic definitions=====
  var/j
  var/i = 4
  var/a, b, c

=====Complex definitions=====
The general syntax is [http://www.byond.com/members/?command=reference&path=var var/type/variable_name = value]

Examples:
  var/obj/item/I = new/obj/item
  [http://www.byond.com/members/?command=reference&path=operator%2F%40dt%3B I.name] = "Some item"

Datum definition and declaration of a variable of that datum type:
  datum/test_datum
    var/test_variable = 0 //declaration of the test_variable var
    
    proc/set_as(var/i) //proc definition within the test_datum datum
      test_variable = i //set the test_variable var to the value in the argument
  
  var/datum/test_datum/TD = new/datum/test_datum //TD will now be a reference to a datum of type test_datum
  TD.test_variable = 4  //Byond doesn't know of private variables, so you can set any variables like this
  [http://www.byond.com/members/?command=reference&path=world world] [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B <<] TD.test_variable //will output 4 to all connected users
  TD.set_as(10) //Will call the set_as proc in the datum with the argument 10
  TD.test_variable //will output 10 to all connected users

==== [[Binary flags|Bitflags]] ====

See the main article at [[Binary flags]].

Bitflags are variables which use bits instead of numbers to determine conditions. The bit operators are [http://www.byond.com/members/?command=reference&path=operator%2F%26 &] and [http://www.byond.com/members/?command=reference&path=operator%2F%7C |]. For now, you should know that bitflag operators use the binary value of numbers to determine the result. So [http://www.byond.com/members/?command=reference&path=operator%2F%26 13 & 3] will result in 1. ([http://www.byond.com/members/?command=reference&path=operator%2F%26 1101 & 0011 = 0001]) and [http://www.byond.com/members/?command=reference&path=operator%2F%7C 13 | 3 = 15] ([http://www.byond.com/members/?command=reference&path=operator%2F%7C 1101 | 0011 = 1111]) see [[#If|if]] for uses

==== Variable types ====
[http://www.byond.com/members/?command=reference&path=var reference]

*[http://www.byond.com/members/?command=reference&path=datum datum] - ordinary object type (class in java)
*[http://www.byond.com/members/?command=reference&path=atom atom] - atom derives into obj, turf, mob and area
*[http://www.byond.com/members/?command=reference&path=turf turf] - tiles which make up the floors, walls and space on SS13
*[http://www.byond.com/members/?command=reference&path=area area] - areas are grouped locations. They combine many turfs and it gives some common properties. Power, atmosphere, etc. are determined by areas
*[http://www.byond.com/members/?command=reference&path=mob mob] - an object with life, be it game controlled or player controlled.
*[http://www.byond.com/members/?command=reference&path=obj obj] - objects which can be placed on the map
*[http://www.byond.com/members/?command=reference&path=client client] - a new client object is created for each connected player
*[http://www.byond.com/members/?command=reference&path=list list] - a list of elements. The first element in a list called L is L[1]
*[http://www.byond.com/members/?command=reference&path=world world] - this is a variable where some global variables for the entire world can be set. World's contents var contains all atoms currently in the game world.

==== [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B%2Foutput Outputting messages] ====
The most basic way of outputting messages is with the [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B%2Foutput '<<' output operator].

  [http://www.byond.com/members/?command=reference&path=world world] [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B <<] "Hello World!" //Outputs a message to all clients in the world
  [http://www.byond.com/members/?command=reference&path=proc%2Fvar%2Fusr usr] [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B <<] "Hello usr" //Outputs a message to only the user who is tied to the calling of the proc which contains this.

===== Output with variables =====
  var/s1 = "Hello"
  var/s2 = "World"
  var/i = 2011
  [http://www.byond.com/members/?command=reference&path=world world] [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%26lt%3B <<] "[s1] [s2], this guide was written in [i]" //Returns "Hello World, this guide was written in 2011"

==== Determining variable types in code ====
The [http://www.byond.com/members/?command=reference&path=proc%2Fistype istype()] proc will come in handy

Example
  var/obj/item/weapon/W = new/obj/item/weapon/baton
  if([http://www.byond.com/members/?command=reference&path=proc%2Fistype istype](W,/obj/item/weapon/baton))
    [http://www.byond.com/members/?command=reference&path=world world] << "It's a baton!"

The second argument is optional, if it's omitted, the variable will be checked against its declared type, like
  var/obj/item/weapon/W = new/obj/item/weapon/baton
  if([http://www.byond.com/members/?command=reference&path=proc%2Fistype istype](W))
    [http://www.byond.com/members/?command=reference&path=world world] << "It's a weapon!"

Standard code for getting specific arguments from variables which have a type that is a subclass of the type the current proc treats them with (see any attackby() proc for examples). Note that the example below is of a proc which is globaly defined, not tied to the object. It doesn't make much sense to do it like this but it works for the purposes of the example. /obj objects don't have the 'amount' variable, it's defined in /obj/item/stack (as ilustrated by the oversimplified definition of classes below. Also note where var/ is used and where it isn't).
  /obj
    var/name = "Object"
  
  /obj/item
    name = "Item"
  
  /obj/item/stack
    name = "Stack"
    var/amount = 50
  
  proc/get_amount(var/obj/O)
    if([http://www.byond.com/members/?command=reference&path=proc%2Fistype istype](O,/obj/item/stack))
      var/obj/item/stack/S = O
      return [http://www.byond.com/members/?command=reference&path=operator%2F%40dt%3B S.amount]

There is another way of doing this. I'll show you that it exists but it is NOT TO BE USED.
  proc/get_aount(var/obj/S)
    if([http://www.byond.com/members/?command=reference&path=proc%2Fistype istype](O,/obj/item/stack))
      return [http://www.byond.com/members/?command=reference&path=operator%2F%3A O:amount]
The [http://www.byond.com/members/?command=reference&path=operator%2F%3A colon operator] (:) in the example above tells the byond compiler: "I know what I'm doing, so ignore the fact the object doesn't have this variable, I'll make sure it works myself." The problem is that people will revise your code and use it in ways you never planed for. This means something might eventually make the O:amount throw exceptions in the form of runtime errors. Some variables might eventually need to be removed or replaced and this is impossible when they are used with object:variable as the compiler will not throw an error when the variable is removed. The error will only become apparent after the game is ran on the live server which might cause it to crash. So just don't use this method, ever.

There are some shortcuts to [http://www.byond.com/members/?command=reference&path=proc%2Fistype istype()] proc:<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fisarea isarea(variable)] = istype(variable, /area)<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fisicon isicon(variable)] = istype(variable, /icon)<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fismob ismob(variable)]  = istype(variable, /mob)<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fisobj isobj(variable)]  = istype(variable, /obj)<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fisturf isturf(variable)] = istype(variable, /turf)<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fisloc isloc(variable)]  = ismob(variable) || isobj(variable) || isturf(variable) || isarea(variable)

==== Switching between variable types in code ====

Byond defined:<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fascii2text ascii2text]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ffile2text file2text]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Flist2params list2params]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fnum2text num2text]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Fparams2list params2list]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ftext2ascii text2ascii]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ftext2file text2file]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ftext2num text2num]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ftext2path text2path]<br>
[http://www.byond.com/members/?command=reference&path=proc%2Ftime2text time2text]<br>

SS13 Defined:<br>
text2dir(direction)<br>
dir2text(direction)<br>
dd_file2list(file_path, separator)<br>
dd_text2list(text, separator, var/list/withinList)<br>
dd_text2List(text, separator, var/list/withinList)<br>
dd_list2text(var/list/the_list, separator)<br>
angle2dir(var/degree)<br>
angle2text(var/degree)<br>
(Defined in [https://github.com/tgstation/-tg-station/blob/master/code/__HELPERS/type2type.dm code/__HELPERS/type2type.dm])

For more useful procs see<br>
[https://github.com/tgstation/-tg-station/tree/master/code/__HELPERS code/__HELPERS/] <br>
<s>[http://code.google.com/p/tgstation13/source/browse/trunk/code/defines/procs/helpers.dm code/defines/procs/helpers.dm]</s> (Dead link)<br>
<s>[http://code.google.com/p/tgstation13/source/browse/trunk/code/game/objects/items/helper_procs.dm code/game/objects/items/helper_procs.dm]</s> (Dead link) <br>

=== [http://www.byond.com/members/?command=reference&path=proc%2Fif If] ===

Ifs default to checking for true if not otherwise stated. True is defined for all variable types as empty, 0 or non-existant (null).
  if(condition)
    action_true()
  else
    action_false()

==== Common variable behavior in if statements: ====
{|
!Variable type
!False when
!True when
|-
!String (text / ascii)
|"" or null
|Anything else
|-
!Int / Real
|0 or null
|Anything else
|-
!datum, atom
|null
|Anything else
|}

==== [http://www.byond.com/members/?command=reference&path=operator Logical operators] ====
Pretty standard:
  [http://www.byond.com/members/?command=reference&path=operator%2F%21 !statement1] //NOT statement1
  [http://www.byond.com/members/?command=reference&path=operator%2F%26%26 (statement1) && (statement2)] //statement1 AND statement2
  [http://www.byond.com/members/?command=reference&path=operator%2F%7C%7C (statement1) || (statement2)] //statement1 OR statement2
  [http://www.byond.com/members/?command=reference&path=operator%2F%3D%3D ==] //equals
  [http://www.byond.com/members/?command=reference&path=operator%2F%21%3D !=] //not equal
  [http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B <] ([http://www.byond.com/members/?command=reference&path=operator%2F%26lt%3B%3D <=]) //less (or equal)
  [http://www.byond.com/members/?command=reference&path=operator%2F%26gt%3B >] ([http://www.byond.com/members/?command=reference&path=operator%2F%26gt%3B%3D >=]) //more (or equal)
  [http://www.byond.com/members/?command=reference&path=operator%2F%26 &] //bitflag AND operator. 13 & 3 = 1 (1101 & 0011 = 0001)
  [http://www.byond.com/members/?command=reference&path=operator%2F%7C |] //bitflag OR operator. 13 | 3 = 15 (1101 | 0011 = 1111)

Byond does not recognize the === (identical) operator. More operators can be found in the left menu on the [http://www.byond.com/members/?command=reference&path=operator reference page]

=== [http://www.byond.com/members/?command=reference&path=proc%2Fwhile While] ===
Byond will cancel a loop if it reaches a certain number of iteration and give a runtime error out of fear of infinite loops. Same applies for recursions.
Same as anywhere else
  while(condition)
    action1()

All loops understand the [http://www.byond.com/members/?command=reference&path=proc%2Fcontinue continue] and [http://www.byond.com/members/?command=reference&path=proc%2Fbreak break] commands

=== For ===
All loops understand the [http://www.byond.com/members/?command=reference&path=proc%2Fcontinue continue] and [http://www.byond.com/members/?command=reference&path=proc%2Fbreak break] commands

For combines the for loop and foreach loop:
====  [http://www.byond.com/members/?command=reference&path=proc%2Ffor%2Floop For loop] ====
  for(var/i = 1; i <= 10; i++)
    [http://www.byond.com/members/?command=reference&path=world world] << i //Will write (each in a new line) 1 2 3 4 5 6 7 8 9 10

==== [http://www.byond.com/members/?command=reference&path=proc%2Ffor%2Flist For each] ====
  for(var/obj/item/weapon/baton/B [http://www.byond.com/members/?command=reference&path=operator%2Fin in] world)  //will iterate through world.contents (which contains all atoms in the world) and only pick those which are of the given type (/obj/item/weapon/baton)
    B.name = "Smelly baton" //Will apply the new name to the baton in the current iteration loop

=== [http://www.byond.com/members/?command=reference&path=proc%2Fdo Do - While] ===

The Do while operator is not commonly used in SS13 code, Byond does support it though.

  var/i = 3
  do
    world << i--
  while(i)

All loops understand the [http://www.byond.com/members/?command=reference&path=proc%2Fcontinue continue] and [http://www.byond.com/members/?command=reference&path=proc%2Fbreak break] commands

=== [http://www.byond.com/members/?command=reference&path=datum Defining objects] ===
Doesn't matter if you want a [http://www.byond.com/members/?command=reference&path=datum datum] or [http://www.byond.com/members/?command=reference&path=atom atom], the definition of objects is the same and simple:
  /obj/item/weapon/item1 //will nmake a new object of type obj.
    var/item_property = 5 //Will define a new variable type for all item1 objs
    name = "Testing Item" //The name var is already defined in parent objects so it is not defined here, but only assigned a new valie.
  
  /obj/item/weapon/item1/[http://www.byond.com/members/?command=reference&path=datum%2Fproc%2FNew New()] //Constructor proc
    [[#..()|..()]] //should always be present in New() procs, see [[#..()|..()]] for more information
    item_property = 3 //An action that is performed in the object constructor.

=== [http://www.byond.com/members/?command=reference&path=proc Procs] (Methods, functions, procedures) ===
You're used to the standards of methods, functions and procedures, right? Well procs ignore some aspects of these. They can best be compared to Java methods, as they're tied to specific objects. They cannot be defined as static, private, public, etc. tho. You can write static methods, however the compiler will not restrict you from calling them in a non-static way or environment. Same applies for non-static methods.

  proc/proc_name(var/argument1, var/argument2)
    [http://www.byond.com/members/?command=reference&path=world world] << "[argument1] [argument2]"

The above would declare a global proc. If you wish to tie it to a certain level

==== <tt>..()</tt> ====
: Reference manual: [http://www.byond.com/docs/ref/info.html#/proc/.. .. proc]

This is the same as super() in Java. It calls the parent object type's proc with the same name and same arguments.

Example:
  /obj/item
    name = "Item"
  
  /obj/item/New() //New() is the proc that gets called whenever a new object of this type is created. A constructor if you will.
    src.name = "It's an item!"
  
  /obj/item/stack
    name = "Stack"
  
  /obj/item/stack/New() 
    src.name = "It's a stack!"
    ..()

If you have the code from the example above and create a new object of type /obj/item/stack, it will first make the item in the game world with the name "Stack", because it's defined to be that by default. Then the New() proc will be called immedietally after. This will change the name to "It's a Stack!" but the call of the parent type's New() proc with the ..() command will then set it to "It's an item!". So in the end, the new object will be called "It's an item!". The ..() command is however very important in many cases as some things are defined only in the common parent's New() procs. In Del(), the proc which gets called prior to an object's deletion, it requires the code to get to the root Del() proc to even delete it. See examples of Del() in the code.

===== <tt>. = ..()</tt> =====
: Reference manual: [http://www.byond.com/docs/ref/info.html#/proc/var/. . var]

This line can be read as: set the <code>.</code> variable (the return value) equal to the result of calling <code>..()</code> (the parent proc).

<code>.</code> is a special variable that represents the return value of a proc. If control reaches the end of a proc, <code>.</code> is returned. Writing <code>return</code> with no value is like writing <code>return .</code>

<code>. = ..()</code> is used when a proc override should usually return the same thing that its parent does, for example in important system procs like <code>Initialize</code> or <code>Destroy</code>.