U61 (v0.4.1) - Script library reference




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


  The library functions are Lua functions I have created and they are used by
  the scripts which are distributed with U61.

  Basically, you could create your own set of rules from scratch, by filling
  user callbacks with pure calls to the core API. I honestly think it's too bad
  not to re-use some of the work I've already done. So a more reasonnable
  approach would be, in my opinion, to take an existing script and modify it
  until it fits your need. And this section's goal is to provide a
  documentation on what I have programmed my own scripts.

  Basically, this section has 2 goals:

  * Give an overview of what alreayd exists, and where to find it. For
    instance, if you want to modify a curse in the "classic" set of rules, you
    might find here in which file this curse is coded, and what resources it
    uses.

  * Set up some coding guidelines. Of course since U61 is GPL'ed, you can
    modify the code the way you want. However, experience shows that no project
    can survive without a minimum of rules. Most of the rules I usein scripting
    for U61 are based on common sense and should not surprise anyone.

  If you look in the "u61-data" package, you'll find 2 subdirectories:
  "library" and "package":

  * "library" contains most of the code, which is split in several modules,
    each ".lua" file being one of these modules.

  * "package" defines the user callbacks. Each package requires functions from
    the library. The idea is that you can create multiples packages which rely
    on the same library modules. This way, when a library module gets some
    bug-fix or improvement, all the packages that uses it can benefit from the
    update.



Coding guidelines
=================


  Why?
  ----

    If you code new scripts for U61, and want them included in the main U61
    release, I'd really appreciate that you respect some basic rules, which
    should make the code easier to maintain. This is not to forbid you anything
    and should not endanger your freedom (remember the game is GPL'ed) but
    without a minimum of organization, I'm pretty sure it will be impossible to
    maintain an important database of scripts. And I'd just love it if zillions
    of Lua scripts for U61 could be available on the net.

  Files
  -----

    I never build complete U61 rules within a single file. The method I use is
    to create many little files and then cat them together. Of course if you
    are trying new features, it might be usefull to take an existing script,
    for instance "classic.lua", and edit it directly. And if you want to share
    this script with other people, you can put it on ftp for download without
    even asking me. BTW, if you do that, a good idea would be to rename the
    script. Indeed, in a network game, clients can automatically save the
    server script on their hard drive, and they might get confused if there are
    33 different "classic.lua" scripts. So "booby-classic5.lua" would certainly
    be a much better file name.

    But if you write some script and want me to include it in U61's main
    distribution, then it will truely make things easier for me if you use the
    method I used. If you want to look how I have set up my scripts, please
    look in the "script" folder of the "u61-data" package.

    As of today, if I ever get enough contributed scripts, this is what I'll
    do:

    * Original and well done scripts will be included in the main distribution,
      that's to say they'll be added to the current scripts, and will use the
      "library-package" structure.

    * Any other other script, as long as it works (no Lua errors, game
      launchable), will go in a "u61-contrib" package which will contain raw
      scripts, saved as is.

    Of course, as I already mentionned, this is not limitative, if you want to
    make your own U61 distribution you can do it, as long as it's still GPL'ed.
    However I'm ready to collect scripts and coordinate the whole project, so
    you're free to accept my offer or not 8-)

  Functions
  ---------

    Functions should always be prefixed with the name of the file they are in.
    This applies to all functions which are defined in the "library" directory.
    This way, there should never be any conflict between function names.
    Basically:

    * Script callback functions are prefixed with "user_".

    * Script API functions are prefixed with "u61_".

    * Script library functions are prefixed with "filename_". So a function
      which is defined in "supercurse.lua" could be name
      "supercurse_hello_world" for instance. BTW, this implies there should not
      be any "_" in file names, so that it easier to figure out where the
      filename ends.

  Constants
  ---------

    Global constants should always be prefixed with "ID_". As of today, there
    are 2 types of constants in U61:

    * Curse indexes. They are prefixed by "ID_CURSE_".

    * Global indexes. They are prefixed by "ID_GLOBAL_".



Modules
=======


  What's this?
  ------------

    Since I do not have the time to document all the script library functions
    in detail, I have decided to provide (at least) a list of the different
    modules available, and give a short description of what they do. If you
    want to know more about them, read the code!

  antedote.lua
  ------------

    Contains the code for the "ANTEDOTE" curse, which gives an antedote to the
    player.

  bigx.lua
  --------

    Contains the code for the "BUGX" curse. The curse replaces the current
    block by a big X shape.

  boost.lua
  ---------

    Contains the code for the "BOOST" curse, which makes the blocks fall very
    fast for a few seconds.

  clear.lua
  ---------

    Contains the code for the "CLEAR" curse. This curse clears the map, ie
    removes all the squares.

  color.lua
  ---------

    Contains function to match color patterns, such as aligned squares of the
    same color.

  colored.lua
  -----------

    Contains code to generate colored bars, as in the "vertical" set of rules.

  connected.lua
  -------------

    Contains a powerfull - but yet the code is ugly 8-} - match function, which
    search any tetramino, pentamino, hexamino. Well, in fact it just recognizes
    any sequence of adjacent squares of the same color.

  drop.lua
  --------

    Contains the code for the "DROP" curse, which forces the block to be
    dropped.

  cycle.lua
  ---------

    Contains some functions to shift the colors of the block. This can be an
    alternative to geometrical rotations when the rules are heavily based on
    colors.

  fiftytwo.lua
  ------------

    Contains the code for the "FIFTYTWO" curse. When affected by this curse,
    the user will only get "5" and "2" like tetraminos.

  goofy.lua
  ---------

    Contains the code for the "GOOFY" curse. This curse inverts the left and
    right commands.

  haha.lua
  --------

    Contains the code for the "HAHA" curse. This curse writes "HA HA" in the
    map.

  holedline.lua
  -------------

    Contains the code for the "HOLEDLINE" curse. This curse adds a line with a
    missing square at the bottom of the map.

  line.lua
  --------

    Contains the code to match a line pattern. This means that it detects
    whenever there's a completed horizontal line of squares, of any color.

  metamorphose.lua
  ----------------

    Contains the code for the "METAMORPHOSE" curse. It changes the current
    block to another block.

  mixedline.lua
  -------------

    Contains the code for the "MIXEDLINE" curse. It adds a colored line at the
    bottom of the map.

  morecolors.lua
  --------------

    Contains the code for the "MORECOLORS" curse. This curse causes some
    functions to use 7 colors instead of 6, which can sometimes make the game
    harder.

  nohands.lua
  -----------

    Contains the code for the "NOHANDS" curse. This curse disables the control
    of the block, like if keyboard was disabled.

  rotation.lua
  ------------

    Contains some functions to perform geometrical rotations.

  shuffle.lua
  -----------

    Contains the code for the "SHUFFLE" curse. This curse shuffles the map so
    that evrything gets messy.

  sides.lua
  ---------

    Contains the code for the "SIDES" curse. This curse moves the block to the
    right or left of the map.

  split.lua
  ---------

    Contains the code to "split" a block as it lands. It is used for instance
    in the "user_land" callback in the "couple" set of rules.

  stairs.lua
  ----------

    Contains the code for the "STAIRS" curse. This curse draws stairs on the
    map.

  tetramino.lua
  -------------

    Contains the code to generate tetraminos. Tetraminos are blocked formed of
    4 squares.

  topdown.lua
  -----------

    Contains the code for the "TOPDOWN" curse, which inverts the map, ie puts
    the blocks that were at the bottom on top.

  topholedline.lua
  ----------------

    Contains the code for the "TOPHOLEDLINE" curse, which puts 2 lines with
    holes in them at the top of the map.

  translation.lua
  ---------------

    Contains some functions to perform translations of the block without
    calling 2 API functions (a "get" and a "set").

  utils.lua
  ---------

    Contains various utility fonctions, which are not linked to any peculiar
    curse or set of rules.

  wind.lua
  --------

    Contains the code for the "WIND" curse. This curse causes the block to move
    on the left on a regular basis.



Constants
=========


  What's this?
  ------------

    This section describes the constants used in the scripts. As you can see,
    these constants are all defined in capitals, and I used the "ID_" prefix
    for all of them. I suggest you do the same if you add some, it should keep
    things simpler 8-)

    I won't describe how these constants work in detail, I just give the name
    of the constants and their value. Please do not assume that, for instance,
    ID_CURSE_GOOFY is equal to 1, for these values may change some day. The
    right method when you need a new constant is to pickup a free number,
    assign it to a variable with a readable name, and then always use this
    variable.

  Curses
  ------

    * 0 : ID_CURSE_ANTEDOTE

    * 1 : ID_CURSE_HOLEDLINE

    * 2 : ID_CURSE_GOOFY

    * 3 : ID_CURSE_CLEAR

    * 4 : ID_CURSE_SHUFFLE

    * 5 : ID_CURSE_WIND

    * 6 : ID_CURSE_FIFTYONE

    * 7 : ID_CURSE_BIGX

    * 8 : ID_CURSE_MIXEDLINE

    * 9 : ID_CURSE_MORECOLORS

    * 10 : ID_CURSE_BOOST

    * 11 : ID_CURSE_DROP

    * 12 : ID_CURSE_TOPDOWN

    * 13 : ID_CURSE_TOPHOLEDLINE

    * 14 : ID_CURSE_STAIRS

    * 15 : ID_CURSE_HAHA

    * 16 : ID_CURSE_NOHANDS

    * 17 : ID_CURSE_METAMORPHOSE

    * 18 : ID_CURSE_SIDES

  Globals
  -------

    * 0 : ID_GLOBAL_WIND_COUNTER

    * 1 : ID_GLOBAL_WIND_BLOCK_X

