1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/timers.inc Sun Jul 06 04:49:55 2008 +0000
1.3 @@ -0,0 +1,208 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 + * =============================================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK.
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify it under
1.13 + * the terms of the GNU General Public License, version 3.0, as published by the
1.14 + * Free Software Foundation.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 + * details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License along with
1.22 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 + *
1.24 + * As a special exception, AlliedModders LLC gives you permission to link the
1.25 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 + * by the Valve Corporation. You must obey the GNU General Public License in
1.28 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 + * this exception to all derivative works. AlliedModders LLC defines further
1.30 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 + * or <http://www.sourcemod.net/license.php>.
1.32 + *
1.33 + * Version: $Id$
1.34 + */
1.35 +
1.36 +#if defined _timers_included
1.37 + #endinput
1.38 +#endif
1.39 +#define _timers_included
1.40 +
1.41 +#include <datapack>
1.42 +
1.43 +#define TIMER_REPEAT (1<<0) /**< Timer will repeat until it returns Plugin_Stop */
1.44 +#define TIMER_FLAG_NO_MAPCHANGE (1<<1) /**< Timer will not carry over mapchanges */
1.45 +#define TIMER_HNDL_CLOSE (1<<9) /**< Timer will automatically call CloseHandle() on its value when finished */
1.46 +
1.47 +/**
1.48 + * Any of the following prototypes will work for a timed function.
1.49 + */
1.50 +funcenum Timer
1.51 +{
1.52 + /**
1.53 + * Called when the timer interval has elapsed.
1.54 + *
1.55 + * @param timer Handle to the timer object.
1.56 + * @param hndl Handle passed when the timer was created.
1.57 + * @return Plugin_Stop to stop a repeating timer, any other value for
1.58 + * default behavior.
1.59 + */
1.60 + Action:public(Handle:timer, Handle:hndl),
1.61 +
1.62 + /**
1.63 + * Called when the timer interval has elapsed.
1.64 + *
1.65 + * @param timer Handle to the timer object.
1.66 + * @param value Value passed when the timer was created.
1.67 + * @return Plugin_Stop to stop a repeating timer, any other value for
1.68 + * default behavior.
1.69 + */
1.70 + Action:public(Handle:timer, any:value),
1.71 +
1.72 + /**
1.73 + * Called when the timer interval has elapsed.
1.74 + *
1.75 + * @param timer Handle to the timer object.
1.76 + * @return Plugin_Stop to stop a repeating timer, any other value for
1.77 + * default behavior.
1.78 + */
1.79 + Action:public(Handle:timer),
1.80 +};
1.81 +
1.82 +/**
1.83 + * Creates a basic timer. Calling CloseHandle() on a timer will end the timer.
1.84 + *
1.85 + * @param interval Interval from the current game time to execute the given function.
1.86 + * @param func Function to execute once the given interval has elapsed.
1.87 + * @param value Handle or value to give to the timer function.
1.88 + * @param flags Flags to set (such as repeatability or auto-Handle closing).
1.89 + * @return Handle to the timer object. You do not need to call CloseHandle().
1.90 + * If the timer could not be created, INVALID_HANDLE will be returned.
1.91 + */
1.92 +native Handle:CreateTimer(Float:interval, Timer:func, any:value=INVALID_HANDLE, flags=0);
1.93 +
1.94 +/**
1.95 + * Kills a timer. Use this instead of CloseHandle() if you need more options.
1.96 + *
1.97 + * @param autoClose If autoClose is true, the timer's value will be
1.98 + * closed as a handle if TIMER_HNDL_CLOSE was not specified.
1.99 + * @noreturn
1.100 + */
1.101 +native KillTimer(Handle:timer, bool:autoClose=false);
1.102 +
1.103 +/**
1.104 + * Manually triggers a timer so its function will be called.
1.105 + *
1.106 + * @param timer Timer Handle to trigger.
1.107 + * @param reset If reset is true, the elapsed time counter is reset
1.108 + * so the full interval must pass again.
1.109 + * @noreturn
1.110 + */
1.111 +native TriggerTimer(Handle:timer, bool:reset=false);
1.112 +
1.113 +/**
1.114 + * Returns the simulated game time.
1.115 + *
1.116 + * This time is internally maintained by SourceMod and is based on the game
1.117 + * tick count and tick rate. Unlike GetGameTime(), it will increment past
1.118 + * map changes and while no players are connected. Unlike GetEngineTime(),
1.119 + * it will not increment based on the system clock (i.e. it is still bound
1.120 + * to the ticking process).
1.121 + *
1.122 + * @return Time based on the game tick count.
1.123 + */
1.124 +native Float:GetTickedTime();
1.125 +
1.126 +/**
1.127 + * Returns an estimate of the time left before the map ends. If the server
1.128 + * has not processed any frames yet (i.e. no players have joined the map yet),
1.129 + * then the time left returned will always be infinite.
1.130 + *
1.131 + * @param timeleft Variable to store the time, in seconds. If the
1.132 + * value is less than 0, the time limit is infinite.
1.133 + * @return True if the operation is supported, false otherwise.
1.134 + */
1.135 +native bool:GetMapTimeLeft(&timeleft);
1.136 +
1.137 +/**
1.138 + * Retrieves the current map time limit. If the server has not processed any
1.139 + * frames yet (i.e. no players have joined the map yet), then the time limit
1.140 + * returned will always be 0.
1.141 + *
1.142 + * @param time Set to the number of total seconds in the map time
1.143 + * limit, or 0 if there is no time limit set.
1.144 + * @return True on success, false if operation is not supported.
1.145 + */
1.146 +native bool:GetMapTimeLimit(&time);
1.147 +
1.148 +/**
1.149 + * Extends the map time limit in a way that will notify all plugins.
1.150 + *
1.151 + * @param time Number of seconds to extend map time limit by.
1.152 + * The number can be negative to decrease the time limit.
1.153 + * If 0, the map will be set to have no time limit.
1.154 + * @return True on success, false if operation is not supported.
1.155 + */
1.156 +native bool:ExtendMapTimeLimit(time);
1.157 +
1.158 +/**
1.159 + * Returns the number of seconds in between game server ticks.
1.160 + *
1.161 + * Note: A tick, in this context, is a frame.
1.162 + *
1.163 + * @return Number of seconds in between ticks.
1.164 + */
1.165 +native Float:GetTickInterval();
1.166 +
1.167 +/**
1.168 + * Notification that the map's time left has changed via a change in the time
1.169 + * limit or a change in the game rules (such as mp_restartgame). This is useful
1.170 + * for plugins trying to create timers based on the time left in the map.
1.171 + *
1.172 + * Calling ExtendMapTimeLimit() from here, without proper precaution, will
1.173 + * cause infinite recursion.
1.174 + *
1.175 + * If the operation is not supported, this will never be called.
1.176 +
1.177 + * If the server has not yet processed any frames (i.e. no players have joined
1.178 + * the map yet), then this will be called once the server begins ticking, even
1.179 + * if there is no time limit set.
1.180 + */
1.181 +forward OnMapTimeLeftChanged();
1.182 +
1.183 +/**
1.184 + * Returns whether or not the server is processing frames or not.
1.185 + *
1.186 + * The server does not process frames until at least one client joins the game.
1.187 + * Once the first player has in, even if that player, leaves, the server's
1.188 + * timers and entities will work.
1.189 + *
1.190 + * @return True if the server is ticking, false otherwise.
1.191 + */
1.192 +native bool:IsServerProcessing();
1.193 +
1.194 +/**
1.195 + * Creates a timer associated with a new data pack, and returns the datapack.
1.196 + * @note The datapack is automatically freed when the timer ends.
1.197 + * @note The position of the datapack is not reset or changed for the timer function.
1.198 + *
1.199 + * @param interval Interval from the current game time to execute the given function.
1.200 + * @param func Function to execute once the given interval has elapsed.
1.201 + * @param data The newly created datapack is passed though this by-reference parameter.
1.202 + * @param flags Timer flags.
1.203 + * @return Handle to the timer object. You do not need to call CloseHandle().
1.204 + */
1.205 +stock Handle:CreateDataTimer(Float:interval, Timer:func, &Handle:data, flags=0)
1.206 +{
1.207 + data = CreateDataPack();
1.208 + flags |= TIMER_HNDL_CLOSE;
1.209 + return CreateTimer(interval, func, data, flags);
1.210 +}
1.211 +
