I've just implemented a basic messaging system for RPG. This allows actions to create output that might be altered before display, and allows it to be displayed in customizable fashions.
A new module was created, RPG Message. It provides an API for two functions, rpg_message and rpg_messages. Also, the RPG Drudge ruleset module now depends on this module, and provides a hook_rpg_message_alter that adds the room to the message, and all "listeners" in a room.
Basically, when you create a message, you will provide the following basic information: WHO did an action, who was the TARGET of the action (if there was one), and with WHAT was the action performed (when needed). You will also create at least a default MESSAGE to be displayed, and possibly customized messages (such as a message to be displayed to WHO, another to the TARGET, and a third to any observers).
The Drudge ruleset will alter the message to include anyone present nearby as observers (in the #listeners array), unless the message is marked as #private.
The message will then be stored in the database, and when a character (noting a user may have multiple characters) next goes to rpg/play, the messages may be displayed. Messages will automatically have links to object views parsed into them (using the Drudge ruleset), though future rulesets may do things differently with their own alterations.
TODO: Create an admin message page that lists all pending messages, filtered by who, action, type of message (WHO/TARGET/WHAT/OBSERVER).
TODO: Create a message block that may be displayed at rpg/play, listing the most recent messages for a character.
Messages are currently cleaned on display, although that may be overridden (for instance, an admin viewing pending messages wouldn't delete them automatically).
The #listeners hook is interesting in that it allows for some unique game play, such as having a camera in a room recording actions happening for remote viewing, a journal that stores interesting game actions, possessing a bat so you can see through its eyes, etc. Listeners in Drudge are any objects defining themselves as such, which are currently only PC's. In the future, you might also have cameras, journals, etc.
Hope I've explained it well enough to understand. If not, you'll just have to wait until its in action, so you can see what I mean. :D
Aaron Winborn
Drupal RPG, home of the RPG module.
Spindowners, an upcoming sci-fi rpg.
<?php
/**
* This will take a message, allow modules to alter it with hook_rpg_message_alter, format it,
* and save it to the db for later display.
*
* @param $message
* an array with the message (see the hook for details)
* @see hook_rpg_message_alter
*/
function rpg_message($message = array())
?><?php
/**
* returns pending messages for the listener
* @param $listener
* the listener id
* @param $action
* if given, then only messages that match the action, like 'take' or 'go'
* @param $type
* if given, then only messages directed by type, such as who/target/what
* @param $limit
* how many messages to retrieve
* @param $element
* we may choose to display a pager, in which case we use this element
* @param $delete
* if true, then delete the entry from the db
* @param $check_for_message_delete
* if true, then check to see if we need to delete the message source
* otherwise, postpone until end of page processing (TODO)
* @param $fetch_original_message
* if true, we return the original message array as $message['#message'];
* @return
* returns an associative array of messages, each in the following form:
* $mid => array(
* 'mid' => $mid,
* 'message' => $message, // string to display, already translated w/ links
* 'created' => $created, // timestamp of message creation
* 'action' => $action, // the string of the action type, such as 'take' or 'attack'
* 'type' => $type, // the role of the listener, either who/target/what/observer
* '#message' => $message, // OPTIONAL (depending on $fetch_original_message) -- the original message structure
* );
*/
function rpg_messages($listener = NULL, $action = NULL, $type = NULL, $limit = 0, $element = 0, $delete = TRUE, $check_for_message_delete = TRUE, $fetch_original_message = FALSE)
?><?php
/**
* Messages are passed using a data structure, which may be altered using hook_rpg_message_alter.
*
* Messages are an array in the following form:
* '#mid' => the unique message id of the message
* '#created' => the time of creation of the message
* '#action' => the action originally defining the message
* '#message' => the default message to be output, ultimately sent through t() using the other parameters
* '#who' => who is performing the action (defaults to $rpg['pc'])
* '#target' => the target of the action
* '#with' => what who is using to do action to target
* '#listeners' => an array of objects who receive the message as observers
* '#room' => the room where the action takes place (defaults to #who's top room)
* '#who_message' => the message to be displayed to #who (overriding #message if provided)
* '#target_message' => the message to be displayed to #target (overriding #message if provided)
* '#what_message' => the message to be displayed to #what (overriding #message if provided)
* '#observer_message' => the message to be displayed to anyone else viewing the action (overriding #message if provided)
* '#args' => an array of extra args to be sent to the resulting t() message, in the form of '!key' => l('!key', 'url/' . $key).
* this will be done automatically for who, target, with, and room.
*
* Examples:
* using the 'take' action:
* $message = array(
* '#action' => 'take',
* '#message' => '!who takes !target.',
* '#who' => $who,
* '#target' => $target,
* '#who_message' => 'You take !target.',
* '#target_message' => '!who takes you.'
* );
* This will ultimately resolve to
* t('!who takes !target', array('!who' => l(rpg_get('name', $who), 'rpg/view/' . $who->rid), '!target' => l(rpg_get('name', $target), 'rpg/view/' . $target->rid)))
*
* @param $message
* The message data structure, as defined above.
*/
function hook_rpg_message_alter(&$message) {
if ($message['#action'] == 'take') {
if (rpg_get('location', $message['#target']) == rpg_get('top_room', $message['#who'])) {
$message['#message'] = '!who lifts !target from the floor.';
$message['#who_message'] = 'You lift !target from the floor.';
$message['#target_message'] = '!who lifts you from the floor.';
}
}
}
?>