We'll begin with the infamous Hello World:
# HelloWorld.cog # # Print "Hello World" on the screen when the level starts. # # [SM] #==============================================# symbols message startup end #==============================================# code #----------------------------------- startup: Sleep(1); Print("Hello World"); // Print the string Return; #----------------------------------- endWhen this cog is run, "Hello World" will appear at the top of the screen when a level is loaded.
The first section is the optional header. The pound sign is used at the beggining of each line so the engine will not read the rest of the line. The header usually lists the name of the cog, a description, and the author.
The second section is the symbols section. It defines all of the variables and messages to be used in the code section.
The third section is the code section. The code section performs the actual work of the cog. Notice that the symbols and code sections begin with their name and end with an end.
The two Cog verbs used in that example were Sleep() and Print(). Sleep() was used to pause the code execution for one second because startup runs just before the level starts. The Print() command prints a string to the screen.
The message, startup, is listed in the symbols section so the engine will look through the code section for startup. The engine will process all code after the startup message until it hits a "return;" command which tells it to stop.
The double slashes after the print command is another comment marker used by cog. It works the same way as the pound sign, but remember that double-slash comments cannot be used outside of the code or symbols sections. If they are, they will be treated by JK as a syntax error and the cog will not function.
Notice the syntax of this example. Each statement ends with a semicolon. Messages in the code section have a colon after them. The parameters of the two verbs used are enclosed in parentheses.
Here's an example of how variables are declared in the symbols section:
symbols flex real1 local float real2 int integer message startup endA symbol declaration has three parts. The first is the type of variable you're defining. The second part is the name of the variable. The third part is an optional extension for the variable. All variables to be used in the code section should be defined in the symbols section.
Here's an example of assigning values to variables and printing them:
int1=5; int2=10; int3=2; int4=int1 * int2 / int3; PrintFlex(int4);Int1, int2, and int3 are assigned to three integer numbers with the assignment operator (=). Int4 is assigned to an expression. The expression returns a value which is then assigned to int4. Anything that returns a value can be thought of as an expression.
The mathmatical expression is processed before the assignment because the multiplication and division operators have higher precedence than the assignment operator (read the Operators document for a chart showing the precedence of Cog's operators). The last line in the example prints the value of int4 (25) to the screen.
if(integer >= 5) { SetTimer(5); } else { SetTimer(1); }This example is easy enough to read. A different action is performed depending on the value of integer. When only one statement is performed by a conditional statement, you don't have to use the brackets to mark a new code block. This example will give the same results and save a few lines:
if(integer >= 5) SetTimer(5); else SetTimer(1);Notice that the conditional statement itself does not end with a semicolon. But the statements after the if statement must end with a semicolon.
For more on conditional statements, read the Conditions tutorial.
Another type of message is the custom message. Here's an example:
# HelloWorld.cog # # Print "Hello World" on the screen when the level starts. # # [SM] #==============================================# symbols message startup end #==============================================# code #----------------------------------- startup: Sleep(1); call printtext; Return; #----------------------------------- printtext: Print("Hello World"); Return; #----------------------------------- endThe custom message in this example is printtext. Notice that it does not have to be defined in the symbols section. The call keyword is used to run custom messages, because the engine will normally ignore them.
SetTimerEx(0.5, 1, 0, 0);Each verb has its own set of parameters. These parameters are values that are passed to the verb so that the verb can perform its action. You can use variables, expressions, and other cog verbs as parameters. For example:
SetTimerEx(0.5, 1, GetSenderRef(), GetSourceRef());The verbs GetSenderRef() and GetSourceRef() both return values. These values are then given to SetTimerEx().
Read the Cog Verb document for more information related to verbs.
startup: Sleep(1); Print("Hello World"); // Print the string Return;Notice that the two statements from Hello World have been put on one line. Here is another version of the conditional statement example:
if(integer >= 5) SetTimer(5); else SetTimer(1);The if statement and the else statement can be put on the same line. But if you put two statements on the same line without a semicolon for each, you will get a syntax error and your cog will not run.