Soundpack Hooks
IntroductionMiriani provides a number of useful out-of-band hooks that soundpack creators can use to enhance their soundpacks. Typically these hooks will provide information to the soundpack that could not ordinarily be gleaned from triggers alone. This help file will explain how to create a soundpack that can communicate with the MOO and will document the available hooks.
NOTE: You may need to view this section on the website, as it contains text that may be interpreted by your client as out-of-band commands and hidden from view. The URL is: https://miriani.toastsoft.net/help2/Soundpack%20Hooks
Soundpack Creation
First, your soundpack must be registered with the game in the soundpack registry. This allows the game to know who is using which soundpack and also allows other players to locate your soundpack. The following commands will be useful in the creation process:
@register-soundpack: This will ask you some questions about the name, version, clients, website, and download URL for your soundpack. This is step one!
@update-soundpack: This will update the version and, if necessary, download link to your soundpack. Once you execute this command, an update announcement will be sent to any connected users of your soundpack.
@soundpacks: Provides a list of soundpacks for your perusal.
Soundpack Negotiation
When a player connects to Miriani, your soundpack will need to send a command in the following format:
Request: #$#register_soundpack <Soundpack Name> | <Soundpack Version>
Example: #$#register_soundpack Not Real | 10.9.8
The MOO will respond with a message in the format:
Response: #$#soundpack status <ok | outdated | unknown>
Example: #$#soundpack status ok
Ok means everything is good to go. Outdated means that your version of the soundpack doesn't match that of the MOO. The MOO will give you a warning and a download link. With both of these cases, a flag is set on your character and you will receive the special soundpack notifications. However, if it says unknown, this means your soundpack wasn't found in the registry and nothing has happened.
Alternatively, if you wish to register your soundpack BEFORE login, you can have it send the registration command at the username prompt BEFORE the user types their username. For example:
Username:
>register_soundpack Not Real | 1.0
>albori
Password:
>mypassword
Soundpack Hooks
Message: #$#soundpack environment starship <space | landed> | <powered | unpowered> | <hostile | safe> | <light | dark> | <indoors | outdoors> | <room types>
Example: #$#soundpack environment starship space | powered | safe | light | indoors | eng cr
This indicates that the player is in a starship, the ship is in space, it's powered up, the room is both a control room and an engineering room, it is a safe environment, and has plenty of light. Indoors is included for completeness.
Message: #$#soundpack environment planet <classification> | <hostile | safe> | <light | dark> | <indoors | outdoors> | <room types>
Example: #$#soundpack environment planet terrestrial | safe | light | outdoors | ocean
Message: #$#soundpack environment room | <hostile | safe> | <light | dark> | <indoors | outdoors> | <room types>
Example: #$#soundpack room | safe | light | outdoors | unknown
Message: #$#soundpack environment space | hostile | <light | dark> | outdoors
Example: #$#soundpack environment space | hostile | dark | outdoors
Indicates you're in space. Obviously it's always going to list as hostile and outdoors, but it shows for completeness.
Message: #$#soundpack environment station | <hostile | safe> | <light | dark> | <indoors | outdoors> | <room types>
Example: #$#soundpack environment station | safe | light | indoors | pool
Indicates you're in a swimming pool on a space station, as I'm sure you guessed. For evident reasons, space stations will always display as indoors.
Message: #$#soundpack environment vehicle <landed | atmosphere> | <planet classification | starship | asteroid>
Example: #$#soundpack environment vehicle landed | starship
If you're in a vehicle, indicate whether it's landed or in an atmosphere. If you're in the atmosphere, indicate the classification of the planet. If you're docked, indicate starship. If you're in a rover, (hopefully) indicate asteroid.
Message: #$#soundpack social | [social name] | [person's gender]
Example: #$#soundpack social | grin | male
Message: #$#soundpack emote | [person's gender] | [emote with quoted substrings removed]
Example: #$#soundpack emote | male | Albori sighs wistfully and says while plunging a block of cheese into the trash.
Message: #$#soundpack video_feed
This message is sent immediately before each message that is played back from a video camera or entertainment center when playing a video.
It replaces the greater than sign prepended to each message in the video feed.
Message: #$#soundpack lore | <computer title>
Example: #$#soundpack lore | a compact black Lore computer
This message is sent immediately before certain Lore computer messages appear.
Message: #$#soundpack fc | <scanner title>
Example: #$#soundpack fc | a silver flight control scanner
This message is sent immediately before a flight control scanner makes an announcement.
Message: #$#soundpack starmap nearest <distance>
Example: #$#soundpack starmap nearest 1
This message is sent right before the nearest ship is announced after typing starmap shipcoords. For reference, read post 98703.
Message: #$#soundpack weapon | <name> | <action> | <outcome>
Example: #$#soundpack weapon | a stun turret | stun | hit
This message is sent whenever a weapon, defined by <name>, has executed an action, defined by <action>, against a target. The action outcome is identified by <outcome>.
Possible values for action are:
* acid: shown by insectoid creatures attacking a person.
* heal: generally shown when a droid is healing an individual.
* pulse: Shown by pulse emitters and so on.
* punch: Shown by stun batons, correction clubs and the like.
* stun: the weapon is likely a stun weapon
Possible values for outcome are:
* hit: The target was hit. In the case in which the action is stun, hit will be reported if stun ammunition was used. For anything else, unknown will be reported and the soundpack should handle the situation accordingly.
* miss: the target was missed. E.G. because of a dodge.
* unloaded: The weapon itself was out of ammo.
* unknown: Everything else.
Soundpack Queries
Request: #$#soundpack_version_query <soundpack name>
Response: #$#soundpack status <ok | outdated | unknown> | version <version>
Example: #$#soundpack status ok | version 5.3
This will return the last reported version from the user as well as whether or not it's ok, unknown, or outdated. If the user isn't using the soundpack given in <soundpack name> then "unknown" will be returned with no version.
Request: #$#soundpack_ping
Response: #$#soundpack_pong
This command is typically used to test latency between client and server. Sending it will not alter idle time and can also help with poor connections, on top of the keep-alive system. See also: #$#soundpack_ping_reply
Request: #$#soundpack_ping_reply <optional ms>
Response: #$#soundpack_lag <time in seconds or milliseconds>
Example: #$#soundpack_lag 0.1068115234375
After receipt of a pong, this command can be used to reply, giving the game necessary data to calculate command latency. You can execute a ping sequence multiple times to obtain an average client-side. Including the ms argument will cause times to be displayed in milliseconds, rather than seconds.
Request: #$#unregister_soundpack
Unceremoniously unsets the soundpack flag on the player. Like a friend when you need to borrow money, there is no response.
Conclusion
That should be everything you need to get started linking a soundpack to the game. If you have any questions, comments, bugs, or suggestions, please REPORT them or contribute to the message board thread mentioned below.
The original suggestion thread, which may contain additional information or insight, can be found by board reference 53586. Users of the web board can find it here: http://toastsoft.net:1111/board/OOC/Suggestions~Ideas/thread/53586