The ArcticPigs 3D viewer downloads files from the internet in an asynchronous manner. This means that when you call LoadModel for example, the viewer will start a process which finds and then loads the file over the internet. However, the call to LoadModel only starts this process. It does not wait for it to complete. Instead it immediately goes to the next line of Java or VB script. As a general rule, commands that alter or read an object will fail if executed before the download has completed. Functions that only refer to the object will execute without problem. Functions in the second class include all script-object building commands such as 'AddAction', 'AddSound' and all sequence- and sound-event functions. Even functions like starting the script can safely be used as the starting will be deferred until all data is loaded. All examples in the tutorials work without having to take into account the async nature of the downloading. An example of a command that will fail most of the time is;

objArcticDocument.LoadModel("www.arcticpigs.com/models/taxi.model')
hTaxi = objArcticLayer.addModel("taxi");
var hTaxiMeter = hTaxi.Groups("meter") 

In the above example (line 2) the model file is added to the arcticLayer object to create a model instance. This is a safe operation even if the model is not downloaded yet. The third line tries to access a particular group within the model. This is only possible after the model has fully loaded and the model instance has been initialised. As 'LoadModel' does not wait for the model to finish downloading, nor does arcticLayer::addModel, the last line will generally get executed before the model is fully initialised. You will get a 'pending for data to load' error if you execute the above script.

To correctly implement the above statements you need to use the OnModelLoaded event. This event will fire as soon as the model is fully loaded and initialised. Your script will look something like this

<script language=javascript for="WebPlayer" event="OnModelLoaded(sName)"> 
  switch(sName) { 
    case "taxi":
       hTaxiMeter = WebPlayer.Models("taxi").Groups("meter")
    ...  
</script>  

This strategy works well for initialisations purely related to a single model or action.

The 'faulty' script does work quite often though. As soon as the browser has loaded the file first time round, it will be saved in a cache locally on the users PC. So each command can be fully completed as it gets called. So within your script you can't count on the model being there, but you also can't count on the model not being there. This complicates matters if you are waiting on a script to start. Whereas the OnModelReady, OnActionReady and OnSoundReady commands will fire with a non-cached download as well as with a load out of the cache, this is not the case for the OnScriptReady event. Instead of going into the exact reasons for this behaviour we would like to give you the 2 commandments for using the OnScriptReady event;

If you use the OnScriptReady event you must call the NeedReadyEvent whilst initialising the script.
You must call NeedReadyEvent after the last AddAction or AddSound command.

If you follow these rules, you will receive an OnScriptReady event no matter what. Make sure to test with cached and non-cached pages.

 

©2000 arcticpigs. All rights reserved.
This is a draft version! The functionality of parts of the software are liable to change.