BNWCS Vehicle API

Intro

To enhance your vehicles for the BNWCS, you will need the "BNWCS Developer's Kit."

The BNWCS Vehicle API allows an in-world, rezzed vehicle (plane, tank, jeep, motorcycle, helicopter, etc) to take damage from physical collisions and BNWCS splash damage, display its health on its pilot's BNWCS HUD, and optionally kill the pilot when the vehicle is destroyed. The vehicle API is special in that all physical collisions deal 1 damage, regardless of velocity or mass, as this is the established standard for armored vehicles. To set up the vehicle API, you will first need a functioning vehicle. Then, follow these steps to make it BNWCS-enhanced:

  1. Place a "!BNWCS Vehicle Settings" notecard in the root prim of the vehicle.

    This notecard must contain the following options:
    • vehicle_health=25
      The vehicle's hit points. Each hit to the vehicle will do 1 damage. Splash damage can do more.
    • armor_factor=1
      You may change the "armor factor" to any number; it will affect how much damage SPLASH damage deals to the vehicle. All collisions will deal 1 damage no matter what this is set at.
    • kill_pilot_on_vehicle_death=no
      If this is "no," the pilot will simply be ejected from the vehicle when it is destroyed. If it is "yes," the pilot will be killed when the vehicle is destroyed.
  2. Place the "BNWCS.api.vehicle.lsl2" script in the vehicle's root prim, right next to the notecard.
  3. If you want the vehicle's health to be visible to anyone who is not the pilot (you almost always want this,) drop the "BNWCS.api.vehicle.floating.lsl2" script into ANY prim in the vehicle. It is a good idea to choose a prim that will keep the floating text as visible as possible.
  4. Done!

    If you want, you can make certain points of the vehicle cause EXTRA damage, if the vehicle is hit there. To do this, read on...
  5. Place the "BNWCS.api.vehicle.weakpoint.lsl2" script into the prim that you want to be a "weakpoint" and cause more than one damage when it is hit.
  6. Open the "BNWCS.api.vehicle.weakpoint.lsl2" script and look at the first two lines:
    integer damage_per_hit=2;
    integer minimum_velocity=15;
    Change the damage_per_hit number to the amount of damage you want a hit to THIS prim to deal.
    Change the "minimum velocity" to the minimum velocity a projectile must be moving to score a hit on this particular part of the vehicle. You probably do not want to change this except in *very* special circumstances. It should never be set over 200.

Usage

To test your vehicle, put on your BNWCS and hop in - an extra "vehicle" health display should appear on your BNWCS HUD. Vehicles respond to the following commands:

  • /8 von
    Turns the vehicle's BNWCS on, making it destructible.
  • /8 voff
    Turns the vehicle's BNWCS off and hides its floating text, making it indestructible.
  • /8 activeonly off
    Allows all avatars, even if they are not wearing a combative BNWCS, to damage the vehicle.
  • /8 activeonly on
    Allows only avatars who are wearing a combative BNWCS to damage the vehicle.

Linked Messages

The BNWCS Vehicle API script sends some link messages that you can use. A summary of these messages, and a description of when they will be sent, follows.

  • llMessageLinked(LINK_SET,state,"BNWCS Vehicle State","");
    This message is sent when the vehicle enters the combative, non-combative, or destroyed state. It is sent every time the state changes. The integer will be:
    0: Non-combative
    1: Combative
    2: Destroyed
  • llMessageLinked(LINK_SET,vehicleHealth,"BNWCS Vehicle HP","");
    This message is sent every time the vehicle's HP changes. "vehicleHealth" will be an integer representing the vehicle's current remaining health.

In addition to sending link messages, the BNWCS Vehicle API will listen for some, too, allowing you to control the script to some extent.

  • llMessageLinked(LINK_SET,newState,"Set BNWCS Vehicle State,"");
    Sending this message allows you to change the vehicle's state from combative or non-combative to one of the other states. You cannot change a destroyed vehicle's state. The possible values of the "newState" integer are the same as the other link messages:
    0: Non-combative
    1: Combative
    2: Destroyed


Last updated Feb 18, 2010
meter_state
integer

Values:
0: Loading
1: Non-combative
2: Combative
3: Dead
Team
string

Values:
None, Red, Orange, Yellow, Green, Blue, Purple, Pink
Achievement_Type
string

Values:
headshot, multi_kill, killing_spree
This is a list of all the avatar's statistics and ranking information for the current sim, in stat=value format.

You would probably want to split this string at an ampersand (&) character, then split each of THOSE pieces at an equals sign (=).

The statistics are identified by shortened names in lower-case, as follows:

rtg: Rating
k: Kills
d: Deaths
a: Assists
kpd: Kills per Death
m: Longest Life
p: Total Playtime
r: Revived
hl: Healed
s: Sniped
hd: Headshots
mk: Multikills
ks: Killing Sprees
rnk: Rank
This is a list of all of the sim's settings, as provided by the "BNWCS Combat Zone Custom Settings Server" object.

You would probably want to split this string at an ampersand (&) character, then split each of THOSE pieces at an equals sign (=).

More information about all the different settings you will encounter in this string can be found at http://BNWCS.org/?zone_notes
Statistic_Name
string

Values:
Rating
Kills
Deaths
Assists
KPD (Kills per Death)
Maxlife (Longest Life)
Playtime (Total Playtime)
Revived
Healed
Sniped
Headshots
Multikills
Sprees (Killing Sprees)
Rank