Projectile Weapons
22/08/07 07:10
This tutorial will show you how to make projectile
weapons (such as guns and rifles) for CERIX, using
either damage or stun bullets.
STEP 1: Get the SDK
Pick up a free CERIX SDK (Projectile) from any CERIX location. If you haven't already done so, set up a CERIX account using the free CERIX HUD and submit a request for Developer status. You will be able to use your own weapon without the status, but to pass it to anybody else you need this status enabled on your account.
STEP 2: Unpack the Contents
Click the SDK box to unpack the contents into a folder called "CERIX Projectile SDK."
The projectile SDK contains two notecards:
And four scripts:
Step 3: Build your weapon
If you have not already done so, go ahead and build your weapon now. The weapon can be any shape or size, but the default example script is set up to assume that it is handgun- or rifle- sized right hand attachment, and that the root prim (the main prim) is reasonably close to the build's center (along the muzzle is okay too).
Step 4: Create the bullet
The projectile kit is designed to fire bullets. All the bullet needs to do for CERIX to work is to fly from the gun and register collision with a target. It can be a simple spherical prim, or if you want to get fancy you can create a shaped bullet. As far as bullets go, an item that is twisted and hollow is sometimes advantageous, as it has many faces on which to register a collision.
The cerix_control script rezzes the bullet at llGetRot(), which means that it will rez the bullet automatically rotated to face the same direction as the avatar. If your prim bullet has fancy shapes (such as a long cylinder), make sure that these are situated along a root prim that will have them line up properly when rezzed facing the direction the avatar is facing.
Note: Setting the bullet buoyancy via llSetBuoyancy(float buoyancy) is a good idea, so that the bullet, if largish, flies along a straight path.
Step 5: Script the bullet
Open the bullet and place the cerix_bullet_damage script inside. Remember that this is the script that enables the bullet to do CERIX damage, so it must be in the bullet for the gun to work.
If you want the weapon to stun instead of damage, use the cerix_bullet_stun script instead. Only one of these scripts may be used in the bullet at any time.
You can add collision effects such as noises or whatnot in another script inside the prim, so long as the script has a name that does NOT start with cerix_bullet.
Remember that if you use llSetDamage(float damage) to make the bullet work in normal SL combat, the bullet will die immediately upon impact in a damage zone. In other words, if the shooter is trying to use the gun as a CERIX weapon in a damage zone, the bullet will do the SL damage first and will probably not get around to doing the CERIX stuff. If you're trying to include a regular SL damage mode, it's probably best to use a separate bullet and set of scripts for this.
Toss the example_bullet script into the bullet as well. This modifiable script (add your own effects and stuff) does important things like delete the bullet when it's done doing its magic.
Remember to make the bullet physical before you take it back into your inventory! We can't shoot a non-physical bullet.
NOTE: We strongly recommend temp-on-rez bullets. All those no-temp prims flying around... bad idea.
Step 6: Script the gun
Place the cerix_control script, the example_gun script, the cerix_config notecard, and your cerix-enabled bullet into the main weapon itself. You don't need to use our example gun script, and we don't provide support for this script. It's just there as a simple out-of-the-box example for you to use.
Step 7: Configure the notecard
Now it's time to edit the cerix_config notecard. The initial notecard looks like this:
First thing's first. Put your key into the DEVELOPER KEY: field (replace "your-key-here"). What we're looking for here is your Second Life avatar key, a unique string of letters and numbers automatically assigned to you by the Second Life database. If you do not know your own key, you can find it by using the optional "My Key" item contained in the SDK; rez and click to have the item speak your key.
Then enter the name of the bullet. By default, this notecard assumes you've named the bullet "cerix bullet," but if you've gotten all creative-like and named it "my kickass bullet" or something, put that name here. Please be aware that this should be spelled and capitalized to match the bullet object's name perfectly.
Now we get down to the fun part: setting up your weapon's stats.
CERIX has 4 points of configuration to allow you to design your weapon to have a specific function - something we've been calling a "strategic personality." These various points of configuration determine what use your weapon will be in certain situations. Here are the four points:
So what's keeping you from maxing out every stat? We're glad you asked.
You'll notice that the CERIX SDK you received has a point value assigned to it. These are NOT hit points. These are "strategic points." Each statistic may be assigned a certain number of points up to the total points included in the SDK. The projectile SDK is a 15-point kit, so you can assign up to 15 points as you see fit to the various aspects of the configuration.
However, this also means that if you want major damage in your bullets, you'll need to sacrifice some on the range, or make it take longer to reload, or lower the number of bullets in the clip in order to keep the weapon balanced.
Points work like this:
Here's an example:
EFFECT: 5
EFFECTIVE RANGE: 5
TOTAL AMMO: 3
RELOAD RELIEF: 2
This weapon will fire up to 15 bullets before requiring a 10-second reload. Bullets will travel up to 80 meters, and will do full damage up to 40 meters away. Bullets will cause 10 damage points (or, if stun, 5 seconds of stun).
This weapon would be a good medium-range semi-automatic weapon because of its limited clip but high damage point ratio. On the other hand, this weapon:
DAMAGE: 3
MAX RANGE: 3
EFFECTIVE RANGE: 6
TOTAL AMMO: 5
RELOAD RELIEF: 3
This weapon will fire up to 25 bullets before requiring a 5-second reload. Bullets will travel up to 48 meters, and will do full damage up to 48 meters away. Bullets will cause 6 damage points (or 3 seconds of stun).
This weapon would be a good spray 'n pray sort of deal because of its limited range but large ammo hold and quick reloading time.
Step 8: Relax a sec
Once you change the notecard (or really any contents of your weapon), the cerix_control script will re-read your notecard automatically. It will spit out all of the stats as it understands them from the notecard (this will only happen if the owner of the item is the same as the key you've placed in the notecard - anybody you pass this to will not have these things spoken to them). If any formatting problems arise, the cerix_control script will tell you so, so that you can go fix your configuration. Once this has passed, the weapon will begin the loading process; once it's loaded, you may commence shooting things at will.
Step 9: Set your permissions
Change the permissions on your contents. At the very least you will need to remove the modify permissions from the cerix_config notecard. In most cases, the permissions (for other users) should look like this:
1. cerix_config - copy, no modify, no transfer
2. cerix_control - copy, no modify, no transfer
3. example_gun (or whatever you've named it) - copy, no modify, no transfer
4. cerix bullet (or whatever you've named it) - copy, no modify, no transfer (scripts too)
OPTIONAL: Customize
If you're comfortable with LSL, you can begin to edit the main gun script to do what you'd like.
Here are the messages you need to know:
To the cerix_control script
• To fire, send a link message to the main prim with the following parameters:
⁃ The integer should be 78548 (since we're using all available methods of data transfer in the link message, we use the integer to tell it what to do)
⁃ The string should be the location (vector) you want to rez the bullet at. Remember to convert this vector to a string.
⁃ The key should be the velocity (vector) you want to rez the bullet with. Remember to convert this vector to a key.
• To reload, send a link message to the main prim with the following parameters:
⁃ The string should be "cerix_reload"
From the cerix_control script
• The script lets your gun script know it's reloading by sending a link message with the following parameters:
⁃ string "cerix_reloading"
⁃ integer reload_time is the number of seconds the gun will be unable to fire (the reload penalty set in config)
• The script lets your gun script know it has completed reloading by sending a link message with the following parameters:
⁃ string "cerix_reloaded"
• The script lets your gun script know it is out of bullets by sending a link message with the following parameters:
⁃ string "cerix_empty"
You can use this information from the cerix_control script to do a number of things, including (but not limited to) the following:
You can setup your messages to the cerix_control script to customize such aspects as:
Feel free to have a blast. Just remember that we can only provide support for potential misbehavior of the cerix_control script or the cerix_bullet_* scripts.
NOTE: The included example script is designed to ask for permissions and attach the gun when the gun is rezzed, even if it is rezzed on the ground instead of in your hands. It is recommended that you keep this option, as we will be producing an HUD for CERIX that can be clicked to rez and attach a new weapon. This HUD will need any weapons a user decides to include to have this automatic attachment aspect.
OPTIONAL (BUT HIGHLY RECOMMENDED): Add an update system
While we promise heartily to try not to make grand, sweeping changes to the system that will screw up your existing content, it's always a good idea to include an update system in your products. We may add functionality you want in your weapons, or we may make slight changes way down the line that make you want to adjust a line or two of script.
Basically, we want to cover our ass so you don't come screaming if we need to tweak something in later versions, and you want in your weapon what all the other developers are now putting in theirs.
For this reason, it's always good to include some kind of automatic update system in case you should want to release a new version.
We recommend hippoUPDATE - it's cheap, it's a pleasure to use, and you can be set up in a matter of minutes. Plus, Andy Enfield's a genuinely nice guy.
ADDITIONAL INFORMATION: Behaviors
Here are a few simple things you should know about how the cerix_control script behaves.
Pick up a free CERIX SDK (Projectile) from any CERIX location. If you haven't already done so, set up a CERIX account using the free CERIX HUD and submit a request for Developer status. You will be able to use your own weapon without the status, but to pass it to anybody else you need this status enabled on your account.
STEP 2: Unpack the Contents
Click the SDK box to unpack the contents into a folder called "CERIX Projectile SDK."
The projectile SDK contains two notecards:
- CERIX SDK Manual - This describes the basic rundown of how the SDK works. There's more info on this website.
- cerix_config - This notecard must be filled out by the developer to configure the weapon.
And four scripts:
- cerix_control (no modify) - This script handles pretty well everything. Pass a link message to it to fire a bullet, and it handles CERIX hud reporting, firing the bullet, how much damage is done, all that stuff. It also sends back other messages to let your own scripts know when to trigger effects like reloading, etc.
- cerix_bullet_damage (no modify) - If it's damage you want, this script goes in your bullet prim. It handles reporting and damage from the bullet's end.
- cerix_bullet_stun (no modify) - If you want to stun, this script goes in your bullet prim. It handles reporting and stunning.
- example_gun - This script is a modifiable example of how to configure your gun script to work with the cerix_control script. If you drop it in a build with the cerix_control script and a cerix_config notecard, it should work OOTB (out of the box), but feel free to change at will. It's heavily commented to help you along.
- example_bullet - Since the cerix_bullet scripts only handle the CERIX part, you'll need another script to do important things like make whiz-bang noises and delete the bullet once it's hit. Here's a bare-bones example to tinker with.
Step 3: Build your weapon
If you have not already done so, go ahead and build your weapon now. The weapon can be any shape or size, but the default example script is set up to assume that it is handgun- or rifle- sized right hand attachment, and that the root prim (the main prim) is reasonably close to the build's center (along the muzzle is okay too).
Step 4: Create the bullet
The projectile kit is designed to fire bullets. All the bullet needs to do for CERIX to work is to fly from the gun and register collision with a target. It can be a simple spherical prim, or if you want to get fancy you can create a shaped bullet. As far as bullets go, an item that is twisted and hollow is sometimes advantageous, as it has many faces on which to register a collision.
The cerix_control script rezzes the bullet at llGetRot(), which means that it will rez the bullet automatically rotated to face the same direction as the avatar. If your prim bullet has fancy shapes (such as a long cylinder), make sure that these are situated along a root prim that will have them line up properly when rezzed facing the direction the avatar is facing.
Note: Setting the bullet buoyancy via llSetBuoyancy(float buoyancy) is a good idea, so that the bullet, if largish, flies along a straight path.
Step 5: Script the bullet
Open the bullet and place the cerix_bullet_damage script inside. Remember that this is the script that enables the bullet to do CERIX damage, so it must be in the bullet for the gun to work.
If you want the weapon to stun instead of damage, use the cerix_bullet_stun script instead. Only one of these scripts may be used in the bullet at any time.
You can add collision effects such as noises or whatnot in another script inside the prim, so long as the script has a name that does NOT start with cerix_bullet.
Remember that if you use llSetDamage(float damage) to make the bullet work in normal SL combat, the bullet will die immediately upon impact in a damage zone. In other words, if the shooter is trying to use the gun as a CERIX weapon in a damage zone, the bullet will do the SL damage first and will probably not get around to doing the CERIX stuff. If you're trying to include a regular SL damage mode, it's probably best to use a separate bullet and set of scripts for this.
Toss the example_bullet script into the bullet as well. This modifiable script (add your own effects and stuff) does important things like delete the bullet when it's done doing its magic.
Remember to make the bullet physical before you take it back into your inventory! We can't shoot a non-physical bullet.
NOTE: We strongly recommend temp-on-rez bullets. All those no-temp prims flying around... bad idea.
Step 6: Script the gun
Place the cerix_control script, the example_gun script, the cerix_config notecard, and your cerix-enabled bullet into the main weapon itself. You don't need to use our example gun script, and we don't provide support for this script. It's just there as a simple out-of-the-box example for you to use.
Step 7: Configure the notecard
Now it's time to edit the cerix_config notecard. The initial notecard looks like this:
//This CERIX SDK features a total of 15 available points, which may be applied to the following statistics as needed:
//EFFECT: This is the damage each point will make. Each point is worth 2 points damage (maximum 10 points). If this is a stun bullet, each point is worth 1.5 seconds of stun.
//Effective Range: Within this range, shots will do full effect. Beyond this range (but within max range), the shot will do a random amount of effect up to the full effect. Each point is worth 8 meters (remember that the bullet will only go as far as you can script the gun to throw it, no matter what this is set to).
//Total Ammo: This is the number of shots available before a reload is necessary (maximum 50 shots).
//Reload Relief: The set reload period is 20 seconds. Each point given here will take 5 seconds off that time (minimum 5 seconds).
EFFECT: 3
EFFECTIVE RANGE: 4
TOTAL AMMO: 6
RELOAD RELIEF: 2
//The developer key is your Second Life avatar key. The bullet name is what you have named the bullet that the CERIX
//control script will rez when you fire the gun.
DEVELOPER KEY: your-key-here
BULLET NAME: cerix bullet
First thing's first. Put your key into the DEVELOPER KEY: field (replace "your-key-here"). What we're looking for here is your Second Life avatar key, a unique string of letters and numbers automatically assigned to you by the Second Life database. If you do not know your own key, you can find it by using the optional "My Key" item contained in the SDK; rez and click to have the item speak your key.
Then enter the name of the bullet. By default, this notecard assumes you've named the bullet "cerix bullet," but if you've gotten all creative-like and named it "my kickass bullet" or something, put that name here. Please be aware that this should be spelled and capitalized to match the bullet object's name perfectly.
Now we get down to the fun part: setting up your weapon's stats.
CERIX has 4 points of configuration to allow you to design your weapon to have a specific function - something we've been calling a "strategic personality." These various points of configuration determine what use your weapon will be in certain situations. Here are the four points:
- Effect: This is the number of damage points (scale of 100) each successful shot will take from the victim, or the number of seconds the victim will be stunned.
- Effective Range: This one's weird. This is the total range in which the bullet will do the full effect assigned to it. Beyond this range (but within the maximum range) it will do a random amount of effect between 0 and its total effect. For instance, if a bullet is set to do 6 damage with an effective range of 64 m, and it hits a target less than 64m away, it will do 6 damage. If it hits the target at 72m, however, it may do only 2. Or 3. Or maybe 6. It's a toss-up beyond the effective range. Note that for obvious reasons, the effective range may be limited by how far the bullet can physically travel, based on the scripts you use.
- Total Ammo: This is the number of bullets (whatever you may choose to call them) that the gun will fire before running out of ammo. Reloading is triggered with a link message from you (so you can choose to do it however you'd like).
- Reload Time: CERIX imposes a time penalty for reloads. You can determine how long this penalty is (between 5 and 20 seconds).
So what's keeping you from maxing out every stat? We're glad you asked.
You'll notice that the CERIX SDK you received has a point value assigned to it. These are NOT hit points. These are "strategic points." Each statistic may be assigned a certain number of points up to the total points included in the SDK. The projectile SDK is a 15-point kit, so you can assign up to 15 points as you see fit to the various aspects of the configuration.
However, this also means that if you want major damage in your bullets, you'll need to sacrifice some on the range, or make it take longer to reload, or lower the number of bullets in the clip in order to keep the weapon balanced.
Points work like this:
- Effect: Each point is worth 2 damage points (not to exceed 20 points) or 1.5 seconds of stun (if using stun bullet).
- Effective Range: Each point is worth 8m (not to exceed maximum range).
- Total Ammo: Each point is worth 5 in the clip (not to exceed 50 points).
- Reload Time: Base reload time is 20 seconds. Each point takes 5 seconds off of the base time (reload time minimum is 5 seconds).
Here's an example:
EFFECT: 5
EFFECTIVE RANGE: 5
TOTAL AMMO: 3
RELOAD RELIEF: 2
This weapon will fire up to 15 bullets before requiring a 10-second reload. Bullets will travel up to 80 meters, and will do full damage up to 40 meters away. Bullets will cause 10 damage points (or, if stun, 5 seconds of stun).
This weapon would be a good medium-range semi-automatic weapon because of its limited clip but high damage point ratio. On the other hand, this weapon:
DAMAGE: 3
MAX RANGE: 3
EFFECTIVE RANGE: 6
TOTAL AMMO: 5
RELOAD RELIEF: 3
This weapon will fire up to 25 bullets before requiring a 5-second reload. Bullets will travel up to 48 meters, and will do full damage up to 48 meters away. Bullets will cause 6 damage points (or 3 seconds of stun).
This weapon would be a good spray 'n pray sort of deal because of its limited range but large ammo hold and quick reloading time.
Step 8: Relax a sec
Once you change the notecard (or really any contents of your weapon), the cerix_control script will re-read your notecard automatically. It will spit out all of the stats as it understands them from the notecard (this will only happen if the owner of the item is the same as the key you've placed in the notecard - anybody you pass this to will not have these things spoken to them). If any formatting problems arise, the cerix_control script will tell you so, so that you can go fix your configuration. Once this has passed, the weapon will begin the loading process; once it's loaded, you may commence shooting things at will.
Step 9: Set your permissions
Change the permissions on your contents. At the very least you will need to remove the modify permissions from the cerix_config notecard. In most cases, the permissions (for other users) should look like this:
1. cerix_config - copy, no modify, no transfer
2. cerix_control - copy, no modify, no transfer
3. example_gun (or whatever you've named it) - copy, no modify, no transfer
4. cerix bullet (or whatever you've named it) - copy, no modify, no transfer (scripts too)
OPTIONAL: Customize
If you're comfortable with LSL, you can begin to edit the main gun script to do what you'd like.
Here are the messages you need to know:
To the cerix_control script
• To fire, send a link message to the main prim with the following parameters:
⁃ The integer should be 78548 (since we're using all available methods of data transfer in the link message, we use the integer to tell it what to do)
⁃ The string should be the location (vector) you want to rez the bullet at. Remember to convert this vector to a string.
⁃ The key should be the velocity (vector) you want to rez the bullet with. Remember to convert this vector to a key.
• To reload, send a link message to the main prim with the following parameters:
⁃ The string should be "cerix_reload"
From the cerix_control script
• The script lets your gun script know it's reloading by sending a link message with the following parameters:
⁃ string "cerix_reloading"
⁃ integer reload_time is the number of seconds the gun will be unable to fire (the reload penalty set in config)
• The script lets your gun script know it has completed reloading by sending a link message with the following parameters:
⁃ string "cerix_reloaded"
• The script lets your gun script know it is out of bullets by sending a link message with the following parameters:
⁃ string "cerix_empty"
You can use this information from the cerix_control script to do a number of things, including (but not limited to) the following:
- Trigger reloading animations
- Produce an empty click or a spoken message when an empty gun is fired
- Produce a spoken message when the gun begins the reloading penalty, so the user knows how long it will take
- Release the gun holding animation during the reloading period so it hangs at the side
- Let the user know when the gun has properly reloaded so they can start firing again
You can setup your messages to the cerix_control script to customize such aspects as:
- Reload automatically on empty
- Reload on spoken command or touch_start()
- Fire slower projectiles, such as arrows or crossbow bolts
Feel free to have a blast. Just remember that we can only provide support for potential misbehavior of the cerix_control script or the cerix_bullet_* scripts.
NOTE: The included example script is designed to ask for permissions and attach the gun when the gun is rezzed, even if it is rezzed on the ground instead of in your hands. It is recommended that you keep this option, as we will be producing an HUD for CERIX that can be clicked to rez and attach a new weapon. This HUD will need any weapons a user decides to include to have this automatic attachment aspect.
OPTIONAL (BUT HIGHLY RECOMMENDED): Add an update system
While we promise heartily to try not to make grand, sweeping changes to the system that will screw up your existing content, it's always a good idea to include an update system in your products. We may add functionality you want in your weapons, or we may make slight changes way down the line that make you want to adjust a line or two of script.
Basically, we want to cover our ass so you don't come screaming if we need to tweak something in later versions, and you want in your weapon what all the other developers are now putting in theirs.
For this reason, it's always good to include some kind of automatic update system in case you should want to release a new version.
We recommend hippoUPDATE - it's cheap, it's a pleasure to use, and you can be set up in a matter of minutes. Plus, Andy Enfield's a genuinely nice guy.
ADDITIONAL INFORMATION: Behaviors
Here are a few simple things you should know about how the cerix_control script behaves.
- If REPORT AMMO is on, it will automatically update the Ammo bar on the CERIX HUD.
- If the user tries to fire their gun without wearing the HUD, the gun will silently fail (noises, effects, but nothing will happen to the target).
- The cerix_control script will tell your gun script when it's empty. It's up to you to make a change to the gun (such as empty clicks on fire or some kind of message). Otherwise, the gun will silently fail (again, noises, all that, but no action on the CERIX front).
- Two guns with REPORT AMMO enabled, equipped at the same time, will confuse the HUD by reporting ammo levels in tandem. If you're doing dual guns, it's best to have one gun with REPORT AMMO enabled, and one without.
- If you're not a Developer, your gun will only work for you.
- When you first wear the weapon, it will need to reload. This is done so that a user may not simply stockpile copies of full copiable weapons to avoid reloading.