src/script/api/script_base.hpp

   1 /* $Id: script_base.hpp 25148 2013-04-06 11:59:27Z rubidium $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file script_base.hpp Everything to query basic things. */
  11
  12 #ifndef SCRIPT_BASE_HPP
  13 #define SCRIPT_BASE_HPP
  14
  15 #include "script_object.hpp"
  16
  17 /**
  18  * Class that handles some basic functions.
  19  * @api ai game
  20  *
  21  * @note The random functions are not called Random and RandomRange, because
  22  *        RANDOM_DEBUG does some tricky stuff, which messes with those names.
  23  * @note In MP we cannot use Random because that will cause desyncs (scripts are
  24  *        ran on the server only, not on all clients). This means that
  25  *        we use InteractiveRandom in MP. Rand() takes care of this for you.
  26  */
  27 class ScriptBase : public ScriptObject {
  28 public:
  29         /**
  30          * Get a random value.
  31          * @return A random value between 0 and MAX(uint32).
  32          */
  33         static uint32 Rand();
  34
  35         /**
  36          * Get a random value.
  37          * @param unused_param This parameter is not used, but is needed to work with lists.
  38          * @return A random value between 0 and MAX(uint32).
  39          */
  40         static uint32 RandItem(int unused_param);
  41
  42         /**
  43          * Get a random value in a range.
  44          * @param max The first number this function will never return (the maximum it returns is max - 1).
  45          * @return A random value between 0 .. max - 1.
  46          */
  47         static uint RandRange(uint max);
  48
  49         /**
  50          * Get a random value in a range.
  51          * @param unused_param This parameter is not used, but is needed to work with lists.
  52          * @param max The first number this function will never return (the maximum it returns is max - 1).
  53          * @return A random value between 0 .. max - 1.
  54          */
  55         static uint RandRangeItem(int unused_param, uint max);
  56
  57         /**
  58          * Returns approximately 'out' times true when called 'max' times.
  59          *   After all, it is a random function.
  60          * @param out How many times it should return true.
  61          * @param max Out of this many times.
  62          * @pre \a out is at most equal to \a max.
  63          * @return True if the chance worked out.
  64          */
  65         static bool Chance(uint out, uint max);
  66
  67         /**
  68          * Returns approximately 'out' times true when called 'max' times.
  69          *   After all, it is a random function.
  70          * @param unused_param This parameter is not used, but is needed to work with lists.
  71          * @param out How many times it should return true.
  72          * @param max Out of this many times.
  73          * @pre \a out is at most equal to \a max.
  74          * @return True if the chance worked out.
  75          */
  76         static bool ChanceItem(int unused_param, uint out, uint max);
  77 };
  78
  79 #endif /* SCRIPT_BASE_HPP */