Custom Object tutorial/Syntax issues and conventions

When creating SOCs, there are some basic rules that should be followed so that the SOC works as intended and is structured properly. Some of them must be followed or the SOC won't work at all, and others help to make the SOC easier to read and understand.

Freedoms

Your SOC blocks do not have to look exactly like the ones you saw in the last chapter. While not all of these differences are advisable, some of them can come in handy, and it's useful to know what is allowed in working SOC files.

• The order of the parameters is irrelevant. Both of these expressions will cause the same effect:

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase
Var1 = 0
Var2 = 0

State S_POSS_RUN1
SpriteFrame = A
Action = A_Chase
SpriteName = POSS
Var2 = 0
Duration = 3
Next = S_POSS_RUN2
Var1 = 0

• You can leave out parameters if their values are unused. Both of these expressions will cause the same effect:

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase
Var1 = 0
Var2 = 0

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase

• You can make as many paragraphs between text blocks as you want, or even none at all. Both of these expressions will cause the same effect:

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase
Var1 = 0
Var2 = 0
State S_POSS_RUN2
SpriteName = POSS
SpriteFrame = B
Duration = 3
Next = S_POSS_RUN3
Action = A_Chase
Var1 = 0
Var2 = 0

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase
Var1 = 0
Var2 = 0

State S_POSS_RUN2
SpriteName = POSS
SpriteFrame = B
Duration = 3
Next = S_POSS_RUN3
Action = A_Chase
Var1 = 0
Var2 = 0

• You can leave comments between text blocks. This will not bother the program, although it will display a warning if the comment doesn't begin with a "#" sign.

#This is a comment.

State S_POSS_RUN1
SpriteName = POSS
SpriteFrame = A
Duration = 3
Next = S_POSS_RUN2
Action = A_Chase
Var1 = 0
Var2 = 0

• You can change the order of the text blocks as you wish. It doesn't matter and makes no difference as long as each block itself is correct.
• You can ignore uppercase and lowercase. All of these expressions would work:
  • sPrIteNaMe = POSS
  • SPRITEname = POSS
  • spRIteNamE = POSS

Limitations

However, there are many things you are not allowed to do. Here are things you have to take care of:

• Each text block has to start with its correct header. Stuff like State S_POSS_STND, Object MT_BLUECRAWLA or Sound sfx_pop always has to be at the top of your text block.
• The character sequence of each text block's parameter must be correct, including the number of whitespaces. Things like StateS_POSS_STND or SpriteName= POSS will not work.
• Each text block's parameter line must end with the respective value, meaning that not even one whitespace may be written after it and before the next line.
• No extra paragraphs can be made inside text blocks.

Conventions

So far for the syntax issues. Even though you are allowed to write down your code in many different ways, some of them are not very advisable. Keeping in mind you might want to release some of your scripts in the future, you should give them a structure that is meaningful. Here are some conventions that are highly recommended to follow:

• Stick to the capitalization conventions used in this tutorial and elsewhere on the Wiki. They are easily readable and feel familiar to most other SOC makers.
• Start out comment lines with the "#" character. Other people immediately will recognize them as what they are supposed to be this way, and it prevents SRB2 from displaying a warning.
• There are some accepted aliases for headers and parameter names, such as Thing instead of Object and SpriteSubNumber instead of SpriteFrame. These only remain for backwards compatibility and should not be used anymore.
• Give your text blocks a certain structure or order. Separate state blocks from Object type blocks, and group states that follow each other together.
• Use comments to explain which Object types or state cycles have which task. Maybe even explain how some of your stuff works.