Interaction API

From RPSWiki

Revision as of 21:38, 16 May 2010 by KennNilsson (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

RPS INTERACTION API version3.00.00 INSTRUCTIONS

    • As this product is an API, 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

The RPS 3.0 Interaction API is built to allow a wide range of interaction possibilities and to be expandable in an unlimited capacity. The end protocol is rather simple:

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

However - before we get into the details of the protocol and what each request returns, there are a couple of preliminaries that you will need to know:

1 - The InteractionAPI has 3 restricted capabilities:

  • Give or Take Influence
  • Give Healing or Damage
  • Give RP$ without carrying an active balance (explained later)

These restricted capabilities can only be enabled if the owner of the API object 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 InteractionAPI script are reported to the owner whenever they rez the object or start the script.

2 - The API will not function for anyone outside of an RPS enabled region. It will only work in RPS enabled areas.

Now - to the meat of things:

SENDING A REQUEST

When sending a request, you will create a CSV in the string-portion of a link message.

The first value of the CSV will be the key/UUID of the avatar to whom you wish to make the request.

The second value of the CSV will be the action you are requesting. You may request the following actions:

  • GET --> Retrieves the value of whatever you're requesting
  • DICE --> Returns a dice-roll value for your request, only valid for stats and skills
  • ADJUST --> Adjusts the value of your request, only valid for Influence and RP$ at this point
  • HEAL --> Heals the target, valid for Stats only
  • DAMAGE --> Damages the target, valid for Stats only

The third value of the CSV will be the portion of the HUD, or 'location' to which you are making your request:

  • 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

The fourth or any further values in your request are determined based on the action you are requesting and whether or not further data is needed.

For GET actions, no further data is needed

For DICE actions, no further data is needed

For ADJUST actions, you need to include a number indicating the amount by which the value should be adjusted.

  • 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.

For HEAL or DAMAGE actions, you need to include two additional variables

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


PROCESSING RETURNS

There are only 3 actions that will process returns: GET, DICE, and taking RP$

A GET return will show as follows: llMessageLinked(-4, 0, "key-of-target,name-of-target,location-returned-from,any-extra-data", "RETURN_GET");

The 'any-extra-data' is related to the get return. In most cases, this return will be a single integer or string. In the case of Stats (Health, Physical, Mental, Social), however, it is a set of 7 integers: current stat, maximum stat, minimum stat, regeneration amount, regeneration rate, regeneration percentage, and damage reduction. In the case of character_name, there is no extra data as the character name is returned by 'name-of-target'.

A DICE return will show as follows: llMessageLinked(-4, dice-roll, "key-of-target,name-of-target,location-returned-from,effect roll,Critical Note", "RETURN_DICE");

TAKING RP$ - and only taking RP$ from avatars, will return: llMessageLinked(-4, amount of RP$ taken, "key of target, name of target", "RP$_TRANSACTION");

It will only return this value on a successful transaction.


ADDITIONAL FUNCTIONALITY

There are three additional functions available to the InteractionAPI that allow it to receive commands originated from avatars:

  • Search

If you send: llMessageLinked(-4, 0, "0,ALLOW_SEARCH", "API_REQUEST") ... the InteractionAPI will respond to any 'Search' commands an avatar gives through their HUD. The received response will be: llMessageLinked(-4, Search-Roll, "key-of-avatar,name-of-avatar,effect-roll", "RETURN_SEARCH");

To disallow further searches, just send: llMessageLinked(-4, 0, "0,DISALLOW_SEARCH", "API_REQUEST")

When the API recognizes the ALLOW_SEARCH command, it will return an empty link message with the "ALLOWED_SEARCH" ID ... when disallowed, it will return the "DISALLOWED_SEARCH" ID.

  • Listen for Defeat

To listen for defeat, you must also listen for Search ... as the two are reported back on the same channel. So - send an ALLOW_SEARCH link message and anytime a character within shouting range of the object is defeated, the following will be returned: llMessageLinked(-4, 0, "key-of-defeated-avatar,name-of-defeated-avatar,key-of-victorious-avatar", "RETURN_DEFEAT");

  • Take RPS Damage

To take RPS Damage, you need to send: llMessageLinked(-4, 0, "0,ALLOW_DAMAGE", "API_REQUEST") The InteractionAPI will then respond to any hits it takes from RPS weapons. The response will be: llMessageLinked(-4, amount-taken, "stat-taken-to,type-taken", "ADJUST_STAT");

This command can also be used to receive healing in the same way. The 'amount-taken' will be either positive or negative, depending on a healing or damage action.

You can disallow damage with the message: llMessageLinked(-4, 0, "0,DISALLOW_DAMAGE", "API_REQUEST")

When the API recognizes the ALLOW_DAMAGE command, it will return an empty link message with the "ALLOWED_DAMAGE" ID ... when disallowed, it will return the "DISALLOWED_DAMAGE" ID.


As time goes forward, the RPS InteractionAPI will continually expand in function and capability without a need for changing that which is already active or for updating the RPS HUD.

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