BroadcastComms MFD [Release]

[phkb]

Zireael and I are excited to announce the release of BroadcastComms MFD expansion pack. For the time being, this is in beta form only. I won't be publishing this in the download manager until we've got some broader comment on the usability and suitability of this pack. We'd like feedback on everything, but if you need a specific list of things we'd like tested, here you go:

• Do the transmissions work as advertised?
• Do any of the transmissions produce weird responses?
• Do any of the transmissions break gameplay in your opinion?
• For those who are happy looking through Javascript, have we done things the right way? Particularly when it comes to npc AI. My experience with this sort of thing is quite limited.
• Suggestions for further comm types, more responses, extra external access functions, different NPC actions in response to communications, that sort of thing.

Although this is still in beta, you can now download this OXP directly using the download manager in Oolite.
To download this as an OXZ, click here. Download and put this file in your AddOns folder to use.
To download this as a OXP inside a ZIP file, click here. You will need to extract the OXP folder to your AddOns folder to use this option.

Below is from the ReadMe.txt file inside the OXP package.

Broadcast Comms MFD - ReadMe

Author: phkb (Nick Rogers) and Zireael
With thanks to: cim, Norby, Wildeblood and marte for their suggestions and fixes

Only works with Oolite 1.79 or greater.

This OXP provides a means by which the player can communicate in a real way with other ships. That is, the types of communications the player transmits will have a bearing on the game in some way, depending on the transmission type


MFD sample display with item selected.

There are 11 types of transmissions:

1. Requests for wormholes (broadcast ie. to all ships in range)
   This transmission asks if anyone is going to your hyperspace destination. The message is only available if a destination has been set.
   Ships can respond in three ways: (a) Not at all. (b) By telling the player they are headed somewhere else, or (c) by telling the player they are heading to the players destination.
   This message can be sent repeatedly.
2. Send distress message (broadcast ie. to all ships in range)
   This transmission requests immediate assistance against attackers. NPC ships may or may not choose to help.
   Only available when the player ship is under attack.
   This message can be sent repeatedly.
3. Send greeting to target
   This transmission sends a basic "Hello" message to the ship the player is targeting. The other ship may choose to respond or not. Once a response has been received from the other ship, no further greetings can be sent to that ship.
4. Send taunt to target
   This transmission sends a taunt to the other ship, and the other ship may or may not respond. But regardless of a verbal response, the other ship may do one of the following:
   1. Nothing at all
   2. If they are currently attacking the player, they might get angry and their accuracy might decrease for a few seconds, or increase for a few seconds.
   3. If they are not targeting the player at the moment, they might choose to start targeting the player instead.
   Multiple taunts can be sent to other ships.
5. Issue threat to target
   This transmission issues a threat to the other ship. Depending on who that ship is targeting, the response may be different:
   1. If the other ship is targeting the player, there is a small chance they might choose to flee.
   2. If the other ship is not targeting the player, they will possibly choose to attack the player.
   Only one threat can be issues to a ship.
6. Offer bribe to target/Offer bribe to nearest attacker
   This transmission offers money to a ship that is attacking the player. That ship can respond in a two ways.
   1. They can reject the offer. The amount the player can offer will then increase by a factor of 2 or 2.5 and the player can then try the bribe again if they wish. If the amount of bribe increase beyond the players current credit balance, the offer to bribe will be removed.
   2. They can accept the bribe. In this case, the bribe amount is deducted from the player bank account, and the ship targeting the player will break off their attack. If they are part of a pirate band, the pirate who accepted the bribe will share the spoils and they will all break off their attack.
   If the attacking ship is targeted by the player, they will see the next bribe amount in the message text when selecting the message. If the player doesn't have a target (for instance, they are fleeing from a group of ships), the bribe amount will only be displayed when the transmission takes place. This is because it is not known who is the closest attacking ship until the transmission occurs, and the bid amounts are stored for each pirate group or ship. If a ship from one pirate group moves closer than another pirate group, the amount of the bribe will be adjusted accordingly.
7. Demand cargo from target
   This transmission sends a demand for cargo to the other ship. They can either accept or reject the demand. If they accept the demand, they will drop some cargo and flee. If this action is performed in sight of a police vessel or the main station, there is a chance the victim will report the crime and the player will receive an increase to their offender status.
8. Surrender to target/Surrender to nearest attacker
   This transmission sends a surrender message to another ship. There is a small chance the attackers might accept the surrender. In that case they will stop attacking the player and wait for the player to dump some cargo. If the player doesn't dump any cargo, the pirates will start attacking the player again.
   If the player decides to use the lull in hostilities to start attacking the ships the pirates will get really angry and get a temporary boost in their accuracy.
9. Offer to rescue escape pod (only if fuel scoop is fitted)
   This sends a message to the targeted escape pod, asking the occupant if they would like to be scooped and returned to the main station. Commanders should check that they have available cargo space before scooping escape pods.
10. Target last comms message
    This will switch the players target to the ship that last sent a comms message.
11. Keep away from my target
    This will send a message to all ships in range, telling them to stay away from the players current target. Only ships that aren't fighting against the player will potentially respond. Enemy ships will ignore this message.

Usage:
The BroadcastComms MFD is available for purchase for 200CR at all stations, regardless of techlevel.
After displaying the BroadcastComms MFD and priming it, press the "b" (Mode) key to select a message from the available options.
The selected message is marked with a ">" in the MFD.
You don't need the BroadcastComms MFD to be visible, though. There might be situations where it is not be visible, so changes to the selected message will also be displayed as a console message.
Once the desired message is selected, press the "n" (Activate) key to send the message.

External access:
Provision has been made for other OXP's to access the comms features in this OXP. There are two methods that can be used:

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$createMessage({messageName : string, callbackFunction : Function, displayText : string, messageText : string, ship : Ship, shipDisplayName : string, transmissionType : string, deleteOnTransmit : Boolean, delayCallback : integer})

Calling this function will add the message to the display that will be displayed when the conditions are met. The passed object can have the following properties:

• messageName = The name of this message, internally used for identification purposes. Can be any text. It is recommended to prefix the message name with the name of your worldscript to prevent the possibility of duplicate message names. (ie. "myworldscriptname_mymessagename")
• callbackFunction = the function to call when the player transmits the message.
• displayText = The message text to display
• messageText = The message text that will be transmitted, if different to the display text
• ship = reference to a ship object for a ship-to-ship transmission. Player must target the ship for the message to become available.
  Can be null, and if transmission type is "target" this will create a message that can be sent to any targeted ship.
  Will be ignored if transmission type is "broadcast".
• shipDisplayName = display name of a ship for a ship-to-ship transmission. Player must target the ship for the message to become available.
  Alternate method of targeting a specific ship, if the ship object is not available.
  Will be ignored if transmission type is "broadcast".
• transmissionType = transmission type, either "broadcast" (ie. transmitted to all ships) or "target" (the ship targeted by the player)
  Including a ship property necessitates a "target" value here. Specifying "broadcast" will over override ship reference.
• deleteOnTransmit = boolean value indicating that the message will be removed from the list as soon as the player transmits it
• delayCallback = integer value indicating how long (in seconds) to take before calling the callback function. A value of 0 (zero) means immediately.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$updateMessage({messageName : string, displayText : string, messageText : string, callbackFunction : Function, deleteOnTransmit : boolean, delayCallback : integer});

This function will update the settings of a particular message. The passed object can have the following properties:

• messageName = the name of the message that will be updated
• displayText = The new message text to be displayed, otherwise null if not being changed.
• messageText = The new message text that will be transmitted, otherwise null if not being changed.
• callbackFunction = The new function to call when the player transmits the message, otherwise null if not being changed.
• deleteOnTransmit = boolean value indicating that the message will be removed from the list as soon as the player transmits it.
  Null if not being changed.
• delayCallback = integer value indicating how long (in seconds) to take before calling the callback function. A value of 0 (zero) means immediately.
  Null if not being changed.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$checkMessageExists(messageName : string);

This function returns true if "messageName" exists, otherwise false.

• messageName = The name of the message that will be searched for.

Code: Select all

$removeMessage(messageName : string);

Calling this function will remove the message from the list. Only messages created via the "$createMessage" function can be removed.

• messageName = The name of the message that will be removed

Code: Select all

$disableMessage(msgid : int);

This function disables one or all of the internal messages, preventing it from being displayed

• msgid = The ID of the internal message that will be disabled, where
  0 - all
  1 - request for wormhole
  2 - send distress message
  3 - send greeting
  4 - send taunt
  5 - send threat
  6 - offer bribe
  7 - demand cargo
  8 - surrender to target
  9 - offer to rescue escape pod
  10 - target last comms message
  11 - keep away from my target

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$enableMessage(msgid : int);

This function enables one of all of the internal messages (if they have been disabled by the $disableMessage function), allow it to be displayed

• msgid = The ID of the internal message that will be enabled, where
  0 - all
  1 - request for wormhole
  2 - send distress message
  3 - send greeting
  4 - send taunt
  5 - send threat
  6 - offer bribe
  7 - demand cargo
  8 - surrender to target
  9 - offer to rescue escape pod
  10 - target last comms message
  11 - keep away from my target

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$isMessageEnabled(msgid : int);

This function is used to determine if an internal message is enabled or if it has been disabled.
Returns true if message is enabled, otherwise false.Passing msgid value of 0 will check if all messages are enabled. Only returns true if all messages are enabled. Otherwise false.

• msgid = The ID of the internal message that will be evaluated

Examples:

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$createMessage({messageName:"myMessage1", callbackFunction:this.$broadcastCallback.bind(this), displayText:"Evacuation message", messageText:"Attention all ships. Please evacuate the area and move to a safe distance.", transmissionType:"broadcast", deleteOnTransmit:true, delayCallback:4});

This example adds a broadcast message to the display. It will be removed when transmitted, and it will take 4 seconds for the
callback function this.$broadcastCallback.bind(this) to be executed.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$createMessage({messageName:"myMessage2", callbackFunction:this.$targetCallback.bind(this), displayText:"Ask native question", messageText:"Are you a native of these parts?", ship:myShip, transmissionType:"target", deleteOnTransmit:false, delayCallback:0});

This example adds a target-specific message to the display, to be shown when the ship object "myShip" is targeted by the player.
It will be not removed when transmitted and the callback function this.$targetCallback.bind(this) will be executed immediately

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$removeMessage("myMessage2");

This example will remove the message "myMessage2" from the list of external messages.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$disableMessage(0);

This example will disable all internal messages, leaving only the external messages to be displayed.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$disableMessage(3);

This example will disable the "Send greeting to target" message.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$enableMessage(0);

This example will enable all internal messages.

Code: Select all

var w = worldScripts.BroadcastCommsMFD;
w.$enableMessage(3);

This example will enable the "Send greeting to target" message.

External messages, and the status of internal messages, are cleared each time the player loads from a saved game. If a persistent message needs to be shown, or if the status of internal messages needs to be changed in an ongoing manner, ensure the changes are made after the player loads from a saved game.

[spara]

Wow, that sounds amazing.

[Wildeblood]

This is going to sound churlish, but here goes anyway: would you please stop thinking that "wideband" is a synonym for "broadcast"; it's not.

Be flattered. If I didn't think this had potential to become very popular, I wouldn't bother saying anything. Please, change it now, before it becomes entrenched wrongness.

[phkb]

I'll get a update with wideband replaced shortly.

[Zireael]

Wow, that sounds amazing.

We just took Kaks' very old idea and ran with it - phkb did the coding and I did most of the messages.

[Norby]

This work is amazing!

I feel more natural if the displayed messages are not prefixed in parenthesis but show "Send greeting to target" and simply the message if broadcast.

I suggest to show first the urgent transmissions like Distress, Bribe, Surrender, then Answer Distress. Should have a broadcast version of these if no target to help using immediately when red alert or a distress call pop up. Then show the other broadcasts (wormhole) before targeted messages.

In external access would be nice the short usage like this:

Code: Select all

worldScripts.BroadcastCommsMFD.$createMessage("spam", "Eat spam!");

My problem here is the required type variable, I suggest "broadcast" to default (others can be null).
In general bring all parameters without defaults to the front to avoid inserting empty values before a needed one.

You should make a checkMessage function to OXPs can determine that a messageName is already occupied before creating a new one. If you ask the worldscript name also and put before the messagename then the names will compete within oxps only.

I think an optional parameter can make persistent messages after docking, for example for OXPs with new functions which should remain (like a "follow me"+callback where the OXP check the chance and set the AI).

The this.this in the 686.line of js seems to be a mistype.

Your $pirateGroupMembers function is slow due to the the filteredEntities call, you can use the ship.group.ships array instead.

[phkb]

Thanks for the suggestions, Norby. It's great feedback, and exactly what we needed!

feel more natural if the displayed messages are not prefixed in parenthesis but show "Send greeting to target" and simply the message if broadcast.

Good ideas. That will probably be how I do the next version.

Should have a broadcast version of these if no target

With regard to sending a "Surrender" or "Bribe" message to be broadcast rather than target based, I'm not sure how that could work, as these need to be sent to a specific target in order to keep track of who's been offered a bribe (and how much) and who as been surrendered to. The distress message can certainly be changed to become available during a red alert status though. That's a great idea.

The this.this in the 686.line of js seems to be a mistype.

Yep, definitely a bug. Thanks for the pickup!

you can use the ship.group.ships array instead

Thanks for that! That's a great help!

You should make a checkMessage function to OXPs can determine that a messageName is already occupied before creating a new one.

Great suggestion. That'll be in the next version.

If you ask the worldscript name also and put before the messagename then the names will compete within oxps only.

Do you mean, suggesting that users give their message names a prefix of their own worldscript name? like $createmessage("myworldscript_mySpamMessage", "Send Spam message", "Eat spam!");, or by having a completely new parameter of worldscriptname?

I think an optional parameter can make persistent messages after docking

I was really trying to avoid having to persist messages after docking, as that would involve putting things into mission variables. Before I go down this path I'd like to hear from some other people, especially OXP developers, with their thoughts on this. My plan was to make this as easy to use as possible. So, if your OXP detects a condition that requires a message to be sent, then you create a message. If you want the message back after launch, you add it back in via the shipLaunchedFromStation or shipWillLaunchFromStation events. That seems fairly natural to me, but I'd really like to hear from other OXPers on what they think about it.

Anyway, I'm working on the new version now, should be released later today.

[phkb]

In external access would be nice the short usage like this:

Code: Select all

worldScripts.BroadcastCommsMFD.$createMessage("spam", "Eat spam!");

Not sure about reducing the call this much. If there's no callback function defined, then wouldn't it be a rather pointless message? Funny maybe, but not exactly useful. I'm thinking to make the minimum call something like this:

Code: Select all

worldScripts.BroadcastCommsMFD.$createMessage("myworldscript_myspammessage", this.$broadcastCallback.bind(this), "Eat spam!");

In this example, we have a message name ("myworldscript_myspammessage"), a callback to execute when the message is sent, and the message to display in the MFD and to send on transmit. That seems to be the most amount of reduction I can do.

Or are you thinking of a scenario where some sort of AI is defined that will respond automatically if "Eat spam!" is sent to it? I'll need some guidance here as I don't have a lot of AI experience yet!

[Neelix]

In external access would be nice the short usage like this:

Code: Select all

worldScripts.BroadcastCommsMFD.$createMessage("spam", "Eat spam!");

Not sure about reducing the call this much. If there's no callback function defined, then wouldn't it be a rather pointless message? Funny maybe, but not exactly useful.
...
Or are you thinking of a scenario where some sort of AI is defined that will respond automatically if "Eat spam!" is sent to it? I'll need some guidance here as I don't have a lot of AI experience yet!

No response needed, just something you broadcast before firing TC's of food at the enemy at high speed (in cargo pods shaped like tins of spam)

- Neelix

[phkb]

V1.0.11 is available via links in the first post. This version fixes the "wideband" issue, I've re-ordered the messages to hopefully put the more relevant ones first. I've removed all of the prefixes, instead making the text of the message clearer as to who it is relevant to. I've fixed a few bugs and cleaned up some code (thanks for the notices, Norby!), and tweaked a couple of the random chances a little. If the player surrenders to some pirates and then dumps cargo, the pirates (well, one of them, anyway) will now scoop the cargo. I added text to the readme (and in the first post) that more accurately describes the possible pitfalls of demanding cargo in view of police or main stations.

I've also reordered the external calls a bit, making it a bit easier to add a message if you want to accept the defaults. Let me know if you think the defaults need tweaking. And I've added the "checkMessageExists" function so you can check that your message name is unique before you attempt to add it.

On a separate note, while I've coded up what I think is a meaningful response to another ships distress call, I haven't been able to accurately test this. My first question (and perhaps one of the devs can answer this) is, when does a ship decide to put out a distress call? I see plenty of ships saying "Help me" but when I check my log file the distressMessageReceived event has never fired. Is there another event I need to look at to determine that a ship is in distress?

[cim]

On a separate note, while I've coded up what I think is a meaningful response to another ships distress call, I haven't been able to accurately test this. My first question (and perhaps one of the devs can answer this) is, when does a ship decide to put out a distress call? I see plenty of ships saying "Help me" but when I check my log file the distressMessageReceived event has never fired. Is there another event I need to look at to determine that a ship is in distress?

Most help requests are intended for other group members only - the sending is requestHelpFromGroup and only group members receive the helpRequestReceived event.

Distress calls are only sent by ships with "oolite_flag_sendsDistressCalls" set as a parameter in their AI, which is only true for shuttles and traders, and they'll only send distress calls around once a minute (while requestHelpFromGroup calls may be sent much more frequently)

[Norby]

sending a "Surrender" or "Bribe" message to be broadcast

Surrender: send to all ships in scanner range due to the player try to stop all of them.
Bribe: give the money to the ship who accept it first when checking all ships in range - the random order is not a problem, the winner was the fastest in accepting the offer.

or by having a completely new parameter of worldscriptname?

The new parameter is better imho.

are you thinking of a scenario where some sort of AI is defined that will respond automatically

Scripted AIs can do anything which is possible in js, but a simple ship script on the target also can catch the message in commsMessageReceived and respond "I like spam!" or something.

[Redspear]

Looking forward to trying this. Good work guys

[phkb]

Most help requests are intended for other group members only - the sending is requestHelpFromGroup and only group members receive the helpRequestReceived event.

So if I see a "Help me" transmission from a ship, there is no event I can pick up unless the player is part of that ship's group?

[off topic question]
One other thing: Where should I ask general script-related questions? In the Scripters Cove thread? Or just create a new topic for each question?
[/off topic question]

[phkb]

Surrender: send to all ships in scanner range due to the player try to stop all of them.

Hmm. I'm not totally convinced yet, but I'll have a look at how I can handle the multi-group aspect. I think my AI skills are going to hit their limit here, though.

Bribe: give the money to the ship who accept it first when checking all ships in range - the random order is not a problem, the winner was the fastest in accepting the offer.

This would change the bribe system quite substantially from what it is now. I'm keeping track of how much has been offered to each pirate/group. Say you work up to 500cr of bribe on one pirate. You can target another group and start from 10cr again. Target the first pirate group and your bribe amount will show as 500cr again. This system wouldn't work in a broadcast mode. Send out a general 10cr bribe offer. No one takes it. get up to 100cr and one group takes it. 2nd group rejects it. Then a third group appears. Wouldn't you want to start from 10cr again with the third group? They might take a lower bribe offer, but there would be no way to lower the bribe amount because the second group has already rejected 100cr.

The new parameter is better

Not sure I agree. The extra parameter makes it harder for me (in that there are two keys involved in all the lookups) and harder for the caller, who has an extra parameter to include in all the calls. It doesn't appear to add any extra benefit for either side of the equation. I'll certainly add the recommendation to prefix message names with your worldscript name, though. If there's enough feedback requesting the feature I can certainly add it.