(Redirected from Guide:Universe Browser Customization)
The help files
- 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.
- Here is an example default.awh file:
- help_base www.activeworlds.com/help/aw34
- topic "Welcome"
- "Welcome to Active Worlds!" welcome.html
- "How do I get started?" get_started.html
- help_with_registration "How do I register?" registration.html
- "Search the User Guide" search/
- topic "Getting Started"
- "System Requirements" system_req.html
- help_with_registration "Immigration and Registration" registration.html
- "Video Problems" video_problems.html
- "Firewalls and Proxy Servers" firewall.html
- "Automatic Upgrades" upgrade.html
- topic "Register now!"
- help_with_registration "How to register" registration.html
- "Never reveal your password!" password.html
- "Managing your Citizenship" citizen.html
- 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
- 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:
- The [elements] setion is used to enable or disable certain interface features. Values are either zero for hidden, or non-zero for elements that are to be visible.
- 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.
- help - This option controls the help tab 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.
- 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.
- The [colors] setion of the file is not very useful in most cases, since it can simply make the browser interface difficult to use, and may make text unreadable for some users if the color you choose is the same as the text color they are using. These features are only documented here for completeness.
- 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.
The aworld.ini file
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- This section defines the positions of the various interface elements and windows. If this section is omitted, the defaults will be used.
- 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.
- This section defines the keyboard keys used by the browser. If this section is omitted, the defaults will be used.
- 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.
- 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_start 496
- help 497
- help_registration 499
- about 500
- menu_start 451
- Menus can be placed in whatever order you choose, and can be nested as deeply as required.
- 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_start 457
- forward 458
- back 459
- teleport 460
- home 461
- teleport_set_home 462
- remember 463
- menu_start 464
- look_up 465
- look_down 466
- look_level 467
- first_person 468
- third_person 469
- 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_start 474
- universe_options 525
- universe_citizens 526
- universe_worlds 527
- universe_ejections 755
- 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_start 486
- login_citizen 487
- login_tourist 488
- privileges 489
- avatar_menu 501
- visibility_menu 852
- menu_start 1487
- slides_prepare 1529
- slide_show 1488
- menu_start 490
- web_back 491
- web_forward 492
- web_stop 493
- web_refresh 494
- menu_start 496
- help 497
- help_help 498
- help_registration 499
- about 500
- menu_start 451
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.
- 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.
- 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
- 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
- The following is a list of possible actions that may be used in a custom menu or toolbar.
- This action does nothing. Any unrecognized keyword is treated as "none". This will produce a spacer in either a menu or toolbar.
- Exit the browser.
- 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.
- Teleport to the previous location in the teleport history. If no location is available, this action does nothing.
- Invokes the teleport dialog
- Teleport to the home location.
- Set the current user location as the home location.
- Adds the current location to the list of possible teleport locations in the teleports tab.
- Causes the user to tilt their view upward.
- Causes the user to tile their view downward.
- Causes the user to look directly ahead.
- Sets the camera to first person view.
- Sets the camera view to third person.
- Opens the browser options dialog.
- Opens the citizen options dialog.
- Opens the world options dialog.
- Opens the world rights dialog.
- Opens the world ejections dialog.
- Opens the universe options dialog.
- Opens the universe citizens dialog.
- Opens the universe worlds dialog.
- Opens the universe ejections dialog.
- Toggles the display of the current location on the browser title bar.
- Toggles the display of the current visibility on the status bar.
- Toggles the display of the current framerate on the status bar.
- Toggles the display of the current bandwidth usage on the status bar.
Toggles the display of the downloads window.
- Toggles the display of the total download progress on the status bar.
- Toggles the display of the current altitude on the status bar.
- Toggles the display of the current property download (data sent by world server, and NOT including http downloads) on the status bar.
- Toggles the display of the tabs window.
- Toggles the display of the toolbar.
- Toggles the display of the gesture buttons.
- Toggles the display of the browser web window.
- Toggles the display of VRT, or virtual reality time, equal to GMT-2, on the status bar.
- Toggles the display of the whisper dropdown and input field. This does NOT affect the display of whispers in the chat window.
- 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.
- Opens the citizen login dialog.
- Opens the tourist login dialog.
- Opens the privleges dialog.
- Navigates the web window to the previous page in the history.
- Navigates the web window to the next page in the history.
- Stops the loading of the current web page.
- Reloads the current web page.
- Toggles the display of the web controls over the web window.
- Opens the help tab.
- Opens "help on help" in the web view.
- Opens the help with registration in the web view.
- Opens the "about" window.
- Opens the keyboard config dialog.
- Sets the camera to an over-the-shoulder 3rd person view, which looks down on the user avatar at 45o.
- Sets the camera to a floating view that attempts to stay behind the user.
- 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.
- Opens the contacts list tab.
- Opens the world list tab.
- Opens the user list tab.
- Opens the telegrams tab.
- Opens the teleports tab.
- Opens the voice chat tab.
- Opens the help tab.
- Opens the search tab.
- Opens the notepad tab.
- Toggles afk mode.
- Toggles mouse movement mode.
- 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.
- 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.
- This action is only available on the toolbar, and NOT the menu. See Toolbar Config for more info on how this command works.
- This captures the contents of the main view window and stores it as an image file in the browser directory.
- 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).