modules/game_clock/game_clock.module

<?php
// $Id: game_clock.module,v 1.1 2008/12/07 21:31:03 aaron Exp $

/**
 *  @file
 *  The Game Clock module will increment an official game turn.
 *  It will activate cron to see whether it's time to increment the turn.
 *  It will also optionally check on page loads, useful for fast turns on busy sites.
 */

/**
 *  Define constant defaults and other variables.
 */
define('GAME_CLOCK_INCREMENT_DEFAULT', 5);          // Increment the clock every 5 seconds by default.
define('GAME_CLOCK_CHECK_ON_INIT_DEFAULT', TRUE);   // If TRUE, then increment the clock on page loads as well as cron.
define('GAME_CLOCK_PAUSE_DEFAULT', TRUE);           // The Game's default Pause state.
define('GAME_CLOCK_TURN_DEFAULT', 0);               // What turn to start a game clock on.

/**
 *  Implements hook_help().
 */
function game_clock_help($section) {
  module_load_include('inc', 'game_clock', 'game_clock.admin');
  return _game_clock_help($section);
}

/**
 *  Pause or start a game clock.
 *  @param $clock
 *    The name of the game clock to pause or start.
 *  @param $status
 *    If FALSE, then pause the clock, and invoke all hook_game_clock('pause', $game, $state).
 *    If TRUE, then start the clock, invoke all hook_game_clock('start', $game, $state),
 *      and increment the clock if needed.
 */
function game_clock_pause($clock = 'default', $status = FALSE) {
  $state = game_clock_state($clock);
  if ($state['status'] != $status) {
    global $game_clocks;
    $game_clocks[$clock]->status = $status;
    db_query('UPDATE {game_clocks} SET status = %d WHERE cid = %d', $status, $state->cid);
    module_invoke_all('game_clock', ($status ? 'start' : 'pause'), $clock, $game_clocks[$clock]);
    game_clock_increment($clock);
  }
}

/**
 *  Start a game clock.
 *  @param $clock
 *    The game clock to start. This calls game_clock_pause, which will in effect
 *    invoke all hook_game_clock('start', $clock, $state) and increment the clock if needed.
 */
function game_clock_start($clock = 'default') {
  game_clock_pause($clock, TRUE);
}

/**
 *  This will check to see if the clock needs to be incremented, and increment accordingly.
 *  If the clock does need to be incremented, then it will also invoke_all hook_game_clock('increment', $clock, $state).
 *  If the game is paused, it will not increment, even if forced.
 *  @param $clock
 *    The game clock to check and increment accordingly.
 *  @param $force
 *    If TRUE, then force the clock to increment, regardless of whether it's time yet.
 *  @return
 *    Returns either TRUE or FALSE, depending on whether the game clock is incremented.
 */
function game_clock_increment($clock = 'default', $force = FALSE) {
  $state = game_clock_state($clock);
  // If the clock is paused or doesn't exist, then return.
  if (!$state->status) {
    return FALSE;
  }
  if (time() >= ($state->next_tick) || $force) {
    global $game_clocks;
    $game_clocks[$clock]->turn++;
    $game_clocks[$clock]->next_tick = time() + $game_clocks[$clock]->increment;
    db_query("UPDATE {game_clocks} SET turn = %d, next_tick = %d WHERE cid = %d", $game_clocks[$clock]->turn, $game_clocks[$clock]->next_tick, $game_clocks[$clock]->cid);
    module_invoke_all('game_clock', 'increment', $clock, $game_clocks[$clock]);
    return TRUE;
  }
  return FALSE;
}

/**
 *  Reset the turns in a game clock.
 *  This will invoke_all hook_game_clock('reset', $clock, $state).
 *  @param $clock
 *    The game clock to reset.
 *  @param $turn
 *    If provided, then reset the game clock to this turn. Otherwise, set it back to GAME_CLOCK_TURN_DEFAULT (which is 0).
 */
function game_clock_reset($clock = 'default', $turn = NULL) {
  global $game_clocks;
  $state = game_clock_state($clock);
  $game_clocks[$clock]->turn = isset($turn) ? $turn : GAME_CLOCK_TURN_DEFAULT;
  $game_clocks[$clock]->next_tick = 0;
  db_query("UPDATE {game_clocks} SET turn = %d, next_tick = %d WHERE cid = %d", $game_clocks[$clock]->turn, $game_clocks[$clock]->next_tick, $game_clocks[$clock]->cid);
  module_invoke_all('game_clock', 'reset', $clock, $game_clocks[$clock]);
  game_clock_increment($clock);
}

/**
 *  Create a new game clock.
 *  @param $state
 *    An object or array with at least the following neccessary parameters:
 *    ['name'] => A unique machine name.
 *    ['title'] => A human readable name for the clock.
 *    ['increment'] => The number of seconds before incrementing each tick.
 *    hook_game_clock('create', $state->name, $state); will be invoked if successful.
 *  @param $report_errors
 *    If TRUE, then display messages of any errors. In any case, errors will be logged to the watchdog.
 *  @return
 *    Either the newly created clock object, or FALSE if there was an error.
 */
function game_clock_create($state, $report_errors = FALSE) {
  module_load_include('inc', 'game_clock', 'game_clock.admin');
  return _game_clock_create($state, $report_errors);
}

/**
 *  Return a game clock state array.
 *  If the state is empty, a new one will be built.
 *  @param $clock
 *    The game clock state to return, as a string. If NULL, then all game clocks will be reloaded.
 *  @return
 *    If $clock is NULL, then return all game clock states. Otherwise, just the state asked for.
 */
function game_clock_state($clock = NULL) {
  global $game_clocks;

  if (is_null($game_clocks)) {
    $game_clocks = array();
  }
  if (is_null($clock)) {
    $game_clocks = array();
    $results = db_query('SELECT * FROM {game_clocks}');
    while ($result = db_fetch_object($results)) {
      $game_clocks[$result->name] = $result;
    }
    return $game_clocks;
  }

  if (is_null($game_clocks[$clock])) {
    $results = db_query('SELECT * FROM {game_clocks} WHERE name = "%s"', $clock);
    while ($result = db_fetch_object($results)) {
      $game_clocks[$result->name] = $result;
    }
  }

  return $game_clocks[$clock];
}

/**
 *  Implements hook_init().
 */
function game_clock_init() {
  global $game_clocks;
  $results = db_query("SELECT * FROM {game_clocks} WHERE status <> 0 AND increment > 0 AND init <> 0 AND next_tick < %d", time());
  while ($result = db_fetch_object($results)) {
    $game_clocks[$result->name] = $result;
    game_clock_increment($result->name);
  }
}

/**
 *  Implements hook_cron().
 */
function game_clock_cron() {
  global $game_clocks;
  $results = db_query("SELECT * FROM {game_clocks} WHERE status <> 0 AND increment > 0 AND next_tick < %d", time());
  while ($result = db_fetch_object($results)) {
    $game_clocks[$result->name] = $result;
    game_clock_increment($result->name);
  }
}

/**
 *  Implements hook_menu().
 */
function game_clock_menu() {
  $items = array(
    'admin/settings/game_clock' => array(
      'title' => 'Game clock',
      'description' => 'Administer the game clock.',
      'page callback' => 'game_clock_settings_page',
      'access arguments' => array('administer game clock'),
      'file' => 'game_clock.admin.inc',
    ),
  );
  return $items;
}

/**
 *  Implements hook_perm().
 */
function game_clock_perm() {
  return array('administer game clock');
}

/**
 *  Implements hook_block().
 */
function game_clock_block($op = 'list', $delta = 'default', $edit = array()) {
  switch ($op) {
    case 'list':
      $blocks = array();
      foreach (game_clock_state() as $game => $state) {
        // Only make a block available if it's been checked on the game clock administration page.
        if ($state->block) {
          $blocks[$game] = array(
            'info' => t('Game clock: @title', array('@title' => $state->title)),
          );
        }
      }
      return $blocks;
    case 'view':
      $state = game_clock_state($delta);
      $block = array(
        'subject' => t('@title game clock', array('@title' => $state->title)),
        'content' => theme('game_clock_block', $delta),
      );
      return $block;
  }
}

/**
 *  Implements hook_theme().
 */
function game_clock_theme($existing, $type, $theme, $path) {
  return array(
    'game_clock_block' => array(
      'arguments' => array('clock' => 'default'),
      'file' => 'game_clock.theme.inc',
    ),
    'game_clock_settings_form' => array(
      'arguments' => array('form' => NULL),
      'file' => 'game_clock.admin.inc',
    ),
  );
}

1	<?php
2	// $Id: game_clock.module,v 1.1 2008/12/07 21:31:03 aaron Exp $
3
4	/**
5	* @file
6	* The Game Clock module will increment an official game turn.
7	* It will activate cron to see whether it's time to increment the turn.
8	* It will also optionally check on page loads, useful for fast turns on busy sites.
9	*/
10
11	/**
12	* Define constant defaults and other variables.
13	*/
14	define('GAME_CLOCK_INCREMENT_DEFAULT', 5); // Increment the clock every 5 seconds by default.
15	define('GAME_CLOCK_CHECK_ON_INIT_DEFAULT', TRUE); // If TRUE, then increment the clock on page loads as well as cron.
16	define('GAME_CLOCK_PAUSE_DEFAULT', TRUE); // The Game's default Pause state.
17	define('GAME_CLOCK_TURN_DEFAULT', 0); // What turn to start a game clock on.
18
19	/**
20	* Implements hook_help().
21	*/
22	function game_clock_help($section) {
23	module_load_include('inc', 'game_clock', 'game_clock.admin');
24	return _game_clock_help($section);
25	}
26
27	/**
28	* Pause or start a game clock.
29	* @param $clock
30	* The name of the game clock to pause or start.
31	* @param $status
32	* If FALSE, then pause the clock, and invoke all hook_game_clock('pause', $game, $state).
33	* If TRUE, then start the clock, invoke all hook_game_clock('start', $game, $state),
34	* and increment the clock if needed.
35	*/
36	function game_clock_pause($clock = 'default', $status = FALSE) {
37	$state = game_clock_state($clock);
38	if ($state['status'] != $status) {
39	global $game_clocks;
40	$game_clocks[$clock]->status = $status;
41	db_query('UPDATE {game_clocks} SET status = %d WHERE cid = %d', $status, $state->cid);
42	module_invoke_all('game_clock', ($status ? 'start' : 'pause'), $clock, $game_clocks[$clock]);
43	game_clock_increment($clock);
44	}
45	}
46
47	/**
48	* Start a game clock.
49	* @param $clock
50	* The game clock to start. This calls game_clock_pause, which will in effect
51	* invoke all hook_game_clock('start', $clock, $state) and increment the clock if needed.
52	*/
53	function game_clock_start($clock = 'default') {
54	game_clock_pause($clock, TRUE);
55	}
56
57	/**
58	* This will check to see if the clock needs to be incremented, and increment accordingly.
59	* If the clock does need to be incremented, then it will also invoke_all hook_game_clock('increment', $clock, $state).
60	* If the game is paused, it will not increment, even if forced.
61	* @param $clock
62	* The game clock to check and increment accordingly.
63	* @param $force
64	* If TRUE, then force the clock to increment, regardless of whether it's time yet.
65	* @return
66	* Returns either TRUE or FALSE, depending on whether the game clock is incremented.
67	*/
68	function game_clock_increment($clock = 'default', $force = FALSE) {
69	$state = game_clock_state($clock);
70	// If the clock is paused or doesn't exist, then return.
71	if (!$state->status) {
72	return FALSE;
73	}
74	if (time() >= ($state->next_tick) \|\| $force) {
75	global $game_clocks;
76	$game_clocks[$clock]->turn++;
77	$game_clocks[$clock]->next_tick = time() + $game_clocks[$clock]->increment;
78	db_query("UPDATE {game_clocks} SET turn = %d, next_tick = %d WHERE cid = %d", $game_clocks[$clock]->turn, $game_clocks[$clock]->next_tick, $game_clocks[$clock]->cid);
79	module_invoke_all('game_clock', 'increment', $clock, $game_clocks[$clock]);
80	return TRUE;
81	}
82	return FALSE;
83	}
84
85	/**
86	* Reset the turns in a game clock.
87	* This will invoke_all hook_game_clock('reset', $clock, $state).
88	* @param $clock
89	* The game clock to reset.
90	* @param $turn
91	* If provided, then reset the game clock to this turn. Otherwise, set it back to GAME_CLOCK_TURN_DEFAULT (which is 0).
92	*/
93	function game_clock_reset($clock = 'default', $turn = NULL) {
94	global $game_clocks;
95	$state = game_clock_state($clock);
96	$game_clocks[$clock]->turn = isset($turn) ? $turn : GAME_CLOCK_TURN_DEFAULT;
97	$game_clocks[$clock]->next_tick = 0;
98	db_query("UPDATE {game_clocks} SET turn = %d, next_tick = %d WHERE cid = %d", $game_clocks[$clock]->turn, $game_clocks[$clock]->next_tick, $game_clocks[$clock]->cid);
99	module_invoke_all('game_clock', 'reset', $clock, $game_clocks[$clock]);
100	game_clock_increment($clock);
101	}
102
103	/**
104	* Create a new game clock.
105	* @param $state
106	* An object or array with at least the following neccessary parameters:
107	* ['name'] => A unique machine name.
108	* ['title'] => A human readable name for the clock.
109	* ['increment'] => The number of seconds before incrementing each tick.
110	* hook_game_clock('create', $state->name, $state); will be invoked if successful.
111	* @param $report_errors
112	* If TRUE, then display messages of any errors. In any case, errors will be logged to the watchdog.
113	* @return
114	* Either the newly created clock object, or FALSE if there was an error.
115	*/
116	function game_clock_create($state, $report_errors = FALSE) {
117	module_load_include('inc', 'game_clock', 'game_clock.admin');
118	return _game_clock_create($state, $report_errors);
119	}
120
121	/**
122	* Return a game clock state array.
123	* If the state is empty, a new one will be built.
124	* @param $clock
125	* The game clock state to return, as a string. If NULL, then all game clocks will be reloaded.
126	* @return
127	* If $clock is NULL, then return all game clock states. Otherwise, just the state asked for.
128	*/
129	function game_clock_state($clock = NULL) {
130	global $game_clocks;
131
132	if (is_null($game_clocks)) {
133	$game_clocks = array();
134	}
135	if (is_null($clock)) {
136	$game_clocks = array();
137	$results = db_query('SELECT * FROM {game_clocks}');
138	while ($result = db_fetch_object($results)) {
139	$game_clocks[$result->name] = $result;
140	}
141	return $game_clocks;
142	}
143
144	if (is_null($game_clocks[$clock])) {
145	$results = db_query('SELECT * FROM {game_clocks} WHERE name = "%s"', $clock);
146	while ($result = db_fetch_object($results)) {
147	$game_clocks[$result->name] = $result;
148	}
149	}
150
151	return $game_clocks[$clock];
152	}
153
154	/**
155	* Implements hook_init().
156	*/
157	function game_clock_init() {
158	global $game_clocks;
159	$results = db_query("SELECT * FROM {game_clocks} WHERE status <> 0 AND increment > 0 AND init <> 0 AND next_tick < %d", time());
160	while ($result = db_fetch_object($results)) {
161	$game_clocks[$result->name] = $result;
162	game_clock_increment($result->name);
163	}
164	}
165
166	/**
167	* Implements hook_cron().
168	*/
169	function game_clock_cron() {
170	global $game_clocks;
171	$results = db_query("SELECT * FROM {game_clocks} WHERE status <> 0 AND increment > 0 AND next_tick < %d", time());
172	while ($result = db_fetch_object($results)) {
173	$game_clocks[$result->name] = $result;
174	game_clock_increment($result->name);
175	}
176	}
177
178	/**
179	* Implements hook_menu().
180	*/
181	function game_clock_menu() {
182	$items = array(
183	'admin/settings/game_clock' => array(
184	'title' => 'Game clock',
185	'description' => 'Administer the game clock.',
186	'page callback' => 'game_clock_settings_page',
187	'access arguments' => array('administer game clock'),
188	'file' => 'game_clock.admin.inc',
189	),
190	);
191	return $items;
192	}
193
194	/**
195	* Implements hook_perm().
196	*/
197	function game_clock_perm() {
198	return array('administer game clock');
199	}
200
201	/**
202	* Implements hook_block().
203	*/
204	function game_clock_block($op = 'list', $delta = 'default', $edit = array()) {
205	switch ($op) {
206	case 'list':
207	$blocks = array();
208	foreach (game_clock_state() as $game => $state) {
209	// Only make a block available if it's been checked on the game clock administration page.
210	if ($state->block) {
211	$blocks[$game] = array(
212	'info' => t('Game clock: @title', array('@title' => $state->title)),
213	);
214	}
215	}
216	return $blocks;
217	case 'view':
218	$state = game_clock_state($delta);
219	$block = array(
220	'subject' => t('@title game clock', array('@title' => $state->title)),
221	'content' => theme('game_clock_block', $delta),
222	);
223	return $block;
224	}
225	}
226
227	/**
228	* Implements hook_theme().
229	*/
230	function game_clock_theme($existing, $type, $theme, $path) {
231	return array(
232	'game_clock_block' => array(
233	'arguments' => array('clock' => 'default'),
234	'file' => 'game_clock.theme.inc',
235	),
236	'game_clock_settings_form' => array(
237	'arguments' => array('form' => NULL),
238	'file' => 'game_clock.admin.inc',
239	),
240	);
241	}
242