Reference

Symbol Basics

The symbols section is used to list variables and give them an initial value. It is not necessary to declare variables in the symbols, but it's considered to be bad syntax to leave out variable declarations. Each cog has a limit on the number of variables of each symbol type that it can store.

There are basically three types of variables: integer, flex, and vector. Sectors, things, surfaces, models, etc. are all integer numbers.

The symbols sections of cogs listed in the items.dat and the static.jkl are loaded only once when JK starts. They are not reloaded with every level. Cogs loaded by the level's JKL will be loaded every time the level is loaded. Also, the values of each cog's variables are stored until you exit JK entirely. When a variable is listed in the symbols section, it is given a value of zero by default.

If you declare two variables with the same name in the symbols section, only the first will be recognized. If you give a variable the same name as a Cog verb, that verb will not work in the cog.

A variable's type will be reset to match whatever type you assign it to. For example, if you define an integer in the symbols section and assign that integer to a vector value of '1 2 3', the integer will be turned into a vector to accommodate this new value.

You cannot define a variable in one cog and retrieve its value in another. Even though cog has a variable extension called "local," ommitting this extension will not allow you to access variables in other cogs.

Linking Symbols to a Level

If the cog is listed in the cogs section (not the cogscripts section) of a .jkl, the JKL can pass values to the variables in the symbols section. This is how JED gives values to variables in placed cogs. Here's an excerpt from the cogs section of a JKL:

  0: 00_door.cog 4 -1 -1 -1 8 2 0.5 
  1: 00_std_elev.cog 839 854 6 0.25 2 4   
  2: 01_funicularA.cog 12 1539 1550 8 4 2 4 
  3: 01_funicularB.cog 16 1748 8 4 2 4   
  4: 01_cargoelev2.cog 1919 21 2 2       
  5: 00_door.cog 23 -1 -1 -1 8 2 0.5 

The code below is from the first cog listed above, 00_door.cog:

symbols

message startup		
message activate	
message arrived		
message timer		
message blocked		

thing   door0     linkid=0 mask=0x405
thing   door1     linkid=1 mask=0x405
thing   door2     linkid=2 mask=0x405
thing   door3     linkid=3 mask=0x405

float   moveSpeed=8.0
float   sleepTime=2.0
float   lightValue=0.5

sector  doorSector       local

int     numDoors=0       local
int     doorStatus       local
int     moveStatus       local
int     i                local

end

The seven values listed in the JKL correspond to the seven variables in the symbols section without the "local" extension. The messages listed in the symbols are variables, but they are ignored when JK passes variable values from a JKL.

It is convenient to define level-specific things like the doors in the level so that simple cogs like 00_door become generic. This value-passing does not work with the static.jkl.

When an object's value is passed from a JKL, the cog will receive messages sent by that object. This is the only way to receive messages sent by sectors and surfaces.