Monday, July 27, 2015

Script: Unpacker Scripts

[Black Tulip] Script - Unpacker Scripts (Script for Designers)

(c) 2015 Auryn Beorn

Script - Unpacker Scripts in Marketplace.

Thank you for having considered this script to enhance the quality of your products. Please read the following instructions carefully, especially the ones explaining which permissions to apply to the scripts for the next owner. Failure to complete this task INVALIDATES the license governing your use of this set of scripts.

IMPORTANT!
Each script contains a check to prevent accidental give-aways. If you haven't set permissions correctly in your inventory, then the scripts will self delete when you try to use them. The best way to ensure you set permissions correctly is by doing it NOW in your inventory.

TABLE OF CONTENTS



CHANGE PERMISSIONS FOR NEXT OWNER


Check the following section on this page, knowing that each [Black Tulip] ASSET refers to the scripts contained in the package as well as the supplied mesh boxes and pose. The textures shouldn't be distributed.

IMPORTANT: If you include any no copy assets in your package box, the script will not attempt to send them, and so they will remain inside the box. The script will warn the user about this, per no-copy item that it founds. Since you're using an unpacker script, you should be always working with COPY assets for next owner.


ABOUT THE SUPPLIED MESH ITEMS, TEXTURES, AND POSE


In the event that you don't have yet any unpacking box to deliver to your customers, and/or a pose for wearable ones, you can use the included ones.

  • [Black Tulip] Holding is a priority 4 pose that you can use in conjunction with the scripts that work with animations (It's explained after this which ones are those).
  • [Black Tulip] Unpacker Box is a mesh box with a face reserved to drop your product vendor. It's textured with the UV Layout, in case you want to create your own textures for it.
  • [Black Tulip] Unpacker Box - TEXTURED is the same mesh box, with the included baked texture applied to it.
  • [Black Tulip] Unpacker Box - Add/Wear - TEXTURED is again the same mesh box, already positioned and rotated to be used with the unpacker scripts that also pose your avatar and the included [Black Tulip] Holding pose.
  • [Black Tulip] Unpacker Box - UV is a texture you can download to your computer with the guides to create your own box textures. It's color-coded so you can easily relate which parts of the mesh correspond with which parts of the UV layout texture.
  • [Black Tulip] Unpacker Box - AO is the corresponding ambient occlusion map, to add shading if you create your own box textures.
  • [Black Tulip] Unpacker Box - BAKED is a baked texture that you can use directly. The [Black Tulip] Unpacker Box - TEXTURED and [Black Tulip] Unpacker Box - Add/Wear - TEXTURED mesh items have this texture already applied.

If you've never used/textured mesh objects, you may want to check out the following documentation posts:


IMPORTANT: The space reserved for your product vendor picture is expecting an 1:1 aspect ratio texture. Product ads having a different aspect ratio may show distorted.


GIVE FOLDER ON TOUCH - BASIC


If you simply want a script that will deliver contents in a folder to the owner of the object, use the [Black Tulip] Unpacker - Give items on touch in folder BASIC script included in the package. The unpacker script itself isn't delivered in the folder.


GIVE FOLDER ON TOUCH


The [Black Tulip] Unpacker - Give items on touch in folder script gives a couple of configuration choices that the [Black Tulip] Unpacker - Give items on touch in folder BASIC script doesn't include. It allows us to add hover text indicating that the box is ready to be clicked for unpacking, and that the unpacking operation has been performed once the folder is sent.

We can decide the text by writing it in the description of the prim with the unpacker script (and the assets to be delivered in a folder) something like this:

rdy=Click to unpack#done=Unpacking complete\nEnjoy!

Notice the # character: it's separating the two fields that the script needs:

rdy=Click to unpack
done=Unpacking complete\nEnjoy!


The rdy= part is what tells the script the text you write after, will show as hover text when rezzing the box to unpack. The done= is what tells the script the text you write after, will show as hover text when the folder with items has been sent. Note that by writing \n we're introducing a carriage return in the hover text: we would use this to separate text in lines.

Try keeping your hover text concise: The description field of a prim only allows for a maximum of 127 characters.


GIVE FOLDER ON TOUCH - WEAR AND ANIMATE - BASIC


The [Black Tulip] Unpacker - Play Anim & Give items on touch BASIC script is meant for attached unpacking boxes that will play a pose/animation while attached. Neither the script nor the configured animation/pose will be sent in the folder delivered to our customer.

In order to achieve this, we need to type one command in the unpacking box description field. Before seeing what exactly, let's talk about the other feature of this script:

When setting the unpacking box to be attached, likely we've changed its rotation, so it fits with the pose. But our customers could rez the box anyway. This would leave the box rezzed in a strange rotation, like the picture shows:


If you would like that the box is rezzed with a correct rotation:


you have to supply a certain parameter also in the unpacking box description field. Let's see that now, together with how to indicate which is the animation to use as "hold" pose (Remember: This pose won't be a part of the contents of the unpacked folder.)

We can write the description of the item as follows:

anim=[Black Tulip] Holding#rot=<0,0,180>

As we can see, again the # character is separating fields, so in this case we have:

anim=[Black Tulip] Holding
rot=<0,0,180>


The first one is pretty obvious: after the anim= part, we write the name of the animation included to pose when wearing the unpacking box. Then after the rot= part, we have three numbers between < and > and separated by commas. How do we know which numbers?

We know which numbers by editing our object, and taking note of the numbers showing under the Rotation edit boxes:


We must type them in the same XYZ order they show in the Edit window, this way:

rot=<X_Value,Y_Value,Z_Value>


GIVE FOLDER ON TOUCH - WEAR AND ANIMATE


The [Black Tulip] Unpacker - Play Anim & Give items on touch script gives the same functionality than the script explained above, plus the rdy and done parameters explained for the [Black Tulip] Unpacker - Give items on touch in folder script, to show hover text. Try keeping the description brief: the description field of a prim only allows for a maximum of 127 characters.


GIVE FOLDER ON TOUCH - HUD VERSION


Creating a HUD version is not so different than creating a regular unpacking box. For starters, if you've never created a HUD and don't know how to go about it, check this tutorial about creating HUDs in SL.

There's a sample HUD supplied, no transfer, to show how you could create your own: [Black Tulip] Test HUD to Inspect - Add/Wear. Knowledge about working with linked sets and what a child prim is, is assumed here. The basic idea is, you will create different prims for the different buttons you want to include:

  • In the button that should be your product vendor picture, you include all the items to deliver plus the [Black Tulip] Unpacker - Give items on touch in folder BASIC script.
  • You may have different buttons to give a landmark to your store, a notecard with information... In all those instances of giving a single item upon touch of the button, you will drop that single item (landmark, notecard...) and the [Black Tulip] Very Simple Single-Item Giver script (with permissions correctly adjusted; green prims on the sample HUD).
  • You may also want that other buttons open a website upon touch. In that case, when editing your HUD object inworld, first, in the DESCRIPTION field of the prim, you write the web address, as-is. Again, remember that the description field of a prim only allows for a maximum of 127 characters. If you have large web addresses, you may consider services like http://tinyurl.com/ to reduce it. After this, you drop the [Black Tulip] Click for Web Address script in that prim.

    This script will write the website address in local (nearby) chat, and will also show a dialog menu offering to open the web page. If you don't want that the popup shows, simply add #no-popup in the prim's description field, after the web address you write. You find the examples to inspect on the purple prims on the sample HUD.


TROUBLESHOOTING


Q: The hover text showing isn't the one I've specified.

A: Make sure that you're using the DESCRIPTION field of the prim, not the name field.

Q: I change descriptions on the HUD, but the scripts don't read them.

A: Make sure that you're changing the description field of those prims when the HUD is rezzed inworld, not attached to your avatar.


-- Auryn Beorn