Communication Links
From HSpace
Contents |
Communication Link Setup
HSpace provides the ability for game administrators to setup personal communication systems. These are often referred to as Communication Links or Commlinks. Often, these are man portable devices that are carried by players to communicate between themselves. Beware, this process is not used for setting up ship communications. Ship objects utilize a different setup. However, the commlinks can be used for listening or transmitting to ships as well as to other communication links.
Basic Setup
Communication links require three core elements. First, they must be set with the HSPACE_COMM flag. This flag tells the HSpace engine that the object is a communication device and should be checked for reception of messages. Next, the object must have a COMM_FRQS attribute set on it containing a space separated list of frequencies that are being monitored. Again, this is used by HSpace to determine if the object should be evaluated for reception of a given message. Finally, the object needs to have the COMM_HANDLER attribute set. This attribute is evaluated after HSpace has determined the object has the HSPACE_COMM flag, it is within range of the sender of the message, and the object is listening on the appropriate frequency. The COMM_HANDLER is passed three arguments: %0-the message, %1-the frequency, and %2-the dbref of the sending device. Think of the COMM_HANDLER as being evaluated like a normal u() call. E.G., [u(comm._handler,%0,%1,%2)]. Typically, the COMM_HANDLER make use of some function to pass the message along to its location.
Sholevi’s Quickstart Guide
Here is a brief and simple tutorial, or quickstart guide, to getting two hspace comm devices communicating with each other:
- Create two devices. Set the HSPACE_COMM flag on both of them.
- Set attributes COMM_FRQS on both of them to: 101.01. This let's them LISTEN on this channel. You can add more channels by space-separating them, but this is just for testing for now.
- Set attributes on both of them COMM_BROADCAST to: 101.01. This is not required by HSpace, but you will want to have something like this on your parent when you set it up.This indicates the channel that the unit will speak on.
- Set attributes on both devices ACTIVE to this: 1. This is also not required, but you will want something like it on your parent, to indicate whether the unit is on or off.
- Set attributes on both devices COMM_HANDLER to this:
if(v(active),pemit(loc(me),Message from [name(pmatch(loc(%2)))] on channel %1: %0))
- Set a command on each object CMD_COM to this:
$com *:@pemit %#=if(match(hs_comm_msg(1,1,1,1,1,5,v(COMM_BROADCAST),%0),Failed),You message could not be sent.,You sent your message to channel [v(comm_broadcast)].)
In the hs_comm_msg() of that command, the parameters are, respectively, the source universe, the destination universe, the x, y and z of the sender, the range of the message (in hspace units), the channel, and the message. Mind you, I'm just typing this up to give you an idea of how it works, and I haven't tested it, so don't be surprised if it's not perfect. To send a message, the holder of the device would just type: "com Hi".
At this point, you have all that you need to test that the system works. As long as both the sender and receiver are in universe 1 and are within the range, you could send a message, which would automatically call the COMM_HANDLER of the other device as a function. Now, to recap, repeat these steps for each device to test the HSpace comm system. Once you have it working and passing the test, you can devise a more complicated Parent for your communications system, and parent the devices to it.
Using HSPACE_LOCATION
As you can see in Sholevi’s example of the com command, he’s hard-coded the source and destination UIDs, as well as the x, y, z coordinates for the transmission via HS_COMM_MSG(). Luckily, HSpace provides a way to automatically retrieve that information by looking on the transmitting player for the HSPACE_LOCATION attribute. This attribute contains the dbref of the current space location that person is in (Note: this will not be set until the person interacts with the space system so you may need to manually set it in chargen or upon creation of the player). Utilizing that dbref, you can get the current UID, X, Y and Z information for that object using HS_GET_ATTR(). Making use of the HSPACE_LOCATION requires the communication device has sufficient powers to read attributes from any object such as wizard flag or inheritance or the see_all power.
Thus, the code could become:
$com *:@pemit %#=[setq(0,get(%#/hspace_location))][if(match(hs_comm_msg(hs_get_attr(% q0,uid),hs_get_attr(%q0,uid),hs_get_attr(%q0,x),hs_get_attr(%q0,y),hs_get_attr(%q0,z),5,v(COMM_BROADCAST),%0),Failed),You message could not be sent.,You sent your message to channel [v(comm_broadcast)].)]
This setup allows the unit to dynamically get the origin location from the sender and utilize that information in the message transmission. For the range, you could have a setup that allows the range to be dynamically set by the unit and thereby replace the last hard-coded value of 5 with a user-settable value.
Sample Comlinks
For some examples of comlinks, please take a look at the Object Parents article.
