How To Cog - Chapter 2.4 - Cog Code

With the Variables tutorial, you learned most of what you need to know about the symbols section. Coding, however, is a lot more diverse. So in this tutorial, I'm going to give a general explanation of everything the code section does. Then in the more advanced tutorials, we'll cover some of the same topics in a lot more detail.

Message Handling

When we refer to messages in the symbols section, they're just variables that need to be declared. Messages in the code section are much different. When something specific happens in the game - when an event occurs - a message is sent by JK to any cogs that are listening for it. JK looks in the event object's associated cogs to see if they're listening for messages about that kind of event. If a cog is listening, then JK will look in that cog's code section for a label to start code execution. A typical message handler in the code section looks like this:

startup:
	// do something

return;

Although some commonly refer to a block of code beginning with a message name and ending with a return as a "message," this is a misuse of the term. It should be called a message handler. The message itself is what JK sends to the cog. The cog's code will "handle" that message. A message name ended with a colon in the code section is called a label. Labels are like starting points in the code section. JK will start executing code right after a label and stop executing when the return command is given or when JK reaches the end of the cog.

The engine is not the only thing that can send messages. There are commands that we can use to send messages to cogs the same way the engine does.

Statements

A statement can be loosely defined as the syntax needed to form a complete command. In the next few sections, you'll learn about assignments, loops, and conditions. These are all statements usually ending with a semicolon.

Operations

An operation is one of the most basic things that Cog does. Operations involve operators and operands (pretty basic, huh). An operator is symbol representing the type of operation to be performed - e.g., addition or multiplication. An operand is the value (or variable) on which the operation will be performed - e.g., 1 or var1. An assignment is an operation which looks like this:

  var2 = var1;

The '=' is the operator and var1 and var2 are the operands. The semicolon at the end marks the end of the statement. Here's a more complicated example:

  var2 = var1 * var3;

Here there are two operations: the assignment of var2 and the multiplication of var1 and var3. The multiplication has a higher precedence and will be performed first. Then JK will assign var2 to the resulting value.

You'll see operations used in many places throughout cog. In any place in the code section that you can input a value, you can give an equation, a variable, or a function that returns a value (covered later).

Keywords

Keywords are special, reserved words that JK will look for in your code. You've already seen how "return" works to end code execution, and how "end" ends both the code and symbols sections. Other common keywords include if, for, while, do, else, and call. These will be covered later.

Verbs

Cog's verbs are the commands that do the work in JK. You can refer to any Cog command as a "verb," but there are two different types. Some verbs return a value, and in "real" languages could be called a function. Verbs that do not return a value could be called procedures.

A typical procedure will look like this:

  DoSomething();

The procedure has a name, followed by a set of parentheses to enclose its parameters, and then a semicolon to end the command. The standard naming convention for verbs is camel-hump notation with the first letter capitalized.

All verbs use a set of parentheses to enclose their parameters. A parameter is an allotted space for an argument (variable or value) to be passed to the verb. When an argument is passed to a verb, the verb will use that value to perform whatever command it is meant to do. A parameter is only a space for a type of variable, while an arguments is the value or variable that is passed. The example procedure above has no parameters, but it needs the parentheses. This procedure has three parameters:

  DoSomethingMore(1, 2, var3);

The first two arguments are given directly as integer values, but the third argument is a variable. The value of this variable will be used by the procedure - the variable will not be changed (known as passing by value). Verbs can form a complete statement and end with a semicolon.

A function works much the same as a procedure, but the function will return a value to any variable assigned to it. A typical function will look like:

  myVar = ReturnSomething();

The function doesn't need to have a variable assigned to it. Although it's considered bad syntax, you can leave out the variable assignment and the function will work the same as a procedure.

When cog reads a verb's parameters, it will start from the right and go to the left. Cog will ignore any extra parameters on the left, and any ones not entered will have a default value of -1. It's not bad syntax to leave out arguments if they should be given the default value.

Code Blocks

In some cases you'll need to group a bunch of statements together so you can treat all of the statements as a group. These are groups are called code blocks and are mainly used with conditional statements. You can create a code block by writing an opening curly bracket just before the first statement and a closing curly bracket after the last statement's semicolon. Here's an example:

startup:
	statement1;
	{
		statement2;
		statement3;
	}
	statement4;

Return;

Statements 1 and 4 are outside of the block, and statements 2 and 3 are inside. The example above is properly indented, but this is not a syntax requirement. This last example will look the same as the first to JK:

startup:
	statement1;
	{statement2;statement3;}
	statement4;
Return;


Previous: Variables Up: How To Cog Next: Conditions
  • Create:
This page was last modified 15:44, 14 April 2006.   This page has been accessed 1,483 times.