KHAOS

A much needed upgrade to the ZHAO script for Open Simulator

Kayaker Magic, August 2020.

An AO is an "Animation Overrider" for Open Simulator. This is a script that makes your avatar move, fidget and sit in nicer ways than the default animations. Listen to Torley Linden to hear the basics of AOs, but don't follow him into the Secondlife Marketplace. ZHAO based AOs are well written for Second Life, but they are laggy. KHAOS is a small upgrade to ZHAO that makes it produce MUCH LESS LAG. It only works on OpenSim, not on Second Life, but who cares about that old closed grid anyway?

Where can you get KHAOS? (It's FREE!)

Teleport to one of these locations and grab a copy. It comes as a ready-to-wear male AO, a female AO, or just as a script you can use to upgrade your existing AO. KHAOS is a drop-in replacement for the ZHAO-II-core script and will work with your existing interface, notecards and animations. You can also grab the full perm source code as text here. I'm selling it for the minimum ammount allowed on the Kitely Market for people who don't want to HG around to find a copy.

How Do I Install KHAOS?

 There are several different ways to intall it. You can get a ready-to-wear version at one of the places above and just wear it! You can get the script-only and replace the script in your existing AO. You can grab the text only version and paste it into the script in your existing AO. Note that once you have an AO installed you can add new animations to it and configure it to be as unique as your avatar. This document will not help you do that but there are many tutorials available elsewhere for this, here is one you can watch later.

How to Install a ready-to-wear KHAOS AO

 For you female avatar you will want to go one of the places linked above,
left-click on the box named "Sweetness khAOs"
 buy the AO for $0
find "Sweetness khAOs" in inventory and double-click it
 your avatar will start behaving in new and attractive ways
Do the same thing with "Rugged khAOs" for your male avatar. These example AOs were originally put together by Shandon Loring of the Seanchai Library. He found free animations all over the Metaverse and set up the default note-card to use them. Thanks to Shandon for letting me add my script to his good work!

How to Replace the Script in Your AO with KHAOS
  • Go to one of the places listed above, left-click on the script-only KHAOS box and buy it for $0.
  • It will put a KHAOS-II-core script in your inventory.
  • Detach your AO if you are wearing it, find it in inventory, and make a copy of it.
  • Rename the copy to something new, for example change the characters "AO" or "ZHAO" to "KHAOS".
  • Then wear that new copy, edit it and look at its contents. You will see a bunch of animations, a notecard or two and two scripts.
  • You may have to scroll way down to find the scripts hidden between the animations.
  • One script will have "interface" in its name LEAVE THAT ONE ALONE.
  • The other script will be named ZHAO-II-core engine or just CORE.
  • Delete that core script, then drag the new ZHAOS-II-core script out of your Scripts folder into the inventory of your AO.
  • The script should chat to you about reading the default file, pause for a while then tell you it is done.
  • Close the build dialog, you are also done, your avatar should go back to fidgeting and sitting the way it did before.
  • But now it will be much more gentle on the servers and will help decrease lag for yourself and your friends.

    Video Tutorial


    This tutorial shows how to get, install or upgrade an old AO several different ways. It goes through all the steps in great detail of how to install a ready-to-wear AO, how to replace the script in your AO, and how to update your AO from the text copy available below.

    How to install the text version of the KHAOS-II-core script in your AO
    • Download a copy of the script from this link: KHAOS-II-core.lsl The easiest thing to do is to click on that link, copy the whole thing to your clipboard then come back here.
    • Detach your AO if you are wearing it, find it in inventory, and make a copy of it.
    • Rename to something new, for example change the characters "AO" or "ZHAO" to "KHAOS".
    • Then wear that new copy, edit it and look at its contents. You will see a bunch of animations, a notecard or two and two scripts.
    • You may have to scroll way down to find the scripts hidden between the animations.
    • One script will have "interface" in its name LEAVE THAT ONE ALONE.
    • The other one will be named ZHAO-II-core, engine or just CORE.
    • Delete that core script, create a new one, and give it a name like KHAOS-II-core.
    • Alternately, you could just rename the core script that is there because the next few steps will replace what is inside it.
    • Open the core script in your AO inventory, delete the script that is there, and paste the new version in its place. (You should still have it in your clipboard, go copy it again if not).
    • Save the script, close the script editing box and the build dialog.
    • The script should chat to you about reading the default file, pause for a while then tell you it is done.
    • You are also done, your avatar shoud go back to fidgeting and sitting the way it did before.
    • But now it will be much more gentle on the servers an will help decrease lag for yourself and your friends.

    How to set out copies of the KHAOS boxes.
    • Go to one of the places linked above.
    • Instead of left-clicking on the boxes to buy the AOs for $0, right-click on each one and take a copy.
    • Copy all three of the boxes, they are full perm and marked as "anyone may copy".
    • Teleport back to your land and to a place where people expect to get free things, like a freebie store or a welcome area.
    • Rez the three boxes on the ground. Edit them and make sure that they are still marked as "Contents for sale for $0" and "anyone may copy".
    • Now people can come to your land to get copies of these new AOs!
    • Send me (Kayaker Magic at Kitely) a link to where you put these and I'll add that link to this WEB page as time and space allows.

    Why do you want KHAOS?

     AOs are popular scripted items in Second Life and Open Simulator. The older ones are HUDs (Heads Up Displays) that you wear on your viewer. They over-ride all the default animations that make your avatar walk, stand, sit and fidget. Most people find the default walk of the avatars to be unpleasant, so that walk has been nicknamed “the duck walk”. An AO solves this and personalizes your avatar’s behavior in other ways. For example when your avatar is not walking but just standing around, the AO changes your animation from time to time to make you fidget in different natural looking ways. For a very basic introduction to AOs, listen to what Torley Linden has to say about them here.

    But there is an ugly dark secret in these AO scripts: There is no way in Second Life for a script to get notified when it is time to change animations. To solve this an AO script must “poll” the system over and over and over again to find out. It is like having your little sister in the back seat saying “Are we there yet? Are we there yet? Are we there yet?” All day long. Your little sister may be annoying but what this means in OpenSim is your server is being asked “Are we sitting yet?” all day long, hundreds of times a minute. This puts a huge load on your server, using up CPU cycles and lagging the region. Imagine there are 30 copies of your little sister in the back seat, each shouting “ARE WE SITTING YET?” 10 times a second. This is what your poor overworked server is dealing with! No wonder it starts to lag at events where all the visitors arrive wearing an AO.

    What do you care if your AO bogs down the servers? If you are someone who hosts venues on OpemSim, like music events, you desperately want all your visitors to have a pleasant experience. You desperately do not want your servers to lag. AOs are not the only source of lag but they are in the top 10 list. If you are just visiting a venue, you should also want to be a good netizen and reduce the lag you may be causing. If everyone does their part to reduce lag we will each have a better experience. Taking off your AO, wearing a low-lag AO or switching to a viewer AO will improve your experience and that of your friends everywhere you go.

    The correct solution to this problem is for everyone to learn to use the AO built into their viewer instead of wearing a scripted one. The viewer knows when animations are changed and can easily override them so it can do a much smarter job of implementing the AO. Any processing that the viewer does is unloaded from the server and spread over all the PCs running on all the viewers. Scripted AOs run a risk of failing every time you cross a border, teleport or HG jump. An AO in the viewer never has this problem. This is a great all around solution! Everyone should use the AO in their viewer! There are lots of tutorials for learning how to use this, here’s a recent one I found: https://www.youtube.com/watch?v=PPnJ7bocLY8 Unfortunately people get used to the tools they have, so many people continue to use the old fashioned wearable AOs that bog down the servers.

    In 2009 (11 years ago as I write this!) the developers of Open Simulator added an improvement that should have solved the lag problem of scripted AOs! They added a new event, CHANGED_ANIMATION, that is sent to scripts whenever the server changes the avatars animation. This only works on OpenSim and not on SL, but ask me if I care about SL. Now a new AO can be written that doesn’t need to poll! A smarter AO that does not bog down the servers! But unfortunately people continue to use 13 year old scripts from SL! I haven’t heard of one script in OpenSim that uses this “new” feature so I wrote one for the Open Sim community. If you will not learn how to use your viewer AO, then please upgrade your scripted AO. Read on for how to get a free copy of the new script.

    On a survey of a dozen or so AOs available for free around the Metaverse, all the ones I found used the same free open source ZHAO script from 2007. Even many for sale in the Kitely Market. (What you are paying for in these cases is the animations and the configuration). This script is actually very well written, it just suffers from the limitations that SL never fixed and OpenSim fixed after ZHAO was written. This script is given away free under the GNU General Public License. So I took a copy of ZHAO and modified it to work well under OpenSim. In the spirit of GNU and open source software I am giving away this new version.

    • It works just like the ZHAO-II-Core script from 2007.
    • It works with the configuration files set up for ZHAO.
    • It works with any “interface” script written to work with ZHAO-II-Core.
    If you have an AO that you like, make a copy in inventory (just to be safe), delete the core script in inventory (not the interface script!), drag this new script in, and your AO will work exactly as before. Except it will be gentle on the servers. I named my version of the script KHAOS-II-core. K for Kayaker and the S on the end because I like pronouncing it like “CHAOS!”

    I set up this WEB page with links to a bunch of places around the Metaverse where you can get free copies of KHAOS. I set out example popular male and female AOs ready-to-wear, or just the script for upgrading. Included above are instructions with pictures showing how to “upgrade” your existing AOs several different ways. I also embedded a video here showing how to do it. Use my script in animation products that you give away or sell, following the guidelines of GNU General Public License. Give away copies to your friends and set out copies to give them out free at all your events.

    Will this help? I fear not. In another 13 years I fear we will still find people showing up with a 26 year old ZHAO script bogging down our servers. (Unless of course we are all running out of quantum computers embedded in the ice on Pluto).

    I have also taken a proactive step to stamp out bad scripts. I have written a patch for the OpenSim sources that lies in wait inside the server. If it sees a script behaving like a bad AO, it disables that script and sends the owner a message about where to get a better one. The bad AOs can be re-enabled by leaving the region, turning them off and on or by detaching them and wearing them again. Restarting HUDS is often necessary anyway after crossing a region border, teleporting or HG jumping. But my patch will immediately disable bad AOs again if you restart them. So if you insist that your bad AO must keep working, you can leave my land, and don’t slam the door on your way out! Or GET A BETTER AO!

    This patch will never be accepted by the OpenSim Core Developers, so it is only available to people who have the expertise to build OpenSim from the sources. If you are someone who hosts events on OSGrid or on your own grid, you will desperately want your visitors to have a better experience. Like me you will want to STAMP OUT THOSE BAD SCRIPTS! You will want to learn how to build OpenSim yourself so you can stop these AOs from lagging your servers. The patch for this change to the OpenSim region servers is available below, so read on:

    How can you ENFORCE the use of better AOs?

     As a land owner who often has events on his land, I am horrified when people arrive at crowded events and bog down MY server because they are wearing a 13 year old laggy AO. I could put up signs, leave the free KHAOS boxes lying around, but I know that people will resist switching to something new. I want to grab those old scripts and throttle them! Well, if you host your own land in OSGrid like I do, and you build your own versions of OpenSim from the sources like I do, or if you have the ear of the admins that do build your version of OpenSim, there is a way to throttle those scripts!

    Here is how it works: I added code to llGetAnimationList() that watches how fast a script calls it. Bad AO scripts call it around 10 times a second. If I see a script call llGetAnimationList twice in less than half a second, I flag that as a bad script. I turn off its timer, send a message to the owner about where to get a better AO and disable all avatar collision events in the prim containing the script. (Physics collisions between prims are not effected). The timer value and disable flag should have been stored in the TaskInventoryItem class just for the offensive script. But I hesitated to change this low-level class that effects many other parts of OpenSim. It turns out that the class for prims, SceneObjectPart, had several unused fields so I recycled them to store my values. I used STATUS_ROTATE_X as the disable flag and STATUS_ROTATE_Y to hold the time that llGetAnimationList was last called. Note that these unused integer values are NOT the same as the enumerated values elsewhere in the code, even though they are spelled exactly the same.

    The patch looks at the OpenSim.ini configuration data where you must enable it and add the following two lines to the [Startup] section. 

         DisableAOPolling=true     ;disables scripts that call llGetAvatarList too often
     DisableAOMessage="Your AO has been disabled. See http://magic.kayaker.net/KHAOS for a better one."
    Note that DisableAOPolling is false by default so you MUST add this line to your OpenSim.ini after applying the patch. The DisableAOMessage is sent like an llOwnerSay message to the owner of the bad script. If there is no DisableAOMessage in your OpenSim.ini, then no message will be sent when an AO is disabled. This is an interesting option: Bad AOs will quietly stop working and not lag your server. If anyone notices, you can plead innocence and say "Gee, HUDs are often disabled by race condtions in teleports and HG travel, perhaps it will work again when you go home". (Both of those statements are true). The AO will work when some of its dialog buttons are pressed but immediatly get disabled again. They may not notice their AOs are disabled. When people are at events, they are usually seated or dancing (a special kind of sitting) and don't need their AOs. I have to restrain myself from putting rude messages in DisableAOMessage like "STOP HURTING MY SERVERS! GET A BETTER AO!".

    Here is a link to my patch, download a copy and apply it to the sources of OpenSim. This patch was made for the OpenSim 0.9.2 Yeti sources as of early August. It may be unable to apply the patch if too many other changes are made to the sources in the future. For example, the patch file cannot apply itself to the NaniSim branch of OpenSim. But it you read the patch file you can apply it manually to the sources and then it works fine on other branches of OpenSim.

    • WEB page by Kayaker Magic