The VEF format (short for: Visual Effect File) has been discovered not too long ago by the forum member Ascension64. Although it is relatively unknown yet, the format can be a big help if used right.
Basically a VEF file enables you to group any number of visual effects (VEF/VVC), animations (BAM), and sounds (WAV) together and specify a delay for each component to be triggered. That way you can create a series of visual effects to be played back on (a single!) command, without the hassle to put lots of Wait() or SmallWait() instructions in between.
It is also possible to use VEF files in spells. By using effect opcode #215 (Play 3D Effect) you can add a VEF file into the resource field as you can already do for BAMs or VVCs. There is a minor drawback however. The effect state 1 (Play on target (attached)) doesn't appear to be supported.
Setting up a VEF file is pretty straightforward. The format consists of a global header and an array of two kinds of components ('Component1' and 'Component2') containing the definitions of the actual effects. It doesn't really matter which one of the components you want to use. Both kinds appear to be used equally by the BG2 engine. The components don't have to be ordered chronologically as well. The game engine will do that for you.
Caution: It is possible to recursively nest a VEF file in itself. This will produce an endless loop and, in some cases, may cause the game to grind to a halt.
Creating a VEF file
The easiest way to understand the format is by creating a VEF by yourself. That's why I will provide a step-by-step instruction to create a nifty visual effect that could be used for imprisonment spells or the like.
Note: You will need a version of Near Infinity that includes VEF support to follow this tutorial. You can find it here.
Starting with Near Infinity w1.3.0, you can easily create a new VEF file by selecting the menu entry File->New Resource->VEF.
Enter the name A7FLASHY.VEF (or any other name you like) into the file creation dialog and click "Save". Press F5 or select Game->Refresh Tree to register the newly created file in Near Infinity.
Depending on how you have configured NI, the resource can be found in the Override or VEF folder and should look like this:
We are now ready to add our effects into the VEF. Each effect has to be defined within a 'component' structure. To create a new component, click on the Add... button in the bottom panel and select either 'Component1' or 'Component2'. It doesn't matter which one you choose. Both types are processed equally by the game engine. Double click the resulting table entry to open our new component for further editing. The table contains five relevant fields:
As this is the first component in our VEF, we want it to be triggered immediately. That's why we leave the 'Ticks until start' field as it is. I will explain this field further down below.
Now to the interesting parts. The 'Resource type' field determines what kind of resource the VEF will be looking for, when it is about to be triggered. As you can see, I have selected 'VVC/BAM'. That will cause the game engine to look for a VVC file first and fall back to a BAM resource if no VVC has been found. The same is true if you select 'VEF/VVC/BAM'. It will signal the game engine to look for the resource in the order VEF->VVC->BAM. The 'WAV' entry will cause the game engine to look for sound files only. For the effect in our example it isn't important whether you choose 'VVC/BAM' or 'VEF/VVC/BAM'.
The 'Resource' field should present you a list of available VVC and BAM files. The files in the list reflect the resource type you have chosen in the field above, so make sure you have already selected 'VVC/BAM'. As the file SPFLSRIN is available as both VVC and BAM, the game engine will choose to trigger the VVC version when you activate the VEF.
The remaining fields won't be touched in our VEF. If you set 'Ticks until loop' to a non-zero value, the animation will be looped endlessly, starting at the first frame of the animation. The specified number of ticks defines how long each pass will take until the loop starts over again. The field 'Continuous cycles?' determines whether only the first or all cycles within a BAM resource will be processed. This field will only be taken into account by the game engine if you select 'VVC/BAM' in the 'Resource type' field.
After our first component has been defined, you can close the window to return to the parent structure.
The second component should be triggered a short while after our first. So we enter a value into the field 'Ticks until start'. In our case, a value of 30 is suitable. One tick is processed in 1/30th seconds, therefore our effect will be triggered after exactly one second. As the default frame rate of animations is 15 fps, you can divide our delay value by two, if you want to find out how many frames of the animation defined in our first component have been processed, before our second component starts up. Sometimes you have to add or remove one tick to ensure a seamless transition between the animations.
Select 'VVC/BAM' again and select SPPLANAR.VVC in the 'Resource' field. The resulting component should now look like this:
For our third component we set the field 'Ticks after start' to 70 and select the BAM resource SPIMPPT.BAM, as seen in the screenshot.
Our fourth and last component contains a sound effect. That's because the previous component makes use of a simple BAM file, which isn't associated with a sound resource. We use the same number of ticks as for the previous component and choose WAV in the 'Resource type' field. The file list of the Resource field should now display all available WAV resources of the game. Select the file EFF_P92.WAV as shown below:
The resulting VEF resource should now look like this:
Note: The order of the components within the VEF file doesn't really matter. The game engine looks only for the starting delay and orders the components appropriately.
Save the changes you've made to the VEF file and we are done.
If you want to test it without creating a VEF by yourself, you can try out this pre-built one: a7flashy.zip 189bytes 114 downloads
To trigger the VEF resource within the game, you can either use a script action, for example
...or place it into a spell or item by using effect opcode #215 (Play 3D Effect). You can not set effect state=1, however.
Note: For testing purposes, you can also open the CLUA console and enter CLUAConsole:CreateVEFVidCell("A7FLASHY") to trigger our VEF resource at the center of the screen.
If everything went well, you should see a sequence of visual effects as shown below:
To do the same sequence of effects the old way, you would have to come up with something like this:
CreateVisualEffectObject("SPFLSRIN", "Edwin") SmallWait(15) CreateVisualEffectObject("SPPLANAR", "Edwin") SmallWait(20) CreateVisualEffectObject("SPIMPPT", "Edwin") ActionOverride("Edwin", PlaySound("EFF_P92"))
As you can see, you can save a lot of code (and trouble) by using VEF files instead. This is especially true when you need to trigger the same sequence more than once or use more complex VEFs.
This tutorial has covered only a small part of what you can do with VEF files. Using the ability to nest VEF resources, you can easily produce a great number of complex sequences in short time. The same would have been accomplished by putting down dozens or even hundreds of lines of repetitive script code that would become unmanageable very soon.
Edited by argent77, 24 June 2013 - 09:47 AM.