Beginner's Guide to 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 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.
AlcScript comments are indicated by a hash sign (#). Anything after a hash sign will not be parsed in PyPRP
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.
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
<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
<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:
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
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
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:
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:
[@<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:
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.