Script API reference

Introduction

The API functions are functions you can call within Lua, when you are scripting, to get information from the core C++ engine, and also modify what's happening in the game.

Technically speaking, these functions are just plain Lua functions mapped over C functions in the core engine, and these C functions call C++ methods off the "U61_Map" and "U61_Block" C++ objects. In this document, I will later say that the C++ engine calls some API fonctions automatically. In fact, it does not call the Lua functions but the C++ methods directly. But the result is exaclty the same, only the C++ engine does not make as many checks as the API functions do.

Those functions are quite "crash proof". I mean that various checks are triggered when you call them. For instance, calling a function which requires an array index with a bad, inexisting index will simply result in returning a default value, but there should not be (such a bug should be reported) a system crash of the core C++ engine.

The design of this API is not perfect, so maybe I'll create more functions later, since the functions I provide here are very low-level functions. However, I'll try and do my best not to remove any functions, so that in the long run scripts can be re-used easyly, and remain compatible with each other.

u61_add_antidote

Declaration

  u61_add_antidote()

• Arguments: none.
• Return values: none.
• Rights: map_write.

Description

Gives an antidote to the current player.

The given antidote should appear in the status zone (a little heart in the default theme). The player is not forced to use it right away. In fact, as long as there's at least one antidote available, any press on the "use antidote" key will run the "user_use_antidote" function.

Note that even if the antidote does not appear in the status zone for there are already too many antidotes available, the "u61_add_antidote" will function correctly, and "u61_get_nb_antidotes" should always return the exact value.

Example

In this example, we give an antidote and a score bonus to the player.

  function nice_present()
      u61_add_score(1000)
      u61_add_antidote()
  end

u61_add_item

Declaration

  u61_add_item(x,y,color)

• Arguments: coordinates and color of the square to add.
• Return values: none.
• Rights: block_write

Description

This function adds a new square to the current block. It is the function which should be called in the "user_do_shape" callback, to build new blocks before they start falling.

You can consider this function as an "append" method on the block object. In a way, the block is a vector of squares, which grows as you call "u61_add_item", and can be emptied with "u61_clear_block". If you had a block with 3 squares, after a call to this function, it will have 4 squares. The added square has an index of [n-1 ] , if the size of the block is n.

Of course, the square properties which are set up by this function (position and color), can be changed later in the game.

Example

In this example, we add a square with a parameterd color at the right of the square which is already at the right extremity of the block.

  function expand_right(color)
      local max_x
      local x
      local y
      local i
  
      max_x=0
      y=0
  
      i = u61_get_nb_items()-1
      while i>=0 do
          x=u61_get_item_x(i)
          if x>max_x then
              max_x=x
              y=u61_get_item_y(i)
          end
          i=i-1 
      end
  
      u61_add_item(x,y,color) 
  end

u61_add_score

Declaration

  u61_add_score(score_diff)

• Arguments: the value which should be added to the score.
• Return values: none.
• Rights: map_write.

Description

This function adds some points to the current score.

You can also use this function with negative values, if you want to decrease the score of a player. In fact, this function is really equivalent to a manual call to "u61_get_score" and then "u61_set_score". It is there to avoid you the pain of calling 2 functions where 1 is enough in most of the cases.

Example

The following function adds some points to the player only if the "NO_POINTS" curse is not activated.

  ID_NO_POINTS=33
  
  function tweaked_add_score(score_diff)
      if u61_get_curse_age(ID_NO_POINTS)  <  0 then
          u61_add_score(score_diff)
      end
  end

u61_blow_up_square

Declaration

  u61_blow_up_square(x,y)

• Arguments: the coordinates of a block in the map.
• Return values: none.
• Rights: map_write.

Description

This function starts an explosion at the given location, it should be used in the "user_match_pattern" function.

Of course, in the "user_match_pattenr" function, you could directly remove squares from the map, but you can get a nicer effect by calling the "u61_blow_up_square" function. It will indeed start an explosion on a given square, and at the end of the explosion - that's to say a few game cycles after the explosion has started -, the C++ core engine will call your "user_square_blown_up" callback. This way you may start an explosion, let the game run while the explosion is displayed to the player, and then get some control of what's happening at the end of the explosion with the "user_square_blown_up" function.

This function is very usefull if you want to create some cascading effects. In fact, I don't know about any other way to do it yet...

Example

This example blows up the bottom line of the map. What has to be done when the explosion is over is not defined here, for it is defined i the "user_square_blown_up" function.

  function blow_bottom()
      local x
      local y
  
      y=u61_get_height()-1
      x=u61_get_width()-1
      while x>=0 do
          if u61_get_square_color(x,y)>=0 then
              u61_blow_up_square(x,y)
          end
          x=x-1 
      end    
  end

u61_cancel_curse

Declaration

  u61_cancel_curse(curse)

• Arguments: the id of a curse.
• Return values: none.
• Rights: map_write.

Description

This function cancels a persistent curse which had been set up with "u61_register_curse".

This function cures the illness caused by a curse by disactivating it. It can be used in the "user_use_antidote" function for instance. Of course any persistent curse is automatically removed with time, but this function is very usefull in the case of a pseudo-permanent curse which has a very long delay.

Example

In this example, we disable the "ID_CURSE_HUNGRY" curse manually.

  ID_CURSE_HUNGRY=10
  
  function feed_the_beast()
      u61_cancel_curse(ID_CURSE_HUNGRY)
  end

u61_center_block

Declaration

  u61_center_block()

• Arguments: None
• Return values: None
• Rights: block_write

Description

This function centers the block, this means that after it has been called, the gravity center of the block (approximately), will be located at (x,y), x and y being the global coordinates of the block.

This is very usefull when you want to code something like a rotation or a symetry. You can indeed code things in a simple manner using "x=-x" like algorithms, and then call "u61_center_block" to center the block. If you had not this function, there could be situations where after a sequence of rotations/symetries, a block could have moved to the left and/or right. Worse, a rotation could cause the block to move down, which is bad in a block-based game. Please note that this function does note change the global (x,y) values of the block (access by "u61_get_block_x" for instance). Its role is only to make (x,y) be the actual center of the block.

This function is automatically called by the script engine after the following user callbacks:

• user_rotate_left
• user_rotate_right
• user_move_left
• user_move_right
• user_move_down

Example

The following example leaves the block in a unchanged state. Indeed, the squares are translated, but "u61_center_block" cancels the translation.

  function leave_block_unchanged()
      local i
  
      i = u61_get_nb_items()-1
      while i>=0 do
          u61_set_item_x(i,u61_get_item_x(i)+1) 
          i=i-1
      end
      u61_center_block()
  end

u61_clear_block

Declaration

  u61_clear_block()

• Arguments: None
• Return values: None
• Rights: block_write

Description

This function clears the current block, this means it removes all the squares from it.

Beware not to leave a cleared, empty block falling in the players map, because it might cause some problems, since the C++ engine will not be able to find out when the block is supposed to have landed.

Example

In this example, we imagine that we want to change the shape of the block as it falls. Since "user_do_shape()" is always called on an empty block, the functions which prepare shapes usually do not clear the block first. So we need to force the block clear in we want to change completely the shape of the block outside the "user_do_shape" function.

  function change_shape_to_tetramino_bar()
      u61_clear_block()
      tetramino_bar()
  end

u61_clear_map

Declaration

  u61_clear_map()

• Arguments: none.
• Return values: none.
• Rights: map_write.

Description

Clears the map, ie removes all the squares.

Keep in mind that this function clears all squares but does not perform a "total reset" since some parameters - such as active curses and score - still keep their values after the map has been cleared.

Example

This function puts a square in the middle of the map, after clearing it:

  function square_in_the_middle()
      u61_clear_map()
      u61_set_square_color(u61_get_width()/2,u61_get_height()/2,1)
  end

u61_delete_antidote

Declaration

  u61_delete_antidote()

• Arguments: none.
• Return values: none.
• Rights: map_write.

Description

Removes an antidote from the player available antidotes.

Note that it's not necessary to call this function within the "user_use_antidote" function, since the number of antidotes is automatically decreased by the C++ core engine. However, you might want to use this function if you want to remove manually some antidotes.

If you call this function too many times, the number of antidotes will remain 0, it should never get negative, since the C++ engine will not allow it.

Example

This function clears all the antidotes of a player.

  function clear_antidote()
      while u61_get_nb_antidotes()>0 do
          u61_delete_antidote()
      end
  end

u61_get_anticipation_state

Declaration

  u61_get_anticipation_state()

• Arguments: none.
• Return values: true (1) if anticipation mode is on, or false (0).
• Rights: map_read.

Description

This function returns the state of the anticipation mode, that means wether the player should see where the block will land if he presses the "drop" key right away.

You may have noticed that this parameter seems available in the player options menu, and the player might choose to have this information or not. However, the "u61_get_anticipation_state" function does not return the state of the menu item. Indeed, the "anticipation frame" is drawn only if the menu option has been set to "on" *and* the "u61_get_anticipation_state" returns true. So if you set the option to false in the menu, you will never see it, no matter what happens in the game.

Example

In this example, we return true if both anticipation and preview mode are set to true.

  function is_game_easy()
      local result
  
      if u61_get_anticipation_state() and u61_get_preview_state() then
          result=1
      else
          result=0
      end
  
      return result
  end

u61_get_block_x

Declaration

  u61_get_block_x()

• Arguments: None
• Return values: The x coordinate of the block.
• Rights: block_read

Description

This function returns the x coordinate of the block. This value should approximately correspond to the center of gravity of the block.

Example

The following function returns the real position of a square in a block, ie the position this square has on the map.

  function get_absolute_x(i)
      return u61_get_block_x()+u61_get_item_x(i)
  end

u61_get_block_y

Exactly the same as "u61_get_block_x", but x becomes y...

u61_get_curse_age

Declaration

  u61_get_curse_age(curse)

• Arguments: the id of a curse.
• Return values: the age of the curse.
• Rights: map_read.

Description

This function returns the time ellapsed since the last call to "u61_register_curse" with the same curse id. If the curse is not active at all, then the function returns -1.

The time is counted in game cycles. It takes 100 game cycles to make one second. It's in fact the same unit used in "u61_get_time()".

This function's primary goal is to allow the scripter to know wether a curse has been registered with "u61_register_curse". These registered curses appear in the player's status zone, and are representent by little skulls in the default theme. A typical use of this function would be to test if its return value is greater or equal to 0, and decide to disable and/or enable features in the game.

Example

In this example, we don't allow the user to use the rotate left key if he's doomed with the "ID_CURSE_NO_ROTATE" curse. It supposes there's a "low_level_rotate_left" function that does the dirty job of rotating the block.

  ID_CURSE_NO_ROTATE=20
  
  function my_rotate_left()
      if u61_get_curse_age(ID_CURSE_NO_ROTATE)  <  0 then
          low_level_rotate_left()
      end
  end

u61_get_curse_state

Declaration

  u61_get_curse_state()

• Arguments: none.
• Return values: 1 if the curse mode is on, 0 if not.
• Rights: map_read.

Description

Returns true if there should be a special "curse square" on the map.

This function is very different from "u61_is_curse_available". Indeed, it returns true if the map is in such a mode that a curse square could exists. But this does not garantee there's a curse square available. A trivial example is the empty map. If there are no squares at all on the map, you can oviously not have a special square anywhere. In fact, this function is merely to return the value set by "u61_set_curse_state" but in most of the cases what you'll need to call is "u61_is_curse_available".

Example

In this example, the player has his score freezed when he can't have any curse square on his map. This is a very unfair script since he is already disadvantaged by having no weapon at hand.

  function add_score_unfair(points)
      if not (u61_get_curse_state()==0) then
          u61_add_score(points)
      end
  end

u61_get_curse_x

Declaration

  u61_get_curse_x()

• Arguments: none.
• Return values: the x coordinate of the "curse square" in the map.
• Rights: map_read.

Description

This function gives the x position of the "curse square". This special square is the black and white "?" in the default theme.

When this special square disappears (after an explosion), then the "user_do_curse" function is called. Of course you can start curses on other events, such as a special pattern match, but the explosion of this special square should remain the most common method to issue a curse - at least this is the way I view things, you may agree or not with me on this point.

This special square historically comes from EITtris. Since U61 is quite extensible I could have honestly imagined a more original and flexible way to launch curses but I was too lazy and I just like this idea since it reminds me of all the nights spent playing EITtris with 3 friends on a single computer in a small student room =8-)

Example

In this example, the player gets a score bonus if the curse square was located in the right or left columns of the map.

  function bonus_if_curse_on_sides()
      local x
  
      x=u61_get_curse_x()
  
      if x==0 or x==(u61_get_width()-1) then
          u61_add_score(1000)
      end
  end

u61_get_curse_y

Exactly the same as "u61_get_curse_x", but x becomes y...

u61_get_global

Declaration

  u61_get_global(i)

• Arguments: the index of the global value.
• Return values: the value of the global.
• Rights: map_read.

Description

This function returns the global value associated to a given index (between 0 and 99).

This function is by no way related to the luac "getglobal" function. For more information about how to use it, see the documentation of "u61_set_global".

Example

This function returns the value of the ID_COUNTER value. Note that the lua object ID_COUNTER is a global lua value. However, you can use it safely since it is a constant. It's just a way to write things in a cleanier way. Without such constants, the code would rapidly become ununderstandable. But the value returned by the function is not a global lua value, it's a local value which has been initialized with a value stored internally by the C++ core engine.

  ID_COUNTER=8
  
  function get_counter()
      return u61_get_global(ID_COUNTER)
  end

u61_get_height

Declaration

  u61_get_height()

• Arguments: none.
• Return values: the height of the map.
• Rights: map_read.

Description

Returns the height of the map.

This function returns a value between 5 and 25. It is pretty much like the "u61_get_width" function, so please read the documentation of "u61_get_width" to understand why you should use this function.

Example

The following example colors the whole map, using the example function "colorize_row".

  function colorize_map(color)
      local y
  
      y=u61_get_height()-1
      while y>=0 do
          colorize_row(y,color)
          y=y-1 
      end
  end

u61_get_item_color

Declaration

  u61_get_item_color(i)

• Arguments: the index of the square.
• Return values: the color of the square.
• Rights: block_read

Description

Returns the color of a square in the block.

The color should normally always be a regular color (ie between 0 and 7), since having an empty square in a block does not really make any sense.

Example

The following function returns true if a given color is present in the block.

  function is_color_present(color)
      local i
      local present
  
      present=0
  
      i = u61_get_nb_items()-1
      while i>=0 do
          if u61_get_item_color(i)==color then
              present=1
          end
          i=i-1 
      end
  end

u61_get_item_x

Declaration

  u61_get_item_x(i)

• Arguments: the index of the square.
• Return values: the x coordinate of the square.
• Rights: block_read

Description

This function returns the x coordinate of a square in the block.

Note that the returned coordinate is not absolute. This means that if you want to have the real position of this square in the map, you'll have to call the "u61_get_block_x" function too and add the results.

Example

This function returns the width of a block, by getting the min and max x values.

  function get_block_width()
      local i
      local min_x
      local max_x
  
      min_x=1
      max_x=-1
  
      i = u61_get_nb_items()-1
      while i>=0 do
          x=u61_get_item_x(i)
          min_x=min(min_x,x)
          max_x=max(max_x,x)
          i=i-1 
      end
  
      return max_x-min_x
  end

u61_get_item_y

Exactly the same as "u61_get_item_x", but x becomes y...

u61_get_nb_antidotes

Declaration

  u61_get_nb_antidotes()

• Arguments: none.
• Return values: the number of antidotes available.
• Rights: map_read.

Description

This function returns the number of antidotes available. It is very similar to "u61_get_nb_curses".

The number of antidotes available is not updated by the C++ core engine. You need to give antidotes to players explicitly, by calling the "u61_add_antidote" function.

You can easily view the value this function would return by counting on the screen the number of little hearts (assuming you are playing with the default theme) in the status zone. Still, if there are too many antidotes available, only a limited number of them is displayed. Howvever, the "u61_get_nb_antidotes" will always return the exact value, even if it's too great to be displayed accurately.

Example

In this example, we increase the score of the player if he has more than 5 antidotes.

  function update_score()
      if u61_get_nb_antidotes()>=5 then
          u61_add_score(10)
      end
  end

u61_get_nb_curses

Declaration

  u61_get_nb_curses(good)

• Arguments: the type of curse to get information about.
• Return values: the number of persistent curses currently active.
• Rights: map_read.

Description

This function returns the number of persistent curses which have been set up with "u61_register_curse".

Calling it with a value of 0 will return you the number of "bad" curses, and calling it with a value of 1 will return the number of "good" curses. For more informations on bad and good curses, see "u61_register_curse".

You can easily view the value this function would return by counting on the screen the number of little skulls (assuming you are playing with the default theme) in the status zone. Still, if there are too many curses activated, only a limited number of them is displayed. Howvever, the "u61_get_nb_curses" will always return the exact value, even if it's too great to be displayed accurately.

Example

In this example, we decrease the score of the player if he is affected by more than 5 persistent curses.

  function update_score()
      if u61_get_nb_curses(0)>=5 then
          u61_add_score(-1)
      end
  end

u61_get_nb_items

Declaration

  u61_get_nb_items()

• Arguments: none
• Return values: the number of squares in the current block.
• Rights: block_read

Description

Returns the number of squares in the current block. It is very usefull if you want to program a loop on all the squares of the block.

If this function returns 4, it means that there are 4 squares available, which can be accessed with indexes 0,1,2 and 3. Any call outside this range to function like "u61_set_block_x" will simply do nothing.

Example

In the following example, the x and y coordinate of each square are exchanged.

  function flip_xy()
      local i
      local x
      local y
  
      i = u61_get_nb_items()-1
      while i>=0 do
          x=u61_get_item_x(i)
          y=u61_get_item_y(i)
          x,y=y,x
          u61_set_item_x(i,x)
          u61_set_item_y(i,y)
          i=i-1 
      end
  end

u61_get_oldest_curse

Declaration

  u61_get_oldest_curse(good)

• Arguments: the type of curse to get information about.
• Return values: the id of the oldest curse.
• Rights: map_read.

Description

This function returns the id of the oldest curse which has been set with "u61_register_curse".

Calling it with a value of 0 will return the oldest "bad" curse, and calling it with a value of 1 will return the oldest "good" curse. For more informations on bad and good curses, see "u61_register_curse".

It's important to be able to know rapidly which of the active persistent curses is the oldest one. A very simple example is a basic "user_use_antidote" where you want to remove a curse. You need a way to choose which one to delete. A possibility is to remove the oldest one, and this way the list of curse behaves like a FIFO (first in/first out) queue. And there you need the "u61_get_oldest_curse" function, or you would have to poll manually each curse to know his age and compare them...

The id returned by this function could typically be used with "u61_cancel_curse".

Example

In this example, we remove the oldest curse, except if it is the "ID_CURSE_BAD_LUCK" curse.

  ID_CURSE_BAD_LUCK=13
  
  function special_antidote()
      local curse
  
      curse=u61_get_oldest_curse(0)
   
      if curse~=ID_CURSE_BAD_LUCK then
          u61_cancel_curse(curse)
      end
  end

u61_get_preview_state

Declaration

  u61_get_preview_state()

• Arguments: none.
• Return values: true (1) if the preview should be displayed, of false(0).
• Rights: map_read.

Description

Returns the preview state of the player. The preview is what shows the player what kind of block he will get next time a block falls.

Unlike the anticipation state, the preview state can not be controlled from the menus. By default, it is set to true at the beginning of the game, and may be changed by calls to "u61_set_preview_state".

Example

This function gives more points to the player if preview state is off.

  function tweaked_add_score(points)
      if u61_get_preview_state()==1 then
          u61_add_score(2*points)
      else
          u61_add_score(points)
      end
  end

u61_get_score

Declaration

  u61_get_score()

• Arguments: none.
• Return values: the current score.
• Rights: map_read.

Description

This function returns the current score.

One important thing about the score is that it is set to 0 each time the game restarts. The core C++ engine knows what is the player's highest score, but it does not inform the script about it on purpose. In fact, different high scores might be displayed for the same player on different machines. This occurs when someone has been playing for hours and has luckily got a high score of 999999. Then a remote player decides to connect himself to the game. In this case, he will not be informed that there's someone with a 999999 high score. I don't consider it a bug since it has been designed like this. High scores and frags are counted differently on every machine. Indeed, each machine calculates the high scores according to what it sees. What has happened before does not count at all. No matter if the guy playing on the server has a high score of 999999, what you see if how much he managed to score playing with you.

Example

This example returns true if the score is greater than a given value.

  function is_score_enough(limit)
      local result
  
      result=0
  
      if u61_get_score()>=limit then
          result=1
      end
  end

u61_get_square_color

Declaration

  u61_get_square_color(x,y)

• Arguments: the coordinates of a square in the map.
• Return values: the color of the square.
• Rights: map_read.

Description

This function returns the color of a square in the map. The possible return values are:

• -1 if the square is not activated, ie there's no colored square at the given coordinates.
• 0-7 if there's a colored the square. There are 8 colors, ranging from 0 to 7.

This function is very important in the game, and you'll probably end up in using it all the time if you create scripts for U61. It is the best way to know if there's a square at a given position. You just have to call it and if it returns something greater than 0, then it means there's something.

It is important to note that it is quite different from "u61_get_item_color". Indeed, "u61_get_item_color" takes an index as a single argument, since the block is a vector of squares, whereas "u61_get_block_color" takes the coordinates of the square as an argument. This is because the map and block objects have fundamentaly different structures.

Example

In this example, we return 1 if there's a square at a given location, and 0 if there's none. This way we have a true/false function which tells us if the place is free.

  function is_there_a_square(x,y)
      local exists
  
      exists=0
  
      if u61_get_square_color(x,y)>=0 then
          exists=1
      end
  
      return exists
  end

u61_get_time

Declaration

  u61_get_time()

• Arguments: none.
• Return values: the current system time.
• Rights: map_read.

Description

This function returns the system time associated to the map. The unit is 0.01 sec, this means that 100 equals one second.

The time can be very usefull, you can for instance use it as a pseudo-random value. This is very important, since the use of any other random value in a script could raise serious problems. Indeed, in U61, all the computers make all the calculus about all the players. So if a script generates internally a random number, then the game may not behave the same on 2 computers which are linked during a network game. By using the time value, you are sure that your pseudo-random number will be exactly the same on any computer, so the game will behave correctly. To sum up, the only pseudo-random values that should be use in U61 are:

• The value returned by "u61_get_time".
• The value returned by "u61_get_score".
• The argument of "user_new_block".
• The argument of "user_new_shape".

The time is always positive, but you should not assume that games start at time 0. Indeed, when a player looses, the game ends, and another game starts, but there's no time reset. This is for the core C++ engine to handle messages correctly. Therefore, the time value can get very great.

Example

In this example, we use the time as a pseudo-random value. The result is a random number between 0 and range-1.

  function pseudo_random(range)
      return mod(u61_get_time(),range)
  end

u61_get_width

Declaration

  u61_get_width()

• Arguments: none.
• Return values: the width of the map.
• Rights: map_read

Description

Returns the width of the map.

This function returns a value between 2 and 10. In previous versions of U61 it used to return 10 all the time, since map size was not configurable. This is not the case anymore, and script programmers should not assume that map width is always 10 (the default value).

You might argue that since the map width is controlled by a user script (see u61_set_width), it's useless and cumbersome to call u61_get_width() when one knows that width is for instance of 8 because one called u61_set_width(8) before. My opinion is that it's much cleaner and less error prone to use u61_get_width() in all scripts.

Example

This function modify the color of a whole line in the map. Only the active colored squares are affected.

  function colorize_row(y,color)
      local x
  
      x=u61_get_width()-1
      while x>=0 do
          if u61_get_square_color(x,y)>=0 then
              u61_set_square_color(x,y,color)
          end
          x=x-1 
      end
  end

u61_is_block_ok

Declaration

  u61_is_block_ok()

• Arguments: none.
• Return values: 1 if the block is correctly placed, 0 if there's a conflict with the map.
• Rights: map_read, block_read.

Description

Returns true if the block is correctly placed, and has a correct shape. By "correct" we mean that:

• there are no squares in the block which are in conflict with the map squares, that's to say we could freeze the block as is without superposing a map square and a block square.
• there are no squares in the block that are outside the map, that's to say too much on the right, left or too low. If the block is too high it does not matter (think of when the block just start falling for instance, and you'll understand why it's obviously possible).

You may use this function when you want to move the block in a complex manner, or completely change it, and really need to keep an accurate control on what's happening. Indeed, this function is called very often by the C++ core engine, and for instance it's perfectly useless to call it in functions like "user_move_down" for instance, since the check is already performed, and you'll only slow down the game by calling it twice.

But a good example of when "u61_is_block_ok" is usefull is a script that needs to make the block cross the entire map, or move it for say at least 10 squares. Then the C++ core engine won't be able to detect if there are squares between the initial and final position. All what the C++ core engine is aware of is the initial and final positions. So this way the block might (from the player point of view) go through a solid wall, which is not what the scripter wants. The scripter wants the block to stop if there's a wall. So what he'll have to do is move the block by steps of 1 square and call "u61_is_block_ok" each time and stop if there's a problem.

It's usually not a problem if at the end of the script function you leave the block in an incorret state, with a conflict. Since the C++ core engine performs himself a check, he will move the block up or sideways so that it fits, or sometimes perform a plain rollback and cancel all your script functions. But if you want to control exactly what's happening, then you'll have to do it yourself in your script.

Example

In this example, the block is moved in both directions x and y, only if there are no squares on its path. The block is left in an incorrect state but this is not a problem since the C++ core engine will automatically cure the problem.

  function translation_yx_safe(n)
      local i
  
      i=n
      while i>0 do
          u61_translate_x(1)
  	u61_translate_y(1)
          if u61_is_block_ok()==0 then
              i=0
          end
          i=i-1 
      end
  end

u61_is_curse_available

Declaration

  u61_is_curse_available()

• Arguments: none.
• Return values: 1 if there is actually a special curse square on the map,0 if there is none.
• Rights: map_read.

Description

Returns true if there's a special curse square available, that's to say if the "curse state" parameter is set to true *and* the curse square is located on an active square in the map.

This function is very different from "u61_get_curse_state". Indeed, if the special curse square is badly placed, or if it is impossible to place it correctly, for instance when there are no squares at all, then you might get a situation where "u61_get_curse_state" returns true and "u61_is_square_available" returns false. For instance, this is often the case when a new game starts, since there are no squares on the map, and by default the "curse state" parameter is set to true.

Example

In this example, we return true if we the special curse square is badly placed, ie when "u61_get_curse_state" and "u61_is_curse_available" do not return the same value.

  function is_curse_badly_placed()
      local result
  
      result=0
  
      if u61_get_curse_state()==1 and u61_is_curse_available()==0 then
          result=1
      end
  
      return result
  end

u61_is_square_exploding

Declaration

  u61_is_square_exploding(x,y)

• Arguments: the coordinates of a square in the map.
• Return values: 1 if the square is exploding, 0 if not.
• Rights: map_read.

Description

This function tells if the square is exploding, that's to say if the player can see an explosion at this location.

When this function is called, the square is "still there". Im mean that it is still possible to test its color for instance. Basically, a square is in the exploding state after "u61_blow_up_square" and before "u61_square_blown_up" have been called.

Example

This function counts all the exploding squares from the map.

  function count_explosions()
      local x
      local y
      local count
  
      count=0
  
      y=u61_get_height()-1
      while y>=0 do
          x=u61_get_width()-1 
          while x>=0 do
              if not (u61_is_square_exploding(x,y)==0) then
                  count=count+1
              end
              x=x-1 
          end
          y=y-1
      end    
  
      return count
  end

u61_register_curse

Declaration

  u61_register_curse(curse,time,good)

• Arguments: the id of a curse, the time it should last, and the kind of curse it is.
• Return values: none.
• Rights: map_write.

Description

This function registers the curse, ie it adds it to the list of active curses. The curse will be active for a limited time, counted in 1/100 of seconds, but a value of 0 should make it last forever - or at least most player won't notice the difference since if you use 0 the curse will last for about 10 hours...

Used with the "u61_get_curse_age", this function allows you program "persistent" curses. By persistent curse I mean a curse which is displayed in the player's status zone (represented with a little skull in the default theme) and can be cancelled by an antidote. A typical non-persistent curse is a curse that fills your map with grabage. A typical persistent curse is the curse that forbids you to use some of your keyboard keys.

Curses set up with "u61_register_curse" can be cancelled manually with "u61_cancel_curse". Otherwise they will disappear automatically after some time.

The third parameter allows you to choose wether the curse is a real bad curse or if it's a "good" curse. Basically, it's up to you to decide which curses are good and which aren't. Basically a curse that accels the player is a bad one, and one that slows the player is a good one, since it makes the game easier. So in fact a "good" curse is an "anti-curse", it's a benediction opposed to a malediction. For U61's C++ engine, the only difference between good curses and bad curses is that the icons used to represent them on the screen are not the same.

Example

In this example, we have defined a function that handles remote curses (see the definition of "u61_send_curse"). And if the curse id is greater than 50, then we assume the curse is a persistent one, so we set it up for a time of 6000, that's to say about 1 minute.

  function my_handle_remote_curse(curse)
      if curse>50 then
          u61_register_curse(curse,6000,0)
      end
  end

u61_send_curse

Declaration

  u61_send_curse(curse)

• Arguments: the id of a curse.
• Return values: none.
• Rights: map_write.

Description

This function sends a curse to the default victim of the current player.

It is probably one the most interesting function in U61. At least it is definitely *the* function which makes U61 a cool (?) game. Basically, this function sends a message over the network - if needed of course - to a remote player, and on the remote machine, the "user_do_curse" function is called. This allows a player to alter the map of another player.

A mojor pitfall is to get confused with the difference between what I call a local curse and a remote curse:

• A local curse is issued when the special "curse square" explodes for instance. The consequence is a call to "user_do_curse" in the map where the square disappeared with the second parameter set to 0. In most of the cases, a local curse will do something positive on the player's map, such as clearing it.
• A remote curse is issued after an explicit call to "u61_send_curse". The consequence is a call to "user_do_curse" in the map of the default victim (the name of the victim is displayed in the player's status zone), with the second parameter set to 1. Any script code that has a "map_write" access may call "u61_send_curse". This way, remote curses can be launched in many situations. In most of the cases, a remote curse will do something negative on the player'smap, such as filling it with garbage.

Example

In this example, the player sends a "SPECIAL_CURSE_1" and a "SPECIAL_CURSE_2" to its default victim. This function might be called within "user_do_curse", but it'snot necessary, you could also call it when the player has matched a very rare pattern.

  SPECIAL_CURSE_1=51
  SPECIAL_CURSE_2=52
  
  function send_special_package()
      u61_send_curse(SPECIAL_CURSE_1)
      u61_send_curse(SPECIAL_CURSE_2)
  end

u61_set_anticipation_state

Declaration

  u61_set_anticipation_state(state)

• Arguments: a boolean (1 or 0) telling if this mode should be on or off.
• Return values: one.
• Rights: map_write.

Description

This function sets the state of the anticipation mode, that means wether the player should see where the block will land if he presses the "drop" key right away.

As mentionned in the doc of "u61_get_anticipation_state", this parameter is mixed with the value entered by the player in the menus, and the preview of where the block will land is drawn only if both are true. Basically, it should be easier to play with this mode set to true, but some players (me for instance) find that in the long run it's not so great to have it set on. So in your scripts, you might decide that a curse disables this mode (to make the game harder) and enables it back when the curse is over. But for players like me who do not like the anticipation mode, it would be annoying to see this mode appearing when I have said in my options that I do not want to have it. So it's OK to call this function with false if you want to make things a little harder, but just remember that it will do nothing on players who have the option set to false anyway.

Example

In this example, we set the mode to false or true according to a curse state.

  ID_HALF_BLIND=8
  
  function update_half_blind()
      if u61_get_curse_age(ID_HALF_BLIND)>=0 then
          u61_set_anticipation_state(0) 
      else
          u61_set_anticipation_state(1)
      end
  end

u61_set_block_x

Declaration

  u61_set_block_x(x)

• Arguments: The x coordinate of the block.
• Return values: None
• Rights: block_write

Description

This function changes the global x coordinate of the block. Basically, it allows translation.

This function is very important, since it's not possible to perform a translation by calling "u61_set_item_x". Indeed, the "u61_center_block", which is called quite often, modifies the individual coordinates of each squares in a block so that it's centered on (x,y), x and y being set by "u61_set_block_x" and "u61_set_block_y". So you *need* to call this function if you want to translate the block horizontally.

Example

In this example, we move the block to the middle of the map.

  function to_middle()
      u61_set_block_x(5) 
  end

u61_set_block_y

Exactly the same as "u61_set_block_x", but x becomes y...

u61_set_curse_state

Declaration

  u61_set_curse_state(state)

• Arguments: 1 if the special curse square is to be activated, 0 if not.
• Return values: none.
• Rights: map_write.

Description

Sets the current "curse state", ie tells if there should be a special curse square available on the map.

As I'm writting this document, the "curse_state" parameter is set to true on a regular basis, so if you really want to remove the curse permanently, you have to call "u61_set_curse_state" continuously. By default, the curse will be disable for a given time (corresponding to a curse period, that's to say the delay until the curse moves and/or changes).

Example

In this example, we disable the special curse square when the user has more than 100000 points. This should prevent scores from getting too high...

  function limit_score_with_curse()
      if u61_get_score()>100000 then
          u61_set_curse_state(0)
      end
  end

u61_set_curse_x

Declaration

  u61_set_curse_x(x)

• Arguments: the x coordinate of the special curse square.
• Return values: none.
• Rights: map_write.

Description

Sets the x position of the special curse square - that's to say the square which launches curses when it explodes, in the default theme it is the black and white "?".

Note that if you call this function with an invalid parameter, ie a position which is outside the map or where there's no active square, then the special curse square won't be visible. In fact, you'll end up in a situation where "u61_get_curse_state" returns true and "u61_is_curse_available" returns false, even if you have set the curse square as active with "u61_set_curse_state".

You should also keep in mind that it's not really necessary to call this function to move the curse square on a regular basis, since this is already done by the C++ core engine. In fact, this function is usefull when you mess up the whole map with calls to "u61_set_square_color", remove accidentally the square which was at the special square's location, and still want the special square to be available. In this case, you have to move the special curse square manually.

Example

In this example, we put the curse square on the first active square founded. The search starts at the bottom of the map.

  function put_curse_on first()
      local x
      local y
  
      y=u61_get_height()-1
      while y>=0 do
          x=u61_get_width()-1 
          while x>=0 do
              if u61_get_square_color(x,y)>=0 then
                  u61_set_curse_x(x)
                  u61_set_curse_y(y)
                  x=-1
                  y=-1
              end
              x=x-1 
          end
          y=y-1
      end    
  end

u61_set_curse_y

Exactly the same as "u61_set_curse_x", but x becomes y...

u61_set_global

Declaration

  u61_set_global(i,value)

• Arguments: an index and a value.
• Return values: none.
• Rights: map_write.

Description

This function updates the global value associated to a given index (between 0 and 99).

This function is by no way related to the luac "setglobal" function. Indeed, in U61, you must *not* use any global lua variable to store parameters. Lua globals can only be used to store constants. This is due to the fact that if you use global lua variables:

• They will be shared by all the players, which might not be what you want.
• They won't be shared accross the network, since the core engine does not transmit lua globals between computers.

Therefore, the chances that you end up with a wrecked game are important. Please do not try to do it, for this kind of bug never appears when you test your script with a single player, but will always occur during a thrilling internet play. See Murphy's theory.

So "u61_get_global" and "u61_set_global" are here to help you in case you want to have a persistent value stored. The values accessed with these functions are different for each player, and do not generate any inconsistency when used in a network game. Basically thay consist in a array of numbers, where you can store your own values, for instance parameters linked to a curse. These numbers are set to 0 each time a new game starts, ie each time the map is filled with squares and the player looses.

As of today, numbers are the only lua type which is usable with this function. It's actually a severe limitation, since being possible to store any lua object would make the writting of scripts a lot easier. However, I haven't yet managed to find a nice solution to this problem. It's true that lua offers the possibility to get a reference on any object, but I fear such a method would lead to memory problems - at least until I or someone else finds a way to handle references in a clean manner.

Please keep in mind that if you want to use a global value such as a boolean telling if the player has the right to do some special action, then "u61_register_curse" might be a better choice than "u61_set_global".

Example

The following function decrements the value of a global counter.

  ID_COUNTER=8
  
  function decrement_counter()
      u61_set_global(ID_COUNTER,u61_get_global()-1)
  end

u61_set_height

Declaration

  u61_set_height(h)

• Arguments: the new map height.
• Return values: none.
• Rights: map_write

Description

Changes the height of the map.

This function can safely be called "on the fly" while a player is playing and moving his block arround. All present squares will automatically be shifted so that the bottom squares stay at the bottom after resizing.

The height can range from 5 to 25. Note that depending on the block size, resizing the map to a "too small" size might make it simply impossible to play at all. Use with caution!

Example

The following function divides the height by 2:

  function half_height()
      u61_set_height(u61_get_height()/2)
  end

u61_set_item_color

Declaration

  u61_set_item_color(i,color)

• Arguments: the index and color of the square.
• Return values: none.
• Rights: block_write

Description

Modifies the color of a square in the block.

The color should normally always be a regular color (ie between 0 and 7), since having an empty square in a block does not really make any sense.

Example

The following example sets all the squares of the block to the given color.

  function set_color(color)
      local i
  
      i = u61_get_nb_items()-1
      while i>=0 do
          u61_set_item_color(i,color)
          i=i-1 
      end
  end

u61_set_item_x

Declaration

  u61_set_item_x(i,x)

• Arguments: the index of the square, and its x coordinate.
• Return values: none.
• Rights: block_write

Description

This function modifies the x coordinate of a square in the block.

Note that the returned coordinate is not absolute. This means that if you want to set the real position of this square in the map, you'll need to call the "u61_get_block_x" function too.

Example

This function sets the absolute position of a square in the block, ie its position in the map. So wherever the block may be, calling "set_absolute_x(0,0)" will place the first square of the block in the leftmost column of the map.

  function set_absolute_x(i,x)
      u61_set_item_x(i,x-u61_get_block_x())
  end

u61_set_item_y

Exactly the same as "u61_set_item_x", but x becomes y...

u61_set_preview_state

Declaration

  u61_set_preview_state(state)

• Arguments: the state for the preview mode (1=on, 0=off).
• Return values: none.
• Rights:

Description

Sets the preview state of the player. The preview is what shows the player what kind of block he will get next time a block falls.

This function would typically used in a curse, to remove the great help provided by the preview, and put the player in a difficult position.

Example

This example sets the preview mode to false if the score is greater than 100000. It assumes that any player capable of getting such a high score is good enough to play without a preview.

  function disable_preview_for_good_players()
      if u61_get_score()>100000 then
          u61_set_preview_state(0)
      end
  end

u61_set_score

Declaration

  u61_set_score(score)

• Arguments: the new score.
• Return values: none.
• Rights: map_write.

Description

This function updates the current score.

You'll have to remember that scores should not exceed 999.999, so that they can fit on 6 digits. However, if you exceed this limit, the value will be truncated to 999.999 anyway.

Example

The following example doubles the score of the player.

  function double_score()
      u61_set_score(u61_get_score()*2)
  end

u61_set_square_color

Declaration

  u61_set_square_color(x,y,color)

• Arguments: the coordinates of a square, and its color.
• Return values: none.
• Rights: map_write.

Description

This function sets the color of a square in the map. The possible values for color are:

• -1 if the square is to be disabled.
• 0-7 if one whishes to put a colored square in this location.

Any call with an invalid color (lower than 0 or greater than 7) will result in setting the color to -1. The question is: "why should the game be limited to 8 colors?". well, in fact, I had to fix a limited number of colors, since theme creation would have been too complex with a flexible number of colors. Indeed, you would have risked to get a 16-color based script with an 8-color based theme. And then you can't play since you can not distinguish all types of squares. So I had to set up a limit. I chose 8 and think it's a good compromise between rich gameplay and easyness of theme creation.

In the scripts and themes I have created, I have tried to respect the following rules:

• Colors 0-6 are standard colors for blocks.
• Color 7 is a special color, used for squares that are generated by curses and which in a general manner don't come with standard blocks. In the "classic" theme, theses are the grey squares.

However, this is just a convention, and you can bypass it. Still, players might find the game more consistent if you respect it,

Example

This example moves all the squares from the current block to the map. This is what is done before the "user_match_pattern" function is called. However, you should never need such a function - it's only an example - since this work is automatically done by the C++ core engine.

  function block_to_map()
      local i
      local x
      local y
      local color
  
      i = u61_get_nb_items()-1
      while i>=0 do
          x=u61_get_item_x(i)+u61_get_block_x(i)
          y=u61_get_item_y(i)+u61_get_block_y(i)
          color=u61_get_item_color(i)
          u61_set_square_color(x,y,color)
          i=i-1
      end
      u61_clear_block()
  end

u61_set_width

Declaration

  u61_set_width(w)

• Arguments: the new map width.
• Return values: none.
• Rights: map_write

Description

Changes the width of the map.

This function can safely be called "on the fly" while a player is playing and moving his block arround. All present squares will automatically be shifted and/or deleted so that they are globally "in the middle" of the resized map.

The width can range from 2 to 10. Note that depending on the block size, resizing the map to a "too small" size might make it simply impossible to play at all. Use with caution!

Example

The following function doubles the width of the map:

  function double_width()
      u61_set_width(u61_get_width()*2)
  end

u61_shift_map

Declaration

  u61_shift_map(x,y)

• Arguments: 2 integers which define how squares will be translated.
• Return values: none.
• Rights: map_write

Description

Shifts/translates all the map squares.

This function can be usefull when you've just resized a map and/or want to move all the squares in the map at once. Note that it's automatically called whenever the map is resized, still the default behaviour might not be the one you expect.

Squares which are outside the map limits after being translated are simply deleted/ignored.

Example

The following function shifts the map down:

  function shift_down()
      u61_shift_map(0,1)
  end