Beginner's Guide to AlcScript

AlcScript?

AlcScript is a way to set more complex properties on objects than you can with simple blender logic proprties.

Basically, AlcScript is just a text file that is read and parsed by the plugin. It is located inside blender - blender has its built-in text editor.

Adding your first AlcScript file

To add a default AlcScript file to your blender file, use "Scripts->Add->PyPRP->Add Default AlcScript" in a script window.

Make one window into a text window. Now on the text-windows-menu bar click the leftmost button with the double arrows on it, and select the file named "AlcScript".

Now you can start adding code to it.

AlcScript structure

Basics

Alcscript has a hierarchical formatting structure that allows us to group settings together, and nest group of settings in other groups of settings. Check the example below: 

Ladder1_Top:
    type: region
    region:
        type: ladder
        ladder:
            direction: down
            style: twofeet
            loops: 7

Ladder1_Bot:
    type: region
    region:
        type: ladder
        ladder:
            direction: up
            style: twofeet
            loops: 7

Now you may notice a couple of things from this example:

  • There is a structure of keys and values much like this: <key>: <value>
  • A value can also be a group of other keys and values - we call this a "dictionary"
  • You indicate a nested dictionary level by indenting it - this can be done with tab-key in your blender file.
  • There can be nested dictionaries in dictionaries
  • The first key is always the name of the object, and object-specific settings are located below that.

In the example above, the two objects (ladder regions) - have two keys, "type" and "region". Now "type" is a simple setting - it corresponds to the "type" logic property (which was the "alctype" property) and just has a simple string as input. (You can either use the 'logic' property "type", or the 'AlcScript' property "type" at your leisure). The key "region" however, contains another set of keys and values inside of it. Those are at another indentation level to indicate that those values belong to the dictionary under the "region" key

That is why in the AlcScript reference, we refer to these settings as "region.type" or "region.ladder.style". the dot in the middle indicates a level of nesting.

You can see that there is a key "ladder" under the "region" key that also has another set of values. This can go on indefinitely, and is used to specify dictionaries within dictionaries, to make location of settings very specific.

Comments

AlcScript comments are indicated by a hash sign (#). Anything after a hash sign will not be parsed in PyPRP

Lists

In AlcScript you can also have lists of parameters - and lists of dictionaries

Below is an example of AlcScript using lists: 

LadderCamera:
    camera:
        brain:
            type: simple
            poa: 0,0,6
            flags:
              - followlocalavatar  # <- First list item in camera.brain.flags
            circleflags:
              - farthest           # <- First list item in camera.brain.circleflags
              - circlelocalavatar  # <- Second list item in camera.brain.circleflags

In this case, you can see that under camera.brain.circleflags there is a list of flag names. Here, there are two flags specified, "farthest" and "circlelocalavatar" Under camera.brain.flags you see a list of one flag ("followlocalavatar") that is also perfectly legal - it is just a list with one entry.

These lists are lists of values (strings in this case), because you have not specified a key.

When you start to enter key: value pairs, they get to be assembled into a dictionary, which is placed under the object

Take the following (fictional) example: 

Cam1Rgn:
    region:
        type: camera
        messages:
         - type: normal         # <--- Both in the dictionary that is list item 1 in  region.mesages
           target: Camera1      # <--/

         - type: deactivate     # <--- Both in the dictionary that is list item 2 in  region.mesages
           target: Cam2         # <--/

         - type: activate       # <--- Both in the dictionary that is list item 3 in  region.mesages
           target: DefaultCam  # <--/

Now under this (fictional) key region.messages there is a list containing three dictionaries. These dictionaries each represent one message.

The first dictionary has key "type" with value "normal" and key "target" with value "Camera1". The second and third dictionaries have the same keys, but with different values.

In AlcScript this principle is used to enable you to specify a number of messages, or actions, each with different values.

Recommended Style

It is recommended to make an indentation 4 spaces (or one tab in blender) in width.

Example with dots substituted for spaces, and commas indicating start of an indentation level. 

<object name>:
,...region:
,...,...type: logic

It is also recommended to cut the last indentation before a list item indicator (dash-sign) to 2 spaces

example: 

<object name>:
,...region:
,...,...type: footstep
,...,...surfaces:
,...,...,.- dirt   # <- List item 1
,...,...,.- metal  # <- List item 2
,...,...,.- stone  # <- List item 3

This way, when you have a dictionary as a list item, you can easily see where a new item starts, and the old one ends, as well as using tabs for following items. With lists that have items that are dictionaries, it is also recommended to leave a empty line between items

example: 

<object name>:
,...logic:
,...,...actions:
,...,...,.- tag: DoorBtn      # <--- Both in the dictionary that is the first list item 
,...,...,...type: oneshot     # <---/

,...,...,.- tag: SoundEffect  # <--- Both in the dictionary that is the second list item
,...,...,...type: responder   # <---/

Object references (advanced topic)

Once you get to the more advanced uses of AlcScript, you will encounter object references. These are ways to reference internal objects in blender.

There are three basic reference types:

Tagged reference

These refer to an uru object that is described in the same blender object's AlcScript (a.k.a scene object's Logic Script). A tag can be added to part of a script, in order to distinguish it from another part. Tags use the objects name as a base, but add an underscore, to it, followed by the tag itself. A special kind of tag is the / symbol, which does not have a dollar sign in front of it. This tag will reference an uru object with exactly the same name as the name of the blender object.

One current exception on this, is when referencing detectors and conditions in a logic.modifier script. There, the name (or objectname+tag) of the logic modifier is used as a base, instead of the blender objects name

Named reference

These refer to a named object that can be described anywhere. The only limitation is that the object is within the same prp page. Also, the type of the object depends on the setting in which it is used.

Full reference (really advanced topic)

These references are the most advanced, and can link to any prp object in your files. The full syntax is 

<object type>:<name>[@<pagename>]

But the following syntaxes are supported as well: 

<object type>:$tag
<object type>:/

These obviously refer to a relative object (name relative to current blender object, or the same as it) of any given type

I will continue with only covering the full syntax. <name> is the objects name <object type> is a hexadecimal number corresponding to the object's type. E.g. 0x0001 for a scene object, 0x002D for a logic modifier, etc. Example: 

0x0001:MyName

There is also a limited supply of text names you can use instead of hexadecimal numbers - a full list is below. It is also valid to use those names, like in this example: 

scnobj:MyName

[@<pagename>] is optional and added to allow you to refer to objects in different pages if neccesary. References to textures for example, should use "@Textures" as a page reference, unless your textures are stored in the local prp file. Example: 

0x0004:islandbase.png@Textures
mipmap:islandbase.png@Textures
List of named object types

The following is a list of names you can use for objects of different types: 

object name     equivalent number 

scnobj        : 0x0001
audioiface    : 0x0011
logicmod      : 0x002D 
pyfilemod     : 0x00A2 
sitmod        : 0x00AE 
animeventmod  : 0x00C4 
npcspawnmod   : 0x00F5 
respondermod  : 0x007C 
dyntextmap    : 0x00AD 
guidialogmod  : 0x0098 
exregionmod   : 0x00A4 
agmastermod   : 0x006D 
msgfwder      : 0x00A8 
oneshotmod    : 0x0077 
mstagebehmod  : 0x00C1 
mipmap        : 0x0004 
waveset       : 0x00FB 
swimcircular  : 0x0134  
swimstraight  : 0x0136 
clustergroup  : 0x012B 
layeranim     : 0x0043 
softvolume    : 0x0088
svunion       : 0x008A
svintersect   : 0x008B
svinvert      : 0x008C
sittingmod    : 0x00AE

Note that not all of these types are implemented yet.