Reference

The COG Scripting Language is an event-driven imperative scripting language designed to help level designers write simple interactivity without requiring extensive programming experience. While COG was initially developed as an incremental improvement over the INF Scripting Language used in Dark Forces, COG quickly grew into a more complete language as the level designers continued to request more advanced features.

In addition to the COG implementation provided in Jedi Knight and Mysteries of the Sith, an independently-developed COG Virtual Machine has been written and released under the GNU General Public License as a part of the Sith 2 Project.

Basic Grammar

At a fundamental level, COG scripts consist of two separate and distinct sections: the first, the symbols section, describes variables that can be manipulated during the execution of the script; the second, the code section, which contains executable information in the form of a C-like compound statement. An example outline follows:

# Comments

symbols
[Symbol List]
end

code
[Compound Statement]
end

Symbols Section

The symbols section is nothing more than a list of variables described by their type followed by their name, optionally including a default value and a list of extensions. It begins with the keyword symbols and ends with end.

# Example outlines
[type] [name]
[type] [name] [extension] [extension]
[type] [name]=[value]

Valid symbol types include numeric and logical types:

• Flex - Generic type that encompasses both integers and floating points.
• Float - Standard floating point.
• Int - Standard integer.
• Vector - Array of 3 floating points, generally representing position or orientation in 3-space.
• Bool - Logical true/false Boolean type. Extended COG only

Resource file types:

• AI - .ai/.ai2 file.
• Cog - Reference to a COG script.
• Keyframe - Animation file.
• Material - Texture.
• Model - 3DO.
• Sound - Sound file.

Engine constructs:

• Sector - A convex polyhedron representing a negative space enclosure.
• Surface - Any polygon in the level geometry.
• Template - Properties and behaviors of a thing.
• Thing - Entities or other interactive objects.

And internal symbols that cannot carry a conventional value:

• Message - Contains an instruction offset within the compiled script.
• String - Contains a pointer to ASCII text. Extended COG only

Extensions are used to apply specific properties to symbols. There are five extensions recognized by COG:

• local is the most common extension and it is used to prevent level placements from altering the default value.
• desc is used as a simple comment that can be displayed within a level editing program.
• linkid assigns a numeric value to the symbol that can be checked when a message is recieved.
• nolink prevents the script from recieving messages from the designated symbol.
• mask offers fine control over the types of messages that are recieved from a symbol.

An example symbols section follows:

# Start symbols section
symbols

# Messages must be specified in the symbols section
# or they cannot be recieved by the COG
message startup

# Define an integer and assign it a value
int i=3

# Define a local thing
thing player local desc=local_player_thing

# End symbols section
end

Code Section

Similar to the symbols section, the code section begins with the keyword code and ends with end. The code section contains a single C-style compound statement with messages indicated by C-style label statements.

Examples

# "Hello, World" Example COG

symbols

message startup

end

code

startup:
print("Hello, World!");
return;
end

# "Hello, World" Over and Over Again

symbols

message startup
message pulse

int max_print=20
int printed=0 local

end

code

pulse:
if(printed == max_print)
{
     SetPulse(0);
     return;
}
else
{
     printed = printed + 1;
     print("Hello, World");
     return;
}

startup:
SetPulse(5);
return;

end

Criticisms

The COG Language is not without fault. Over the years several incorrect design decisions have become rather grating. For instance, the symbols section is context-sensitive and requires complex two-stage parsing when a slightly different grammar could be parsed much more easily and efficiently in a single stage by a pregenerated component.

Extended COG

In 2005 an independently-developed COG Virtual Machine was released as part of the Sith 2 Project. Although it faithfully emulates the original COG scripts provided with Jedi Knight and Mysteries of the Sith it also offers several of its own advancements.

• Bool and String symbol types.
• Prefix and suffix incrementation operators (++, --)
• Full set of assignment operators (+=, -=, *=, ...)
• Modulus operator.
• Symbols section is optional.