MultiPath OP System - Installation and Guidelines
=================================================
The following text is designed as a brief instruction manual for the
MultiPath OP System for use with world OP servers in ActiveWorlds (and
Activeworlds clone universes). if you are intending on using or trying
this system please read through carefully to avoid any problems with
operation.
The MultiPath system is a project of Who (Aw cit# 230147) and is freely
available to anyone that wishes to use or modify it. Email address for
enquiries is ricta@ricta.net The system employs the use of certain php
scripts written by Ananas (also an AW citizen), further information
about certain sections contributed by him (described later) or general
information may be obtained from his website at http://oct31.de/aw/index.html
This document is divided into a number of sections as listed below, all
should be read thoroughly if you intend setting up the system.
Note: MultiPathOP is still considered "beta" in nature due to this being
its first release. There are bound to be a number of instances (commonly
called bugs) that may appear through various use. If you encounter such
a problem, please advise via email of the problem and any error code
reported so they may be addressed in future updates.
It is strongly recommended that a novice user avoid this system in its
current form. The system does have the ability to make a real mess of
your OP if used incorrectly. But then, you can also make a real mess of
your OP without the aid of this system! :-)
Section:
1. Basic Ideals.
2. System Requirements
3. Installation.
4. Using the system.
-----------------------------------------------------------------------
1. Basic Ideals:
From my own point of view the main problem with building and creating
within Activeworlds was being able to know what objects where available,
what they looked like and what they were called. Many an hour has been
wasted trying to find something suitable for a build only to discover
later that there was a particular object already available for use, I
just didn't know it was there or what it was called!
The MultiPath system attempts to alleviate this while also providing
various other features as well. In fact, the system is basically a
database that you create 'as you go' providing information about any or
all your files you make available on your world OP and provides search
facilities for others to discover certain files through word or category
searches and then be able to see such things within AW itself.
The database backend of the system allows you to create your own
categories for any group of files and uses this to distribute files to
worlds and provide information to builders. Each "category" basically
becomes a path on your OP server, the more categories you create, the
more directories the system creates, the more flexibility in distribution
is obtained. Having a greater number of directories rather than just the
standard 5 (models, textures, avatars, seqs, sounds) provided in a
normal OP means that multiple worlds can access the OP, each can have
access to different directories, thus it is possible to have
different avatar.dat files for different worlds; a category of files
available to one world yet not another, and so on.
Other features, that I believe AW should have, have been built into the
system. Uploads are handled directly from within AW - FTP is no longer
used - and each builder has their own login to the system with their own
password. No longer do you have to give out the password to your web
server account to builders while having that little bit of fear deep
down inside that these people could now trash everything you have made.
The MultiPath OP actually stops this from happening, No-one can delete
your files! (explained later)
The system also comes with a Xelagot bot script and the built-in web
download of a pre-formatted database dump. This allows the use on an in-
world bot that not only has the search abilities of the web system but
also can display requested objects for viewing to anyone in the world.
Users have the ability to search on the web and also display the files
they are looking for.
The MutiPath web system is designed to be used within aw's inbuilt browser.
The pages are 275 wide, thus on any client that is running a screen res
greater than 800x600 it takes up but a small portion of the aw screen.
it is recommended to use aw's inbuilt web browser to use this system.
Done like this, you should never have to close or swap your aw screen
for any uploading, normal building or world use practices.
---------------------------------------------------------------------
2. System Requirements:
MultiPath OP has been developed only on one system (well thats all I
have!) and so currently is tested only on a Linux server running
Apache/PHP4/MySql. However similar systems should be possible, the base
requirements are:
1. A web server - Apache is preferred.
2. PHP4 support including GD (graphics) support.
3. A MySQL server.
4. The ability to think for oneself.
5. A Xelagot bot - not necessary - only required if you wish to
use it.
6. A copy of "funzip", standard issue on a linux system and
available as a download from InfoZip for Windows systems
http://www.info-zip.org/pub/infozip/Info-ZIP.html
While web/php is common amongst world OP servers, MySQL is not. Often if
your OP is hosted, the host will normally be able to provide a MySQL
database for your use. If you host your own OP, your system might be
capable of running a MySQL server. Note that Apache, PHP4 and MySQL are
all free software under the GNU or GPL licencing (as far as I remember).
Information about these products is commonly available on the web.
Please remember that the system, nor its author, is here to help you set
up Web/PHP/MySQL servers, it is expected you have done this already
yourself.
---------------------------------------------------------------------
3. Installation:
================
Prior to installation you need to have a few things. First you need to
have created a database (a blank one) within MySQL. You need to know:
a) The MySQL server address (usually "localhost")
b) The name of the database created for the system.
c) The username to access this database
d) The password to access this database
You also need to know the path on your Web server where you are going to
install the files that come with this system. It is strongly recommended
that if you have any doubts, then install the system in an entirely new
directory, copy a few models and things across, mess with it, play with
it, try and break it etc etc. Once you get used to the system, then
delete the above trial setup and create the system in the directory that
currently holds your models/textures/sounds/seqs/avatars directories.
Remeber if you do it as a trial first, you will have to clean your
database as it will be re-setup during install and will fail if
tables already exist. Most MySQL hosts provide something like the php
program "PhpMyadmin" to provide easy manipulation of MySQL databases.
This software is free also if you want to install it on your own server.
The following instructions will assume you are installing for real on
your existing OP.
Step 1: Checking what you got.
You will notice other than this readme text there are 2 directories in
the base of this system. One is entitled "Xelagot" the other "Website".
The Xelagot directory merely contains the bot script for your Xelagot
bot to run. it contains one file, the script, copy this to your bots
"script" directory. Xelagot's are created by aw citizen XelaG and are
available from: http://www.imatowns.com/xelagot/index.html
there is also a copy of Ananas' "RWGenParm.exe" included - more on this
later.
The wesite dir contains all the necessary files for your installation.
lets take a quick look at whats inside there. It is expected you will
either be uploading the contents to your OP host via ftp or merely
copying it across if you run your own OP server.
Looking at the contents of the website directory.
=================================================
the first thing you will most probably notice is that it contains the 5
standard directories as your OP does - avatars models textures sounds
seqs - you will also notice that these directories are empty except for 2
files, qmark2.jpg and qmark2.zip (users of Ananas' fetch.php wil be
familar with these files). These 2 files are used by the system, if you
do not already have them, upload them to your OP (they are in models and
textures directories). If you are installing from scratch, upload the 5
standard directories as well thus creating them on your OP.
You will also notice 2 other empty directories "wrk" and "deleted",
these directories must be created (or uploaded) to your OP as well,
their function follows.
The "wrk" directory is a temporary directory used by the OP. here it
works on any altered downloaded objects as well as storing temporary
file uploads while users are uploading things to the OP.
The "deleted" directory is exactly that. When a model, texture or ANY
file is deleted from your MultiPath system, the system merely removes it
from your OP and the database. IT DOES NOT DELETE THE FILE! It instead,
moves it across to the "deleted" directory, just in case deletion was
done by accident or done by wilful damage, thus any deleted file can
easily be re-added to the OP and the system. If files are supposed to be
deleted, then the owner (or person with ftp access) must enter the
directory and delete the files manually - just like you would on a
standard system. This is merely done as a safety feature.
*IMPORTANT*: After creating or adding to the 7 directories listed above -
models textures seqs sounds avatars wrk deleted - it is important that
you alter the permissions on these directories for the MultiPath system
to work. All directories MUST be enabled "chmod 0777", or in human
terms, they must have read/write/execute permissions for everybody. An ftp
client will show directories with the permissions as "drwxrwxrwx" if you
do not enable the directories read/write like this the system will be
unable to create categories or work on uploads etc. in other words it
will fail.
The rest of the stuff in the "website" directory.
=================================================
All the rest is the MultiPath OP System files. These are a website. The
files you see straight away are the pages displayed to users in your aw
web browser. The "images" directory contains images used by the system
and the "admin" directory contains the pages shown to users who have
logged in using a username/password you have given them in the system.
You should upload the "admin" and "images" directories including their
contents to your OP. Also upload all the files in the base website
directory. When complete, your OP should be an exact lookalike to what
you see in the "website" directory of the distribution.
There are a couple of files you have to change as well, but you can re-
upload these later after editing.
Now that you have everything on your site you need to alter the
permissions of the file called "config.php". Using chmod (like on the
directories earlier) you need to alter this to 0666 which means
read/write access for everybody. This needs to be done as the installer
script you will soon be running needs to be able to write to this file
(no need to look inside it, theres nothing there - yet!).
The one other file that always has to be manually edited and uploaded is
the file called "fetchsub.php". This file is the modified version of
fetch.php written by Ananas (http://oct31.de/aw/index.html). it supports
all the 'on the fly' rwx modifications. The RWGenParm.exe to produce
the code for use with the fetchsub.php is also included with this
distribution (thanks to Ananas yet again). More information on the
features of this can be found at Ananas' website.
The difference between fetch.php and fetchsub.php is the subdirectories
- called "categories" used by the MultiPath system. When you create
categories on your MultiPath system they must be MANUALLY added to the
fetchsub.php or else the system wont be able to find the files. If you
open the fetchsub.php it looks likes the example below.
If you kept the qmark2.zip and .jpg in the right directories and have
the "wrk" directory placed as is in the distribution, then the only
editing you need to do is as follows:
The $PLocal=''; here you must put the local path of your baseOP directory,
thus if it is in http://www.somewhere.com/world/ then $PLocal=''; will
look like this:
$PLocal='/world';
If your OP path is the root of your site eg: http://www.somewhere.com/
then the $PLocal=''; stays as is.
the next section is what you will alter most - the subdirectories. For
example, lets say you created 2 categories in the system under models -
"animals" and "plants", then you need to edit fetchsub.php and add those
paths to it. You will see in the example how they are added, as well as
example categories for the other areas (textures sounds etc). Note that
the "//" are comment lines in php, in the example the /models/animals/
will not work as its commented out. if the // are removed then it is
active.
For whatever categories you create, you must edit the fetchsub.php and
add those directories to it - else things will not be found on your OP.
(cont after example)
if you create a "ground" category for models then you need to add the
path to the fetchsub.php This would be another line like "/models/ground/" ,
----------------------------------------------------------------------
define ("UNZIP", '/usr/bin/funzip');
define ("NUMBASE", '0123456789abcdefghijklmnopqrstuvwxyz@$-_');
$PLocal=''; # MODIFY
$Jpg404='/textures/qmark2.jpg'; # MODIFY
$Zip404='/models/qmark2.zip'; # MODIFY
// This belongs to the subdirectory part (configuration area)
$aSubModels = array (
// "/models/animals/" ,
// "/models/plants/" ,
"/models/"
);
$aSubTextures = array (
// "/textures/animals/" ,
// "/textures/plants/" ,
"/textures/"
);
$aSubAvatars = array (
// "/avatars/male/" ,
// "/avatars/female/" ,
"/avatars/"
);
$aSubSeqs = array (
"/seqs/" );
$aSubSounds = array (
// "/sounds/midi/" ,
// "/sounds/wav/" ,
"/sounds/"
);
// End of subdirectory configuration area
-----------------------------------------------------------
So, you can see that if you wish to create directories (categories) only
available in some worlds you merely create a fetchsub.php with the
directories you want. For example, if I had those 2 models categories -
animals and plants - and only wanted "animals" distributed to WorldA
then WorldA's fetchsub.php would only contain the subdirectory path to
animals (models/animals/) and World B would not have that directory
listed in its fetchsub.php.
If you wish to setup multiple worlds off the same OP each with
independent directories then the way to do it is have a different
fetchsub.php for each world. Simply rename them to something more
suitable as the only place the name is seen is from within aw in the
world object path setting. So you could have fetchworlda.php and
fetchworldb.php and in the aw config for world A's OP setting you would
have www.somewhere.com/world/fetchworlda.php? and in world B's Op
setting you would have www.somewhere.com/world/fetchworldb.php?
You should be able to realise that by creating a category in "avatars"
called "worlda", you could put the avatar.dat for this world in there
and have it only available in world A's fetch script, then you could
create a category called "worldb" and have world B's avatar.dat in there
and only have it in world B's fetch script.
Voila! different av dats for both worlds running off the same OP. :-)
To start with, you have no categories configured, so there's little to
alter in fetchsub.php except the $PLocal=''; path.
NOTE: Depending on systems and where you put your OP on your web server
there may need to be alterations to the subdirectory format. You will
notice the models directory is listed as /models/ and a animals category
is listed as /models/animals/ - this may not be correct in some
situations. if your OP does not appear to be working at the end of
everything you may need to write these directories like so: models/ and
models/animals/ (without the / at the front). It will work one way or
the other. the general rule that is most common is:
If your OP is in a subdirectory of your website then you do not need the
first / (eg: models/)
If your OP is in the base directory of your website then you most
probably need the / (eg: /models/).
----------------------------------------------------------------------
Running the Installer.
======================
Now that you have everything uploaded onto your OP it is time to
configure the MultiPath System. here you will need the MySQL information
stated earlier plus other information.
In the help here I will assume the path to your OP website is:
http://www.somewhere.com/world/ and the entire installation resides in a
subdirectory called "world" on your website. Follow the steps below to
assist with running the web based installer.
1. Open your web browser
2. Browse to http://www.somewhere.com/world/installer.php
(remember to change that for your correct website address)
3. You should see the online configuration for the MultiPath
System, if you do not you got something wrong.
The first screen asks for various information, first, the
database server address (quite often "localhost" for most MySQL
systems), the name of the database and the username and password
to access it.
Next it asks your sitename - here you can put your World name or
a similar title for your world (or world's) OP.
The homepage address is your "http://www.somewhere.com/world" as
per the example used above - note do not put a / at the end.
Next is your email address, this email should be for the person
who owns the website.
The following 3 items Admin, Files, funzip dont need to be
altered on most systems. If you copied as in these instructions
your admin directory is "admin". Files per page relates to the
number of results shown when someone does a search. This is most
apparent in the Category searches where it will list all files
in the category. By default it will list 10 entries per page and
give points to click for next page etc (like search engines do).
The path to funzip should be correct for most Linux systems, if
you are using the Windows version - your guess is as good as mine..
4. Press "Next Step"
If everything worked you should see a list of results saying OK
with a "Next Step" button at the bottom. if you received errors,
then you have made a mistake somewhere along the way...
5. Press "Next Step" again :-)
You will now be prompted to create the admin account for the
system. This is a high level access account. it is a good idea
to use your AW nickname for your username and think up a good
password. The email address? well you should know yours :-)
Once you fill out the info press "Add User"
You should see a screen confirming the adding of the user or an
error - if the later, you are in trouble again :-)
6. Press "Next" (no "step" this time... nothing like variety ;) )
The final confirmation! Congrats, its setup. Press the link to
take you to the admin area. here the page size will alter (to
suit inside aw use), login using the username and password you
just provided.
You have completed the install. Now it is time to use your system!
First, your AW settings:
If your script location is http://www.somewhere.com/world the
entry in World options Object path has to be:
www.somewhere.dom/world/fetchsub.php?
with no leading http:// and including the trailing question mark.
After you made this change you should close your AW browser, remove the files
"world.dat" and "world.idx" from your browser cache and restart the browser
and everything should load through the script.
NOTE: You should remove the following files from your site, they are the
installer scripts and since it is installed they are no longer needed.
There are 3 files, delete all 3, they are called:
installer.php
installer_layout.php
installer_style.css
Also you can change the chmod back on "config.php" as it is written and
removing the "write" access means no-one can alter it.
-----------------------------------------------------------------------
4. Using The System.
====================
Although you have just completed installing and are most probably have
your web opened at the admin page of the site, this descriptive text
will start from the standard page of ythe website. You can use a
webrowser to get there or better yet, add the URl to the World homepage
setting in your World Options. As per the example above, this would be
in AW's settings: http://www.somewhere.com/world/ You can also type the
url in your browser, but because of its size, you may as well use it
from within AW.
You should be presented with a screen with some text and an image that
says 'put your logo here' and a lower frame that has links. The upper
frame can and should be edited by you, the file is called
"frame_top.php" it is basically mostly standard html script.
In the lower frame are 6 links and 2 spaces (where you can add links you
would like to add). The links do the following:
Main - displays the home page, the one you are currently viewing.
Latest Files - Displays a page where you can select a database section
and then the system will show the last 3 files added to each category.
Currently you will get nothing here as you haven't created any
categories as yet or added files to the system.
Files Search - Allows you to select a database section (models, textures
etc) and then type in a word for the system to do a search. This search
will search all categories for matching word entries under the section
(eg: models). it searches file names as well as descriptions, locations,
origins and uploaders to obtain results.
Cat Search: Shows a list of current categories in each section,
selecting a category will display a list of the files in that
category.
Note that all search results on the "Textures" section returns results with
the word "DISPLAY" in red, if you click on display, the system will show
you the texture in a popup window.
Help - Is an overview of how the system operates, perhaps good reading
for you and your builders who you are going to add to the system.
Login - Takes you to the login screen for the admin area - you will need
to enter your username and password for access.
The Admin Section:
==================
Once you have logged in you will be shown the admin pages - these are
all kept in the "admin" directory on your OP, again you may wish to edit
the "frame_top.php" file to alter the text and include a logo.
The admin section has 3 levels, you were given access level 3 at install
and have control over all current functions. Only level 3 access has the
Add and Delete User, Add, edit and delete Category's and the database
dump download sections. Levels 1 and 2 have only access to file
functions, level one can add and edit them, level 2 can add, edit and
delete them.
The links at the bottom do as follows:
Main - shows the screen you are currently looking at.
Home - takes you back to the normal web page (you will have to login
again to get back)
Add User - add user accounts to the system. You can click here and the
page should be self explanatory. NOTE: It is a good idea to add users
according to their AW nickname, the system keeps track of who uploaded
files and automatically adds the username of the person who logged in and
did so. Thus keeping common nicknames avoids confusion.
Del User - Shows a user list and you can select any you need to delete
(don't delete yourself!)
Search - the search on the admin site is similar to the normal search
except it returns a more compact list, this search is designed for
people who are about to upload files to the system and wish to check a
file (object texture etc) by the same name doesn't already exist on the
system. NOTE: The system refuses duplicate files - to update an object
the old one must be deleted first before the new one can be uploaded (if
using same name).
Del File - allows you to delete a file from the system. You must select
the section and enter the filename exactly WITHOUT the extension. eg: to
delete pp01.rwx you would select Models and type pp01 The system will
display a confirmation screen after selecting.
Note: As stated earlier the system does not actually delete, it merely
removes the file from the OP and the entry from the database. All
deleted files are copied into the "deleted" directory.
Del Cat - Deletes a category from the system. if there are files inside
the directory of the category the system will not be able to delete the
directory, however it will remove all knowledge of the category from its
database. This option is only really used when you are thinking up your
categories at the start (for fixing errors and 'change of mind').
Now for the stuff you want to know :)
Add Cat - basically the first thing you do after you install your
system! You need to think up categories for your files. Categories can
have the same name in different sections, thus you can have a "plants"
category in Models and also a "plants" category in Textures. Do not be
worried about the categories, just sit back and think about some. Also
you can add more later, so if you have a "misc" category for all those
other files you might discover a category for a bunch of them - you can
create and move those files later. remember to give your categories brief
descriptions (keywords) so they are more easily understood. Also this
helps if you want an "animals" and "creatures" categories for models and
don't want people sticking dragons in the "animals" and cats in the
"creatures", or something like that.
NOTE 1: After you have created a category it will create a directory of
the same name. Don't forget this path MUST be added to fetchsub.php or
the files inside the category will not be seen by the OP.
NOTE 2: Every section (models textures sounds seqs avatars) has a pre-
made default category called "nocategory". This relates to the files
that have not been added to the system as yet and may already reside in
the base models/ textures/ etc directories of your OP. A quick method of
adding to these files to the database using the "nocategory" category is
explained later.
NOTE 3: The Add Cat section also includes the Edit Cat section and the
database dump for the Xelagot script - you will see the links. you will
notice the only editing you can do to a category is to change its
description. As to the Xelagot function, you merely click on the link
and the system will get a dump of everything in the models section, re-
format it so the Xelagot can use it and then send it to you. All you
need do is to save the file (keep the name the same) into the script
directory of the Xelagot that is running the multipath.txt script and it
will see it and use it straight away.
Edit File - This section is used to edit information on files that
ALREADY exist in the database. For example if you have tree1m.rwx in a
"misc" category and then decided it was time to create a 'plats' or
'trees' category and wanted to move (edit) the tree1m into the new
category. Also you can edit descriptions and various other information
about files within the Edit File area. This area is available to all
users with a login to the system (get them to write some descriptions :)
)
Add File - The big part of the system. Selecting this will prompt you to
select a section - models textures etc, and after doing so will show a
screen which either prompts you to upload a file or to add one it found
in the base directory of that section. (Warning: if you have thousands
of objects in your models directory and this is the first time you hit
this, it could take a little while to compile the list).
Part A:
Firstly, lets look at uploading files. The user merely selects the
"browse" button and is able to browse their machine for the file to
upload. On finding the file they can then hit the send button and the
file will upload. Then, the system will acknowledge receipt of the file
and ask the user to press "continue" to add it to the database. If an
object was uploaded, on pressing continue you will notice some things
have automatically been determined. the system has interrogated the
object, discovered its textures, whether its tagged, prelit, solid on or
off and of course added the name of the person uploading the file. You
should at this point stress to your users that they must fill out the
fields marked in RED. They are: Category, File Path, Description. The
category and file path must also match ie: if you have a "misc" category
the file path will be /models/misc. These 2 items are selected by pull
downs so there is no excuse for not selecting them. With the
description, well thats text, but typing in a good description means
searching for things is so much better and easier. IF the file being
uploaded is a texture, something different happens. After hitting
"continue" one of the options is concerning if the texture has a mask or
not. If the user selects the texture includes a mask the system will
process the texture AND then request that the user also upload the mask
for the texture as well. Again with textures users have to choose a
category and its file path, this is the same for all sections (sounds
seqs avatars etc).
NOTE1: Anything left out can be added later by using Edit File
NOTE2: "Origin" means "who originally made the object (or file)", thus
if you are uploading some objects you found on a free site it would be
good to name that person in the origin field - other users can then see
where those objects came from when doing searches. Plus it gives a
little recognition to those people who create objects for use by others.
NOTE3: "Size" means the size of an object when related to a model eg:
walk 4x4, and the file size when related to other sections (sounds etc).
Currently I have no idea how to figure out the size of an object using
php, so the system cannot automatically detect object size as yet. As
far as I know only Andras' Reggen can figure out sizes of objects
(without using a 3D modeller).
Part B:
Now lets look at adding all those files that came up in the list after
you selected the section from add file (models textures whatever). These
files are all those existing in you current base directory eg: models/
You can select thsese one at a time and go through a similar procedure
as done when uploading a file (objects will be interrogated, textures
will be semi-inteligent about masks etc) but this could take you a long
time, especially if you got thousands of files. Note that any file that
is not added to the system but resides like this in your base directory
is unknown by the system, it will not appear in any searches and the
system has no way of telling it even exists.
If you have copies of these files on your local machine (or you run a
windows server) you can use Andras' reggen utility to extract
information from these files and save it ina format which you can upload
directly to the database. In this instance, all the files are added to
the "nocategory" category, they will still be visible in the add file
area, but will also appear in the edit file area where you can move them
to your categories at any time. The good point about this is that once
the files are added to "nocategory" the system is aware of them, so they
will appear in searches and the system will not allow dupes to be
uploaded. The format to use in reggen is as follows:
;descrip;;xx;;;no;no;on;models/.zip;;;1;;no;;
there is a trade off here, reggen doesn't know about tag/prelight/solid
but knows about size of objects. The system file addition is aware of
all but the size. The choice is yours :)
To upload the reggen result directly into the database requires an admin
program similar to PhpMyadmin, it can be done with a php script, but i
have not written one, and do not know of one. However if you need help,
contact me.
-----------------------------------------------------------------------
Well thats about all I can think of right know for the "install"
instructions. If you have any questions you can email me at
ricta@ricta.net My AW nickname is Who.
Acknowledgements and thanks are given to those that assisted me in
creating this php based management system and allowed the use of
sections of their own developments. Special thanks are also due to
Ananas who modified fetchsub.php for me and assisted with various other help
and advice.
I hope you enjoy this MultiPath OP System!
|
