NAME

Cual is the main language used to describe the animations in cuyo. Strictly speaking it's the stuff between the << >> brackets in the level description files (xxx.ld).

On the other hand this man page aims at being a complete description of how to write levels for cuyo. But it's still under construction. See the file "example.ld" to get an idea of how the rest of the level description works. There's also a bit of example Cual code in "example.ld". And of course, all the existing levels are examples.

Note that Cual is probably still very buggy. So if strange things happen and you're sure it's not your fault, tell me (cuyo@karimmi.de).

HOW IT WORKS

A section is defined by name = {contents}. name is the name of the new section and contents contains the definitions that pertain to that section. This is a sequence of definitions of the form name = stuff. Here stuff can be {contents} as above, or it can be a single datum, or it can be a comma-separated list of data. Inside such a list, datum * number can be used as a shorthand for datum, ..., datum, i.e. a number-fold repetition of datum. A datum can be an identifier, a string (enclosed by '"'), a word, or a number. In place of a number <expression> can be used, where expression is an arbitrary expression made up from literal numbers, previously defined numeric data, and the operators +, -, *, / and %.

Definitions can also depend on versions. See section VERSIONING below.

Apart from definitions, a section can also contain cual definitions (see below). These have to be enclosed in << and >>.

Each blob has its own (main) Cual procedure which does the drawing and the animation stuff. The procedure only depends on the kind of the blob, that is, it is the same for blobs of the same kind. However each blob has its own instance of the variables.

In every game step, the procedure of each of the blobs is called once. (There are 12.5 game steps per second.) It has to draw the blob each time, even if nothing has changed. (However, there's an internal routine in cuyo which checks if the same is drawn as in the last step and which then supresses the drawing.)

There may be other procedures associated to a kind of blob, which are executed at special events, for example when a falling blob lands. In contrast to the main procedure, these event handlers are not allowed to draw anything. See section EVENT HANDLERS for a list of the existing events.

The name of the main procedure of a blob (the one which draws the blob) is the name of the kind of the blob. Normally, that name is the word listed after pics= entry in the .ld file; but if that "word" contains a dot, only the part before the dot makes up the name. (E. g. with pics=redblob.xpm,greenblob.xpm, the names are "redblob" and "greenblob".)

The name of an event handler procedure is the name of the kind, followed by a dot, followed by the event name. (E.g. "redblob.land" for the landing event of the redblob from above.)

[Explain the default procedures.]

LEVEL DATA

KIND DATA

numexplode, neighbours

Defining these data in the section of a kind overrides the level-wide value for the kind. See section LEVEL DATA for a description of these data.

pics

A list of file names of pictures to be used for this kind. The nth entry can later be accessed in cual with file=n-1.

colourprob

The probability that this kind appears as one of the two steered falling blobs. More precisely, this is a nonnegative integer weight. For determining the actual probability, the value is divided by the sum of the colourprobs of all kinds. This sum must be positive. The default is 1 for kinds declared with pics= and 0 for all other kinds. The probability is also used for + in startdist. For more details see section STARTDIST.

goalprob

This affects the semantics of * in startdist in the same way, as colourprob does for +. The default is 1 for kinds declared with startpic= and 0 for all other kinds.

greyprob

The probability that this kind appears as a grey blob. This is similar to colourprob, but there is a difference: For greyprob, nogreyprob is included in the sum, so that it might happen that no blob appears at all. There is a notable difference between a positive nogreyprob and a positive greyprob in kind nothing, when several lines of grey blobs appear: In the latter case, empty blobs appear in the wall of greys, making holes. In the former case, the wall is made less high. Usually this is preferable. The default is 1 for kinds declared with greypic= and 0 for all other kinds. The value also affects the semantics of - in startdist. In this case, nogreyprob is not included in the sum.

versions

At the creation of a blob, its version variable is initialized. Usually, it is chosen at random from 0 to versions-1, but startdist provides the possibility to specify it exactly. See section STARTDIST for details. The default is 1.

distkey

An alphanumerical key, which is used in startdist to identify this kind of blob. The default is A for kinds declared with startpic and undefined for all other kinds. See section STARTDIST for details.

CUAL DEFINITIONS

procname = code ;

Defines a "procedure". The next section describes how code looks like. Example:

var varname1 [= def1 [: reapply]], varname2 [= def2 [: reapply]], ... ;

Defines variables with default values. If no default is specified, zero is used. See section VARIABLES AND CONSTANTS about the meaning of the default value and the optional suffix : reapply.

default varname1 = def1 [: reapply], varname2 = def2 [: reapply], ... ;

Changes the default for already defined variables. Again, the suffix : reapply is optional. This is useful to give to a single kind a different default for a variable than to the other kinds. Also, the default of a system variable can be changed this way.

CODE

{ code; code; ...}

Executes one command after the other.

code, code, ...

This is useful for simple animations. Executes exactly one of the commands: In the n-th call, the n-th command is executed. After the last command, the first one is executed again. However, if one of the commands is "busy" (see section BUSIENESS), this one will be executed until it stops being busy, and only after that, the next command will be executed.

procname

Executes the procedure procname, which has to be already defined. The result is the same as if the code from procname would have been inserted in that place.

&procname

Executes the procedure procname; however, every instance of such a procname is the same. This concerns busieness and the state of an animation sequence. (See sections BUSIENESS and AMPERSAND-CALL.)

busy

Does nothing except being busy. (See section BUSIENESS.)

varname = expr

Sets the variable. See section VARIABLES AND CONSTANTS for details.

The same with +=, -=, *=, /=, %=, .+=, .-=.

Does what you would expect.

[ varname = expr ] code

Sets the variable varname to expr, executes code and then resets the variable to the old value.

number

A shortcut for file = number.

letter

A shortcut for pos = number, where different letters mean different numbers: A: 0, B: 1, ..., Z: 25, a: 26, ..., z: 51

*

Draw the icon specified by the variables kind, file and pos. May also draw only a part of the icon, if specified by the variable qu (see section VARIABLES AND CONSTANTS).

*@(position)

Like *, but draws the icon at some other position. This drawing is performed after all drawing by *. If *@ is used from several blobs, the further order of drawing is not specified. It is guaranteed, however, that at any given time this order is the same for all positions. (See section VARIABLES AND CONSTANTS for more details about @.)

@(position)*

Like *, but draws the icon at some other position. This drawing is performed before all drawing by *. If @* is used from several blobs, the further order of drawing is not specified. It is guaranteed, however, that at any given time this order is the same for all positions. (See section VARIABLES AND CONSTANTS for more details about @.)

if expr if-arrow if-code ;

if expr if-arrow if-code else [else-arrow] else-code ;

The arrows can be either "->" or "=>". If you use "->" arrows, it does exactly what you would expect. If the if-arrow is "=>", then once the expression gets true, the if-code will be executed every subsequent time (without testing the condition), as long as it is "busy". For more details see section BUSIENESS. If the else-arrow is "=>", then once the expression gets false, the else-code will be executed every subsequent time as long as it is busy. The else-arrow may only be omitted, if the if-arrow is "->". Then the else-arrow also is "->". (But this might change in the future.)

switch {

  expr1 arrow1 code1 ;

  expr2 arrow2 code2 ;

  ...

}

The arrows can be either "->" or "=>". Does the same as:

bonus(expr)

The player gets expr bonus points.

message(String)

The string is displayed (blinking) on the screen. To be used together with bonus(...). Example:

explode

Makes the blob explode. For the next 8 steps or so, the blob is still what it was before, but the explosion is drawn over the graphics. After that, it's changed to a nothing-blob.

lose

The players immediately lose the level.

sound(Filename)

Plays the given sound file.

You can also omit the code completely. Then, of course, it does not do anything. This can be useful as part of ,-sequences.

There's a shortcut for drawing: You may omit the ";" between a number, a letter and the "*".

EXPRESSIONS

Of course, variables, constants and numbers are expressions, and you can use parentheses. There are the following operators (listed here in order of increasing precedence):

/ and % work mathematically correct and do not make funny changes when the sign of the numerator changes. More specifically, if b is positive, then a/b is the largest integer n such that n*b<=a. If b is negative, then a/b is the largest integer n such that n*b>=a. In both cases a %b is such that (a/b)* b+a%b = a. Examples:

The following are the special operators:

expr1 == expr2 .. expr3

Is true, if expr1 lies between expr2 and expr3. You may also omit one of expr2 and expr3. (Then, it does the same as <= resp. >=.) The precedence implies that x==y==2..3 is the same as x==(y==2..3) and is neither (x==y)==2..3 nor x==(y==2)..3. Note that this operator might change in the future. (I plan to make something like "expr in set" in Pascal.)

expr1 : expr2

Is true (that is, 1) with probability expr1/expr2

neighbour_pattern

neighbour_pattern is a sequence of six or eight characters 0, 1 and ?. It is true if the sequence fits to the neighbour sequence of the blob. The neighbour sequence is a string of "0"s and "1"s with a "1" for each neighbour of the same kind, starting above and going clockwise. This way, you get a string of "0"s and "1"s (six or eight, depending on wether this level is in hex mode).

The following functions exist:

rnd(expr)

Returns a random value between 0 and expr-1

gcd(expr1, expr2)

Returns the greatest common divisor of expr1 and expr2

VARIABLES AND CONSTANTS

—

User defined variables (see section CUAL DEFINITIONS). At the start of the level (or at the creation of the blob) the value is the default value you provided. If you supplied the default with : reapply, whenever a blob's kind changes, the value of the variable is also set to the default of the new kind. There is a subtlety: This only happens if the new value of kind is in fact different from the old one.

—

System variables. These variables are always defined and have special meanings, e.g. file and pos. Some of them are read-only.

—

User defined constants. These are defined in the main .ld part, not in cual (not inside << >>).

—

System constants. Some of them depend on properties of the level, some are really constant.

Of each variable, there's one instance in each blob. Normally, you access the instance in your own blob, but with the following syntax, you can access variables of other blops:

varname@@(x, y; side) varname@@(x; side) varname@@(; side) varname@(dx, dy; side) varname@(dx; side) varname@()

If x and y are given, these are absolute coordinates in the grid of blops, that is the variable is taken from the blob with loc_x=x and loc_y=y (see under The system variables). If only x is given, it specifies one of the two blobs that are currently falling. If there is only one such blob left, because the other one got stuck on some tower, the remaining blob's coordinate is 0. Otherwise one of the two has coordinate 0, the other 1.

In the @ variants, the coordinates are relative to the current blob. The variant @@(; side) refers to the semiglobal blob, the variant @() to the global blob (See section THE GLOBAL BLOB). The extra part ; side is optional and specifies the side of the game. This is only meaningful in two-player mode. side = < specifies the left player, side = > the right player, side = = the player to which the current blob pertains, and side = ! the other player. @() and @@() can also be given as @ respectively @@.

This can be done for both, reading and writing variables. It also works for system variables (but not for constants).

In hex mode levels, for odd dx, dy should be a "half integer", that is a number ending in ".5". This is the only place in Cual where non-integers appear. Especially, ".5" is not allowed in composite expressions. Therefore, also integer dy is always allowed. If a half-integer is expected and an integer is given, it is assumed to be rounded to above, that is 5 then represents 4.5 and -5 represents -5.5.

Caution: With mirror=1 the absolute and the relative coordinates use different coordinate systems. Handle with extreme care.

Accessing foreign variables is not as easy as it might look at first glance; it might easily introduce a dependence of the internal order of execution of the blob codes. For this reason,

—

reading variables with @ or @@ always returns the value of the variable it had at the beginning of the current step, that is, before any of the blob codes has been executed.

—

when writing variables with @ or @@, the write operation will only be executed at the end of the current step. (The write operations are stored in a kind of queue.)

This is also true if a blob accesses its own variables with @(0,0).

The operators +=, -=, etc. are also performed in the future if the left hand side is an @-variable. (To be more precice, the right hand side is calculated instantanousely.)

For illustration, look at the following six statements:

Only 1) and 3) do the same; they simply increment X by 1. Statement 4) sets X to one more than it was at the beginning of the step. Statements 2), 5) and 6) cause the value of X to be changed in the future (after the current step): X is set to one more than:

2)

the value of X just before the change (that is, X is incremented in the future),

5)

the current value of X,

6)

the value of X at the beginning of the step.

VERSIONING

This is done by qualifiing a definition with the versions it should apply to. It is best explained by an example:

numexplode = 8 numexplode[2] = 6 numexplode[1,hard] = 10

This specifies that normally numexplode should be 8. In two-player mode it should be 6. In one-player hard mode it should be 10. Here the specifiers 2 for two-player mode, 1 for one-player mode and hard for hard mode are used. Along with easy for easy mode these are all predefined specifiers intended for levels. Additionally (and for internal purposes), there are specifiers for the level tracks: main, all, game, extreme, nofx, weird, and contrib.

Furthermore, you can make up and use your own specifiers. In order for them to take effect, though, you have to give cuyo additional information about the current version. This is done on the command line using the --version option. For example

cuyo --version=hard,geek

Specifies both hard version (you can change that in the menu) and version "geek", which is not predefined.

There are several constraints to be observed:

—

All versions of a definition must be made before the first use of the thing defined. As sometimes it is not obvious where the defined thing is used (for example startpic uses a previous greypic by assigning successive numbers to kinds), it is best to group all these versions into one block.

—

A given version also applies to every more specialized version, for which no definition is given. In the above example, numexplode is set to 6 in two-player hard mode and in two-player easy mode as well.

—

Cuyo knows that easy and hard exclude each other. Consequently, it is unnecessary (and indeed prohibited) to give an [easy,hard] definition, even if both [easy] and [hard] are given. The same holds for 1 and 2, and for level tracks.

—

Furthermore, cuyo knows that 1 and 2 are exhaustive: There is no mode which is neither single-player nor two-player. (The human-versus-AI mode counts as two-player as far as cual is concerned.) Therefore, if there are definitions for both, it is unnecessary, (and again illegal) also to define a version without any of both. For example, if [1,de] and [2,de] are given, [de] must be omitted. Alternatively, you could of course give [1,de] and [de] or [de] and [de,2]. The level track specifiers are exhaustive as well.

BUSIENESS

Busieness is a concept to make it easier to implement simple animated sequences which are triggered by certain events. Each code fragment has an internal state which tells if it is busy.

—

Normal statements like assignments are never busy.

—

A chain of commands separated by "," is busy as long as not all of the commands have been executed.

—

code1 ; code2 is busy as long as at least one of code1 and code2 are busy.

Here's an example of how to use busieness for an animation which appears at random intervals:

switch { 1:100 => {B*, C*, D*, E*}; -> A*; };

This code fragment normally draws the icon at position A (0). But in each step, with a probability of 1/100, an animation sequence consisting of icons B, C, D and E is started. With a normal arrow ("->") after the "1:100", after the step in which B has been drawn, the probability would be 99/100 that A is drawn again. But with the double arrow, the switch statement won't switch back to A until the animation has terminated.

(Btw: It doesn't matter if there's a "->" or a "=>" before the "A*"; A* isn't busy anyway.)

THE GLOBAL BLOB

There are also semiglobal blobs. There is one for each player. These are programmed with semiglobal=code.

EVENT HANDLERS

init

Is called only once, when the blob gets into life, just before the first time its main drawing routine is called.

turn

Is called for falling blobs each time they are rotated.

land

Is called when the steered blob lands (just after it landed).

changeside

Is called when a blob moves from one player to the other, just after the blob has arrived at the new player.

connect

Is called when the connection of blobs is recalculated.

row_up

Is called when a player got a row from the other side, after everything is finished and just after the loc_y of all blobs has been decreased by 1. Is only called for the semiglobal blob, though.

row_down

Is called when a player gives a row to the other side, before anything visible happens, but just after the loc_y of all blobs has been increased by 1. Is only called for the semiglobal blob, though.

keyleft, keyright, keyturn, keyfall

Are called when the player presses the left, right, turn or fall key. Are only called for the steered falling blobs and the semiglobal blob, though. (Note that, in contrast to turn, keyturn is called even if the steered blob cannot be rotated due to some obstacles, and also if there is no steered blob.)

THE LIFE OF A BLOB

The life of empty blobs is different from the one of normal blobs. Empty blobs are not affected by gravity, and they often start or stop existing. For example, when a single grey blob is falling down, the empty blob below it stops existing when the grey blob arrives and a new empty blob starts existing when the grey blob moves on. There is only one situation in which empty blobs move: When a row moves from one player to the other, and everything moves up resp. down, the empty blobs move, too.

STARTDIST

Every line of the startdist describes one row of blobs in the level's initial state. The lines are aligned to the bottom and the topmost lines come first (normal reading order). Each line must contain exactly 10 or exactly 20 characters, except the last which is special. In a line of length 20 the first 10 characters describe the left player, the second 10 characters describe the right player. A line of length 10 describes both players. Hence, each character describes one blob. The semantics are:

.

An empty blop.

+, -, *

A blop chosen at random according to colourprob, respectively greyprob, respectively goalprob. The value of nogreyprob has no influence.

0..9, A..Z, a..z

These characters denote a specific kind. If the character matches the distkey of some kinds, the first of these is chosen. More generally, these characters are ordered such that "9" comes before "A" and "Z" comes before "a". In this order, the maximal distkey, which does not come after the character, specifies the blob's kind. The difference between the character and the distkey then specifies the blob's version.

%

An info blop with the version set according to the level-wide neighbours.

&

An info blop with the version set according to the level-wide chaingrass.

The last line may have length 4, 8, 10, or 20. If it has length 10 or 20, it is just a normal line as above. Otherwise it describes the informational blops next to the field. In case of length 4, the first entry describes the blop which depicts the number of greys. The second entry describes the blop which depicts the number of grass blops. The third entry describes the blop which depicts connection information. The fourth entry describes the blop whoch depicts chaingrass information. In case of length 8, the above holds for the left player. The remaining 4 entries then describe the same for the right player, but in reversed order. The default is "-*%&&%*-" (or equivalently "-*%&").

As seen above, startdist can reference 62 kind/version combinations directly (and more at random). Because this might at some time not be enough, the multichar extension has been introduced. In this case, each blob is described by more than one character. However, the number of characters per blob must be the same for all keys. Hence, the lengths of startdist lines then must be this number multiplied by 10 or by 20. Every multicharacter combination starting with ".", "+", "-", or "*" is treated as the corresponding character in single-character format. All other character combinations are treated as numbers in base 62 representation. Here, "A" to "Z" are digits with decimal value 10 to 35, and "a" to "z" are digits with decimal value 36 to 61. Leading spaces are allowed instead of zeroes (however, the all-space string is forbidden). The maximal distkey which (as a number) is not larger than the number given in startdist, specifies the blob's kind. The difference between the startdist number and the distkey then specifies the blob's version. In the case of multichar distkeys, the default for distkeys of kinds declared by startpic= is 10 in decimal.

For blops whose kinds are chosen at random (i.e. characters "+", "-", "*" in single-character startdists), cuyo tries to make these as different as possible. That means, by a certain heuristic, cuyo minimizes the number of neighbouring blobs of the same kind. "Neighbouring", of course, refers to the neighbours entry. inhibit and the calculate_size bit of behaviour have no effect (these are mutable during the lifetime of blobs, while at the time of startdist processing, no blob's lifetime has started yet). So the only way to influence the unneighbouring (if you really wish to do so), is by setting neighbours appropriately. (Of course, this possibility is even more limited, when you intend to set the calculate_size bit during the blob's lifetime.)

WHERE DO I PUT THE CUAL CODE?

—

Outside of everything; that code is accessible from every level coming after that definition.

—

In the section of a level.

—

In the section of a kind.

This basically does what you expect. However, there's one thing you might want to know: Even if you define a variable inside a kind, every blob in that level will have that variable. The only effect of defining the variable in the section of a kind is that this kind is the only one which can access it.

AMPERSAND-CALL

Example 1:
<<
myblob = { ... switch { myvar -> { 0A*; 1; A,B,C,D; *; 2A*}; -> { 0B*; 1; A,B,C,D; *; 2B*}; };
};
>>

Example 2:
<<
anim = {1; A,B,C,D; *};

myblob = { ... switch { myvar -> { 0A*; &anim; 2A*}; -> { 0B*; &anim; 2B*}; };
};
>>

The difference between these examples is what happens when myvar changes. In example 1, the animation "A, B, C, D" will restart at the beginning (because the two animations are different ones); in example 2, the "same" animation is used in both cases, so the animation will simply continue. (Removing the ampersands from example 2 will turn the behaviour to the one of example 1.)

THE AI UTILITY FUNCTION

—

For each new neighbour of blob, the neighbour utility.

—

aiu_two_above, if the blob is two above a blob of same kind.

—

aiu_height*20/(the blob's y coordinate).

The neighbour utility for a single new blob and a single one of its new neighbours is the sum of the following:

—

aiu_color, if the neighbour has the same kind as the blob.

—

aiu_grass, if the neighbour fulfills behaviour.goalblob.

—

aiu_grey, if the neighbour fulfills behaviour.explodes_on_explosion.

SEE ALSO

BUGS

There are several problems with busieness and that stuff. There are several situations in which Cual doesn't behave in the way I would like, and in other situations I don't know how Cual should behave.