Game Utility Clock

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.

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:

  $state = array(
    'name' => $name,           // A unique machine-name.
    'title' => $title,         // A human-readable title.
    'type' => $type,           // An optional string. Some modules may act only
                               // on events by clocks of a certain type.
    '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($state);

Other available functions in the Game Clock API that may be useful:

  game_clock_state($clock = NULL);
  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_create($state, $report_errors = FALSE)
  game_clock_save($clock, $report_errors = FALSE);
  game_clock_delete($clock, $report_errors = FALSE);

Additionally, you may create a hook_game_clock function in your module to act on game clock events, as follows, noting that $state will be an object, rather than an array:

  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. 
        // $state->ticks returns the number of ticks actually incremented.
        break;
      case 'reset':
        // The clock named $clock has just been reset to 0 turns.
        break;
      case 'save':
        // The clock named $clock has just been edited and saved.
        break;
      case 'delete':
        // The clock named $clock has just been deleted.
        break;
    }
  }

Please read the documentation in the game_clock.module file for more information.

Feb 2013: A rough port into Drupal 7, not quite fully working, with lots of debug code, is available at https://github.com/HongPong/game_clock/tree/7.x-1.x . HongPong now a co-maintainer. See #354674: Update code to D7 for thread on D7 update.