How To Cog - Chapter 2.2 - Cog Structure

Hello World

Now it's time to start looking at how cog files are put together. Almost every language has someway of addressing the human world. Cog is no exception. This tutorial will proudly continue with the tradition of starting 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;
#-----------------------------------
end

All this cog does is print "Hello World" to the screen when a level is loaded. The first command in the code section is Sleep(1). This tells the cog to wait for one second before continuing. The next command is Print("Hello World"). This prints the text to the screen. And the last command is return which tells JK to stop executing commands.

Comments

When JK reads a cog, it will ignore any text to the right of a pound sign or two forward slashes. This gives you a way to add comments to your code. You can use the pound sign anywhere in both the symbols and code sections (explained below), but the forward slashes can only be used in the code section. Otherwise, there's no difference between them.

Comments are added to a cog to either improve its structure or to explain what a command is doing. Comments can visually improve a cog's structure so that it's easier to see where one part of a cog ends and another begins - this is done in the cog above with pound signs and dashes.

Other comments explain something that isn't obvious when read. Even if you're working on a cog that only you will use, you should still write comments for yourself. While you're actively working on a cog, you'll remember everthing and the comments will seem useless. But if you take a break for a week or two, you will be thankful those comments are there.

The Header

A header is a bunch of comments that come before the symbols section to give the reader some basic information about the cog such as the file name, purpose, and author. It might also contain the cog's version, a history of its updates, and the date it was last updated. The header is optional, but every cog you write should have one.

Symbols Section

The symbols section begins with the keyword "symbols" and ends with the keyword "end." In the symbols section, every variable that the cog uses will be defined and optionally given an initial value.

Code Section

The code section contains all of the commands that a cog can perform. When an event happens in a game, a message is sent out to associated cogs. If the cogs are listening for that message (if they have it declared in their symbols section), then JK will look for that message's name in the code section and execute any code that comes after it until it finds a return command.

You're given a lot of freedom when it comes to whitespace (spaces, tabs, and line breaks) in the code section. With the symbols section, each variable declaration must be on its own line. But JK allows you to write everything between "code" and "end" on one line if you want. Even so, you should always try to make your code as readable as possible - with lots of comments and good indentation.


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