Truth & Beauty Lab Network Vendor Manual

Table of Contents
Introduction...........................................................................................................1 Quick Start Guide.................................................................................................2 Rez the vendor server - note & copy the vendor server ID...........................2 Add your products to the server....................................................................2 Configure the server......................................................................................2 Rez the vendor client(s)................................................................................3 Grant debit permission..................................................................................3 Configure each vendor client with the vendor server id................................3 Setting Up the Truth & Beauty Lab Network Vending System..............................3 Rez your vendor server.................................................................................3 Add and configure products in the vendor server.........................................4 Rez your vendor client(s)..............................................................................5 Grant debit permission..................................................................................5 Configure each vendor client with the vendor server id................................5 Configuring split payments............................................................................5 Setting up a Standalone Vendor...........................................................................6 Rez the "Truth & Beauty Lab Vendor Client" object from your inventory.......6 Grant debit permission..................................................................................6 Edit the CLIENT_SETTINGS notecard setting server to the null key............6 Drag and drop objects you wish to sell into the vendor's contents................7 Create product information notecard(s)........................................................7 Create a PRODUCTS_LIST notecard...........................................................7 Client Configuration Variables (CLIENT_SETTINGS)..........................................7 Server Configuration Variables (SERVER_SETTINGS).......................................8 Link Configuration Variables (LINK_SETTINGS).................................................9 Setting Up Inventory...........................................................................................10 Verbal Commands (Vendor)...............................................................................10 Verbal Commands (Server)................................................................................11 Scripts.................................................................................................................11 Creating a Custom Network Vending System....................................................12 Changes Since v0.5...........................................................................................12 Further Information.............................................................................................12

Introduction
The Truth & Beauty Lab Network Vending System consists of two primary

components - a vendor server and vendor clients. The vendor server contains the products you wish to sell as well as the information on their name, price, etc. The vendor client displays your products to other residents, accepts payment, and delivers purchases to your customers. A typical setup would have a single vendor server with multiple products and several vendor clients spread around a sim. It is also possible to setup multiple vendor servers, each with their own product lines and vendor clients spread around the grid talking to different vendor servers. The Truth & Beauty Lab Network Vending System is pre-configured for immediate deployment. All that is necessary to get setup and start selling products is to: a) rez your vendor server b) add and configure products in the vendor server c) rez your vendor client(s) d) configure each vendor client with the vendor server id Each of these steps will be detailed below after first presenting a minimal "Quick Start Guide".

Quick Start Guide

Those desiring to deploy the Truth & Beauty Lab Network Vendor with a minimal amount of effort may do so by utilizing the default settings and following these abbreviated instructions. Subsequent sections will detail additional configuration and deployment features. Rez the vendor server - note & copy the vendor server ID When you rez the "Truth & Beauty Lab Vendor Server" object, it will chat its UUID to local chat. Note and/or copy this ID as it will be needed when setting up the vendor client(s). Add your products to the server Drag and drop objects you wish to sell from your inventory into the server's contents. Configure the server Edit the PRODUCTS_LIST notecard, adding one line for each product you are selling. The format of the product description lines is:

(Category)#(SubCategory)#(Price)#(Inventory Name)#(Texture UUID) The notecard TRUTH_BEAUTY is provided as an example product list. The texture UUID in the last field is the UUID of the texture you want displayed on the vendor for that product. Rez the vendor client(s) Drag the "Truth & Beauty Lab Vendor Client" object from your inventory to the ground. You may deploy as many of the vendor clients as you wish to any location on the grid where you have permission to rez objects. Grant debit permission Granting debit permission is required. Configure each vendor client with the vendor server id Edit the CLIENT_SETTINGS notecard in each of the vendor clients you rezzed. Set the "server" setting in this notecard to the server UUID you copied above. Your Truth & Beauty Lab Network Vendor System is now setup and selling the products you added to the server. To additionally configure your network vendor or for a more detailed step by step setup, read on.

Setting Up the Truth & Beauty Lab Network Vending System

Rez your vendor server After unpacking the Truth & Beauty Lab Network Vending System box there will be a "Truth & Beauty Lab Network Vendor" folder in your inventory. Inside this folder you will find a "Truth & Beauty Lab Vendor Server" object. Drag the vendor server object from your inventory to the ground. When you rez the "Truth & Beauty Lab Vendor Server" object, it will chat its UUID to local chat. Note and/or copy this ID as it will be needed when setting up the vendor client(s). The vendor server can be located anywhere you have permission to rez objects and does not need to be visible to your customers. It can even be placed inside another object to hide it completely. However, you will need to gain access to it to update your product list so do not hide it so well you cannot locate it :)

Add and configure products in the vendor server Right click the vendor server object and select "Edit" then click on the Contents tab in the edit window. Drag and drop the products you wish to sell from your inventory to the Contents of the vendor server object. Note that each product must have Copy and Transfer permissions in order to be copied and transferred to your customers. Next owner permissions can be however you want. Once you have populated the vendor server object with your products you will need to edit the PRODUCTS_LIST notecard to inform the server of your product names, prices, etc. To do so, right click the PRODUCTS_LIST notecard in the server's contents and select "Open". Each line of this notecard describes a single product and each product in your vendor will require a line in this notecard. The format of the product description lines is as follows: (Category)#(SubCategory)#(Price)#(Inventory Name)#(Texture UUID) The notecard TRUTH_BEAUTY is provided as an example product list. It contains 27 products in 4 categories. Feel free to view the TRUTH_BEAUTY product notecard as a guide to configuring your own product list in the PRODUCTS_LIST notecard. You can use existing textures for the product texture UUID field or create new textures that display your product and, optionally, price. These textures are displayed on the vendor client board - three products at a time on the right panel of the board and whatever product is selected on the main panel. Note that the vendor client board can be resized to accomodate any aspect ratio product pics. By default, the board is sized to display product textures in a 5:3 aspect ratio. For instance, textures with resolution 256x154 or 128x77 would display properly. If your product textures are a different ratio then you can simply resize the vendor client board. If you wish to deliver separate product information notecards when customers click the "Product Info" button, create a notecard for each product and name the notecard the same as the product name followed by "Info". For instance, a product named "Foo Bar Widget" would need an information notecard named "Foo Bar Widget info". See "separate info" below. Finally, edit the SERVER_SETTINGS notecard and set the following configuration variables: email agents - whether your vendor has an email notification script

anon access - do you want to allow anonymous access email sales - do you want the server to track sales and inquiries email address - email address to use for server output See the Server Configuration Variables section below for a complete list of server configuration variables. Rez your vendor client(s) Inside the Truth & Beauty Lab Network Vendor folder in your inventory you will find a "Truth & Beauty Lab Vendor Client" object. Drag the vendor client object from your inventory to the ground. The network vendor client can be located anywhere you have permission to rez objects and should be placed so as to be easily accessed by your customers (e.g. near a landing point or in a shop). This will be the board that displays your products and collects purchase payments. Grant debit permission When first rezzed the network vendor client will display a dialog window requesting debit permission from the owner. The board needs debit permission in order to refund payment amounts exceeding the price of a product. No Lindens are ever debited from the owner's account that were not erroneously paid through the network vendor. Granting debit permission is required. Configure each vendor client with the vendor server id Edit each of the vendor clients you rezzed by right clicking the board and selecting "Edit". You will need to edit the CLIENT_SETTINGS notecard - right click the CLIENT_SETTINGS notecard and select "Open". This notecard contains the following configuration variables: info card - the name of a product information notecard separate info - does each product has an individual information notecard buffer - size of buffer email agents - whether your vendor has an email notification script server - UUID of vendor server you wish to use email - your email address, if email notification are to be sent blog - URL of your blog, if any marketplace - URL of your Second Life Marketplace shop, if any See below for a complete list of client configuration variables. Configuring split payments If you wish to split payments to the vendor between 2 or 3 avatars you will need

to edit the BUY_SETTINGS notecard. To do so, while editing the vendor client check the "Edit linked parts" box and click the main (largest) product display panel on the vendor board. In the contents of this prim, edit the BUY_SETTINGS notecard, setting SPLIT = 1, the avatar key for each avatar, and either a flat amount or percentage to each avatar.

Setting up a Standalone Vendor

The Truth & Beauty Lab Network Vending System can also be deployed in standalone mode. In standalone mode the vendor client searches its own inventory for the product database, products, information notecards, etc. There is no server in this mode and each vendor client deployed must contain all the products and information needed to act as a vendor. This mode is preferable in situations where only a single vendor client will be deployed as it avoids any network performance issues. Setup of a standalone vendor is essentially the same as that for a network vendor but the products, product information notecards, and product list notecard are placed in the vendor client rather than the vendor server. No SERVER_SETTINGS is needed and a NULL_KEY server setting is used. Follow these steps to setup a standalone vendor: Rez the "Truth & Beauty Lab Vendor Client" object from your inventory See the Rez your vendor client(s) subsection of the previous section for details. Grant debit permission See the Grant debit permission subsection of the previous section for details. Edit the CLIENT_SETTINGS notecard setting server to the null key This is essentially the same as detailed in the Configure each vendor client with the vendor server id subsection of the previous section except for the server setting. In standalone mode the server must be set to the NULL KEY: server = 00000000-0000-0000-0000-000000000000 Alternately and maybe more simply, the server line in CLIENT_SETTINGS can be deleted as the default setting is NULL_KEY. All other settings in the CLIENT_SETTINGS notecard are identical in nature to that described in the

previous section on network vendor setup. Drag and drop objects you wish to sell into the vendor's contents See the Add and configure products in the vendor server subsection of the previous section for details. Create product information notecard(s) See the Add and configure products in the vendor server subsection of the previous section for details. Create a PRODUCTS_LIST notecard See the Add and configure products in the vendor server subsection of the previous section for details.

Client Configuration Variables (CLIENT_SETTINGS)

offline texture - (DEFAULT: b8426d53-221d-9fc2-5b29-3ef16e2bd7a3 ) If the vendor is configured to be networked and the server it has been configured to contact is offline or if the vendor's owner requested it to become offline, the vendor will use this texture uuid on all displays to signify that the vendor is unusable. nothing texture - (DEFAULT: 93481f65-67ff-f166-cc64-e6fe1069c1c1 ) When no product is found for a certain index, the vendor will use this texture uuid to show that no product is available for that index. product card - (DEFAULT: "PRODUCTS_LIST" ) Vendor will use this notecard to load products that the owner wants to sell info card - (DEFAULT: "INFO" ) Whenever information has been requested, give the person who requested it a notecard of that name. comm channel - (DEFAULT: 45 ) Vendor owner will use this channel to give the vendor certain commands. buffer - (DEFAULT: 0 ) Vendor will not load the complete list of products into an array as other vendors normally do. To conserve script memory, the vendor will keep a list of products in a list of a certain size. The size of this list is as large as the number of displays used to show products plus the value of the buffer. Increasing this value will

reduce the chance that the vendor will retrieve the product from a notecard slowing the vendor down. Having a buffer that is too large will however cause the script to produce a stack heap collision. server - (DEFAULT: NULL_KEY ) When set to a key value other than NULL_KEY, vendor will try to network with that uuid in a networked mode instead of relying on its own inventory in a standalone mode. key - (DEFAULT: "" ) When set to a value other than "", vendor will encrypt its communications between itself and the server using this shared key. refresh - (DEFAULT: 3,600 seconds = 1 hour ) Whenever vendor is in a networked mode, vendor will try to clear its inventory out and obtain the latest product card uuid ensuring the vendor has the latest product line. timeout - (DEFAULT: 60 seconds = 1 minute ) The server may not reply to the vendor immediately. Give the server this long to respond to the requests of this vendor. If server didn't respond to the requests of the vendor in this time server will be considered down and vendor will go offline after the timeout has occured. email agents - (DEFAULT: 0 ) If vendor is networked and there are dedicated e-mail scripts to offload the 20 second script sleep penalty, setting this value to 1 will make the vendor use the dedicated script keeping the vendor active instead of running into the 20 second e-mail penalty. blog - (DEFAULT: none) If set, the blog URL will be IM'd to the avatar clicking the Product Info button along with the product's information notecard. marketplace - (DEFAULT: none) If set, the marketplace URL will be IM'd to the avatar clicking the Product Info button along with the product's information notecard.

Server Configuration Variables (SERVER_SETTINGS)

comm channel - (DEFAULT: 54 ) Server owner will use this channel to issue server commands. product card - (DEFAULT: "PRODUCTS_LIST" ) Vendor will use this notecard to load the products the owner wants to sell. Server will give the uuid of this card out to the vendors that request it. email agents - (DEFAULT: 0 ) If server has a dedicated e-mail script to offload the 20 second script sleep penalty, setting this value to 1 will make the server use the dedicated script keeping the server active instead of running into the 20 second e-mail penalty. key - (DEFAULT: "" ) When set to a value other than "", server will encrypt its communications between itself and the vendor using this shared key. anon access - (DEFAULT: 0 ) When set to 1, server will accept requests from in-world objects owned by all people. Otherwise, server will only resond to requests that come from in-world objects of the same owner. outside access - (DEFAULT: 0 ) When set to 1, server wil accept requests that came from outside Secondlife. Otherwise, requests are limited to in-world objects. To make use of this variable, "anon access" must be set to 1.

Link Configuration Variables (LINK_SETTINGS)

images - (DEFAULT: 0 ) When set to 1, the containing prim will be used to show a product with associated index. absolute category - (DEFAULT: 0) When set to 1, the assigned Category index will not change as vendor index changes category - (DEFAULT: 0 ) This sets the category index of the link. When containing prim is clicked, this will tell the vendor to move the category either to that index, or relative by that index. This depends on whether or not the category is absolute or relative.

absolute subcategory - (DEFAULT: 0) When set to 1, the assigned subCategory index will not change as vendor index changes subcategory - (DEFAULT: 0 ) This sets the subcategory index of the link. When containing prim is clicked, this well tell the vendor to move the subcategory either to that index, or relative by that index. This depends on whether or not the subcategory is absolute or relative. texture The texture uuid to use for the category selection button. Defaults for the four category selection buttons are textures for Clothing, Gadgets, Textures, and All. A few category textures are provided with the Truth & Beauty Lab Network Vendor. You can use these textures for your category selection buttons or create new textures of your own. The uuid of a texture can be copied by right clicking on the texture in your inventory and selecting Copy asset UUID. If you wish to disable one or more of the category selection buttons, set the texture variable in that buttons section of the LINK_SETTINGS notecard to none (texture = none).

Setting Up Inventory
Notecard configuration of vendor products is different than that of setting up a configuration card for vendor scripts. Each line of this notecard contains a variable length record of the inventory to be sold. Record structure is as follows... (Category)#(SubCategory)#(Price)#(Inventory Name)#(Texture UUID) When creating a list of records, make sure that there are no spaces between elements separated by the "#" character. The UUID of a texture can be found by right clicking the texture in your inventory.

Verbal Commands (Vendor)

online - When vendor is in an offline mode, attempts to return functioning status to the vendor. offline - When vendor is functioning, takes the vendor into an offline mode.

reset - Resets vending system scripts. debug - As the vendor operates, vendor will give its owner an indication of its current processes through verbose output. count - Returns the number of information notecard requests from this vendor memory - Returns the number of bytes that are free within the vendor

Verbal Commands (Server)

debug - As the server operates, server will give its owner an indication of its current processes through verbose output. id - returns the uuid used by the containing object. Use it for configuring the vendors in networked mode. reset - Resets server system scripts.

Scripts
The Truth & Beauty Lab Network Vending system contains the following LSL scripts: VendorMainClient - This script manages the state of the vendor in general as well as keeping track of the Vendor index and updating the displays. VendorProductDatabase - This script contains all of the inventory for your products within an inventory buffer. Scripts can make queries in its database using product category and subcategory index. If the query isn't within the product buffer, this script will search the product notecard for the requested item. The result of searching in the notecard will then be added to the buffer for quicker access. VendorLink - This script when clicked notifies the Vendor to move to a certain product index. If specified, the script will also register itself into VendorMainClient as a display to show its associated product. VendorBuy - This script when paid a specified amount, will notify

VendorMainClient that a sale has been made. It will also get messages from VendorMainClient to change the amount one has to pay to get a product. VendorInfo - This Script when clicked, will notify VendorMainClient that a person requests an information notecard. VendorMainServer - This script will help keep all the client vendors updated with the uuid of the products notecard. It will also give inventory to a specified uuid upon request. VendorEmailAgent - This script will offload the 20 second script delay penalty from either VendorMainClient or VendorMainServer.

Creating a Custom Network Vending System

The Truth & Beauty Lab Network Vendor System comes pre-configured and ready to deploy "out of the box" with minimal configuration (see Quick Start Guide above). However, the LSL scripts in this vendor system are licensed under the GNU General Public License and my be modified, redistributed, etc under that license. As such, it is entirely legal and possible to create your own vendor system from scratch using these scripts.

Changes Since v0.5

This Version of the Truth & Beauty Lab Network Vending System underwent a major redesign. This adds new features to the system, making it more flexible to configure, adding product category selection buttons, and drastically reducing the number of scripts thereby significantly reducing lag. This vending system can either be standalone or networked with a central server that has been rezzed in a supposedly permanent location. Also, it is possible now for others to re-sell your content. And communication in-world can be kept safer from exploitation using a shared key for encrypting messages between vendor and server.

Further Information
The Truth & Beauty Lab Network Vendor Manual (this document) is available in

PDF format at http://www.scribd.com/missyrestless View the Truth & Beauty Lab Network Vendor inworld at http://slurl.com/secondlife/Gualdo/210/226/42/ View other Truth & Beauty Lab creations in the Second Life Marketplace at https://marketplace.secondlife.com/stores/44210 Have fun and email missyrestless@gmail.com with any questions, comments, suggestions, and problem reports.