U61 (v1.1.0) - Script callbacks reference




Introduction
============


  User callbacks are lua functions which are called from the C++ engine. U61
  requires all these functions to be declared in a script, even if they do
  nothing. In these user callbacks, you may use functions from the U61 system
  API, but be carefull, you can not use any system API functions in any user
  callback, since there are some access right constraints.



user_do_curse
=============


  Declaration
  -----------

    user_do_curse(num,sent)

    * Arguments: a code previously returned by "user_new_curse", a boolean
      saying if the curse is local or comes from another player.

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function can be called int 2 cases:

    * When a square explosion has ended, and this square's location was the
      location of the current curse. If you are playing with the default theme,
      it means that the square with the blinking "?" has exploded.

    * When another player has called the "u61_send_curse" function, and the
      current player was his default victim.

    Basically, one could separate the curses into 2 categories:

    * Those who affect the player which launches them. They usually have a
      positive effect. For instance, it can be a goodie which slows your blocks
      down so it's easier for you to play. These curses are executed directly
      by "user_do_curse", the parameter "sent" being set to 0 (false).

    * Those who affect the launcher's victim. They usually have a negative
      effect. For instance, it can be a nasty curse which speeds up the blocks,
      so that they become uncontrollable. These curses are also executed by
      "user_do_curse" (with "sent" set to 0), but one has to call
      "u61_send_curse" manually to send the curse to the other player (the
      victim). This other player will receive the curse, but this time the
      "sent" parameter will be 1 (true). So the "sent" parameter is fundamental
      since it allows you to identify if the curse is to be sent to the victim
      or to be executed.

    You might wonder why I did not simply create 2 categories of curses, and
    let the C++ engine handle all this "send to victim" business. Well, I liked
    the idea of letting the scripter control what's happening. For instance,
    you may create a special curse which sends severa curses (all the ones you
    currently have for instance) to your victim. Basically, what I described
    with the "sent" parameter determining if one has to send the curse or not
    is only a suggestion. You may use the system the way you want, for
    instance, it's possible to create a special curse which forces your victim
    to send a curse to its own victim...

    Of course one of the big strenghs of U61 is that the "user_do_curse" and
    "u61_send_curse" work pretty well, even in a slow networked environment -
    at least I hope so 8-) -.

  Example
  -------

    The following example is a very simplified version of "user_do_curse". This
    function can indeed grow very big and it's a wise decision to make it call
    smaller functions. But still this purpose of this example is to remain
    simple. It has the 2 main types of curses:

    * "ID_CURSE_PLUS" is a goodie which is executed locally and increases the
      player's score.

    * "ID_CURSE_MINUS" is a nasty curse which reduces the score of the player's
      victim.

    ID_CURSE_PLUS=3
    ID_CURSE_MINUS=4
    
    function user_do_curse(num,sent)
        if (num==ID_CURSE_MINUS) then
            if (sent==0) then
                u61_send_curse(num)
            else
                u61_add_score(-1000)
            end
        elseif (num==ID_CURSE_PLUS) then
            u61_add_score(1000)
        end    
    end



user_do_shape
=============


  Declaration
  -----------

    user_do_shape(num)

    * Arguments: a number previously given by user_new_shape

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    This function shapes the block before it appears on the screen. You should
    not include any random behavior in this function. In fact it is a bad idea
    to include random behaviors in U61 in general, but I mention it here for it
    might be very tempting to ignore the "num" parameter and do a random number
    generator oneself. But this is bound to fail in a network game for you can
    not garantee the remote players will see the right shape. In fact the "num"
    parameter "is" what U61 sents to other players, so it's only by using it
    that you can garantee game consistency.

    A typical "user_do_shape" only needs to call the "u61_add_item" function.
    Indeed this function allows you to add squares to a block and this is what
    you generally need to do since at the very start of the function the block
    is empty, and you wish to end with a fully defined block. You should add
    least one square in evrey block, or the game might freeze.

    Of course you can make the shape generation depend on a curse flag or
    something, but I feel that these kind of things should be done in the
    "u61_new_shape" instead. For instance, if you want to block the shape 0 for
    a while, it's IMHO better not to generate a 0 output in "u61_new_shape"
    than modify temporarly the creation of shape 0 in "u61_do_shape".

    One important thing is to know that after "user_do_shape" has been
    executed, U61 always executes the "u61_center" function, which might alter
    the coordinates you have set. So you should not try to recognize a block
    later in the script by asking the coordinates of his squares, unless you
    are sure that "u61_center" can not alter them, or if you know in what way
    they have been changed. You may wonder why I chose this behavior, for it
    can seem anoying. Well, I just personnally estimate that an automatic
    "u61_center" is a comfortable thing to have, and it avoids badly centered
    blocks.

  Example
  -------

    This set of functions generates:

    * A triangle with color 0 if num is 0

    * A square with color 2 if num is 1

    * A circle with color 5 if num is 2

    function user_do_shape(num)
        if num==0 then
            triangle(0)
        elseif num==1 then
            square(2)
        else
            circle(5)
        end
    end
    
    function triangle(color)
        u61_add_item(0,0,color)
        u61_add_item(0,1,color)
        u61_add_item(1,1,color)
        u61_add_item(0,2,color)
        u61_add_item(2,2,color)
        u61_add_item(0,3,color)
        u61_add_item(1,3,color)
        u61_add_item(2,3,color)
        u61_add_item(3,3,color)
    end
    
    function square(color)
        u61_add_item(0,0,color)
        u61_add_item(1,0,color)
        u61_add_item(2,0,color)
        u61_add_item(3,0,color)
        u61_add_item(0,1,color)
        u61_add_item(3,1,color)
        u61_add_item(0,2,color)
        u61_add_item(3,2,color)
        u61_add_item(0,3,color)   
        u61_add_item(1,3,color)   
        u61_add_item(2,3,color)   
        u61_add_item(3,3,color)   
    end
    
    function circle(color)
        u61_add_item(1,0,color)
        u61_add_item(2,0,color)
        u61_add_item(0,1,color)
        u61_add_item(3,1,color)
        u61_add_item(0,2,color)
        u61_add_item(3,2,color)
        u61_add_item(1,3,color)
        u61_add_item(2,3,color)
    end



user_get_curse_name
===================


  Declaration
  -----------

    user_get_curse_name(num)

    * Arguments: a code previously returned by "user_new_curse"

    * Return values: the name of the curse, which should be shown to the player

    * Rights: map_read

  Description
  -----------

    This function has a very simple goal: provide the user with a name for each
    curse. This name will be disaplyed in the status zone, under his map. Of
    course the game will run correctly if this functions returns a blank
    string, bug it will certainly not help the players.

    The names should not be too long. At the time I write these lines, there's
    a limit of 10 characters, so if you exceed this limit the name will be
    truncated. And be carefull if your name uses lots of "W" and "M", for these
    letters are usually wider then plain "I"s.

  Example
  -------

    The following sample defines 2 curses names. A default name ("surprise")
    has been defined in case the curse is unknown, which should, it's true,
    never arrive if the code is consistent.

    function user_get_curse_name(num)
        local name
    
        name="surprise"
    
        if (num==ID_CURSE_MALEDICTION_OF_GOOLOO) then
            name="gooloo"
        elseif (num==ID_CURSE_YOULLDIE) then
            name="you'll die"
        end
    
        return name
    end



user_get_program
================


  Declaration
  -----------

    user_get_program()

    * Arguments: none

    * Return values: the name of the program ("u61")

    * Rights: none

  Description
  -----------

    This function must be present so that the game engine makes sure the script
    is a valid U61 script. Of course the fact that this function does not exist
    or does not return the good value does not mean the script is actually
    error free, but it provides a good way to detect obvious errors such as
    using a totally wrecked file.

    If this function is not present or does not return the correct value, U61
    will display an error message each time the script is read.

  Example
  -------

    The code for this function should always be the same and look like this:

    function user_get_program()
        return "u61"
    end



user_get_version
================


  Declaration
  -----------

    user_get_version()

    * Arguments: none

    * Return values: the version of the program

    * Rights: none

  Description
  -----------

    This function allows the game engine to know which version the script was
    designed for. This is very important, since the script API can slightly
    change between 2 different releases - of course the less it changes the
    better it is, but it's good to have a way to know the version anyway.

    If this function is not present or does not return the correct value (the
    version of the U61 binary which should be used with the script), U61 will
    display an error message each time the script is read.

  Example
  -------

    The code for this function should look like this:

    function user_get_version()
        return "1.0.0"
    end



user_land
=========


  Declaration
  -----------

    user_land()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    This function is called when it's not possible to move the block down any
    more. It's role is to modify the shape of the block before it is merged
    with the map. Most of the time, this function will do nothing, but you may
    wish - in some cases - to change the shape of the block just as it lands.

    Let's take an example: you might consider that your blocks are not "solid"
    blocks, ie they break themselves into parts as they land. This is a very
    common trick in block-based games, and that's why it's available in U61.

    You could also wish to send a curse as the block lands, or modify the map.
    This is not allowed because of performances issues, which lead me not to
    give the "map_write" right to this function. Indeed this function is very
    important for the "anticipation" mode. In this mode, the user can view in
    real-time where the block will land. This feature is achieved by calling
    the "user_move_down" function until "user_block_land" is required. And I
    have decided that such operations (as they are called very very often)
    should not require a full backup of the map, which can be quite
    CPU-consuming since the map structure can be quite big. It isn't that big
    now but I expect it to grow as I will add features to U61. So basically,
    just remember that there's a good reason not to modify the map in this
    function. However, it does not mean you have no callback at all when a
    block lands. Indeed, it is possible to set up a callback on a pattern match
    by using "user_match_pattern". This should - I hope - be enough in most
    cases.

  Example
  -------

    This example shows a function that makes blocks move up of one row as they
    land. This should make them hang in the air as they land. I can't figure
    out in what kind of context it could be usefull, but it's only a theorical
    example:

    function user_land()
        u61_set_block_y(u61_get_block_y()-1)
    end



user_match_pattern
==================


  Declaration
  -----------

    user_match_pattern(match_count)

    * Arguments: the number of times "user_match_pattern" has already been
      called during last matching session.

    * Return values: 1 if some matching shapes and/or colors have been found, 0
      otherwise.

    * Rights: map_read, map_write

  Description
  -----------

    This is a fundamental function in U61. It is responsible for saying which
    squares should explode when a block lands. It is called after the block has
    landed, ie "user_land" has already been called when "user_match_pattern" is
    called. It is also responsible for incrementing the score of the player.

    You'll notice that this function has no access rights on the block. This is
    because there's no more block when this function is called. Indeed, all the
    squares of the falled block are merged with the map. This means that if
    there were 10 squares in the map and 3 squares in the block, when this
    function is called you get an "all in one"map with 13 squares. By default,
    the block squares are put "as is" on the map, but if you want a more
    accurate control, you may tweak the "user_land" function.

    The pattern to be matched can be anything, based on the position and the
    color of the map squares. You may search a completed horizontal line (as in
    the "classic") script, some sort of alignments, a shape, a sequence of
    colors, well, anything! I believe the "user_match_pattern" function is what
    makes a given set of rule realy different from the others.

    Once the pattern is matched, it is a good idea to make the squares which
    should disappear explode. Technically, you could remove them right away
    (I've not tried it still), but I just think it's more user friendly for the
    player to see the block explode. The common method is to try and find a
    pattern, and when the first pattern is found, stop the search and make the
    founded pattern explode. Then, the Lua function is exited, and the game
    keeps on going. It's take a little time for squares to explode. While
    there's at least one square exploding on the map, U61 does not make a new
    block appear. Instead, it waits for the explosion to end, and when the
    explosion is ended, it runs the "user_match_pattern" function again. This
    way, it's possible to have cascading effects, and the player can understand
    why 12 of his squares disappeared while a pattern is usually made of 3
    blocks.

    This leads to a very important point: the "match_count" parameter. This
    parameter is equal to 0 when "user_match_pattern" is called for the first
    time. Then logically, "user_match_pattern" should make some squares explode
    (if needed of course) and let the squares alone while they blow up. When
    the explosion is finished, "user_match_pattern" is called again, but this
    time "match_count" is 1. Next time it will be 2, etc... When there's no
    more pattern to match, then U61's engine gives the player a new block, and
    resets the internal value corresponding to "match_count". This is a usefull
    feature for it allows an accurate control of the score, for instance, you
    might make something that gives:

    * 100 points if there's only one pattern matched

    * 300 points if there are two pattern matched

    * 700 points if there are three pattern matched

    * etc...

  Example
  -------

    The following example finds any horizontal line which is filled with
    squares, or has only one square missing. It's very close from the pattern
    match used in the "classic" script. Note that the code does not lie
    directly in user_match_pattern but in an external function which is more
    general and can be used in another set of rules if needed.

    function user_match_pattern(match_count)
        return match_holed_line(match_count,1)
    end
    
    function match_holed_line(match_count,max_hole)
        local x
        local y
        local width
        local height
        local holes
        local lines
        
        width=u61_get_width()
        height=u61_get_height()
    
        lines=0
        y=0
        while y    <    height and lines==0 do
            holes=0
            x=0
            while x    <    width do
                if u61_get_square_color(x,y)    <    0 then
                    holes=holes+1
                end
                if not (u61_is_square_exploding(x,y)==0) then
                    holes=holes+1
                end
                x=x+1
            end
            if holes    <    max_hole then 
                delete_line(y)
                lines=lines+1
            end
            y=y+1
        end    
    
        if lines>0 then
            u61_add_score((match_count+1)*1000)    
            if (match_count>=3) then
                u61_add_antidote()
            end
        end
    
        return lines
    end



user_move_down
==============


  Declaration
  -----------

    user_move_down()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    This function looks like "user_move_left" and "user_move_right" at first
    sight, but it is quite different. Indeed the "user_move_down" function must
    imperatively move the block down in some way. The reason is that this
    function is used in the following cases:

    * The user presses the "move down" key (that's to say he presses the key
      which he has specified in his settings to be the "move down" key).

    * A certain amount of time has ellapsed, and U61 decides to make the block
      move down. How long this delay is depends on the global speed of the
      game, which can be set in the game options, and generally increases while
      the game is running. And this is why it is important that one of the
      actions performed by "user_move_down" is actually to shift the block
      down. Indeed, one of U61 basic rules - the ones you can not change within
      the script -, is that "the block falls, and when it lands on other
      blocks, it freezes". If "user_move_down" does not move the block down,
      you could get a situation where your block never freezes and you never
      get any new block. Basically, a new block is sent to the user when a call
      to "user_move_down" has created a conflict between the block's squares
      and the map's squares. It is only in this case that the block will be
      freezed and that "user_land" and "user_match_pattern" will be called.

    * The user presses the "drop" key, in this case "user_move_down" is called
      as often as possible until the block is stuck on the map. Again, if you
      ever make a "user_move_down" that does not lead to an incoherent position
      after a certain amount of calls, this function will loop for ever...

    Please note that in this function you do not need to check wether the
    operation you want to perform is possible or not. As with other
    "user_move_..." or "user_rotate_..." functions, the C++ engine
    automatically checks if something is wrong, and if there's a conflict it
    rollbacks the whole operation.

  Example
  -------

    The following function moves the block down, and increments the value of a
    global value at the same time:

    MOVE_DOWN_COUNTER=123
    
    function user_move_down()
        u61_set_block_y(u61_get_block_y()+1)
        u61_set_global(MOVE_DOWN_COUNTER,u61_get_global(MOVE_DOWN_COUNTER)+1)
    end



user_move_left
==============


  Declaration
  -----------

    user_move_left()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    This function can generally be called in 2 cases:

    * The user has pressed the "Move left" key. (which key it is physcically
      depends on the user's settings). This is the most common case, and you
      had certainly thought of it.

    * The "Rotate left" or "Rotate right" key has been pressed, and the
      "user_rotate_..." corresponding callback has put the block in such a
      state that there's a conflict between a square of the block and a square
      of the map. Therefore U61 automatically simulates a "Move left" or "Move
      right" key press, and then retries to execute the "user_rotate_...". This
      is an interesting feature since it enables the user to rotate his blocks
      even if the block is stuck to a wall.

    Apart from this last point the "user_move_left" function is very similar to
    "user_rotate_left". One could certainly imagine scripts vhere
    "user_move_left" would not translate the block on the left. And even if in
    your script "user_move_left" perfor;s a left translation of the block, it
    is possible in this function to test if a given curse is active and change
    the function's behavior. This is what the "goofy" curse (in U61 0.2.2)
    does: it inverts the effects of "user_move_left" and "user_move_right",
    which makes the game a little... harder to control!

    It's important to note that substracting 1 to the x coordinate of each
    square of the block won't make the block move to the left. Indeed after
    each call to "user_move_left" U61 centers the block (similar to a call to
    u61_center), so the only way to make a block translate is to use the
    "u61_set_block_x" function (or any associated function).

  Example
  -------

    This example function makes the block move left and down at the same time:

    function user_move_left()
        u61_set_block_x(u61_get_block_x()-1)
        u61_set_block_y(u61_get_block_y()+1)
    end



user_move_right
===============


  Declaration
  -----------

    user_move_right()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    Similar to "user_move_left" but associated to the "Move right" key.

    Like with the "user_rotate_..." functions, "user_move_right" does not have
    to be the exact contrary of "user_move_left". You are just free to imagine
    the weirdest behaviors.

  Example
  -------

    In this example, the block is shifted of 2 blocks right:

    function user_move_right()
        u61_set_block_x(u61_get_block_x()+2)
    end



user_new_curse
==============


  Declaration
  -----------

    user_new_curse(num)

    * Arguments: a random value generated by the C++ engine

    * Return values: the code of the curse that will be triggered if the
      current curse block explodes

    * Rights: block_read, map_read

  Description
  -----------

    This function is very similar to "user_new_shape". It's goal is to control
    the nature of the next curse which will be given to the player. Its only
    purpose is to return an integer which will be interpreted by
    "user_do_curse" later.

    This function is called long before the player actually matches a pattern.
    Indeed, it is required to do so since the name of the next curse must be
    displayed in the player's information board/zone.

    Of course, this "next curse" generation can be influenced by curses which
    affect the current player. For instance, you might decide that when a
    player is victim of the "THOU_SHALL_DIE" curse, then he can only get poor
    curses which have almost no effects on the opponents, and leave him in a
    hopeless position, bound to lose very soon. This is not fair practice but
    it's theorically possible 8-P

  Example
  -------

    The following example returns a curse code between 0 and 9 if the
    "ID_ZOUBIDA_MALEDICTION" curse is activated, and a code between 0 an 19 if
    not.

    ID_ZOUBIDA_MALEDICTION=5
    
    function user_new_curse(num)
        if u61_get_curse_age(ID_ZOUBIDA_MALEDICTION)    <    0 then
            num=mod(num,20)
        else
            num=mod(num,10)
        end
    
        return num
    end



user_new_shape
==============


  Declaration
  -----------

    user_new_shape(num)

    * Arguments: a random number between 0 and 1 000 000 000

    * Return values: the code that should be use for the next call to
      "user_do_shape"

    * Rights: block_read, map_read

  Description
  -----------

    This function is usefull for you to control the codes used for shape
    generation. Basically, a set of scripts might require the shape number to
    be between 0 and 6. So in this case you will return a value between 0 and
    6. The "num" argument is here to provide a randomly generated number. You
    are free to use this value or not, but keep in mind that if you don't use
    it, it will be too late in the "user_do_shape" function to use some random
    numbers. You can consider this function as an intermediate between the
    random function and the function that generates the shape. Indeed the
    number it returns is used by the C++ engine to generate an internal event
    which will be sent to all remote players.

    Tweaking this function can be very interesting if you want for instance to
    set up a mode where the player only receives blocks with shapes 34 an 125.

  Example
  -------

    This function returns a shape code between 0 and 6. More precisely, it
    returns:

    * 40% of 0

    * 20% of 1

    * 10% of 2,3,4

    * 5% of 5,6

    user_new_shape(num)
        local result
    
        num=mod(num,100)
    
        if num>=60 then
            result=0
        elseif num>=50 then
            result=1
        elseif num>=30 then
            result=2
        elseif num>=20 then
            result=3
        elseif num>=10 then
            result=4
        elseif num>=5 then
            result=5
        else
            result=6
        end
    
        return result
    end



user_rotate_left
================


  Declaration
  -----------

    user_rotate_left()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    This function is called when the user presses the "Rotate left" key (what
    key exactly it is depends his key settings).

    It may or may not perform a geometrical rotation. This is the case with the
    "classic.lua" script, but if you play with the "vertical.lua" script,
    you'll find out that rotation is in fact a "color shift". Basically,
    rotation should be any player launched function that alters your block but
    is not a plain translation.

    If after executing the code of "user_rotate_left" there's a confict between
    a block square and a map square, I mean if they have the same absolute
    position, then the operation is automatically cancelled. This is one of the
    reasons you do not get "map_write" access in this function, indeed, the
    rollback of a map, especially the act of making a copy of a whole map in
    case the operation fails would in my opinion be exagerately time consuming,
    and I like the idea that "user_rotate_left" only affects the block.

    This function is granted a "map_read" access, therefore you check if a
    curse is activated and modify the behavior of "user_rotate_left"
    dynamically.

  Example
  -------

    In order to show that "user_rotate_left" does not need to be a geometrical
    correction, this sample function performs a left/right flip of the block:

    function user_rotate_left()
        local size
        local i
      
        size=u61_get_nb_items()
        i=0
        while i    <    size do
            u61_set_item_x(i,-u61_get_item_x(i))
            i=i+1
        end
    end



user_rotate_right
=================


  Declaration
  -----------

    user_rotate_right()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read

  Description
  -----------

    Exactly the same than "user_rotate_left". It's important to note that
    "user_rotate_left" does not need to be the contraryof "user_rotate_right".
    You may for instance decide that for a given script the "rotate left" and
    "rotate right" keys will correspond to 2 "special actions" which are by no
    way linked to each other. In fact the reason these functions are call
    "user_rotate_..." for is that in most scripts this name makes sense, and it
    would be IMHO a waste of time to redefine for each key and each script what
    label should be associated to keys.

  Example
  -------

    The following function is a function that increments the color of all the
    squares of the block:

    function user_rotate_right()
        local size
        local i
      
        size=u61_get_nb_items()
        i=0
        while i    <    size do
            u61_set_item_color(i,mod(u61_get_item_color(i)+1,8))
            i=i+1
        end
    end



user_square_blown_up
====================


  Declaration
  -----------

    user_square_blown_up(x,y)

    * Arguments: coordinates of the square which blew up

    * Return values: none

    * Rights: map_read, map_write

  Description
  -----------

    This function is called when a square has exploded. Explosions are usually
    started after a pattern match (see "user_match_pattern"), and then the C++
    engine handles the explosion by himself, without calling any script. This
    takes a little time - during which the game keeps running - and when the
    explosion is finished, after say approximately 1/2 second,
    "user_square_blown_up" is called.

    If the square that exploded had the same location that the current curse,
    then the "user_do_curse" function is launched. You do not have to do
    anything about this, it's just done automatically by the C++ engine.

    Note that a single call to "user_match_pattern" can cause several squares
    to explode, so there will be several calls to "user_square_blown_up" - one
    per square to be precise -.

    It's the responsibility of "user_square_blown_up" to change the map's
    structure after the square's explosion. If for instance the blown up square
    is to be replaced by the squares which are above it, one has to shift
    "manually" the squares down. Of course, you can decide that in some
    circumstances, the end of the explosion should cause the start of a new
    explosion elsewhere...

    When this function is called, the square is still present on the map, and
    it still has its color. I mean that you can make the difference between a
    blue and a red blown up squares. This can be usefull if you want to set up
    cascading chains of explosions. Such effects can also be obtained by
    tweaking "user_match_pattern", but you may prefer to place your code in
    "user_square_blown_up", especially if your chain of explosion really
    depends on where the previous explosion was. The important thing to
    remember is that when there are no exploding squares and no pattern to
    match left, then the player gets a new block.

  Example
  -------

    The following function shifts down all the squares that are above the blown
    up square, and changes their color to that of the disappeared square. Note
    that this function moves the "curse" square if needed.

    function user_square_blown_up(x,y)
        shift_column_down_and_color_it(x,y)
    end
    
    function shift_column_down_and_color_it(x_col,y_bottom)
        local y
        local color
    
        color=u61_get_square_color(x_col,y_bottom)
        y=y_bottom
        while u61_get_square_color(x_col,y-1)>=0 and y>0 do
            u61_set_square_color(x_col,y,color)
            y=y-1
        end
        u61_set_square_color(x_col,y,-1)
    
        if u61_get_curse_x()==x_col and u61_get_curse_y()    <    y_bottom then
            u61_set_curse_y(u61_get_curse_y()+1)
        end
    end



user_start
==========


  Declaration
  -----------

    user_start()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function is called at each "fresh start". A "fresh start" is when the
    player either enters the game or has just lost so his map and all its
    parameters but the score have been cleared.

    A typical use is if you want the game to start with "some blocks" already
    placed so that it's harder to play.

    It's also a good place to define global parameters such as map width and
    height.

  Example
  -------

    In this example, whenever a player starts a game, he's granted an antidote,
    and has the "STARTER" curse on him for 30 seconds.

    ID_CURSE_STARTER=123
    
    function user_start()
        u61_add_antidote()
        u61_register_curse(ID_CURSE_STARTER,3000,0)
    end



user_time_callback_1
====================


  Declaration
  -----------

    user_time_callback_1()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function is called once per second. It has all rights on the map and
    block, so it's possible to do anything with it. By default, it increments
    the score of the player by 1 point, since the longer you play, the better
    you are...

    Another typical use of this function would be to check if a curse is active
    and execute a special function if the curse is set on.

  Example
  -------

    In this example, if the "ID_BAD_LUCK" curse is active, then the player's
    score is not incremented any more.

    ID_BAD_LUCK=13
    
    function user_time_callback_1()
        if (u61_get_curse_age(ID_BAD_LUCK)    <    0) then
            u61_add_score(1)
        end    
    end



user_time_callback_10
=====================


  Declaration
  -----------

    user_time_callback_10()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function is called 10 times per second. It has all rights on the map
    and block, so it's possible to do anything with it.

    This is a very good place to code most of the curse effects. Indeed, doing
    something 10 times per second makes things look fast and smooth enough in
    many cases, and it's not *too* time consuming (at least not as much as
    placing the code in user_time_callback_100).

  Example
  -------

    In this example, if the "ID_SHIFT_LEFT" curse is active, then the block is
    moved to the left.

    ID_SHIFT_LEFT=33
    
    function user_time_callback_10()
        if (u61_get_curse_age(ID_SHIFT_LEFT)    <    0) then
            u61_set_block_x(u61_get_block_x()-1)
        end    
    end



user_time_callback_100
======================


  Declaration
  -----------

    user_time_callback_100()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function is called 100 times per second. It has all rights on the map
    and block, so it's possible to do anything with it.

    Please take care not to put any complex code here, since it's executed very
    often. For instance, if there are 5 players in a game, it will be called
    500 times per second, so if it takes 1 millisecond to be executed, then
    this function will eat up 50% of the CPU, so there won't be much left for
    other functions (which include all other Lua functions, C++ core engine,
    other tasks ran by the OS....). Basically, this function is here so that
    people who want a very accurate control of what's happening have this
    control, but in most cases one should try to use user_time_callback_10 or
    user_time_callback_1.

  Example
  -------

    In this example, if the "ID_SHIFT_RIGHT" curse is active, then the block is
    moved to the right. One could have - as in most cases - used the
    user_time_callback_10 function instead, only the block would have moved
    slower.

    ID_SHIFT_RIGHT=66
    
    function user_time_callback_100()
        if (u61_get_curse_age(ID_SHIFT_RIGHT)    <    0) then
            u61_set_block_x(u61_get_block_x()+1)
        end    
    end



user_use_antidote
=================


  Declaration
  -----------

    user_use_antidote()

    * Arguments: none

    * Return values: none

    * Rights: block_read, block_write, map_read, map_write

  Description
  -----------

    This function is called when the player presses the key associated to the
    "use antidote" function. It is a user callback since there can not be a
    generic function for this. Indeed, what has to be done for such an action
    really depends on how all the curses have been coded.

    Here are a few examples of what one could code in this function:

    * Remove the oldest curse. That's an obvious solution, when you use an
      antidote, it cures your oldest illness.

    * Remove the curses in a special order, based on the severity of the curse.
      This way one could imagine that an antidote always cures the most
      annoying curse.

    * Change the effect of curses. One could imagine special curses which the
      antidote can't really kill, but can make them less annoying, as if the
      desease were half cured.

    * Invert the effect of the antidote. Indeed, a nice curse would be to put
      the player in such a state that the use of an antidote has the opposite
      effect of what he expects.

    So as there are so many possibilities, I think it's a good thing to let the
    scripter code whatever he wants for this function. In fact, the one thing
    to remember about antidotes is that they appear in the status box of the
    player, and it's supposed to help the player.

  Example
  -------

    In this example, the antidote cures the oldest curse which affects the
    player, except for the "ID_ROTTEN_CURSE" curse. This makes the "rotten"
    curse an uncancellable curse, from an antidote point of view. Of course you
    can imagine that there are other ways to cure it, such as matching a
    special pattern for instance.

    ID_ROTTEN_CURSE=66
    
    function user_use_antidote()
        local oldest
    
        oldest=u61_get_oldest_curse(0)
        if oldest~=ID_ROTTEN_CURSE then
            u61_cancel_curse(oldest)
        end
    end

