Notes on Print Verbs


Format Specifiers

Format specifiers are used by two of the concat verbs to insert values into a string. You can use different format specifiers to concatenate the value in a different form. Syntax:

%[-][+][ ][#][0][width][.size][prefix]specifier

[-] Optional. Add the minus sign to make the value align to the left inside the width. The default alignment is to the right.

[+] Optional. If used with a specifier that works with signed numbers, the '+' sign will be put before positive numbers to show their positivity.

[ ] Optional. If used with a specifier that works with signed numbers, numbers outputted with no sign will have a space put before them.

[#] Optional. Octal numbers will be prefixed with a 0, and hex numbers will be prefixed with a 0x. When used with flex specifiers, a decimal point will always be outputted.

[0] Optional. When used, all of the width's digits to the left of the number will be ouputted as zeros instead of being left blank.

[width] Optional. This sets the minimum width for the concatenated value. All of the value's significant digits will be outputted though this may exceed the width.

[.size] Optional. For integer specifiers, this is the minimum size for the number. For flex specifiers (other than %g), this is the number of decimal digits to output (default of six). Size digits unused by the value will be outputted as zeros.

[prefix] Optional. This is a specifier prefix used to modify the output value type. These prefixes are of little use to Cog, because the concat verbs' parameters have set types. Refer to the chart below.

specifier This is the format specifier to use. The charts below show which specifiers are used by integers and flexes.

Specifier Prefixes
PrefixFormat
lLongint or double.
LLong double.
hShortint.

Integer Format Specifiers
SpecifierFormat
%cASCII character.
%dSigned decimal integer.
%iSigned decimal integer.
%oUnsigned octal integer.
%uUnsigned decimal integer.
%x, %XUnsigned hexadecimal integer.
%%'%' character.

Flex Format Specifiers
SpecifierFormat
%e, %ESigned decimal flex in scientific notation.
%g, %GSigned decimal flex in short form.
%fSigned decimal flex.

Specifiers that are "unsigned" do not accept negative values. Using an unsigned specifier with a signed value will cause the engine to output meaningless numbers.

These format specifiers are from Visual C++, they are not part of Cog. Cog is able to use them because the concat verbs pass the string and argument to the VC++ engine.

In doing that, format specifiers lose some of the their functionality because Cog cannot pass more than those two arguments. The above description of the syntax and use of the specifiers has been somewhat simplified because the excluded information doesn't apply to Cog's use of the specifiers.

Concatenation

To concatenate is to link together. In Cog, concatenation refers to linking values together into a string that is printed with jkStringOutput(). When you concatenate a value, JK adds it to the end of a stored string. jkStringClear() clears the stored string for a new series of concatenations. Each computer has its own concatenated string.

Here's an example of concat verbs in use:

jkStringClear();
jkStringConcatAsciiString("The number of players in this game is: ");
jkStringConcatInt(GetNumPlayers());
jkStringOutput(-3, -1);
Notice in that example that jkStringClear() is run before the concatenation. Even after the string has been outputted, it is still in memory. But because all concatenation code in cog clears the string before the concatenation, this will not cause problems.

Strings

A string, in programming terms, is a collection of letters, numbers, and odd characters which is enclosed by quotation marks when written. There is no string symbol type to store a string with, but JK does store one string for concatenation. Uni files store generic strings. The two uni files that can be accessed by cog are jkstrings.uni and cogstrings.uni.

The jkstrings.uni holds strings that will be used during normal gameplay in any level. Strings like "Using Bacta" and "Fists" are stored in this file. Cogstrings.uni is a level file that holds the strings that are to be used by an episode. "Locked!" and "This looks interesting!" come from the cogstrings of The Force Within.

In both of these files, strings are defined like this: "COG_x" 0 "string" - where x is the number of the string. It is this number that cog verbs use to locate the string. If you give a verb the number to a string that does not exist, you'll see "COG_yourNum" print on the screen.

Destinations

Output Destinations
DestinationPlayer that receives the message:
0, 1, 2, etc.If there's a player with the thingref of this dest, the message is sent to him. Otherwise, it's local.
-1Local player.
-2Unknown.
-3Everyone.

Debugging

The print verbs are the most useful tools for debugging. Print() can tell you if a message runs, and PrintFlex() can print variable values. When you have a problem with a cog, one of the first things you should do is print something. The print verbs (not the concat verbs) were most likely created just for debugging purposes.