Applying Scripts

[Damon Caskey]

Alright, I promised a library of scripts and some basic tutorials, and here they are. Via use of these functions, non-scripters can begin to learn the basics of script, and you pros out there won't have to reinvent the wheel for simple functions since I've already wrote them for you.

Note: My tutorials focus on application and examples of scripting as opposed to the script itself. If you have not already, I recommend refer to Utunnels basic script reference here along with my tutorial. His documents the available commands and what they do whereas mine will show you how to use them.

Tutorials:

Click on the links below to see a specific tutorial.

• Animation Functions - A how to for activating functions in animations. Included in this post below.
  
  
• Range Based Animations - Street Fighter style range based attacks without alternate animations or broken attack chains.
  
  
• Persistent Blocking - Holding the block position without getting stuck in an infinity loop. Now obsolete thanks to holdblock command, but the principal could prove useful elsewhere.
  
  
• True Key Captures - Learn how to use the "key#.c" scripts to perform true real time key capturing and create your own custom controlled events in response to player input.
  
  
• Global Variables And External Entity Synchronization - Learn to use values stored in global and local variables to create "impossible" moves and gain control of other active entities.

Script Files:

These are the actual script files for download. To use them perform the following steps:

1. Download and unzip.
2. Create a folder in data called "scripts".
3. Place the unzipped files inside.
4. To edit a script, use Visual Studio or one of the many free script editors out there. Alternatively, you can just open the script with Notepad (but make sure the script is saved with ".c" or it won't work).

• lib001.c - This script contains a collection of functions to be activated on demand during animations.
  
  
• Key1.c - This script activates in response to key events. It's perfect for performing actions in response to player commands.

Animation Functions

Animation functions can do a huge variety of actions, and will probably be the most common use of script. An animation function is essentially a scripted command that runs on a specified animation frame. It’s a lot like standard commands (such jumpframe) except you don’t need to specify the frame and you can use as many as you want. The first thing to note is there are two ways in which this can be done. The first is to insert a script directly into the entity using "@script" and "@end_script" tags. These are great for doing quick one time or character specific actions, but for scripts you will wind up using over and over, it is much easier to use the @cmd tag and that is what I am going to be covering in this post. All you need to do is prepare your module and entities to use it. This is very easy; just add the following to an entity header you want to be able to use animation functions on: “animationscript data/scripts/lib001.c”

You are now ready to use functions in your animations, pretty painless huh?  The functions themselves are contained within the script, and to activate one, we call it by name. To do this you use the “@cmd” tag followed by the function name and then its parameters immediately above the frame you want the function to run on. So say, if you had a function named “kill” that killed the character and had a parameter telling it switch to remap 7 at the same time, you would do this:

Code: [Select]

Frame data/chars/john/suicide1.gif #I’m sick of life!
Frame data/chars/john/suicide2.gif #I’m killing myself!
@cmd kill 7
Frame data/chars/john/suicide3.gif #Blarg I’m dead!

On the third frame of this animation, the “kill” function would activate, performing whatever actions it was scripted to do. You can use up to eight @cmd functions per frame in a given animation, and they will always execute on the frame immediately following the @cmd tag itself.

See, that’s not so tough! Now, let’s go over a few of the functions the included “lib001.c” file has to provide some idea of how powerful the script engine can be.

• ani001 {Animation} {Frame – 0} {Command – 0} {MP Cost - 0} {HP Cost – 0} {Minimum X Range – 0} {Maximum X Range – 0 } {Minimum Z Range – 0} {Maximum Z Range – 0 }{Minimum Y Range – 0} {Maximum Y Range – 0 }:
  
  Animation – The animation you wish to switch to. Uses a list of Constants which can be found here. This is obviously a requirement or the script will fail.
  Frame – The frame of new animation you want to switch to. If not provided, the first frame is used.
  Command – The required player command (see keyd001 in the script file to find command parameters). If not provided, no player input is required.
  MP Cost – If provided, the character must have the given MP, and the appropriate amount will be deducted.
  HP Cost – Same as HP Cost, but for HP instead. The two can be used in conjunction to create a “double cost” move.
  Min/Max X/Y/Z Range – If provided, the nearest hostile character must be within the given Minimum and Maximum X, Y, or Z range. Negative numbers are accepted (and necessary when dealing with ranges below or behind character).
  
  This is easily the most complicated function, but it is also the most powerful. With this, you can actually create your own follow-ups or scripted moves completly outside of the engine's normal limits, and as of this writing it is the only way to use the extra attack buttons. Essentially it forces the engine to switch animations if (and only if) all the provided conditions are met.
  
  As an example, Kasumi in my IAF module has 4 finishing blows for her regular attack string:
  
  -The normal knock down finisher that’s simple and easy (ATTACK).
  -A low sweep that does minimal damage but is fast and unblockable (Down + Attack).
  -A pirouette kick that is a little slower and not much more damaging then normal knockdown but has the “blast” effect (Forward + Attack).
  -A somewhat slow and low damage kick that is of little value on its own but lifts opponent high into air and enables juggle combos (UP + ATTACK).
  
  Here is the actual text from Kasumi that makes those possible:
  
  

Code: [Select]

anim attack4

#Spin kick

             delay 5
offset 50 78
bbox 15 3 40 50

#If holding Forward, then switch to Follow1.
@cmd ani001 "ANI_FOLLOW1" 0 10 0 0 0 0 0 0 0 0

#If holding Up, then switch to Follow3.
@cmd ani001 "ANI_FOLLOW3" 0 3 0 0 0 0 0 0 0 0

#If holding Down, then switch to Follow2.
@cmd ani001 "ANI_FOLLOW2" 0 4 0 0 0 0 0 0 0 0

frame data/chars/kasdoa/kas0289.gif
offset 49 78
frame data/chars/kasdoa/kas0290.gif
offset 42 78
frame data/chars/kasdoa/kas0291.gif
offset 26 80
frame data/chars/kasdoa/kas0292.gif
offset 15 81
attack  40 15 39 42 24 1
frame data/chars/kasdoa/kas0293.gif
offset 14 81
frame data/chars/kasdoa/kas0294.gif
offset 23 81
attack  0
frame data/chars/kasdoa/kas0295.gif
offset 26 81
frame data/chars/kasdoa/kas0296.gif
offset 29 81
frame data/chars/kasdoa/kas0297.gif
offset 32 81
frame data/chars/kasdoa/kas0298.gif
offset 40 81
frame data/chars/kasdoa/kas0299.gif

Notice in Kasumi’s case that no conditions other then key commands are used, so all the player has to do is enter the appropriate command. For other moves, you might want to add range requirements, MP or HP cost, etc., but that part is up to you. Also notice I am using follow-ups as my “extra” moves. This is simply a personal choice of mine because follow-ups are unlimited now. You could just as easily switch to a special, a pain animation, or even back to one of the Attack animations to create an infinite combo. It’s up to you.

          Potential issues: One thing to be careful about is forcing a switch to or from AI moves like move/jump/fall. It works, but can sometimes produce odd effects like instant teleportation to a screen corner. Also, if using this for a non PC character don’t put in a command requirement or the move won’t work. Kind of obvious I know, but worth mentioning. I am working on an update that will use random numbers so an enemy or NPC has a chance to use the alternate move without ALWAYS using the alternate move, but that is not yet included.

• jump001 {Y - 0} {X – 0} {Z – 0}:
  
  Y – Height.
  X – X distance.
  Z – Z distance.
  
  This one is simple. It duplicates jumpframe and well... that’s it. Its usefulness comes into play with longer animations in that you don’t need to guess and count frames. You just put this where you want the jump and it works. Also unlike jumpframe, you can use as many of these in an animation as you want. Very handy for moves like handsprings or whatever you might want that has more then one arc in it.
  
  Oh, and one more thing, jumpframe, like most scripts, accepts decimals. Meaning you can use “@cmd jump001 0.5 0 0” for a tiny hop not possible with jumpframe.
  
  Potential issues: None. It works flawlessly, and the only thing that might possibly snag you is that decimal numbers in parameters cannot be abbreviated (as in, “0.5” will work, but “.5” won’t).
  
  
• velo001 {Y - 0} {X – 0} {Z – 0}:
  
  Y – X speed.
  X – Y speed.
  Z – Z speed.
  
  This function works like “move”, only about 10 times better. Instead of moving a certain number of pixels per frame, it enables the same silky smooth movement used by the engine when walking, jumping, falling, etc. Sick of combining “move 1” with huge animations that really only have about 3 different frames in them just to create a smooth looking movement? This is what you need.
  
  Run the function a second time with all “0” to stop the movement. Decimals are accepted, and like any “@cmd” you can use this an unlimited number of times in a given animation.
  
  Potential issues: The script works by using AI movement, and that means you can’t use this within any animation that already has AI controlled movement (jump, move, fall, etc.). Nothing bad happens, it simply won’t work (well, it does, but the AI just overrides the script on the next update, and since that can be near 200 times a second you get the idea).
  
  

And there you have it; three handy little functions. The principal remains the same no matter what function you are using, and I would encourage you to look inside the script and try out some of the others. The next step is to tweak them a bit for your own needs. Eventually, you will strike out on your own and try writing a simple function or two from scratch. Before you know it, you will be scripting up a storm!

DC

Attachment timed out.

[Orochi_X]

Thanks DC. Now that you've provided this , and explained how things worked , I (and hopefully others) have a better picture now.

I might even be able to create my own scripts sometime soon 

Thanks again.

EDIT: Can I use ani001 to use a sequence of inputs to change animations? Like d,b,attack instead of just attack?

[Fightn Words]

Awesome! This I can understand. Thank you for taking the time to annotate the script for all us 'lame-ones'- extremely usefull/powerful. 

[SX]

Outstanding work Damon!!!!

[Damon Caskey]

Can I use ani001 to use a sequence of inputs to change animations? Like d,b,attack instead of just attack?

As I wrote it, no. I haven't found an effciant way to capture multi command sequences yet that won't eat up loads of resources.

You could try using it to go to a jumper move that can accept the next part of command sequence and otherwise does nothing but return to idle or go back to the orginal move. It's hokey, but at least it would be effciant at runtime.

You CAN stack multiple (up to 8, as that is the limit of @cmds per frame, and more if you use jumper frames) ani001 on top of each other to check for multiple conditions though, just like I did for Kasumi's chain ender in the tutorial.

DC

[Damon Caskey]

Hey guys, if anyone is using these scripts, make sure to re-download or recopy. I had accedently used an older development copy of the script that was only suited for single player. The current version is in its place.

DC

[Damon Caskey]

Range Based Moves

Here is an example of using my "ani001" function to create KOF/Street Fighter style alternate close range attacks without needing to switching animations or breaking an attack chain.

For anyone who remembers World Heroes, the main character Hanzou's light punch was a jab at long range, and changed to a slightly stronger elbow up close. I want him to do the same thing in my IAF module, but I don't want to switch animations or use the range option in atchain, because either one would stop the rest of his attack chain from working.

Here is how to do it:

Code: [Select]

anim attack1

delay 6
offset 60 120
bbox 43 55 28 65

#If close, then switch to 3rd frame (elbow strike).
@cmd    ani001 "ANI_ATTACK1" 2 0 0 0 -10 30 0 0 0 0
frame data/chars/hanzou/hanz0050.gif
attack  53 60 47 15 6
frame data/chars/hanzou/hanz0051.gif

#Switch to end frame.
@cmd    ani001 "ANI_ATTACK1" 4 0 0 0 0 0 0 0 0 0
frame data/chars/hanzou/hanz0058.gif
attack  53 60 45 15 10
frame data/chars/hanzou/hanz0059.gif
attack  0
frame data/chars/hanzou/hanz0050.gif

Now to break it down:

1. The first ani001 looks for a range, and if our nearest enemy falls within it, it changes animations, but to the same animation we are already playing, just on a different frame. The effect is that frames 50 and 51 get skipped, which are the "jab" frames, and the animation continues at 58, which is the elbow punch.

2. If the first ani001 was outside the given range, then frames 50 and 51 play, thus we get the jab. Upon reaching frame 58, ani001 activates without any conditions at all, so we always skip over the elbow punch frames (58 & 59) to the last frame, which is in this case a recoil frame that works for both the elbow and jab.

The advantage here is that no matter which part of the animation hits, the attack chain will continue normally. On screen the effect is simply an elbow up close or a jab farther away to start the combo. We could also easily add a Z and Y range as well so Hanzou won’t be throwing elbows at someone who is close on the X axis but in the air or up/down on the screen from him. That is a personal choice though, since mechanically it makes no difference; in those cases the attack is going to miss anyway unless you are aligned by Z so I prefer to just check for X and leave the others be.

Extra Cedit: Two is by no means the limit, and who says range has to be the only factor? Eight @cmds can be used per frame, so that's eight alternate moves off the first frame alone. Get creative with jumper frames and it goes up to 16, 32, and so on.

Potential Issues: None really, if done right, this technique works without any problems. I would like to note however that as of right now, you do NOT have to use this trick if you really don't want to, but it is highly reccomended.

As of the time of this post, switching to another animation retains the properties of the original animation (this is a caveat of the script engine itself; you can't change it). That means, you could force the character to go to a special or follow-up in the middle of an attack chain, and the attack chain will still continue with the next move in the series. This is obviously a little easier to do then the trick above, and it might be a tempting alternative. Retaining properties of the original animation is not intentional however and will probably be fixed in the future. For that reason, it is a good idea to use the technique I just documented instead to insure range based chain moves remain forward compatible (kind of the same way that pshot still works, but sooner or later it won’t so you should use knife now instead of later).

More to come…

DC

[Damon Caskey]

*EDIT* This trick is not necessary now as you can get the same effect by including "holdblock 1" in the entity header. I am leaving it up though, as the principal might prove useful elsewhere.

Here is an easy one. Ever wonder how characters in my module are able to maintain a block position? Oh wait, you haven't because it's not released. 

Well, no worries, because now you will know and can perhaps show it off before I do. 

Seriously, this is a very simple trick that will allow your characters to hold a block position as long as they want. Check out another example with Hanzou to see how:

Code: [Select]

anim block

#Defence.

delay 10
offset 60 120
bbox 43 55 28 65
frame data/chars/hanzou/hanz0026.gif
#If holding Shift, then loop back to start frame of block.
@cmd ani001 "ANI_BLOCK" 0 7 0 0 0 0 0 0 0 0
frame data/chars/hanzou/hanz0025.gif

Now if I have to explain the above text, you obviously haven't paid attention to any other part of this thread. All that is happening is a simple check for the Special key during block animation. If the player is pressing it, then the animation reverts back to first frame and the cycle continues.

There is one thing to know though. The BOR engine  strangely reports a key press as "TRUE" until another one is pressed, even once you let go. What that means for this trick is that once you hold down Block long enough to trigger persistent blocking.. it will stay on (the character will remain blocking) forever until you do something else (That something being anything.. attacking, moving, jumping, etc).

Potential Issues: On its own none. Do keep in mind what I said in another post about animations retaining properties though. If you modify this trick to force the character to a different animation while blocking, the new animation will still have the "blocking" property. This could actually be handy if used right, but it is something to keep in mind.

DC

[Orochi_X]

Hmm....Isn't there a "holdblock" command anymore? 

I'm immensly gratefull for everything else so far , though.

[Damon Caskey]

Really?

LOL, what else have I missed? Last time I tried the block simply caused an infinity loop. I've been using script as a workaround as soon as script was available and guess I just didn't catch the feature being added to engine. I'll look for the command.

Thanks OX.

[Damon Caskey]

OX, I just searched documentation and the code and couldn't find the command. Do you know what it was specifically?

DC

[Orochi_X]

Lol. NP. It's been around for quite a while now....

Usually , for me atleast , when you press block it will play the anim and then go back to idle. If you put holdblock 1 in the character's header , he will keep blocking until you release the button.

EDIT: Updated post to answer DC's question

[Damon Caskey]

Thanks, I tried it and it works great.

That's one more workaround down!

DC

[Orochi_X]

So , I tried to adapt your ani001 script to allow 2 simultaneous inputs as a trigger.

Code: [Select]

else if (getentityproperty(vSelf, "direction")==1 && (playerkeys(iIndex,iNewKey, "moveleft", "attack"))){
     
          return 12; //"back + attack"
but it's not working. Care to help me out a little? Please?

I swapped the variables for the direction checking code to check for "backwards" instead of "forwards" and that seemed to work well on it's own....I'm just having trouble with adding another key....

[Damon Caskey]

You don't need two separate checks like that. Have a look at the documentation on scripting itself by UT. The getkeys functions can check for multiple keys at once.

That should get you going.

DC