Scripting character

Introduction

This tutorial shows solution how to make something practical using Apricot pipeline but doesn't teach details. Also note that tools are under heavy developing and some names or techniques can be outdated when you reading this. Always please refer Crystal Space , CEL , Blender2crystal and Blender manuals.

Step 1 - Crystal Space settings

So... that lazybones (you know - your artists) already made a character ! It's rigged and animated. But I bet they didn't read your guide :) so make sure that character has proper direction: face to you in the Front view, origin of the object is placed on floor - between character's legs, all necessary animations are added to NLA, all the names are clean and both object and armature are added to one group, no werid parenting (only standard armature->object), also position, rotation and scale are cleared/applied. You can create Blender material but don't apply any textures (will be created automatically). But most important is to load and map textures into UV editor using one UV channel. Aha, let's make a floor, just add simple plane with size, say 20x20 and some light. Now we can start.

> Use the file in SVN: pro/tutorials/scripting_character_01.blend

Enable Blender2Crystal: Scripts->Export->CrystalSpace, in the 3d viewport View->Space Handler Scripts->Event: blender2crystal.py, make sure that Script Links are enabled: Buttons window: Scripts: Scriptlinks: Enable Script Links.

Character is already properly detected as Crystal Space animesh, and armature as Crystal Space skeleton:

To validate properly animated character for Crystal Space let's check a couple of things. It's a good habit to have root bone for a character (1). With this you can easily change direction of the character and correct other problems. Also use for this bone at least one key (2) but also not too much (one is perfect). No key can cause sometimes problems when you rotationg it in other animation, then switching back. Too big amout of keys can make possible correcting hard. Also be careful with very closely overlapping keys, sometimes there are two keys but looks like one and character "blinks" for a moment.

Because Blender materials are not compatibile with Crystal Space - first custom thing what we need to do is material setup. In the B2CS UI choose first icon in row and bottom vertical. Default Cg shader lighting_default is good enough so we don't need to change it. Diffuse texture is necessary, you can additionally add specular and normalmap textures by pushing 'add', typing name 'tex specular' or 'tex normal' and picking choosen texture.

You can preview how it looks rended by Crystal Space. Choose last green icon in row and press CTRL+V, scene will be exported and showed after a couple of seconds. This is Crystal Space embended inside Blender window.

Step 2 - Crystal Entity Layer settings

After basic visual setup now we can put life into our character. CEL tab is under second icon in row.

> Use the file in SVN: pro/tutorials/scripting_character_02.blend

Activate this object as entity and also as player. Entity means this object 'lives' executing some logic.

Go to second vertical tab, here we can add property classes which are components to build an entity. So we have components for walking, cameras, navigating, physics, sounds, neural networks, even for cars and hovers. CEL has already a lot of pre-defined Property Classes like that, but you can make also your custom one in C++ or Python. By default B2CS creates DefaultCamera for a player, but delete it (click red 'x'). To make basic character we need 5 standard CEL Property Classes. you can add them by clicking 'add pc' and choosing proper one from menu.

• cel->camera->DelegateCamera which is general camera manager/switcher
• cel->camera->mode->TrackingCamera which is camera mode typical for analog-steering characters
• cel->move->LinearMovement which is for general component for movement in space
• cel->move->AnalogMotion which is for analog and directional control of character without rotation
• cel->input->CommandInput which is for taking input from keyboard, joystick and mouse

To see all the property classes please refer CEL API documentation - search all methods with name celPc*.

Property Classes have Properties and Actions which are in tabs below Property Class name. Properties contains some values, for example AnalogMotion's 'movespeed' which says how fact character can move. For a moment lets leave default values for everything. Actions doing something, for example AnalogMotion's 'SetAxis' activates movement in given axis.

So Property Classes are 'building blocks' of our character - now we need way to control character's logic during game. It's called Quest and you can find it in second horizontal tab and fourth vertical. CEL also contains set of standard pre-defined Quests, so choose 'add quest -> AnalogMotionControl.xml' it's Quest to standard control character using keyboard arrows, and it's good enough for a beginning. One more hidden property class will be added by B2CS called 'Quest' which contains quest name and settings.

Step 3 - Run

Open Scripts window with Crystal Space. Optionally if Crystal Space is not loaded into memory - you can do it initially (but probably should be at this step already because 3d View overlay making this too):

1. Open 'Crystal Space' tab.
2. Enable 'Celstart View'.
3. Compile game - now B2CS will be busy for a moment with compiling this game.

After compilation by default Virtual Clock is disabled (game is paused), so enable it to play game. Now we can play Crystal Space game inside Blender window. Make sure that mouse cursor is inside this window to get proper input (all standard Blender input will be disabled and redirected to Crystal Space).

Step 4 - Animation settings

Probably you noticed that animation is more or less random. It's because you need to make map of animations, name, set priorities and states also optional speed.

> Use the file in SVN: pro/tutorials/scripting_character_03.blend

Now we can create animation graph for our character.

1. In the Scripts window with Export->Crystal Space enabled - Open 'Crystal Space' tab.
2. Activate 'Graph Editor'.
3. Add 'New' graph and name it for example 'FrankyAnim'.
4. Assign this graph to Armature name 'frankie_rig'.
5. Add new node (C button) type 'animation', connect root node to this node by clicking and dragging Left Mouse Button.
6. Click on new green animation node and set properties: choosed name for this animation e.g. 'idle'.
7. Link it to choosen NLA action.
8. Save graph - Crystal Space compilant FrankyAnim.xml will be created in the defined 'scripts' directory.

Keys: C - create new node, D - Delete node, LMB - select/create connection, MMB - move node/view, RMB - clean connection

Open 3d window, select Armature and assign it to your new animation graph in the b2cs overlay:

Done. You have first simple animation. Now add also 'walk' as excersise so we have two basic animations already.

Step 5 - Quest system

Now we can take a closer look on standard quest AnalogMotionControl.xml.

1. In the Scripts window with Export->Crystal Space enabled - Open 'Tools'.
2. Activate 'Quest Editor'.
3. Open 'AnalogMotionControl' quest.

Quest is decision system, it's kind of 'router' - can take some input and decide what reaction give as output. Every Entity in CEL can send and receive message and this is most useful feature for a quest.


4. In this column you can create States. Only one state can be active at one time, so for example we can make different logic for walk, different for swim and flying.
5. In this column you can create Triggers (input). Clicking on '+' you can open/collapse window. Most important Triggers are:
• message - received message
• oninit - case when state is executed first time (switching from other state)
• onexit - case when state is executed last time (switching to other state)
• propertychange - listening given property changes, we can optionally use simple conditions to compare with given value: eq (equal), ne (not equal), le (lower or equal), ge (greater or equal), lt (lower than), gt (greater than)
6. In this column you can create Rewards (output). Clicking on '+' you can open/collapse window. Most important Rewards are:
• message - sending message
• action - executing action in Property Class
• changeproperty - changing property
• newstate - switching to other state

How it works ?
Let's trace information flow in this Quest:

1. We have only one State 'default' so always everything works here.
2. Just after initialization Trigger 'oninit' will be executed. Select this brick and see what is it in Reward section.


3. Rewards contains four Actions Bind from Property Class pcinput.standard Refer CEL API documentation. This actions binds key to our custom command name. So in the begining we binded four keyboard arrows to commands: north, south, west, east.
4. Now all of the other triggers will be processed. This Quest using Messages only. As you read in manual - Property Class pcinput.standard sends message everytime when input is activated, syntax is cel.input.(command).down - in case of pushed button, cel.input.(command).up - in case of released button. So according to our Rewards in case of receiving messeage 'cel.input.north.down' we executing in Reward Action SetAxis from Property Class pcmove.analogmotion with given parameters value=1.0 and axis=1, which moves our character. Note that SetAxis workd continuesly, so in second reward in case of released button we clearing SetAxis value to 0 and our character stops.

Excersise:
Let's add jumping.

1. In the 'oninit' Bind choosed key to choosen command name
2. Add new trigger which receives this command and fires Action Jump from Property Class pcmove.jump