Guide:Universe Browser Customization

From ActiveWiki
Jump to navigation Jump to search

Browser Customizations

The following browser configuration settings are intended to customize settings and appearance for Universes and Galaxies.


The help files

Overview

The default.awh file is an optional file you may choose to include in your browser distribution. This file will be read in to the browser at startup and is used to define the help interface used by the "Help" tab in the tab window.
If you choose to include this file, it should be placed into the root directory of the main installation directory. When users click on a topic in the help window, the resulting URL is sent to the browser web window.
An example default.awh file:
help_base http://wiki.activeworlds.com/index.php?title=

topic "Welcome to Active Worlds"
  "Welcome to Active Worlds" Browser
  "How do I Get Started?" Get_Started
  "Search the User Guide" Special%3ASearch
  "Latest Build Notes" Latest_version
endtopic

topic "Getting Started"
  topic "My Account"
    "Citizenship" Citizen
    "Never Reveal Your Password!" Password_Security
  endtopic
  "Firewalls and Proxy Servers" Firewall
  "Automatic Upgrades" Automatic_Upgrades
  topic "FAQs"
    "FAQs" http://forums.activeworlds.com/list.php?337
    "Community Help" http://forums.activeworlds.com
  endtopic
  "System Requirements" System_Requirements
endtopic

topic "Moving Around"
  "Moving with the Mouse" Moving_Around#Mouse
  "Moving with the Keyboard" Moving_Around#Keybaord
  "Touch Devices" Touch_Devices
  "Flying and Gravity" Moving_Around#Flying
  "Teleports" Teleports
endtopic
  
topic "Communicating"
  "Chat Tips" Chat
  "Communicating" Communicating
  "Contacts and more" Contacts
  "Privacy" Privacy
  "Public Speakers" Public_Speaker
endtopic

topic "Avatars"
  "What are Avatars?" Avatars
  "Gestures" Gestures
endtopic

topic "The Interface"
  "Interface Overview" Browser_interface
  "The Menu Bar" Menu_Bar
  "The Tabs Window" Tabs
  "The Tool Bar" Tool_Bar
  "System Tray" Tray_Icon
endtopic

topic "Building"
  "Before Your Start" Building_start
  "Building" Building
  "Object Properties" Object_Properties_Dialog
  "Sharing Privileges" Privileges
  "Special Commands" World_rights#Special_Commands
  "Triggers" Object_Scripting#Triggers
  "Commands" Object_Scripting#Commands
  "Lists of models" Model_Lists
endtopic

topic "Browser Settings"
  "Overview" Browser_Settings
  "General" General_Settings
  "Advanced Options" Advanced_Settings
  "Performance Tuning" Performance_Settings
  "Disk Usage" Disk_Usage_Settings
  "Downloads" Downloads_Settings
  "Privacy" Privacy_Settings
  "Chat" Chat_Settings
  "Graphic Options" Graphic_Settings
  "Web Options" Web_Settings
endtopic

topic "Other Topics"
  "AWORLD Log" Aworld_log
  "Troubleshoot Graphic Card" Video_Troubleshooting
endtopic

topic "3D Desiger Topics"
  "RWX Model Scripts" Renderware
  "COB Support" TrueSpace
  "Skinned Avatars" Skinned_avatars
  "Custom Avatars Tech" Custom_Avatar
  "DX Animations" DX_Animation
  "Converting 3D Models" AccuTrans_3D
  "Blender" Blender
endtopic

topic "Development Kit"
  "Software Development Kit" SDK
  "Bots (3rd party SDK based apps)" Bots
endtopic

topic "The Active Worlds Server"
  "World Planning" Guide%3AWorld_administration#Planning_Ahead
  topic "Installing"
    "System Requirements" World_Server#System_Requirements
    "Windows" World_Server#Windows_Installation
    "Linux" World_Server#Linux_Installation
  endtopic
  "Server Administration" World_Server_Administration_Tool
  "Running Multiple Servers" World_Server#Running_Multiple_Servers
  "Configuration" World_features
  "Using an Object Registry" Registry
endtopic

File structure

The first line of the file defines the root url for your help pages. All web pages will be appended to this url.
The "topic" keyword is used to define a section of related information that will then be listed under the given heading, and all indented relative to the parent topic. You may nest topics to create a tree hierarchy. Each line after "topic" must be an entry, another topic, or an "endtopic".
An entry consists of the entry label in quotes, followed by the relative url. The url provided will be appended to help_base, and the result will be sent to the web window when the user selects this entry.
An "endtopic" is used to close a set of indented topics.

The controls file

Overview

The controls.ini file is an optional file you may choose to include in your browser distribution. This file can be used to enable or disable a number of different interface elements.
If you choose to include this file, it should be placed into the /default directory under the main installation directory.
The default controls.ini is as follows:
[Elements]
telegrams=1
teleports=1
worlds=1
contacts=1
help=1
web_nav=1
whisper=1
voip=1
users=0
notepad=0
search=0

[Colors]
background=
dialog=
dialog_stripe=
balloon_background=
balloon_text=

[Options]
balloon_font=
balloon_font_size=

Elements

The [elements] setion is used to enable or disable certain interface options for the tabs. Values are either zero to disable, or non-zero to enable tab entries. Note, enabling a tab does not imply that the universe server is set to provide content for these tabs.
telegrams - This option controls the telegrams tab in the tab controls window. Set this to zero if you do not wish to use telegrams in your universe.
teleport - This option controls the teleports tab in the tab controls window, where users may maintain a list of teleport destinations. Set this to zero if you do not wish to use this window in your universe.
worlds - This option controls the worlds tab in the tab controls window. Note that if you disable this window, users will have no way of knowing what worlds are available or where they may go, and you will need to provide teleporters if you want them to be able to change worlds.
contacts - This option controls the contacts tab in the tab controls window, where users may maintain a list of other citizens. Set this to zero if you do not wish to use this window in your universe.
users - This option controls the users tab in the tab controls window, where users may see a listing of all users currently logged into the universe. Note that you must also enble this tab in the universe options in order for the data to be sent to your users.
search - This option controls the search tab in the tab controls window, which will display a web page (as defined in the universe options) in the tab window. In the activeworlds universe, this is used to provide an interface to users where they can search the activeworlds website for information, but that this is just a web window, and may be used for many other purposes. The rating is passed to this website.
help - This option controls the help tab, labled User Guide, in the tab controls window, where users view a list of help topics. This list of topics is read from the AWH file, which you must also include if you want users to be able to use this window. This window provides a list of topics, which will invoke a webpage when clicked. Set this to zero if you do not wish to use this window in your universe.
web_nav - This option controls the navigation controls over the web window, where users may navigate forward, backward, reload the current page, or enter a URL of their own. Set this to zero if you do not wish to allow users to navigate away from webpages provided by the universe / world / SDK.
whisper - This option controls the whisper window just beneath the main chat window. If this is disabled, users will not be able to whisper to one another.
notepad - This is a custom window only available to certain universe configurations. Most browser setups will leave this window disabled. Note, the user's account number, the session, as well as the current world of a user is passed to the website. The website must be fully controlled by the universe, only applicable for isolated environments.
voip - This option controls the voip tab in the tab controls window, which provides an interface for users to voice-chat with one another. This feature is only available in certain configurations. Please contact support if you are interested in using this feature in your universe.

Colors

The [colors] and the [options] sections allow to change color avatar name and chat balloon appearance, as well as certain feature dialog's background stripe colors.
Each entry in this section can use either the name of a color (e.g. "white") or an RGB value (such as "FF0000") to define the color.
background - This defines the color of narrow areas between the major interface elements. The default value is the button color as defined by the local windows settings.
dialog - This defines the color of alternate lines of certain dialogs in the browser, such as the World Features and Object Properties popups. The default value is the button color as defined by the local windows settings.
dialog_stripe - This defines the color of alternate lines of certain dialogs in the browser, such as the World Features and Object Properties popups. The default value is the button color as defined by the local windows settings, only slightly brighter.
balloon_background - The background color of comic style bubbles.
balloon_text - The text color for name tags and for chat message render.
The [Options] section define a custom font face name and a font size. The font size will scale with DPI scaling.
balloon_font - The font face name to use for name tags and chat text render overlays.
balloon_font_size - The font height to use for name tags and chat text render overlays.

The aworld.ini file

Overview

The aworld.ini file is a required file that you must include in your browser distribution. This file controls numerous settings in the browser, including key setups, login info, window layout, and universe connection info. The file will be stored in the root instalation directory, and must be named aworld.ini. The browser will not start without this file.
Since defining each entry by editing the ini file directly would be time-consuming, the most common way to set up this file is to run the browser and adjust the settings to the values you want yourt users to have when they first run the browser. Then the contents of the [layout] and [citizen] sections can be removed and the resulting file is included in the browser distribution. However, some settings cannot be adjusted in this way (because the browser interface does not provide a way to set these values) and thus must be set directly. Below are some of those settings.

[Universe]

The [universe] section is the most important section of the ini. This tells the browser where to find the univese server. If you do not include these entries, the browser will use the default values, which point to the main Activeworlds universe, instead of your universe.
host - This is the host machine for your universe. The default value is host.activeworlds.com. The main universe uses auth.activeworlds.com as its default value.
port - This is the port number for your universe. The default value is 5670 for servers version 3.6 and older, or 6670 for servers 4.1 and newer.

[Interface]

These features are new in version 4.1.
allow_standalone - If set to zero, the "skip" button will not appear during logon, and the user will not be able to use "standalone" mode.
remember_login - If set to zero, the user name and password must be entered each time the browser is run. This is useful for situations where one install of the browser may serve several different users, such as in a workplace or classroom setting.

[Vendor]

The [vendor] section is used to track browser distributions. For example, if more than one source is distributing copies of your browser, and you want a way to determine the origin of a particular browser, you can look in the vendor section.
code - This is a number used to identify the original source of the browser. This is sent when a new user becomes a citizen (if the immigrate dialog was used). This may be used to pay commission to various sources of your browser, or simply to track where your users acquired the software.

[Special]

kiosk - If this entry is non-zero, the browser will start in "kiosk" mode. In this mode, much of the interface is disabled, and the user may not exit the browser. This is usually used in situations where the browser is to be left running while many users will take turns at the machine. A demo machine at a tradeshow is a good example of when kiosk mode would be used.
join_distance - This defines the distance (in centimeters) between avatars when one user joins another.
max_pick_count - Introduced in Build 981, this enables selection for more than 128 objects simultaneously. The maximum supported value for this setting is 1024.
disable_screensaver - Introduced in Build 1089, this disables the system screensaver for Windows XP, and Windows Vista and 7 with proper User Account Control elevation.

[Chat]

omit_render - If set to 1, this will omit rendering of names, chat (and bubbles, if enabled), and stars. Any other value will render them. Introduced in Build 1111

[Performance]

cull_mode - Cull mode allows one to choose how the browser culls back faces. Replace the # with the appropriate number.
If set to 1, do not cull back faces.
If set to 2, Browser and RenderWare default. Culls faces with clockwise vertices.
If set to 3, Culls faces with counterclockwise vertices.


fill_mode - Fill mode allows one to choose between render states. Replace the # with the appropriate number.
If set to 1, Point Cloud, rendering vertices only.
If set to 2, Wireframe, rendering connecting lines between verticies.
If set to 3, Browser Default, the normal view. It's the same as setting it to 0 or leaving it undefined.

[Debug]

Generally, the [debug] section is omitted in new browser installations, since these settings are only meaningful for users working with the development team. These settings control the debug log, which records browser activity in order to diagnose crashes and other browser-related problems.
purge_time - This is the time (in milliseconds) between purges of the debug log. The log file can get quite large (growing sometimes by hundreds of kilobytes per second) and in order to keep the file from filling the hard drive it is sometimes desireable to simply clear the file at constant intervals.
flush - If non-zero, then the log file is cleared each time the browser is run. Otherwise, new data is appended to the file.
timing - If non-zero, then a timestamp is added to each line written to the log. This is useful when diagnosing performance issues.
all - If non-zero, then all browser activity is recorded in the log file. This provides the most detailed logging to the development team, but also produces huge log files. This is usually used when trying to diagnose a crash.
connection - If non-zero, then activity related to the browser connection is written to the log.
sequence - If non-zero, then activity related to sequences (the performing of gestures by avatars) is written to the log.
tasks - If non-zero, then activity related internal tasks is written to the log. This provides a much smaller logfile than the "all" option (see above) but still provides information to the development team about what may have caused the crash.

[Layout]

This section defines the positions of the various interface elements and windows. If this section is omitted, the defaults will be used.

[Visible]

The [Visible] section controls visibility options for the universe browser. Compatible only with build 1159 and newer. Note: The area beyond 200 meters of your current view must be cached to the local hard disk already. The browser will not request property data from the world server for areas beyond 200 meters visibility automatically.
range_limit_float - Introduced in Build 1159, this value sets the float visibility range in the [Visible] menu. The maximum supported value for this setting is 500.
range_limit_fixed - Introduced in Build 1159, this value sets the maximum available visibility range, up to 500, increasing in steps of 10 meters. The maximum supported value for this setting is 500, and the minimum supported value is 200.

[Keyboard]

This section defines the keyboard keys used by the browser. If this section is omitted, the defaults will be used.

[Show]

This section defines what interface elements are visible at startup. Note that some elements must be enabled both here and in the controls.ini in order to be visible.

The menu.cfg file

Overview

This feature is new in version 4.1.
The menu.cfg file is an optional file that may be placed in the /default directory. This file will define the structure of the main menu used by the browser. If this file is not included, the default browser menu is used.
Each line is the file is either the start of a menu (followed by a number that tells the menu what message set entry to use as a label), the end of a menu, or one of the available Browser Actions followed by the message set number to use as a label. The "none" action is used to create spacers. See also: Browser Actions.
Here is an example file that would create a menu bar with only 2 menus, the familiar File and About menus:
menu_start 451
exit 452
menu_end
menu_start 496
help 497
none
help_help
help_registration 499
none
about 500
menu_end
Menus can be placed in whatever order you choose, and can be nested as deeply as required.

Default Menu

Below is the menu.cfg text that will create the standard default browser menu. You can use this as a starting point and remove or add whatever options you like for your own universe.
menu_start 451
exit 452
menu_end
menu_start 457
forward 458
back 459
none
teleport 460
none
home 461
teleport_set_home 462
none
remember 463
menu_end
menu_start 464
look_up 465
look_down 466
look_level 467
none
first_person 468
third_person 469
menu_end
menu_start 470
options_browser 471
options_citizen 472
options_controls 1008
menu_start 473
world_features 522
world_rights 523
world_ejections 755
menu_end
menu_start 474
universe_options 525
universe_citizens 526
universe_worlds 527
universe_ejections 755
menu_end
menu_end
menu_start 475
show_position 476
show_visibility 477
show_framerate 478
show_bandwidth 479
show_downloads 480
show_progress 855
show_altitude 481
show_cache 482
show_tabs 515
show_toolbar 483
show_gestures 859
show_web 484
show_vrt 485
show_whisper 652
show_cell_grid 844
menu_end
menu_start 486
login_citizen 487
login_tourist 488
none
privileges 489
menu_end
avatar_menu 501
visibility_menu 852
menu_start 1487
slides_prepare 1529
slide_show 1488
menu_end
menu_start 490
web_back 491
web_forward 492
web_stop 493
web_refresh 494
menu_end
menu_start 496
help 497
none
help_help 498
help_registration 499
none
about 500
menu_end

The toolbar.cfg file

New in 3.5 is the ability to use a custom toolbar layout, along with customized toolbar graphics. This feature is primarily designed for use by universe administrators who can now design a custom toolbar prior to distributing the software.
The new toolbar can have many commands available in addition to those traditionally used on the toolbar. For example, a button could be added to open the World Features dialog, or to exit the application. The buttons may be used in any order and may be grouped in any manner using spacers. If the toolbar is wider than the available space, then a dropdown menu button will automatically be added to allow access to the remaining buttons.

Toolbar Images

A toolbar image is a grid of button images stored as a Windows Bitmap (BMP) or Portable Network Graphics (PNG) file type in the /default/toolbars directory. Different toolbar images can be used to change the look of the toolbar buttons. Toolbar images are interchangeable (even those of different sizes) as long as the images convey the same meaning, and are arranged in the same order.
The toolbar image itself is divided into five rows, and any number of columns. The first column is always used for the dropdown menu button graphic. Each column represents a single button, and each row represents a different version of the button as follows:
Row 1: Image of button in its normal, unpressed state.
Row 2: Image of button pressed
Row 3: Image of button in its normal, unpressed state with mouseover.
Row 4: Image of button pressed, with mouseover
Row 5: Image of disabled button.
The buttons may be any size, but they must be square. The browser determines the button size by dividing the height of the toolbar by 5. The image above is 160 pixels height, so the browser will determine the button size to be 32 x 32. The width of the image is then divided by this number to determine the number of columns. The image above is 192 pixels wide, which tells the browser that there are a total of six columns available. These columns are numbered left-to-right, starting with zero for the first (the drop-down menu button image) column.

Toolbar Configuration

The toolbar layout is stored in the toolbar.cfg file in the /toolbars directory. This file tells what commands are available on the toolbar, and what images those commands should use. Each line in the file represents one button. The line should contain the command the button performs, followed by the column number of the toolbar image to use for that button, followed (optionally) by the message number from the message set to be used as a tooltip. For a complete list of available commands see below.
Here is an example toolbar file:
back 3
forward 2
none 0
look_up 8
look_level 10
look_down 9
none 0
first_person 11
third_person 12
none 0
camera_front 51
camera_chase 50
none 0
mouse_move 61
afk 60

Toolbar Commands

Each button can be assigned one of the Browser Actions (Browser Commands). Any button which is not not associated with a valid command will act as a spacer. A spacer will only use the image from row zero (Unpressed) and will not respond to user input. See also: Browser Actions.
The command "sdk_event" is a special command which requires further elaboration. In the toolbar config, you may assign any number of buttons to this action in the following format:
sdk_event image_number message_number id_number
As with other commands, image_number and message_number specify what toolbar button image and message set entry to use for the button. For sdk_event, all fields must be specified, even message number. Additionally, an sdk_event button must be assigned a message id. This can be any number between 0 and 32767. When the user presses this button, a message is sent to the world server along with the given id, which is in turn sent to all bots with caretaker status. In this way a bot can be written than can react to toolbar buttons to perform various game-type functions such as "attack" or "show inventory". This provides another way for the user to interact with game-style worlds.
Note that this command is meaningless unless used with a world configured to handle these special commands. This feature requires the 3.5 versions of the world server and SDK.

The Browser Actions

Action List

The following is a list of possible actions that may be used in a custom menu or toolbar.
none
This action does nothing. Any unrecognized keyword is treated as "none". This will produce a spacer in either a menu or toolbar.
exit
Exit the browser.
forward
Teleport to the next location in the teleport history. If no location is available ( for example, if the user has never teleported "back" then this action does nothing.
back
Teleport to the previous location in the teleport history. If no location is available, this action does nothing.
teleport
Invokes the teleport dialog
home
Teleport to the home location.
teleport_set_home
Set the current user location as the home location.
remember
Adds the current location to the list of possible teleport locations in the teleports tab.
look_up
Causes the user to tilt their view upward.
look_down
Causes the user to tile their view downward.
look_level
Causes the user to look directly ahead.
first_person
Sets the camera to first person view.
third_person
Sets the camera view to third person.
options_browser
Opens the browser options dialog.
options_citizen
Opens the citizen options dialog.
world_features
Opens the world options dialog.
world_rights
Opens the world rights dialog.
world_ejections
Opens the world ejections dialog.
universe_options
Opens the universe options dialog.
universe_citizens
Opens the universe citizens dialog.
universe_worlds
Opens the universe worlds dialog.
universe_ejections
Opens the universe ejections dialog.
show_position
Toggles the display of the current location on the browser title bar.
show_visibility
Toggles the display of the current visibility on the status bar.
show_framerate
Toggles the display of the current framerate on the status bar.
show_bandwidth
Toggles the display of the current bandwidth usage on the status bar.
show_downloads

Toggles the display of the downloads window.

show_progress
Toggles the display of the total download progress on the status bar.
show_altitude
Toggles the display of the current altitude on the status bar.
show_cache
Toggles the display of the current property download (data sent by world server, and NOT including http downloads) on the status bar.
show_tabs
Toggles the display of the tabs window.
show_toolbar
Toggles the display of the toolbar.
show_gestures
Toggles the display of the gesture buttons.
show_web
Toggles the display of the browser web window.
show_vrt
Toggles the display of VRT, or virtual reality time, equal to GMT-2, on the status bar.
show_whisper
Toggles the display of the whisper dropdown and input field. This does NOT affect the display of whispers in the chat window.
show_cell_grid
Toggles the display of the cell grid. This is a wireframe overlay in the main view window that shows a 10m grid, defining the terrain shape and cell boundaries.
login_citizen
Opens the citizen login dialog.
login_tourist
Opens the tourist login dialog.
privileges
Opens the privleges dialog.
web_back
Navigates the web window to the previous page in the history.
web_forward
Navigates the web window to the next page in the history.
web_stop
Stops the loading of the current web page.
web_refresh
Reloads the current web page.
web_controls
Toggles the display of the web controls over the web window.
help
Opens the help tab.
help_help
Opens "help on help" in the web view.
help_registration
Opens the help with registration in the web view.
about
Opens the "about" window.
options_controls
Opens the keyboard config dialog.
camera_locked
Sets the camera to an over-the-shoulder 3rd person view, which looks down on the user avatar at 45o.
camera_chase
Sets the camera to a floating view that attempts to stay behind the user.
camera_front
Sets the camera to a floating view that attmpts to stay in front of the user, aimed at their head. This may not work if the avatar has an unusual shape (non-humanoid) or bounding box. For example, if the user has a very tall hat, the view may aim too high.
contacts_tab
Opens the contacts list tab.
worlds_tab
Opens the world list tab.
users_tab
Opens the user list tab.
telegrams_tab
Opens the telegrams tab.
teleports_tab
Opens the teleports tab.
voip_tab
Opens the voice chat tab.
help_tab
Opens the help tab.
search_tab
Opens the search tab.
notepad_tab
Opens the notepad tab.
afk
Toggles afk mode.
mouse_move
Toggles mouse movement mode.
vote_yes
Sends an SDK event to the world server to "vote yes". It is up to a bot to notice this event and take whatever action is required.
vote_no
Sends an SDK event to the world server to "vote no". It is up to a bot to notice this event and take whatever action is required.
sdk_event
This action is only available on the toolbar, and NOT the menu. See Toolbar Config for more info on how this command works.
screen_shot
This captures the contents of the main view window and stores it as an image file in the browser directory.
activate
Much like the Activate command used when building in worlds, this allows you to
tag custom web content to a button on the toolbar. An example in the CFG file
would be - activate 13 1117 URL http://www.yoururl.com. Also instead of the
http: you can also use local: as a substitute in order to use content stored
on the local hard drive or media. When using local: 8 character naming rules
apply for directories and filenames (not long names).
Retrieved from "https://wiki.activeworlds.com/index.php?title=Guide:Universe_Browser_Customization&oldid=32934"