On this page, I'm going to explain how to declare and use the different types of variables that JK uses. For more technical information on variable types, look in the Symbol Types section of this reference.
int yourInt=1int is short for integer. With every variable that you define, the variable's type will come first. Next is the variable's name - in this case, yourInt. In this declaration, the integer is given an initial value of 1. You can also add arguments after the declaration which tell JK how to use the variable - we'll cover that later on this page.
JK has two floating point types: float and flex. Apparently, both types are exactly the same. Float is the standard programming term, but flex is more commonly used in Cog. Their declarations look like this:
float yourFloat=1.1 flex yourFlex=1.2Floats are most often used to store physics variables like speed, mass, and vector axes.
template yourTemp=+tempNameA template contains an integer value. This integer is the template's number in its JKL's listing. For the static.jkl, there is an offset number that's added to the list number.
vector yourVecA vector's value can be expressed in several different ways, but when passing a value from a JKL, you'll use the form
(x/y/z)
.
ai yourAI=example.ai material yourMat=example.mat sound yourSound=example.wav keyframe yourKey=example.key model yourModel=example.3doNotice that no path is given. JK will look for these files in their respective resource subfolders. All of these variable types contain integer values. This value will be the number of the resource in its JKL's list for that file type. In some cases, JK will add a resource that's not already in the JKL's list.
cog yourCog
message startupMessage variables must be given message names (refer the the Messages Section for a listing). Like most variables, messages hold integer values, but these values are set within JK's executable. Messages are only declared so that JK will see the declarations, you can tell by printing the value of an undeclared message that the cog already knows what a message's value is.
thing yourThingThings have integer values - the number of the thing in the thing list. You can give them initial values just like integers, but it's not that helpful from the cog itself. A thing that's already placed in the level should be left open for the level's JKL to define.
surface yourSurfSurfaces should be left open for the level to define.
sector yourSecSectors should be left open for the level to define.
symbols thing myThing message created endAnd the cog's listing in the level JKL looks like this:
Section: cogs World cogs 10 #Num Script Symbol values 0: yourCog.cog 18 endThe value of 18 is being passed to the variable myThing. So when the level finishes loading, myThing will have a value of 18. This is how the level defines variables.
When the level passes a thing, sector, or surface value to one of its cogs, it associates the cog with that object. In our example above, yourCog will receive the created message from myThing.
If you don't want to define a variable in the JKL, or you do but don't want to receive its events, you'll need to add symbol extensions after your variable.
Desc serves only to add commenting to a variable. A typical use would look like:
thing myThing desc=this_is_my_thingJK won't complain either way, but it's considered bad syntax to have spaces or special characters in the description.
Local is the most common extension used in cog. This extension tells JK that the variable will not be given a value by the JKL. For example, let's say your symbols looks like this:
symbols thing myThing int myVar local thing myOtherThing message created endAnd your JKL looks like this:
Section: cogs World cogs 10 #Num Script Symbol values 0: yourCog.cog 18 20 endmyThing will be given a value of 18, and myOtherThing will be given the value of 20. Because myVar had the local extension, JK skipped over it when it assigned the JKL's values.
Mask is used to limit the events that the cog receives from a thing. All events have source and a sender. The source is the thing that caused the event. And the sender is the thing that the event happened to. When the event happens to the sender, it will send a message out to its cogs telling them what's happened. The message includes the thing that caused the event - the source.
Mask Flags are used to block messages that have irrelevant sources. Let's say you want your cog to listen for the touched event of a thing so that your cog can do something when the thing is shot. If the thing is touched by the player, you don't want him to do anything. Instead of adding extra code to your cog to make sure the source of the touched event is a laser, you can use mask flags to block out events caused by players.
For this example, the declaration would look like:
thing myThing mask=0x8Flags have not been covered yet, so it's ok if 0x8 makes no sense. The 0x8 flag tells JK that only the cog will only receive messages of events that were caused by a weapon. If we wanted the reverse - if we wanted only events caused by the player and nothing else, the flag would be 0x400. If we wanted both players and weapons, the flag would be 0x408.
Remember that there are default masks for things, sectors, and surfaces. These are explained in the symbols documentation. By using the mask extension, you are overriding this default. To receive all the messages that a thing sends, use a flag of 0xfff.
Linkid is used to make a group out of a bunch of symbols so that it's easier to refer to them in the code section. A declaration looks like:
thing myThing linkid=1 thing myOtherThing linkid=1Then in the code section, you'd be able to refer to all the objects that have a linkid of 1 instead of having to write the variable name of every one of the objects in your group.
Nolink is used when you want to define a thing in the JKL, but you don't want to listen to any of its events. Its declaration looks like:
thing myThing nolinkRemember that all of these symbol extensions are only useful in level cogs. To class and inventory cogs, these are useless. However, it's considered proper syntax to add local to all of a class or inventory cog's variables. This is a way of telling the reader that all of the variables are being defined within the cog.
Another common method is to use underscores: one_word_two_word and red_fish_blue_fish. In the author's opinion, this is worse because underscores make you type out more characters, and you get more typos trying to shift-hit the underscore key.
A constant is a variable that's given a value in the symbols section and never changed in the code section. To make it clear that a constant shouldn't have its value changed, many programmers use all capital letters: ONEWORDTWOWORD and REDFISHBLUEFISH. This is a good rule to follow, but it can be an eyesore.
Keywords, symbol types, and symbol extensions are most often written with lowercase letters. Some programmers prefer to capitalize the first letter, but it's just not worth your time for keywords that you'll use in most of your cogs.
There are memory limits to how many variables you can have in the symbols section. It's not known how these limits work, but declaring your variables can solve some memory problems.