Open Source

GPHUD is now open sourced at GitHub

This details deploying the code base from scratch

You can bypass this step entirely by downloading the package file attached to GPHUD. You may also wish to “star/watch/whatever” this project to get notifications when a new release is made.

You will need

• JDK version 11 or higher
• Maven
• Mysql/Mariadb database, version 5.7? (untested on MySQL8)
• Probably Apache

• Create a directory
• Check out SLCore, JavaCore and GPHUD repositories
• Go into the GPHUD directory
• Run “mvn package”
• Check the bin directory for the results

• Create a mysql database “sl” and “gphud”, and import the schema SQL files from the SLCore and GPHUD repositories respectively.
• Configure a user with all permissions (including create, drop table, etc, schema upgrades are part of the code) on the appropriate database for the server application

The process for starting the server is to just run the JAR file with a properties passed in.

Please see SLCore repository for an example.properties file, the file is documented but at a minimum you'll need to specify:

• A listening port (port)
• A host name (hostname)
• A contact email address to spam you with system logs (developermail)
• A database host, db name, username, password for the SL database (jdbc)
• A randomly generated string to use as a secret salt (digestsalt)
• A database host, db name, username and password for the GPHUD database (gphud-jdbc)

You can ignore the later secionts about JSLBotBridge and LSLR

• Start the application ; “java -jar GPHUD-version-name.jar yourhost.properties”

You should be able to web browse to its port (HTTP).

• Configure an apache proxy on 443 with a certificate for user access. For reasons of an SL bug, HTTP is used for the connections from LSL.

You need to add a basic record to the user table in the SL database You can either use a database editor of your choice - create a new row containing a username (your avatar name), an avatarkey, a developerkey and set superadmin to 1 and lastactive to 0

insert into users(id,username,avatarkey,superadmin,lastactive,developerkey) values(1,'Bob Smith','12345678-90ab-cdef-1234-567890abcdef',1,0,'LONG-RANDOM-SECRET-STRING-HERE (32-64 chars)');

Configure your Firestorm (Prefernces, Firestorm→Preprocessor build path) to point to where you checked out the 3 Git repositories (you need at least SLCore and GPHUD).

Copy “configuration.lsl” from the SLCore repository and place it in the directory above (Where your checked out repositories live, and the folder above in Firestorm is pointing)

• Construct a single prim to be a server
• Create a one line script called “Dispenser” and insert the single line: #include “GPHUD/LSL/Dispenser.lsl”
• Create a one line script called Dispenser Slave and insert the single line: #include “GPHUD/LSL/Dispenser Slave.lsl”
• Do this for scripts “Dispenser Slave 1”, “Dispenser Slave 2” and “Dispsenser Slave 3” (all the same include line)
• Create a NOTECARD called “GPHUD Non Server Functionality Inhibitor” containing some text and insert it into the Server prim (this stops the Object Driver from activating)
• Create script “GPHUD Object Driver” containing #include “GPHUD/LSL/Objects.lsl”
• Create script “Server” containing #include “GPHUD/LSL/Server.lsl”
• Turn off Modify for next owner on all scripts, and the prim its self

• Create a prim called “GPHUD Item Giver”
• In it, create “GPHUD Item Giver” script containing just #include “GPHUD/LSL/Item Giver.lsl”
• Turn off Modify for next owner on all scripts, and the prim its self
• Take this object and insert it into the server's inventory

• Create a prim named “GPHUD Remote Dispenser”
• In it, create a script called “Remote Dispenser” containing the line #include “GPHUD/LSL/RemoteDispenser.lsl”
• Turn off Modify for next owner on all scripts, and the prim its self
• Take this object, insert it into the server's inventory

• Create a prim named “GPHUD Titler”
• In it, create a script “Attacher” containing #include “GPHUD/LSL/Attacher.lsl”
• Create another script “Titler” containing #include “GPHUD/LSL/Titler.lsl”
• Turn off Modify for next owner on all scripts, and the prim its self
• Take this object and insert it into the server's inventory

• Create 37 prims (4 x 4 x 2 and 5 more) and link them all together
• Attach your 37 prims to your HUD_BOTTOM position (for now)
• Create a script called “Builder” containing the following line #include “GPHUD/LSL/HUD Builder.lsl”
• This will reshape and move all the prims around, and if on the SL grid, texture them.
• Move the HUD's main panel so it is bottom center of the HUD screen
• Delete the “Builder” script
• Create a script “UIX” containing #include “GPHUD/LSL/UIX.lsl”
• Create a script “UI” containing #include “GPHUD/LSL/UI.lsl”
• Create a script “Attacher” containing #include “GPHUD/LSL/Attacher.lsl”
• Create a script “HUD” containing #include “GPHUD/LSL/HUD.lsl”
• Detach this object and rez it on the ground (THIS MIGHT BE IMPORTANT - LOOK UP THE SLAM BIT if you don't know why)
• Turn off Modify for next owner on all scripts, and the prim its self
• Take the HUD and insert it into the Server object

Assumed starting point:

• A fresh install of Ubuntu 20.04 server with no particular options selected.
• A functional OpenSim (You must configure “ExternalHostNameForLSL” to your public sim ip/name and “OutboundDisallowForUserScriptsExcept” to your GPHUD server name)
• A functional SMTP daemon on your Ubuntu server

Your sim and server can be the same, they can be different, in my walkthrough, they are different. I will be using a VM called “gphudtest.coagulate.net” to run the server software.

Throughout this documentation I will refer to 3 machines

• “The windows machine” - wherever you run firestorm, could be a Linux box really, this is where you'll do stuff that requires LSL functionality.
• “The server” - will refer to the Linux server running the GPHUD software, Ubuntu in this run through
• “The opensim server” - any config changes necessary to opensim will be prefaced with this identifier

Unix operations are presumed to be performed as a normal user (don't run GPHUD as root). It is assumed you have sudo access during the setup. You can use root logins and su down for the non root parts if you prefer.

sudo sh -c 'echo deb http://repo.mysql.com/apt/ubuntu/ bionic mysql-apt-config >>/etc/apt/sources.list.d/mysql.list'
sudo sh -c 'echo deb http://repo.mysql.com/apt/ubuntu/ bionic mysql-5.7 >>/etc/apt/sources.list.d/mysql.list'
sudo sh -c 'echo deb http://repo.mysql.com/apt/ubuntu/ bionic mysql-tools >>/etc/apt/sources.list.d/mysql.list'
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 8C718D3B5072E1F5
sudo apt-cache policy mysql-server
sudo apt-get install apache2 default-jre mysql-server=5.7.31-1ubuntu18.04 mysql-community-server=5.7.31-1ubuntu18.04 mysql-client=5.7.31-1ubuntu18.04

Download all the relevant software - see [https://github.com/CoagulateSL/GPHUD/releases/latest https://github.com/CoagulateSL/GPHUD/releases/latest] for latest release

wget https://github.com/CoagulateSL/GPHUD/releases/download/3.16.12/GPHUD-3.16.12-jar-with-dependencies.jar
git clone https://github.com/CoagulateSL/WebResources
wget https://raw.githubusercontent.com/CoagulateSL/SLCore/master/example.properties
mv example.properties gphudtest.properties

Set up the database, schemas, and db user

mysql -u root -p -e 'create database sl';
mysql -u root -p -e 'create database gphud';
wget https://raw.githubusercontent.com/CoagulateSL/SLCore/master/slcore-schema.sql -O- -q|mysql -u root -p sl
wget https://raw.githubusercontent.com/CoagulateSL/GPHUD/master/gphud-schema.sql -O- -q|mysql -u root -p gphud
mysql -u root -p -e "create user gphud@localhost identified by 'mypass'"
mysql -u root -p -e 'grant all on sl.* to gphud@localhost'
mysql -u root -p -e 'grant all on gphud.* to gphud@localhost'

Configure the properties file with the following settings

• hostname=gphudtest
• developeremail=whatever@somewhere.some (not telling you :P)
• jdbc=jdbc:mariadb:localhost:3306/sl?user=gphud&password=mypass&maxPoolSize=10&connectTimeout=5000 * grid=OSGrid * digestsalt=Nd93ng0sk3A * urlhostname=gphudtest.coagulate.net * gphud-jdbc=jdbc:mariadb:localhost:3306/gphud?user=gphud&password=mypass&maxPoolSize=10&connectTimeout=5000
• gphud-distributionregion=Coagulate
• skipshardcheck=true

Start the server

java -jar GPHUD-3.16.12-jar-with-dependencies.jar gphudtest.properties

Install the apache config sudo wget https://raw.githubusercontent.com/CoagulateSL/SLCore/master/example-apache.conf -O/etc/apache2/sites-enabled/gphud.conf Edit this file (/etc/apache2/sites-enabled/gphud.conf) and change

• ServerName gphudtest.coagulate.net
• Change the PORT in Proxy lines to 12345
• Change LOCATION-OF-WEB-RESOURCES - on my machine this overall becomes /home/iain/WebResources/resources/$1
• SSLCertificateFile /home/iain/keys/cert.pem
• SSLCertificateKeyFile /home/iain/keys/privkey.pem
• SSLCertificateChainFile /home/iain/keys/fullchain.pem

Enable SSL + proxying in apache

• a2enmod ssl
• a2enmod proxy
• a2enmod proxy_http

At this point, you should be able to browse to http://gphudtest.coagulate.net/ (or whatever) and load your index page.

One last thing, we bootstrap our avatar name/UUID as a super user with a dev key

mysql -u root -p sl -e "insert into users(id,username,avatarkey,superadmin,lastactive,developerkey) values(1,'iain maltz','cb191fe5-0941-46e6-81b9-c57431fd0ee4',1,0,'MAUISfh9udhwue9AS9b39qubf9udba');"

• On the “windows” machine, create a folder and check out from github (download, or better use github desktop to clone the repositories) the GPHUD and SLCore repositories
• Copy configuration.lsl from SLCore folder to the folder above (the folder containing the SLCore folder)

Edit it as follows:

• #define DIGEST_SALT “Nd93ng0sk3A”
• #define CHANNEL_MUTATOR 356965858
• #define COMMS_DEVKEY “MAUISfh9udhwue9AS9b39qubf9udba”
• #define SERVER_HOSTNAME “gphudtest.coagulate.net”
• #define SYSTEM_OWNER_UUID “cb191fe5-0941-46e6-81b9-c57431fd0ee4”
• #define NOEXPERIENCES

(Just remove the at the start of #define NOEXPERIENCES) * #include “SLCore/LSL/SecondLifeConstants.lsl”

• #include “SLCore/LSL/OSGridConstants.lsl”

Go to firestorm, preferences, firestorm, build 1, and set the preprocessor include path to the folder containing the configuration.lsl file, SLCore and GPHUD folders

Build all the objects as detailed earlier on

Say **createinstance Test near your newly forged Region Server, observe the successful result.

60 seconds later, click the Region Server to obtain a HUD.

While opensim doesn't have Experience support used for the auto attachment in Second Life, it does have the ability to bypass permissions checking for the region/estate owner/managers

• On your region, press Alt+r to bring up the region settings.
• On the debug tab, select “Region Debug Console” at the very bottom
• In the new window, type in

set auto_grant_attach_perms true

• The simulator should reply and state roughly the same as what you told it to do
• Attachments should now be automatic when triggered (which if auto attach is enabled in the GPHUD Server means it will attach to everyone automatically, without even the “Accept Experience” dialog of Second Life)