Revision as of 16:30, 13 January 2008

AlcScript Technical Information

AlcScript

AlScript is a hierarchical, human readable script, basically just a YAML implementation.

It is stored in the Blender text file "AlcScript" - but this may change to "ObjScript", to perhaps reflect different files, one for blender objects ("ObjScript"), and one for generic age settings and to replace the Book/Page objects ("BookScript").

YAML is based on different indentation levels.

Object Script

Basically, the first indentation level should contain object names, and each further indentation level, a different class of settings. All key names should be lowercase!

Example:

- island:
    visual:
        sprite: true
    physical:
        friction: 5.0
        elasticity: 3.0
    logic:
        type: clickable
        python:
            file: filename.py
            arguments:
                - type: int
                  value: 0.0
                - type: str
                  value: Access
                
- camera1:
    brain:
        type: avatar
        poa: 0,0,0
        offset: 0,0,6

As you see, each key/subkey can either contain a further indentation level, or a value. The "-" character indicates a new list item.

The alcscript object

In alc_AlcScript.py there is defined the AlcScript class. The object loads in an alcscript YAML text, and converts it into a list or dictionary that contains dictionaries or lists containing the subkeys or sublists. This list or array is stored in the object.

The object also defines the .Find(key) and .FindOrCreate(key) functions, which locate a root object in either the list or array, to obtain a dictionary that corresponds to the object's name (the 'key').

.Find(key) 

returns an empty dict if the keyt is not found. (Used on exports)

.FindOrCreate(key) 

creates a new entry in the object dictionary, and returns that object. (used on imports).

Static properties

The AlcScript object has static functions that read in the files, and are called on start of export.

It also contains the static variable "objects", which is an AlcScript object, that has the list of object-related AlcScript items.

So, to get the alcscript related to an object, one should do:

objscript = AlcScript.objects.Find(obj.name)

It returns a dictionary object that contains the parsed alcscript data

Reading in object properties

After obtaining the dictionary, getting a sub-sub-subkey out of it could require a lot of code, and if statements.

To avoid that, the alc_AlcScript.py file also defines the function:

FindInDict(dict,key,default=None)

It locates the subkey in your dictionary (use "." to separate it), and returns the default value that you specify (or None if it is not found

So, in order to get the value of [object].camera.brain.type, one should do:

objscript = AlcScript.objects.Find(obj.name)
camtype = FindInDict(objscript,"camera.brain.type","fixed"

In this case, it returns "fixed" if the key was not in alcscript, but else, it returns whatever value was specified...

Current AlcScript properties

This list describes current alcscript properties - if you add it, be sure to add it under the correct code. Use heading levels to reflect the alcscript indentation level. Follow the example given to describe the functionality of the field.

type

type type:string

Can be used to set the alctype of an object.

visual

physical

friction

physical.friction type: float

Sets friction of object. If not set, or if set to a value lower than 0.0, friction will be disabled. (This means full friction)

elasticity

physical.elasticity type: float

Sets elasticity of object. Only useful on kickables.

campassthrough

physical.campassthrough type: boolean string ('true' or 'false')

If set to 'true', the camera will pass through the object. If omitted or not set to 'true' the object will block the camera.

camera

brain

Contains camera brain settings:

type

camera.brain.type type:string range:[fixed, circle, firstperson, avatar] default: fixed

Sets the type of camera brain to use. Further camera.brain keys depend on brain type used.

sound

flags

sound.flags type:string range:[loop, 3d, start] default:null

This controls the sound properties. These can be combined! loop: causes the sound file to loop indefinitely 3d: causes the sound to occur from a 3D emission point start: causes the sound to start immediately upon linking in

To combine the properties, separate them with the pipe character (|).

type = loop|start (Will cause the sound to start automatically and loop)

file

sound.file type:string

This is the name of the Blender Sound block that will be exported as a sound file. Do not include the .wav extension.

type

sound.type type:string range:[SoundFX, Ambience, BackgroundMusic, GUISound, NPCVoices] default:Ambience

This controls which type of sound it is. Remember that the volume can be adjusted for each type, so be sure to set the type correctly.

volume

sound.volume type:float

A value between 0.0 and 1.0 that determines the maximum volume of the sound.

softvolume

sound.softvolume type:string

The name of a soft volume object in the Age to which the sound will be confined. You can combine soft volumes using the same method as for lights (U for union, I for intersection, ! for inverse). This will make your sound not work. Do not use it at this point.

channel

sound.channel type:string range:[left, right] default:null

The channel to which the sound is bound. If no channel is specified, then the sound will be heard through both channels.

softvolume

Not currently implemented

type

softvolume.type type:string range:[bounds, convex] default:convex

The type of soft volume region. Bounds will use the bounding box of the object, while convex will take the individual faces and generate a soft volume object.