include <file>Allows the inclusion of definition library files. I expect this will be the main way this language will grow. Many capabilities that start out as definitions inside include files will eventually be programmed as new modules and dropped from the include files. Note that the include files are ordinary world files, but with lots of defines in them. Many include files will also have an implemention of the included geometry at the end so that the include files may be run to see a demo of the includes defined within, though this is not required. This will not interfere with a file that uses it as a library file because only defines are read by the include command.
define <label> <object>|<attribute>|<parameter>|<formula>|<constant>These are what, in large part, make up the include files. However they are not limited to include files and may appear anywhere in any files. Unlike in VRML, definitions do not appear in the scene until they are subsequently used. They are a little like VRML's PROTO. An include file can demonstrate the definitions when run separately, but when included from another file it acts as a library of denitions without showing the demonstration.
Defines are global in extent, but definitions that are inside other definitions aren't available for use in the main file until the enclosing definition is used in the scene.
name <label> <object>|<attribute>|<parameter>This lets the user name any part of the file as it is being used (like the VRML's DEF) and use it or refer to it elsewhere in the file. Names are local.
Because name really marks a spot in the current file it can only be used with objects, attributes, and parameters. It doesn't really make sense to use it with formulas or constants.
Things can also be named or queried for their names under program control.
Examples:
//assign a name to an object using scripting
CollectedObjects[2].name="FrontDoor"
//return the name of the 15th object in the Plants group
WhichOne=Plants[14].name
[<result>=]hide <name>|select <flag>Commonly used to switch things in and out of the scene graph. It will mostly be used with objects and is like unload, except that the object remains in memory, ready to be instantly used again.
The special name select hides whatever objects in the scene are currently selected. (See the select command below.)
The flag can be given explicitly with the command as a boolean value (nonzero/zero, true/false, yes/no) to hide or show the object(s).
The flag can also be read to see if something is currently hidden or displayed. In that case hide acts like an attribute of the object being queried.
The command will <return> an error condition (-1) if hide was unsuccessful. The error condition has two parts: the errorcode, and the name of the object it choked on. If more than one object was (un)hidden then the result indicates how many were processed. If the hide command is running on a large number of objects then this will count through them dynamically as it works.
While hidden the object is not visible, doesn't respond to scripts, or collision. It acts exactly as if it was not loaded. Any selected objects become deselected on hiding.
Simple wildcards can be used with hide.
Examples:
//See if Thing is hidden or not. Don't hide or unhide it.
InWorld=Thing.hide
//Hide Car01, Car02, Car03,...
Gone=hide Car??
[<result>=]load [<path>[<file>[<name>]]|select] [<flag>]Loads one or more files or directories of files and returns a result when each file has loaded. If no parameters are given or just flag then load refers to the current file, which is useful if scripting starts executing before all the file is loaded but depends upon some part to be loaded and in memory. (See the init command below for a more convenient version to use in that case.)
Regex wildcards can be used with load.
If the name is a named object inside the target file then only that object will be loaded instead of the whole file. This is another way to encourage development of libraries. Note that named objects inside files are treated as if they were files in their own right, using the
The special name select queries the load-state of whatever objects in the scene are currently selected (selection can be made via mouse, keyboard, program, etc see select below).
The flag can be read to see if something is currently loaded. In that case load acts like an implied attribute of the object being queried. If the named object or world is loading but not yet finished then it returns 0. If it is nowhere in the tables of named objects or worlds loaded then it returns -1 error.
If an object produced an error when trying to load then <result> returns -2. In that case the result has two parts: the errorcode (-2), and the name of what it choked on. When load completes it returns a positive number indicating the number of worlds processed, along with the name of the last world loaded.
While loading multiple files, the <return> value has two parts: a number which increments for each file processed and the name of the file currently loading. (This can be used for making a "loading..." gauge.) These values are stored in a 2d array which can be accessed by reading the load command without any parameters. The zeroth element of the array is special. It contains two elements: the number of files or objects unsuccessfully loaded (if that is zero then there were no errors) and name of the first file or object which failed.
A flag can be given explicitly with the command as a boolean value (nonzero/zero, true/false, yes/no) which decides whether to load the object(s).
Examples:
//Check if Pilot's avatar is currently loaded or not. Don't do any actual loading.
PilotAv_here=PilotAvatar.load
//load the Chair object from inside the household file.
gotChair=load homeObjects/household.vrl/Chair
[<result>=]unload <name>|select <flag>Lets you unload named parts of a scene and returns a flag when the unload is complete and the memory it occupied is freed up.
The special keyword select unloads currently selected objects in the scene. Any selected objects become deselected on unloading of course.
Regex wildcards can be used with unload.
The flag can be given explicitly with the command as a boolean value (nonzero/zero, true/false, yes/no) which decides whether to unload the object(s).
The command returns an error condition if unload was unsuccessful, otherwise zero. The error condition has two parts: the errorcode, and the object it choked on.
Like load, if unload is used with multiple files then the returned value has two parts: a number which increments with each successful load and the name of the currently unloading object. These values are automatically stored in a 2d array which can be accessed by querying unload without any parameters.
Example:
*** security danger - reads & writes data ***
[<result>=]io <flag> from <file>|<device>|<object> to <file>|<device>|<object> char|line|stream //defaults to char <protocol>Previously listed among the attributes, I have moved this to the commands. I am still not sure of its status though, so don't be surprised if it moves again.
The io command can only read and write from and to specified areas on the machines. Each person running this program has to set in their preferences whether read is allowed, whether write is allowed, and what directories are shared. If read and/or write is allowed then it is absolutely not allowed outside the shared directories. The preferences file that set those limits is kept outside the shared directories so that it is unreachable from inside the virtual worlds.
The flag can be given explicitly with the command as a boolean value (nonzero/zero, true/false, yes/no) which decides run the command or not.
Regex wildcards can be used with io.
Reading and writing files in Unix and Linux is easy because it is treated the same as file access. Device access under MSWindows is a bit more difficult.
If char or line or stream keyword is not given then it defaults to char, which means data is sent as bytes. (I'm not sure stream is really needed.)
The protocol can be http, udp, rtp, etc. (I need to learn more about this aspect.)
The command returns an error condition if io was unsuccessful, otherwise zero. The error condition has two parts: the errorcode, and the object it choked on.
[<result>=]save <name>|select <file> <flag>Lets you save named objects or the currently selected objects as a file. If no object is named or currently selected then the whole world is saved. This can also be done with the io command above, but save is simpler and more specialised.
The flag can be given explicitly with the command as a boolean value (nonzero/zero, true/false, yes/no) which decides whether to save the object(s).
The flag can be read to see if an object has been saved during this session. In that case save acts like an attribute of the object being queried.
Regex wildcards can be used with save.
The command returns an error condition if save was unsuccessful, otherwise zero. The error condition has two parts: the errorcode, and the object it choked on.
Files can only be saved to the shared area. (I need to spend more time working on the security issue.)
[<result>=]select [<path>|<object> <object> <object> ...] <flag>Lets you select a list of objects for saving or manipulation by other commands.
Regex wildcards can be used with select.
This command will most often be used with an input device like a mouse to interactively operate upon objects in the scene.
It returns an error condition if select was unsuccessful, otherwise zero. The error condition has two parts: the errorcode, and the object it choked on.
[<result>=]freespace <string>This is actually two commands.
Freespace with no parameter queries the system as to how much memory it has free and returns a string with information on such things as free RAM, free disk space, number of tasks running, demand on processor, etc.
Freespace with a parameter frees up <n> Mbytes of RAM. It returns the actual amount successfully freed.
Comments must not be discarded by GUI builders unless specifically instructed to (as in de-bloating).
if <condition>
<then>
else
<else>
This lets you test for certain settings, for example modes, hide load and unload, freespace, and in the future probably versions. It also lets you test user variables.
function <name> <passed values>
It is essential to be able to write callable blocks of code. They can be sprinkled anywhere in the file for convenience, though most of it will probably live near the top of the file, for readability.
init <name>
It will ensure some part of the file is run before anything else as soon as the world is completely loaded. This is like a special form of the load command that does this:
function Init
if load
<name>
else
OnLoad
[<result>=]distance from <name>|select to <name>|select
Returns the distance between two objects. This is especially useful for forces. The from and to keywords are optional. If just one object name is given then the other is assumed to be the current object. At the top of the scenegraph the current object is implied to be a null object centered at the origin (0,0,0).
The special keyword select indicates a selected object. If there are two selected objects then the from object will be the first selected and the to object will be the second object. If more than two objects are selected then if it is not indicated which selected objects are to be considered this command will default to the first two. Selected objects can be distinguished by select[0], select[1], select[2],...
[<result>=]direction from <name> to <name>
Returns an angle or axis between two objects relative to the z=0 axis of the from object. This is especially useful for forces. The from and to keywords are optional. If just one object name is given then the other is assumed to be the current object. At the top of the scenegraph the current object is implied to be a null object centered at the origin (0,0,0).
The special keyword select indicates a selected object. If there are two selected objects then the from object will be the first selected and the to object will be the second object. If more than two objects are selected then if it is not indicated which selected objects are to be considered this command will default to the first two. Selected objects can be distinguished by select[0], select[1], select[2],...
LOD [<n1> <name1>, <n21>:<n22> <name2>, <n3> <name3>...]
Should LOD be an object? It would sit in the scene tree like an object, but it acts like a specialised if-then-else, or case
LOD works quite a bit differently than in VRML. The LOD command lists a number of named objects in order of priority. The priority numbers (n1, n2, n3,...) are not simple distances, though it would be common for world builders to use distance as a guide for setting those numbers. It actually takes into account the frames per second rendering of the viewer software and the user's preferences as regards to detail versus framerate. The world builder should bear this in mind while deciding on those numbers.
Using a list of named objects makes reading the file much easier than in VRML. Because the objects are not actually rendered in VRL until they are called it is quite natural to define a slew of objects for LOD and simply refer to them via the LOD command, which activates the appropriate ones.
Note that in the usage example above, the second object has its LOD number specified as a pair of numbers separated by a colon(:). This lets the world builder set a range for the LOD, allowing LOD objects to overlap. In certain situations this can make for more realistic-looking worlds where LOD objects don't flick in and out of vision, but blend nicely. The world author must bear in mind though that during the overlap two LOD objects are simultaneously visible, which places more load on the system than one alone, thus is is a capability that should be used sparingly or where it won't appreciably affect performance.
Check out the possibility and pros/cons of using a C++ scripting language for this. The big danger, of course, is in getting bogged down in the whole typed language thing -- major drag. However I can't help thinking it may be possible to do...
Two possibilities:
Pike
http://pike.roxen.com
http://www.roxen.com
PHP
http://www.linuxdoc.org/HOWTO/PHP-HOWTO.html
Maintained by Miriam English