Interaction API

From RPSWiki

Jump to: navigation, search

The RPS 3.0 Interaction API is built to allow a wide range of interaction possibilities and to be expandable in an unlimited capacity. It has been written for the purpose of enabling 3rd party scripters to create a wide variety of tools for RPS regions. Some examples of tools that have been built by API developers are: quest stations, RP$-based slot machines, admin influence reward/penalty HUDs, and prim-creatures used in combat.

The instructions are written below with the assumption that you are, at minimum, an intermediate level LSL scripter. While RPS would love to be able to walk everyone through exactly how to complete the script-functionality they desire, we simply do not have the time or resources to do so. If you are tackling a scripting project, please do not ask us how to do it - only contact us if you suspect a bug in the actual Interaction API script.

It is also assumed that you have a good technical knowledge of RPS before you being scripting RPS Interaction items ... some information here is very basic as it assumes you know what a 'damage type' is or what each skill represents. RPS suggests that you use RPS for at least a month before attempting to script using the RPS Interaction API.

Contents

Restricted Capabilities

Several Interaction API capabilities are restricted because of their potential for abuse should they not be restricted. There are three restricted capabilities:

  • Give or Take Influence
  • Give Healing or Cause Damage
  • Give RP$ without carrying an active balance (explained below - giving RP$ while carrying an active balance is an unrestricted capability)

These restricted capabilities can only be enabled if the owner of the object containing the Interaction API has been granted those capabilities by region ownership in an active RPS region. You may script the actions into your object without restriction - but for the capability to be usable, the object must be owned by an 'authorized avatar'. The authorizations granted to the Interaction API script are reported to the owner whenever they rez the object or start the script. If permissions are granted to the object owner after the object has been rezzed, the object will need to be reset in order to re-acquire its allowed permissions.

The RPS Interaction API will not function at all for anyone outside of an RPS enabled region. It will only work in RPS enabled areas.

API Protocol

Sending a Request

llMessageLinked(-4, 0, "key-of-avatar,action-requested,location,extra-data", "API_REQUEST");

When you send a request to the Interaction API, it requires you to send a specific CSV (comma-separated-value) list via the string-variable in a link message to the API. The components of this string variable are:

  • key-of-avatar: The UUID/key of the avatar interacting with the API
  • action-requested: A word indicating the type of action you want to perform (see below)
  • location: A word indicating the location/portion of the RPS HUD with which to interact (see below)
  • extra-data: Not always required, but if additional data is needed (such as amount of healing to grant or amount of RP$ to take) it will be appended to the end of the string. Some interactions require multiple pieces of extra data, other interactions will have no pieces of extra data.

The API requires all requests to have a key variable of "API_REQUEST", but does not read the integer value sent at all.

Receiving a Response

llMessageLinked(-4, 0, "key-of-target,name-of-target,location,extra-data", "return key");

When a reply comes back to you from the Interaction API, it will give you a specific CSV (comma-separated-value) list via the string variable in a link message from the API. The components of this string variable are:

  • key-of-target: The UUID/Key of the avatar from whom information was requested
  • name-of-target: The name of the avatar from whom information was requested
  • location: The location/portion of the RPS HUD from which information is being received (see below)
  • extra-data: Data provided to you from the RPS HUD via the API. This data varies by what has been requested and is detailed below.

The key variable of the return will vary by the type of request made, with some requests not requiring a return at all. Each return key will be explained below.

Actions

Every request to the RPS Interaction API must declare a request action. The action declares the type of request being made. There are five currently available actions that may be requested:

GET

Extra Data Required in Request: None

Example Request: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",GET,LEVEL", "API_REQUEST");

Returns: llMessageLinked(-4, 0, "key-of-target,name-of-target,location,extra-data", "RETURN_GET");

The GET action retrieves the value associated with the RPS HUD location from which you are requesting the GET action. It will return a CSV string-value link message containing this data, using the key variable "RETURN_GET" in the returned link message.

In most cases, the extra-data returned by a GET request will be a single integer representing the value requested. However, there are a few exceptions:

  • In the case of Stats (Health, Physical, Mental, Social), seven integers are returned as the CSV extra-data: current stat, maximum stat, minimum stat, regeneration amount, regeneration rate, regeneration percentage, and damage reduction.
  • In the case of CHARACTER_NAME requests, there is no extra data provided as the character name is returned already in the 'name-of-target' portion of the return.

While the Interaction API returns only a single integer for MODE type GET requests, this integer may not be easy to understand without knowing what each integer represents. The following list shows what each MODE integer return represents:

  • 0 = RP Mode
  • 1 = Spar Mode
  • 2 = Tournament Mode
  • 3 = Global Mode
  • 4 = OOC Mode
  • 5 = AFK Mode
  • 6 = NonCombat Mode
  • 7 = Admin Mode (useful for identifying admins)
  • 8 = Defeat Mode

DICE

Extra Data Required in Request: None

Example Request: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",DICE,RESEARCH", "API_REQUEST");

Returns: llMessageLinked(-4, dice-roll, "key-of-target,name-of-target,location,effect roll,Critical Note", "RETURN_DICE");

The DICE action retrieves a dice-roll result from the RPS HUD location to which you sent your DICE request. It will return an integer and CSV string-value link message containing this data, using the key variable "RETURN_DICE" in the return link message. The dice roll returned is identical to the type of dice roll result a player would receive in chat when choosing to roll dice on their HUD.

The DICE return is unique in that the actual dice-roll returned is returned through the integer variable of the return link message.

The extra-data returned in the CSV list includes the effect roll and a final value that is either blank or declares CRITICAL SUCCESS or CRITICAL FAILURE.

ADJUST

Extra Data Required in Request:

  • A number representing the amount to be taken from or granted to the affected avatar must be provided as extra data.
  • For Influence, a negative value will take influence away from the target and a positive value will give influence to the target.
  • For RP$, a negative value will take RP$ away from the target and a positive value will give RP$ to the target.

Example Request: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",ADJUST,RP$,-100", "API_REQUEST");

Return (only when taking RP$ from a target): llMessageLinked(-4, amount of RP$ taken, "key of target, name of target", "RP$_TRANSACTION"); Return (all cases other than taking RP$ from a target): None

The ADJUST action affects the value of the location of the RPS HUD to which you have sent the ADJUST request. It does not return a link message, as the action is complete once the target's HUD has been affected. However, there is an exception with RP$ ADJUST actions, as it is sometimes important for an object to receive notice that it has been given RP$ by a player. In this case, a return link message is given - but only in the case that a successful request to take RP$ from the player has been made. Should a player not have enough RP$ to complete the request, no return will be given.

HEAL

Extra Data Required in Request:

  • The amount of healing done, represented as a number between 1 and 63
  • The method by which the healing is done (Physical, Mental, or Social based damage or healing)

Optional Extra Data (version 3.01.00+):
To heal only one template type - or heal all except for one template type, add the following information to the end of the extra data request.

  • The name (correctly capitalized) of the template to be affected/not affected
  • If the template is to be excluded, the number 1. If the template is to be the only one affected, the number 0.

Example Request: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",HEAL,HEALTH,10,MENTAL", "API_REQUEST");

Example Request w/3.01.00 Template Option: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",HEAL,HEALTH,10,PHYSICAL,Human,1", "API_REQUEST");

Return: None

The HEAL action will heal the stat requested for the RPS HUD being targeted. There is no return link message given as none is required.

DAMAGE

Extra Data Required in Request:

  • The amount of damage done, represented as a number between 1 and 63
  • The method by which the damage is done (Physical, Mental, or Social based damage or healing)

Optional Extra Data (Version 3.01.00+):
To cause damage to only one template type - or to cause damage to all except for one template type, add the following information to the end of the extra data request.

  • The name (correctly capitalized) of the template to be affected/not affected
  • If the template is to be excluded, the number 1. If the template is to be the only one affected, the number 0.

Example Request: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",DAMAGE,HEALTH,10,PHYSICAL", "API_REQUEST");

Example Request w/3.01.00 Template Option: llMessageLinked(-4, 0, (string)av_key + "," + av_name + ",DAMAGE,HEALTH,10,PHYSICAL,Human,1", "API_REQUEST");

Return: None

The DAMAGE action will damage the stat requested for the RPS HUD being targeted. There is no return link message given as none is required.

Locations

Each request to the RPS Interaction API must declare a portion of the RPS HUD to which it is sending the request. Below is a list of each location available for request. Some locations are valid only for a restricted set of actions (it would not make sense to try to HEAL or DAMAGE the CHARACTER_NAME of a player's RPS HUD). Each location lists the action requests for which it is valid next to the location name.

  • CHARACTER_NAME --> Valid only for get actions
  • CHARACTER_TEMPLATE --> Valid only for get actions
  • MODE --> Valid only for get actions
  • LEVEL --> Valid only for get actions
  • INFLUENCE --> Valid only for get or adjust actions
  • HEALTH --> get, dice, heal, damage
  • PHYSICAL --> get, dice, heal, damage
  • MENTAL --> get, dice, heal, damage
  • SOCIAL --> get, dice, heal, damage
  • ARMOR --> get, dice, heal, damage
  • RESOLVE --> get, dice, heal, damage
  • IMMUNITY --> get, dice, heal, damage
  • RPCASH --> Valid only for get or adjust actions
  • ARMED --> Valid only for get or dice actions
  • UNARMED --> Valid only for get or dice actions
  • HEAVY_ARMED --> Valid only for get or dice actions
  • COMBAT_TRAINING --> Valid only for get or dice actions
  • ARMOR_SKILL --> Valid only for get or dice actions
  • ATHLETICS --> Valid only for get or dice actions
  • OFFHAND_USE --> Valid only for get or dice actions
  • ROPE_USE --> Valid only for get or dice actions
  • ENDURANCE --> Valid only for get or dice actions
  • FAST_HEALER --> Valid only for get or dice actions
  • MAGIC --> Valid only for get or dice actions
  • SUPERNATURAL --> Valid only for get or dice actions
  • MEDICAL --> Valid only for get or dice actions
  • MENTAL_ACUITY --> Valid only for get or dice actions
  • RESEARCH --> Valid only for get or dice actions
  • AUGMENT --> Valid only for get or dice actions
  • DECRYPT --> Valid only for get or dice actions
  • LANGUAGES --> Valid only for get or dice actions
  • STUDIOUS --> Valid only for get or dice actions
  • MYSTIC --> Valid only for get or dice actions
  • POISON --> Valid only for get or dice actions
  • CONCEALED_WEAPON --> Valid only for get or dice actions
  • RESOURCING --> Valid only for get or dice actions
  • LUCK --> Valid only for get or dice actions
  • INFILTRATION --> Valid only for get or dice actions
  • CRAFTER --> Valid only for get or dice actions
  • DECEIVE --> Valid only for get or dice actions
  • INVESTIGATE --> Valid only for get or dice actions
  • CHARISMA --> Valid only for get or dice actions
  • GLIB --> Valid only for get or dice actions
  • VEHICLE --> Valid only for get or dice actions
  • SURVIVAL --> Valid only for get or dice actions
  • OTHER_BLOOD --> Valid only for get or dice actions
  • CONSTITUTION --> Valid only for get or dice actions
  • ROBUST_HEALTH --> Valid only for get or dice actions
  • MYTH --> Valid only for get actions

Additional Functionality

There are four additional functions available to the Interaction API that allow it to receive commands originated from avatars:

Skill Code Compatibility

RPS Skill Items are craftable, in-game items, that give bonuses to users who use the item with a compatible in-world object. For example, a player using a skill item called 'lock picks' may expect those lock picks to help them successfully pick open the locks of doors. In order for that to happen, however, both the lock picks and the doors they interact with are required to share a 'skill code'. This code is a shared string between the two objects that mutually declares 'we are supposed to work with each other'. In the lock pick example, a scripter may build RPS-compatible doors and set the skill code 'pickable' on them (this skill code is, coincidentally, the recommended skill code for doors or other pickable locks). The lock pick creator will then add the skill code 'pickable' to their lock pick item and whenever a player uses those lock picks with the doors also set as 'pickable', they will receive a bonus to their skill check.

It is understood that requiring skill codes on both skill items and their compatible in-world objects can be a bit onerous, but it has been determined as the most straightforward way to allow for skill items to work. Setting the skill code prevents an individual from being able to pick the lock on, say, a metal portcullis with no locks on it or -- even worse -- gaining a generic 'Infiltration' bonus (the related skill) when wearing lockpicks (which would give a bonus to Infiltration generically without a skill code) and choosing to disguise themselves. Lock picks as a disguise? Not unless you're Edward Scissorhands.

To add a skill code to your API Object, send the following link message:

llMessageLinked(-4, 0, "0,SKILL_CODE,skill-code", "API_REQUEST");

  • skill-code is the actual code string you wish to set to the object

To remove skill code compatibility from your API Object, simply send a blank code:

llMessageLinked(-4, 0, "0,SKILL_CODE,", "API_REQUEST");

Note that there is still a comma after SKILL_CODE, but the space after is completely blank - not even a space. Sending a message in this way will set the code to "", which completely disables it.

Search

The RPS HUD has a built in Search command to which an Interaction API enabled object may respond. To enable Search capability in an Interaction API object, send:

llMessageLinked(-4, 0, "0,ALLOW_SEARCH", "API_REQUEST");

... to the Interaction API. The API will return the following link message when it recognizes that search-compatibility has been turned on:

llMessageLinked(-4, 0, "", "ALLOWED_SEARCH");

Once search-compatibility has been turned on, any search performed by an RPS HUD using avatar within twenty meters will send the following to your script from the API:

llMessageLinked(-4, Search-Roll, "key-of-avatar,name-of-avatar,effect-roll", "RETURN_SEARCH");

The Search-Roll returned as the integer variable of the return link message is a dice-roll result representing the character's search attempt. The CSV returned in the string portion of the return link message includes the UUID/key of the avatar searching, the name of the avatar searching, and the effect roll of the Search attempt.

To disallow further searches, send:

llMessageLinked(-4, 0, "0,DISALLOW_SEARCH", "API_REQUEST");

... to the Interaction API. The API will return the following link message when it recognizes that search-compatibility has been turned off:

llMessageLinked(-4, 0, "", "DISALLOWED_SEARCH");

Recognize Defeat

The Interaction API may listen for and detect the defeat of any avatar within 100 meters of itself. In order to recognize such messages, the Interaction API must listen for search requests (both message-types are transmitted on the same channel). Therefore, in order to listen for the defeat of avatars, simply send an ALLOW_SEARCH link message as detailed above. To disable this capability, send a DISALLOW_SEARCH message as detailed above.

With defeat recognition enabled, the API will send your script the following link message anytime an avatar within range (100 meters) is defeated:

llMessageLinked(-4, 0, "key-of-defeated-avatar,name-of-defeated-avatar,key-of-victorious-avatar", "RETURN_DEFEAT");

Take RPS Damage

An Interaction API object may be set to recognize damage and/or healing. To enable this capability, send the following link message to the Interaction API script:

llMessageLinked(-4, 0, "0,ALLOW_DAMAGE", "API_REQUEST");

When the Interaction API recognizes that damage has been allowed, it will return:

llMessageLinked(-4, 0, "", "ALLOWED_DAMAGE");

Once damage capability has been enabled, anytime the Interaction API object recognizes itself as being hit by an RPS weapon it will send the following link message to your script:

llMessageLinked(-4, amount-taken, "stat-taken-to,type-taken", "ADJUST_STAT");

Interaction API 3.01.00+ Returns: llMessageLinked(-4, amount-taken, "interact_key,interact_name,stat-taken-to,type-taken", "ADJUST_STAT");

  • interact_key is the key of the avatar or object affecting the API object
  • interact_name is the name of the avatar or object affecting the API object
  • amount-taken is the amount of damage/healing experienced
  • stat-taken-to is the stat being affected
  • type-taken is the type of healing/damage given (via Physical, Mental, or Social means)
  • If the amount-taken is positive, healing has been received. If it is negative, damage has been received.

Healing and damage can be disabled by sending:

llMessageLinked(-4, 0, "0,DISALLOW_DAMAGE", "API_REQUEST");

When the Interaction API recognizes that damage has been disabled, it will return:

llMessageLinked(-4, 0, "", "DISALLOWED_DAMAGE");

Retrieved from "http://wiki.bnjrps.com/index.php/Interaction_API"
Personal tools