Game Clock
I've just committed the Game Clock module. The module is fully functional, except that you cannot edit existing clocks from the UI yet. (That should come later this week, allowing for an initial official release).
The module is a gaming utility, that allows the creation of game clocks. Game clocks may be used for various purposes, such as keeping an in-game calendar, tracking game effects and events, and limiting characters to acting at a slower pace suitable for a web-based game.
For example, you might want to limit players to acting only once per 5 seconds, so that a person with a slow connection might have a fighting chance against a person with a paperweight sitting on their enter key. Or you might use the API to implement spell effect durations.
By itself, the module does little except (optionally) create a block displaying the current turn of a specific clock. However, I plan to release the Game Calendar module soon, which depends on both this module and the Date API to create an in-game calendar that runs at a different pace than in real life, and handling dates from medieval times to the distant future.
Game clocks may be created through an administrative UI, or with its API. You may view all active game clocks from the Game Clock administration page, as well as create new clocks there. Additionally, you can create new game clocks programmatically with the API provided with the Game Clock module.
To do so, you would create a game clock array as follows:
<?php
$game = array(
'name' => $name, // A unique machine-name.
'title' => $title, // A human-readable title.
'status' => $status, // If TRUE, then the clock will begin started. If FALSE it begins paused. Defaults to FALSE.
'turn' => $turn, // The current turn to begin the clock. Defaults to 0.
'increment' => $increment, // How many seconds before incrementing to the next turn. Defaults to 0 (never; must be manually incremented).
'block' => $block, // If TRUE, then a block displaying this clock's current turn and status will become available. Defaults to FALSE.
'init' => $init, // If TRUE, then the clock will be checked for incrementation on every page load, assuming the proper time has passed.
);
game_clock_create($game);
?>Other available functions in the Game Clock API that may be useful:
<?php
game_clock_pause($clock = 'default', $status = FALSE);
game_clock_start($clock = 'default');
game_clock_increment($clock = 'default', $force = FALSE);
game_clock_reset($clock = 'default', $turn = NULL);
game_clock_state($clock = NULL);
?>Additionally, you may create a hook_game_clock function in your module to act on game clock events, as follows:
<?php
function hook_game_clock($op, $clock = 'default', $state = NULL) {
switch ($op) {
case 'create':
// A clock named $clock has been created with \$state.
break;
case 'pause':
// The clock named $clock has just been paused.
break;
case 'start':
// The clock named $clock has just been started.
break;
case 'increment':
// The clock named $clock has just been incremented a tick.
break;
case 'reset':
// The clock named $clock has just been reset (usually to 0).
break;
}
}
?>Please read the documentation in the game_clock.module file for more information.
game_clock_delete
Note to self to add
<?phpgame_clock_delete($clock = 'default');
?>
Aaron Winborn
Drupal Multimedia (book, in October!)
AaronWinborn.com (blog)
Advomatic (work)
Fudging missed ticks...
The version in CVS now implements hook_game_clock('delete'). Additionally, after a conversation with litwol, it now properly increments the clock according to the number of ticks that should have passed, even if the clock wasn't actually incremented every turn. This is temporarily stored in the clock $state->ticks and passed to hook_game_clock('increment').
Thus, for instance, you might have a 'poison' clock, that damages its target every turn, which happens to be 15 seconds in real life. However, cron may run only once an hour, and the site may have no activity for 5 minutes. Rather than running the clock 20 times on the next page load, the clock will simply increment once (to the proper turn), and simply tell all modules implementing the hook that it's been incremented 20 ticks, allowing the modules to fudge things. (Poor dead goblin... although its gryphon mount might be able to fudge a few attacks in that time as well.)
Aaron Winborn
Drupal Multimedia (book, in October!)
AaronWinborn.com (blog)
Advomatic (work)
Official release!
There's now an official release for the Game Clock module! It's fully featured, with a robust API, performance settings, and (hopefully) great documentation. Give it a whirl! Next on my list is to create the Game Calendar module, which will be dependent on the Game Clock module. Then create a few working examples of other ways this utility module might be used.
Aaron Winborn
Drupal Multimedia (book, in October!)
AaronWinborn.com (blog)
Advomatic (work)