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
orSound 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
orSpriteName= 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 ofObject
andSpriteSubNumber
instead ofSpriteFrame
. 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.