تبیان، دستیار زندگی

Version 6.1

Tutorial & Reference

 =======================================================================
New features implemented in A6 6.20: ==================================
=======================================================================
Material, Effects, Shaders ============================================
Script-based material effects and shaders (Commercial & Pro)
Material effects help you use all the rendering capabilities of the
3D hardware. Effects are a collection of different rendering
techniques that can fit onto a variety of hardware devices. This
enables you to not only to program games that make optimum use of
video card functionality - effects also make it easy to upgrade an
existing game to run on newer video cards as additional features are
developed.
For example, to create a realistic rippled pond of water that
reflects light, you begin with the first technique that renders the
water, adds specular highlights, adds caustic textures, and applies
light to the water in a single pass. If your hardware cannot render
this technique in a single pass, a second technique might render the
water, add specular highlights or caustic textures, but not apply
light to the water.
You must be familiar with the texture stage concept of DirectX for
defining effects. Therefore, writing effects is only a matter for
advanced users, although it"s fun to try out the different render
states and texture operators, and look which effects they produce on
the screen. However, once an effect is properly written it can be
used by anyone.
Effects are defined in an effect string in the material object, that
contains a syntax similar to C-Script.
Example:
// the following code creates a material that adds DOT3 bumpmapping
// to a model
bmap reptile = ;
material mat_bump
{
skin2 = reptile; // set a reptile skin
scale1 = 0.2; // factor for the skin scale at stage 0
// define a material effect string
effect = "
// declare the used textures and variables
texture entSkin1; // the entity skin
texture mtlSkin2; // the bump map
dword mtlSkill1; // the light vector
// default technique
technique bump_dot3
{
pass P0
{
// set texture stage states
Texture[0] = ;
Texture[1] = ;
TextureFactor = ;
ColorArg1[0] = Texture; // stage 0 = bumpmap
ColorOp[0] = DotProduct3;
ColorArg2[0] = TFactor;
ColorArg1[1] = Texture; // stage 1 - skin texture
ColorOp[1] = AddSigned;
ColorArg2[1] = Current;
ColorArg1[2] = Diffuse; // stage 2 - lighting
ColorOp[2] = Modulate2x;
ColorArg2[2] = Current;
}
}
// fallback technique for devices that do not support bumpmapping
technique fallback
{
pass P0
{
// set texture stage states
Texture[0] = ;
ColorArg1[0] = Texture; // stage 0 = skin texture
ColorOp[0] = Modulate2x;
ColorArg2[0] = Diffuse; // modulate by lighting
}
}
"; // end of the effect string
}
starter mat_bump_init {
// initialize the material properties
vec_set(mat_bump.ambient_blue,mat_model.ambient_blue);
vec_set(mat_bump.diffuse_blue,mat_model.diffuse_blue);
vec_set(mat_bump.specular_blue,mat_model.specular_blue);
mat_bump.power = mat_model.power;
// create the normals map for DOT3 bumpmapping
bmap_to_normals(mat_bump.skin2,2);
// set a lighting vector for DOT3 bumpmapping
mat_bump.skill1 = pixel_for_vec(vector(200,200,200),100,8888);
}
An effect is a text string (given in "") that consists of one or more
techniques. Each technique consists of one or more passes. Each pass
consists of a setting of one or more texture stage registers of the
3D hardware, and optionally a pixel or vertex shader that redefines
the behavior of the stage. The model is rendered once for each pass,
using the given settings.
If a certain technique does not work because the 3D hardware does not
support the given texture stage states (like
CameraSpaceReflectionVector in the above example, which is not
supported by old hardware like TNT2), the next technique from the
effect is automatically selected. Therefore, an effect should always
contain a simple fallback technique for supporting old hardware.
The effect string is compatible to the DirectX .fx format. The
keywords used in the texture stage settings are basically the same
used in the Microsoft DirectX 8.1 reference for texture and render
states. Therefore, an effect can be written based on the microsoft
documentation.
A reference list can be found in the DirectX8 documentation under
DirectX Graphics -> Reference -> Effect Files Reference.
Remarks:
- Effects can be copied from another material in an initialisation
function, like 
mtl.effect = mtl_envcube.effect; 
and can be reloaded at runtime through the effect_load instruction.
-Effect materials can only be assigned to models, sprites and terrain
at the moment.
-Effects are compiled at runtime into DirectX register states. Syntax
errors will be indicated.
-Effects can use 4 skins from the model, plus 4 additional textures
defined in the material object. So every effect can use up to 8
textures.
-The rendering speed of an entity is reduced when an effect or a
Pixel or vertex shader is used. So be careful with effects.
Pixel and vertex shaders (Commercial & Pro)
Programmable shaders add a new dimension to graphics rendering by
allowing the transform, lighting, and rendering functionality to be
modified at runtime on a vertex and pixel basis. A shader is a small
program that runs for every vertex, or every pixel that is rendered
on the screen. It can control the vertex position, color and normal,
the texture coordinates, as well as the pixel color and brightness,
dependent on the influence of light, textures or arbitrary C-Script
variables. This gives the user a new level of dynamic flexibility
over the way that pixels are rendered.
A shader description contains register declarations and shader
instructions. Pixel and vertex Shaders can be defined as part of the
material effect script, by using the VertexShader and PixelShader
keywords.
Example:
material shadertest {
...
effect "
{
...
matrix matWorldViewProj;
matrix matWorld;
technique shader_test
{
pass p0
{
VertexShaderConstant[0] = ; // the screen transformation
VertexShaderConstant[4] = ; // the world transformation
...
VertexShader =
decl
{
stream 0;
float v0[3]; // Position
float v3[3]; // Normal
float v7[3]; // Texture Coord 1
float v8[3]; // Texture Coord 2, or tangent vector
}
asm
{
vs.1.1
// Transform position to screen coordinates
m4x4 oPos,v0,c0
// Transform normal to world coordinates
m3x3 r0,v3,c0
... // do something
// send the texture coordinates to the pixel shader
mov oT0.xy,v7.xy
mov oT1.xy,v8.xy
};
}
}";
}
Shader programming is non-trivial and requires good DirectX and
shader assembler knowlege. There are several books about shader
programming. However, once a shader effect is defined, it can be used
by everyone. With the help of advanced users, we hope to build up a
library of impressive material and shader effects for A6 soon.
While the effect script only supports shader assembler (Cg and HLSL
will not be supported before the DirectX 9 implementation), the
shader source can nevertheless be written in Cg and then compiled to
shader assembler through an external Cg compiler. Cg is a
C-Script-like shader language recently developed by nVidia and
Microsoft.
Note that many even new 3D cards, like the GeForce MX series, do not
support pixel shaders. Always add a fallback technique when
programming vertex or pixel shaders.
Literature recommendation:
Microsoft DirectX 8 help file
Wolfgang Engel, ShaderX Shader programming techniques
Effects & Shaders predefined variables
The following variables, vectors and matrices are available within
effect scripts and shaders:
mtlSkin1 ... mtlSkin4
The 4 material skins, to be set to any bmap through material.skin1
... material.skin4.
entSkin1 ... entSkin4
The current entity skin and the 3 following skins. If a skin does
not exist, it is replaced by the corresponding material skin.
entSkill41 ... entSkill44
Four general purpose variables, set by entity skills.
mtlSkill1 ... mtlSkill8
8 general purpose variables, set by material.skill1 ...
material.skill8. They are often used for an ARGB color value, which
can be set through pixel_for_vect(vector(blue,green,red),alpha,8888).
Note that the alpha range is 0..100, while the color range is 0..255.
vecSunDir
The normalized direction vector of the sun light, used for vertex
shaders.
vecAmbient, VecDiffuse, vecSpecular, vecEmissive
The current material properties, converted to color vectors for
vertex shaders (alpha, red, green, blue, range 0.0f..1.0f).
Example:
effect "
...
vector vecAmbient;
vector vecDiffuse;
technique shader_test
{
pass p0
{
VertexShaderConstant[12] = ; // the material ambient values, 0.0f..1.0f range
VertexShaderConstant[13] = ; // the material diffuse values
...
}
}";
vecSkill1
vecSkill5
vecSkill41
Material skills 1..4, 5..8, and entity skills 41..44 as vector for
vertex shaders. Note: The skills are _not_ automatically converted to
float. This has to be done by C-Script through float(), floatd() or
floatr() instructions.
vecTime
A vector set from engine variables:
vecTime.x = float(time);
vecTime.y = time.y; // to be set in C-Script
vecTime.z = time.z; // to be set in C-Script
vecTime.w = float(total_ticks);
vecFog
A vector set from camera parameters:
vecFog.x = float(Camera.clip_near + Camera.fog_start);
vecFog.y = float(Camera.clip_near + Camera.fog_end);
vecFog.z = 1.0f / float(Camera.fog_end - Camera.fog_start);
vecFog.w = 1.0f;
vecLight
A vector set from the sum of the entities" red, green, blue values
and the environment light.
vecLight.x = float(entity.red + ground.red)/255.0;
vecLight.y = float(entity.green + ground.green)/255.0;
vecLight.z = float(entity.blue + ground.blue)/255.0;
vecLight.w = entity transparency;
vecViewPort
A vector to be used in shaders, which gives the view dimensions:
vecViewPort.x = float(view.size_x)
vecViewPort.y = float(view.size_y)
vecViewPort.z = 1/vecViewPort.x
vecViewPort.w = 1/vecViewPort.y
vecViewPos
A vector to be used in shaders, which gives the view position.
vecViewDir
A vector to be used in shaders, which gives the view direction.
vecCycle
A vector to be used in shaders, which gives a cyclic repeating
time value and it"s sine, cosine, and tangent:
vecCycle.x = float((total_ticks % material.cycle)/material.cycle);
vecCycle.y = sin(2 * PI * vecCycle.x)
vecCycle.z = cos(2 * PI * vecCycle.x)
vecCycle.w = tan(2 * PI * vecCycle.x)
See also:
material.cycle
matWorld
The world transformation 4x4 matrix, set by the entities" position
and angles.
matView
The view transformation 4x4 matrix, set by the view position and
angles.
matViewInv
The inverse view matrix.
matProj
The view projection 4x4 matrix, set by the view angle and the
clip_near / clip_far range.
matWorldView
The product of World and View matrix.
matWorldViewProj
The product of World, View and Projection matrix.
matMtl
The material.matrix.
Material Parameters
material.matrix
material.matrix11..material.matrix44
A user-writable matrix that is available for effect scripts through
, and can be used for shaders or texture transformations. The
matrix parameter can be used for matrix operations, while the
elements of the matrix are accessible through the matrix11..matrix44
parameters.
Remarks:
The material matrix can be used for scaling and shifting a texture
according to the following formula:
u" = u * mtl.matrix11 + v * mtl.matrix21 + mtl.matrix41
v" = u * mtl.matrix12 + v * mtl.matrix22 + mtl.matrix42
(u,v = skin coordinates)
Shifting and scaling a texture this way is faster than using the
entity.u and v parameters, or the material.scale1 and scale2
parameters, which directly affect the model mesh. Therefore,
entity.u and entity.v will be abandoned, and material.scale1,scale2
can not be changed anymore during gameplay.
Examples:
// use a matrix for cubic environment mapping
function mtl_env_init()
{
bmap_to_cubemap(mtl.skin1);
// generate a user matrix that transforms camera space back to world space
while(1) {
mat_set(mtl.matrix,mat_viewinv);
// reset the translation part of the matrix
mtl.matrix41 = 0; // 0 is the same as float(0)
mtl.matrix42 = 0;
mtl.matrix43 = 0;
wait(1);
}
}
material mtl_envcube // environment cube
{
skin1 = bmp_envcube;
event = mtl_env_init;
effect = "
texture mtlSkin1;
matrix matMtl;
technique envcube
{
pass p0
{
Texture[0]=;
AddressU[0] = Clamp; // don"t wrap around edges
AddressV[0] = Clamp;
TexCoordIndex[0] = CameraSpaceReflectionVector;
TextureTransformFlags[0] = Count3;
TextureTransform[0] = ; // transform camera space back to world space
ColorOp[0] = SelectArg1; // ignore the ambient light
ColorArg1[0] = Texture;
}
}
";
}
// use an effect for scaling or shifting a texture with a matrix
effect = "
matrix matMtl;
technique scale {
// use material transformation matrix, leave everything else at default values
pass p0
{
TextureTransformFlags[0] = Count2; // use u,v values
TextureTransform[0] = ;
} }
technique fallback { pass p0 { } }
";
material.event
This function is called once for every entity this material is
assigned to. It can be used to initialize material and entity
properties.
Modified:
mtl - predefined material pointer, set to the material
my - predefined entity pointer, set to the entity.
Example:
function mtl_enviro_init()
{
bmap_to_cubemap(my.skin1); // convert the entity"s skin 1 to a cube map
}
material mtl_enviro {
event = mtl_enviro_init;
...
}
See also:
material.enable_view, material.enable_render
material.enable_view
If this flag is set, the material"s event function is executed at the
beginning of every view rendering. This can be used to calculate a
texture matrix from the view or projection matrices. 
Example:
// generate a matrix that transforms camera space back to world space
function mtl_env_view()
{
mat_set(mtl.matrix,matViewInv);
// reset the translation part of the matrix
mtl.matrix41 = 0; // 0 == float(0)
mtl.matrix42 = 0;
mtl.matrix43 = 0;
}
function mtl_env_init()
{
bmap_to_cubemap(mtl.skin1);
mtl.event = mtl_env_view;
mtl.enable_view = on; // run the event at the beginning of every view rendering
}
material mtl_envcube // environment cube
{
skin1 = bmp_envcube;
event = mtl_env_init;
...
}
material.enable_render
If this flag is set, the material"s event function is executed at the
beginning of every entity rendering, if the material contains an
effect and was assigned to the entity. This can be used to perform
effect calculations based on entity skills or the entity"s world
matrix.
material.tangent
If set, the second texture coordinate set (v8) is the tangent u
vector rather than skin coordinates. Used for vertex shaders.
Type:
Flag (can only be set in a definition, but not during gameplay)
Example:
material mat_bump3 {
...
flags = tangent;
...
}
Remarks:
- The binormal vector (v tangent) can be calculated by the vertex
shader from the cross product of the vertex normal and the u tangent.
- The tangent flag affects the meshes of all models or terrains that
use this material. It does not affect sprites.
material.cycle
Determines the time value in ticks for the vecCycle vector for vertex
shaders.
Range:
1..999999, default 480 (30 sec)
See also:
vecCycle
material.skill1 ... material.skill8
8 variables that can be used by effect scripts and shaders. They
are referred by  ...  in the effect.
material.skin1 ... material.skin4
4 bitmaps that can be used by effect scripts and shaders. They
are referred by  ...  in the effect.
material.scale1
material.scale2
Scale factors for the texture coordinates of the first and second
DirectX texture stages for models and terrain. The resulting texture
coordinates are the UV values assigned in the model editor multiplied
by the scale factor if it"s nonzero.
Type:
Var, redefinable.
Range:
0.001..9999, default 0.
Remarks:
The scale factors directly influence the model mesh and thus affect
all entities which use that model. They can only be initialized, but
not changed during gameplay.
mat_unlit
It"s diffuse color is now black (0,0,0) by default, and it"s emissive
color is grey (128,128,128).
effect_load(material,string name) (Commercial & Pro)
Loads an effect file in Microsoft .fx format from the work folder
into the given material, and applies to effect to all models and
terrain that have this material sssigned. This instruction can be
used to edit effects and shaders in real time and observe the result
immediately in the game.
Example:
effect_load(mtl_bump,"specularbump.fx");
W1550 - Error in effect
The effect or shader script has a syntax error. The line number will
be indicated by the error message.
W1551 - Effect unsupported by hardware
The technique uses a feature or shader version that is unsupported by
the 3D card. Do never forget to add a fallback technique to any
effect. The DirectX Caps Viewer gives information about which
features are supported by your hardware.
-emu
Engine command line option; enables vertex shader emulation on 3D
cards without shader hardware, like GeForce1. Vertex shader emulation
deactivates hardware vertex processing and thus can reduce the frame
rate remarkably, even if no vertex shader is used. Some render or
texture stage modes, like CameraSpaceReflectionVector, as well as
pixel shaders are not available in vertex shader emulation mode and
lead to an error message when used in effect scripts. Therefore
vertex shader emulation is used mostly for testing purposes, and is
normally not recommended for released games.
effects.wdl, effects.wmp
A test level that contains examples for the newly implemented sky
cube, material and matrix functions, is included in the work folder.
The sky bitmap is (c) Mighty Pete.
Multiplayer Mode Improvements =========================================
session_connect(string session,string hostname) (Pro Edition)
...
Remarks:
- This instruction can be used to switch the engine to client mode
even if it wasn"t started with the -cl command line option. Note that
after switching from normal to client mode, the level has to be
loaded anew.
Switching the engine to client mode at run time has certain
consequences for the script. IFDEF CLIENT can not be used - it"s
undefined because the engine was not started with the -cl option.
Client dependent functions or initializations must run _after_
connecting to a session. For instance, creating a client player in
the main function won"t work when the engine was not in client mode
when running main(). A good place for creating the client player is
after reloading the level after connection.
- There is no dialogue box for entering the hostname. If the server
or session is not found, the engine will remain connected to the
current server, or remain in non-multiplayer mode.
Example:
session_connect("office","127.0.0.1");
while (connection == 0) { wait(1); } // wait until connected
level_load("office.wmb"); // load level anew
sleep(0.5); // wait until the level state is received from the server
player_create(); // user function to place the player into the level
dplay_sync
This variable determines whether multiplayer send functions wait
until the data is actually sent, or write the data into an internal
send buffer and return immediately.
type:
var
Range:
-1 : Never wait until the data is sent (not recommended - client and server will fall out of sync).
0 : Wait until data is sent for entity updates, don"t wait for send instructions (default).
1 : Always wait until the data is sent (behavior prior to version 6.2).
Remarks:
Setting this variable to 1 before a send instruction ensures that the
data is really sent when the instruction returns. However, this can
remarkably reduce the frame rate on a slow network when applications
perform many send instructions.
Example:
dplay_sync = 1; // don"t use send buffer
send_var(var1); // slow
dplay_sync = 0; // use send buffer for send instructions
send_var(var2); // fast
See also:
dplay_unreliable,send_var,send_string,send_skill
-cl command line option
...
If no server or no session is found, the engine now automatically
starts in non-multiplayer mode.
Bones Animation Improvements ==========================================
ent_bonerotate()
ent_animate()
ent_blend()
...were often used in a wrong way in bones animation examples sent to
the support, resulting in garbled animations. The usual error was an
attempt to compose a bones state from several animations, but using a
wrong animation/blending order, or forgetting to reset the bones at
the beginning of every cycle. Bones animation requires more
reflections and understanding than vertex animation. We"ve improved
the documentation, added more examples, and implemented another
blending method that is easier to use:
ent_blendpose(entity,var target,var source,var percent)
Linearly interpolates between a source and a target bones pose, and
copies the result to the target pose. Can also be used to copy a pose
to another one by setting the percent value at 100.
Parameters:
target - the target pose, 1..4
source - the source pose, 1..4
percent - the blending percentage, 0..100
Speed:
Medium (percent >= 100)
Slow (percent < 100)
Remarks:
A pose is a state of the entity"s bones, built through ent_animate or
bones_ instructions after setting the pose number by entity.pose. For
blending entity animations in a complex way, a model entity can have
up to 4 different poses that can be blended by this instruction. The
visible pose is pose 1.
Blending by linear interpolation computes intermediate vertex
positions rather than intermediate bones angles. Thus it produces the
best results when the bones angles of source and target pose are not
too different, like less than 90 degrees.
Using poses for animation blending is slower and requires more code
and more memory than using the ent_blend instruction, but is easier
to script - using ent_blend can sometimes be a little tricky. Poses
also offer more freedom for complex blending operations.
Example:
// let a model run, and smoothly blend over to shooting when [Ctrl] is pressed
action bones_test
{
while(1)
{
my.skill1 += 3*time; // running torso animation
my.skill2 += 3*time; // running legs animation
if (key_ctrl == on) // fire key pressed?
{
my.skill3 += 20*time; // shoot blending percentage
my.skill3 = min(my.skill3,100); // limit at 100 percent
}
else
{
my.skill3 -= 20*time;
my.skill3 = max(my.skill3,0); // limit at 0 percent
}
// reset skeletion and then compose the animation (order is important):
ent_animate(me,NULL,0,0); // reset all poses
ifdef USE_POSES;
// compose the poses: 1 = running, 2 = shooting
// animate the running legs in pose 1 and pose 2
my.pose = 1;
ent_animate(me,"run_legs",my.skill2,anm_cycle);
// copy the running legs from pose 1 to pose 2 - faster than animating separately
ent_blendpose(my,2,1,100);
// animate the torso in pose 1 only
ent_animate(me,"run_torso",my.skill1,anm_cycle+anm_add);
// if [Ctrl] pressed, animate the shooting torso in pose 2 only
if (my.skill3 > 0) {
my.pose = 2;
ent_animate(me,"shoot",0,anm_add); // we assume only one shooting frame
// now blend shooting (pose 2) into running (pose 1)
ent_blendpose(my,1,2,my.skill3);
}
ifelse;
// alternatively, same animation without poses - order is important
// first, move the torso during running
ent_animate(me,"run_torso",my.skill1,anm_cycle);
// then blend over to, or blend back from shooting (only affects the torso)
if (my.skill3 > 0) { ent_blend("shoot",0,my.skill3); }
// finally animate the legs
ent_animate(me,"run_legs",my.skill2,anm_cycle+anm_add);
endif;
wait(1);
}
}
See also:
ent_animate,ent_blend,entity.pose
entity.pose
The current bones pose number of the model entity. All bones
animation instructions relate to the pose given by this parameter.
Range:
1..4.
Remarks:
A pose is a state of the entity"s bones, built through ent_animate or
bones_ instructions. For blending entity animations in a complex way,
a model entity can have up to 4 different poses that can be blended
by ent_blendpose() instructions. Pose 1 is used for the visible model
pose.
See also:
ent_blendpose
ent_bonereset_all(entity)
like ent_bonereset_branch, but resets all bones of the current pose
of the entity.
ent_animate(...)
...
Remarks:
ent_animate(entity,NULL,0,0) resets all bones poses of the entity.
C-Script Instructions =================================================
ent_fixnormals(entity,frame)
Recalculates the normal vectors for the given model or terrain entity
and frame number. Necessary to achieve correct gouraud shading after
having modified the frame mesh by displacing vertices.
Speed:
Slow.
Example:
ent_fixnormals(my,my.frame);
See also:
vec_for_mesh,vec_to_mesh
effect_local()
...
Remarks:
If the effect_local instruction was performed by an entity, the
particle functions can access this entity through the you pointer.
This way, the particle effect can use the entity parameters and
skills.
bmap_to_cubemap(bmap) (Commercial & Pro)
Converts a six-sided sky cube bitmap into a cubic environment map,
which can be used for enviroment mapping or shader effects. 
Speed:
Slow.
Remarks:
The bmap must look like a sky cube sprite: consisting of 6 adjacent
square cube faces in the order south, east, north, west, down, up.
Thus its width must be six times larger than its height. Each cube
face should be a power of 2 in size, like 512x512. The faces must be
tiled in a way that they can be wrapped around a cube.
Example:
bmap envmap = ;
material mat_env
{
skin2 = envmap;
effect = "
texture mtlSkin2;
technique env_cube
{
pass P0
{
Texture[0] = ;
AddressU[0] = Clamp; // don"t wrap around edges
AddressV[0] = Clamp;
ColorOp[0] = SelectArg1; // ignore the ambient light
ColorArg1[0] = Texture;
TexCoordIndex[0] = CameraSpaceReflectionVector;
TextureTransformFlags[0] = Count3;
}
}
technique fallback { pass p0 { } } // empty fallback causes normal rendering without effect
";
}
starter mat_env_init {
bmap_to_cubemap(mat_env.skin2);
}
See also:
sky.cube
bmap_to_normals(bmap,factor) (Commercial & Pro)
Converts the given bmap into a normals map, needed for DOT3
bumpmapping. A normals map contains, at each pixel position, instead
of the RGB color values the XYZ components of the normal of a height
map calculated from the luminance of the original bmap.
Returns:
0 if the conversion failed, otherwise the bmap pointer
Parameters
bmap - bitmap to be converted to normals
factor - scale for the bitmap luminance
Speed:
slow
bmap_to_uv(bmap) (Commercial & Pro)
Converts the given bmap into a UV offsets map, needed for environment
bump mapping. An UV offsets map contains, at each pixel position,
the luminance difference values of the blue channel of the original
bmap in u and v direction.
Returns:
0 if the conversion failed, otherwise the bmap pointer
Parameters
bmap - bitmap to be converted to uv offsets
Speed:
slow
Remarks: While DOT3 bump mapping modulates the texture brighness
according to a light vector, environment bump mapping modulates the
texture UV offset, creating bumps on a mirror like surface.
bmap_to_mipmap(bmap)
Creates a chain of 4 mipmaps for the given bmap. Can be used to
create mipmaps for textures that are used by effect scripts.
Returns:
0 if the conversion failed, otherwise the bmap pointer
Speed:
slow
Parameters
bmap - bitmap to be converted to a mipmap chain
Example:
// create a mipmapped normals map for bumpmapping
bmap_to_normals(bmap_to_mipmap(material_bump.skin1),2);
video_window(vector pos,vector size,var style,string title)
changes the position, size, style or title of the engine window.
Parameters:
pos - vector containing the new x and y position in pixels, or nullvector for no change.
size - vector containing the new x and y size in pixels, or nullvector for no change.
style - 0 for no change, or a combination of the following modes:
1 - no border
2 - thin border
4 - thick border
16 - title bar and border
48 - title bar with system menu
112 - title bar with system menu and minimize button
title - new title of the window, or NULL for no change.
Speed:
Medium
Remarks:
Changing the window size does not change the resolution. Use
video_size() for changing the window resolution.
Example:
// place the window at position (500,300) and remove the border
video_window(vector(500,300,0),nullvector,1,NULL);
video_set(var width,var height,var depth,var screen)
Like video_switch, but the width and height can now be set
individually, thus allowing arbitrary video resolutions not contained
in the 12 supported modes.
Remarks:
In window mode, arbitrary video resolutions are supported as long as
they fit on the desktop screen and sufficient video memory is
available.
In fullscreen mode, only a few video resolutions are supported,
dependent on the 3D card.
video_switch
mode 9 was changed to 1280x1024, because this resolution is supported
by more 3D cards than 1280x960.
A new mode 12 of 1920x1200 was implemented.
txt_load(text,string name)
Opens a file, reads its content into separate strings of the text
object, and closes the file. This instruction can be used to fill an
empty text object from a file.
Parameters:
name - name of the text file to be read.
text - empty text object.
Returns:
Number of strings filled.
Speed:
Slow.
Remarks:
This instruction uses file_str_read() to parse the file content into
separate strings. The text strings are created as variable length
strings. If the file contains more strings than the text, the rest
will be omitted.
This instruction replaces the legacy dataview parameter of a text
object. The old A3 database and dataview objects will be abandoned in
one of the next updates.
Example:
text bigtext { strings = 77000; } // empty text with a lot of strings
...
txt_load(bigtext,"bigfile.txt"); // fill the text, allocate strings
bigtext.visible = on;
See also:
file_str_read
file_str_read()
...
Returns:
0..4000 - number of characters read (4000 max)
-1 - end of file reached
Remarks:
The instruction automatically changes the size of variable length
strings to the string read. The maximum string size to be read is
4000 characters.
execute(string commands);
can now be called from DLLs, and accept direct sctrings.
exec(string program, string arguments);
can now be called from DLLs, and accept direct sctrings.
Remarks:
"\" Characters in strings, like for file paths, have to be given in
C-Notation as "\\". Example: "C:\\program files\\internet explorer\\iexplore.exe"
Matrix instructions
A set of instructions was implemented for performing calculations
with 4x4 transformation matrices. Matrix calculations are used
exclusively for effect scripts. A matrix is just an array of 16
variables:
var my_matrix[16];
The elements of the matrix can be accessed through the array indices
[0]..[15], as usual. However, unlike normal variable arrays, a
transformation matrix contains values in a special format, the IEEE
32 bit floating point format. Thus, matrix elements can not be
written to or read from like normal C-Script variables. They have to
be converted to the IEEE floating point or the C-Script fixed format
before, like this:
my_matrix[0] = float(my_value);
my_value = fixed(my_matrix[0]);
The exception is the value 0, which is the same in fixed and float
format.
Handling matrix operations requires some mathematical knowledge. They
are not intended for beginners to games programming, and are not
necessary unless for advanced shader programming.
Additionally to the user-defined matrices and material matrices, there
are 4 predefined matrices:
matView
The view transformation 4x4 matrix, determined by the view position
and angles.
matViewInv
The inverse view transformation matrix.
matProj
The view projection 4x4 matrix, determined by the view aspect, arc,
and clip_near / clip_far range.
matWorld
The world transformation 4x4 matrix, determined by the entities"
position, scale, and angles.
The following matrix instructions were implemented:
mat_identity(matrix)
copies the identity matrix to the given matrix.
Remarks:
The identity matrix is a matrix of 1"s for all diagonal elements and
zeros for the rest. A matrix multiplied by the identity matrix
remains unchanged.
mat_scale(matrix,var x,var y,var z)
Scales the given transformation matrix by the given factors about the
x, y, and z axis.
mat_set(matrix1,matrix2)
copies the content of matrix2 to matrix1.
mat_inverse(matrix1,matrix2)
copies the inverse of matrix2 to matrix1.
Remarks:
The inverse of a matrix, multiplied by the matrix itself, results in
the identity matrix. Note that not every matrix has an inverse, but
transformation matrices usually have.
mat_transpose(matrix1,matrix2)
copies the transpose of matrix2 to matrix1.
Remarks:
The transpose of a matrix is a matrix with rows and colums exchanged.
In case of rotations, the inverse of a rotation matrix is its
transpose.
mat_multiply(matrix1,matrix2)
Multiplies matrix1 by matrix2, and copies the result to matrix1.
Remarks:
Multiplying two transformation matrices results in a matrix that
concatenates both transformations.
float(x)
Returns x converted to a 32 bit IEEE floating point value. Not to be
used for C-Script calculations, but handy for passing floating point
values to effect scripts, vertex shaders, and matrices.
Example:
mtl_bump.skill1 = float(time); // pass the time variable to a material effect
floatr(var x)
Returns 1/x converted to a 32 bit IEEE floating point value. Higher
precision than float(1/x) when x is a large number.
Example:
mtl_bump.skill2 = floatr(camera.fog_end - camera.fog_start); // pass 1/(fog_end-fog_start) to a vertex shader
floatd(var a,var b)
returns float(a)/float(b). Used for increasing the precision of
fixed -> float conversions for small values.
Example:
function mtl_shift_texture()
{
mtl.skill1 += time; // shift texture left
mtl.matrix41 = floatd(mtl.skill1,1000); // change texture u offset by 0.001 units
}
fixed(var float)
Returns the fixed format value of a variable that was converted to
floating point through the float() instruction, or is an element of a
transformation matrix.
See also:
float,floatr,floatd
Object Parameters =====================================================
sky.cube
Defines a six sided environment cube from a 6-frames sky sprite.
Type:
Flag
Remarks:
The cube flag allows defining sky cubes without having to create a
model.
The sides of the sky cube are drawn at a distance of Camera.clip_far
from the viewer. The sky z parameter can be used to move the cube up
and down. The x, y, angle, and scale parameters are ignored.
The sprite image must consist of 6 adjacent square frames in the
following order: west, north, east, south, down, up. Thus its file
name must end with "+6" and its width must be six times larger than
its height. Each frame should be a power of 2 in size, like 512x512.
The frames must be tiled in a way that they can be wrapped around a
cube.
A lot of sky cube images can be found at http://www.wadfather.com.
The sky sprite image can be put together by adding the single cube
images in the order bk, rt, ft, lf, dn, up from left to right.
Example:
sky mountain_cube {
type = ;
flags = cube,visible;
layer = 2;
z = 30; // move 30 pixels upwards
}
See also:
sky.dome, sky.scene
entity.skill1..entity.skill100
The number of entity skills was increased to 100.
Remarks:
Entity.skill1..entity.skill20 are used for entering default
properties in WED. Entity.skill21..entity.skill50 are used by the
template scripts, except for entity.skill41..Entity.skill44, which
are used for shaders. Entity.skill51..entity.skill100 are free for
the user.
entity.parent
If the entity was contained in a map entity, this pointer points at
the map entity. Otherwise it contains Null. Can be used to move the
entity together with it"s "parent" entity; or can alternatively be
used as a general purpose entity pointer like my or you.
Type:
Entity pointer
See also:
map_subents
entity.polygon (Commercial & Pro)
If set, the model entity"s real shape is used for collision with
physics entities. Otherwise, an oriented bounding box is used.
Type:
Flag
Range:
on - use the entity"s polygonal shape (default on terrain and maps)
off - use the entity"s oriented bounding box (faster, default on models and sprites)
Remarks:
Though it is not enforced, this flag should be seen as mutually
exclusive to calling phent_settype with PH_POLY. Only one of the
objects involved in a collision should use polygons for collision
detection.
Example:
action SelectHull {
my.polygon= on; // now using shape of MDL
wait(10000);
my.polygon= off; // now using oriented bounding box
}
button.actionOff
.. is now also triggered when the mouse leaves the button area with
no mouse button pressed.
text.shadow
Draws TTF texts with a black shadow.
Type: Flag
text.outline
Draws TTF texts with a black outline around the characters.
Type: Flag
Predefined Variables ==================================================
mip_sprites
Mipmap bias factor for sprites. If defined at 0, no mipmaps for
sprites are created; otherwise the variable gives the relative
distance for sprite mipmap switching. The higher the value, the later
mipmaps are switched and the "sharper" sprite images appear.
Type:
Var, redefinable
Range:
0 .. 10.0, default 2.0
Remarks:
If this variable is defined at 0, sprite loading is a little faster
because no mipmaps are created.
Example:
var mip_sprites = 0; // no mipmapping for sprites.
See also:
mip_shaded, mip_flat
d3d_lodfactor[3]
Gives the 3 distances for the LOD switching in percentage of
view.clip_far. At the distance given by lodfactor[0] the entity
switches to LOD 1; at lodfactor[1] it switches to LOD 2; at
lodfactor[3] it switches to LOD 3.
Type:
vector
Range:
0..100, default 12.5, 25, 50.
Example:
var lodfactor[3] = 5, 10, 20; // switch LOD at 5%, 10%, and 20% of view.clip_far
shadow_mode
Gives the trace_mode for every entities" tracing downwards in order
to find the shadow plane and the environment brightness.
Type:
var, r/w
Range:
See trace_mode.
Default: IGNORE_SPRITES+IGNORE_MODELS+IGNORE_PASSENTS+IGNORE_PASSABLE
Example:
// place shadows on top of models below the player
shadow_mode = IGNORE_SPRITES+IGNORE_PASSENTS+IGNORE_PASSABLE;
freeze_mode
...
Range:
0 - All functions are running (default)
1 - Level entity functions are suspended, all other functions are running
2 - All functions are suspended.
map_subents
Determines whether entities contained in map entities are to be
placed into the level, or not.
Type
Variable, redefinable
Range:
on - place sub entities (default).
off - don"t place sub entities.
See also:
entity.parent
WED/MED/SED improvements ==============================================
WED: New texture management
WED can now load textures directly from folders, instead of WAD
files. For this, an [Add Folder] button was added to the Texture
Manager. For adding a texture, simply copy it into the folder. The
texture list can be refreshed by right click and [Refresh].
WED: Loading sub-entities from a map entity
Models, sprites, or terrain that are part of a map entity are now
also placed into the level in which the map entity is placed. This
way, entity groups can be defined and compiled as map entities.
WED: New Script
When clicking "new script", a requester will pop up that allows to
select between any template script found in the template_6 folder,
or an empty script. This way you can now choose between the old and
the new templates, or add your own default script template.
The old template scripts are used in the tutorials. They are for
simple shooter style games only, and not recommended for commercial
projects.
The new template scripts are much more flexible and powerful, can be
easily combined with own code, and are suited for commercial
projects.
WED: multiple selection in object tree
Multiple objects in the object tree can now be selected by holding
[Ctrl] while clicking the objects.
WED: Ignore by Build
Objects or groups can be omitted by the Build process, for speeding
up the testing of parts of a level. For this, click right onto the
object, and select Render Style->Ignore.
WED: Vertex Snap
Vertex Snap can be toggled with the [V] button in the button bar. In
Vertex Snap mode, objects snap to the next vertex of another object
within the same group.
MED: Import (Commercial Edition)
MED can now directly import 3DS, Milkshape ASCII, and .X models
including skin texture and bones animation.
Restriction: When importing a bones animation from an external
editor, the whole animation must be done externally - external and
internal bones animations use different rotation axes and thus can"t
be combined. This restriction will be overcome in a future update.
MED: Save As
You can now choose between the MDL5 and the MDL7 format. The MDL5
format can also be read by old engine versions, like A5, and some
external programs, like Milkshape. Bones are only supported by the
new MDL7 format.
MED: Add Frame
Can now copy an arbitrary bones source frame to the new frame.
Miscellaneous =========================================================
Model normals...
...are now calculated by the engine, instead of loaded from the
normals table. This increases model loading time a little, but leads
to more precise shading.
Automatic skin animation...
...that occured when an entity had several skins, but no action, was
abandoned in order to avoid confusion for beginners.
Abandoned =============================================================
A3/A4 instructions
Two years after their official removal, the following abandoned A3/A4
WDL style instructions are now physically removed from the engine, in
order to reduce the engine size and increase the compiler speed:
MUSIC - not used anymore
PLAY_SONG - replaced by media_loop()
PLAY_SONG_ONCE - replaced by media_play()
PLAY_SNDFILE - replaced by media_play()
MOVE_VIEW - not used anymore
LOOK - replaced by trace() or c_trace()
PRINT... - replaced by file instructions
entity.u,entity.v
To be removed from the documentation. For new applications we
recommend to use a material with a texture matrix for shifting or
scaling a texture (see example).
detail_size
To be removed from the documentation. For new applications we
recommend to use a material effect for detail textures.
 

    =======================================================================
New features implemented in A6 6.11: ===================================
======================================================================= 

 C-Script Instructions =================================================
ent_animate(entity,string scenename,var percent,var mode)
Like ent_frame and ent_cycle, but for both vertex and bones
animation. If the name of a bones scene is given, the instruction
does not alter my.frame and my.next_frame, but modifies the entity"s
skeleton. Only bones affected by the given scene are set to their new
orientation; bones not contained in this scene keep their old state.
By executing this instruction several times for different animation
scenes, bones animations are combined if the scenes affect different
sets of bones. Bones animation can also be combined with vertex
animation.
Parameters:
entity - the entity to be animated
scenename - the name of the scene. If NULL is given, the frame and
nextframe parameters, as well as the entity"s skeleton are reset
to their default states. Used for setting a start bones position
before combining several bones animation scenes.
percent - the animation percentage within the scene
mode - to be combined from the following predefined values:
ANM_CYCLE - for a cyclic scene, like walking or running. Otherwise
it"s a noncyclic scene like jumping or shooting.
ANM_ADD - for adding the new bones angles to the current angles,
rather than replacing the current angles by the new ones.
Remarks:
Use ANM_ADD for combining different bones movements even if they
affect the same bones. For instance, if a bone was already rotated
by 10 degrees and the new scene rotates the same bone by further 20
degrees, the new bones angle is 30 degrees after ent_animate with
ANM_ADD. Without ANM_ADD it"s 20 degrees.
Bones animation is also sent to the clients. However only basic
frames, without ANM_ADD mode, and without any direct bones
manipulation are sent. Sending bones animation to the clients
causes high traffic and does not interpolate between bones frames.
Therefore, we stronly recommend to perform bones animation on the
client side by using a local function and setting the entity"s
NOSEND_FRAME flag on the server. The same is recommended for vertex
animation.
ent_animate also affects vertex frames of models and bitmap frames
of sprites, and thus can completely replace ent_frame and
ent_cycle.
Example:
ent_animate(me,NULL,0,0); // reset the skeleton
ent_animate(me,"walk",walk_percent,ANM_CYCLE); // set walk cycle
ent_animate(me,"turnhead",turn_percent,ANM_CYCLE+ANM_ADD); // add head rotation
ent_animate(me,"shoot",shoot_percent,AND_ADD); // add shooting
ent_frame ent_cyle was replaced by ent_animate, and is to be removed from the manual.
ent_blend()
Can now also be used to interpolate between arbitrary bones scenes.
However it interpolates the vertex positions rather than the bones
angles.
ent_bones(entity)
Returns the number of bones of the entity, or 0 if the entity has
no bones.
vec_for_vertex()
vec_for_normal()
Use the current state of the entity skeleton for calculating the
vertex or normal position.
ent_bonerotate(entity,string name,vector angle)
rotates an entity bone, it"s childs and all attached vertices about
it"s hinge point.
Parameters
entity - entity pointer
name - name of the bone
angle - pan, tilt, roll euler angles.
Returns
0 if bone not found, otherwise nonzero.
Remarks
This instruction does not set the bone to a certain angle, it rather
adds the angle to the current bone orientation. For setting the bone
to an absolute angle, perform ent_bonereset before.
ent_bonerotate_parent(entity,string name,vector angle)
Like ent_bonerotate; however rotates an entity bone, it"s children
and all attached vertices about it"s parent"s joint. This corresponds
to rotate3 mode in MED.
ent_bonescale(entity,string name,vector scale)
scales an entity bone, it"s childs and all attached vertices in x, y,
and z direction.
Parameters
entity - entity pointer
name - name of the bone
scale - x, y, z scale factors.
Returns
0 if bone not found, otherwise nonzero.
Remarks
This instruction does not set the bone to a certain scale, it rather
multiplies it"s current scale by the given factors. For setting the
bone to an certain scale, perform ent_bonereset before.
This instruction can also be used to remove polygons attached to a
certain bone by setting its scale to (0,0,0).
ent_bonemove(entity,string name,vector offset)
moves a bone by the given offset in x, y, and z direction.
Parameters
entity - entity pointer
name - name of the bone
offset - x, y, z move distance.
Returns
0 if bone not found, otherwise nonzero.
ent_bonereset_branch(entity,string name)
Resets a bone and all it"s children to their default position, scale
and orientation.
Parameters
entity - entity pointer
name - name of the bone
Returns
0 if bone not found, otherwise nonzero.
ent_bonereset(entity,string name)
Resets a bone to it"s default scale and orientation.
Parameters
entity - entity pointer
name - name of the bone
Returns
0 if bone not found, otherwise nonzero.
file_length(var filehandle)
returns the lenght of the file with the given handle, in bytes.
file_asc_read(var filehandle)
returns -1 when the end of the file is reached.
vector(x,y,z)
Can now be used for more than one parameter of a vector instruction.
snd_stopall(mode)
Stops all level, entity, or other sounds.
Parameters:
mode - 1 = stop all currently playing level sound sources.
2 = stop all entity sounds.
3 = stop all level and entity sounds.
4 = stop every sound that is currently playing.
Speed:
Medium.
Example:
camera.audible = off; // disable the sounds of the camera view
snd_stopall(3);       // silent all playing level sounds
view2.audible = on;   // switch the sound focus to a different view
Remarks:
Useful to immediately reflect a change of a view"s audible flag or of
the global sound volume.
breakpoint_on(condition);
Conditional breakpoint. Activates the source debugger at any place in
the script code as soon as the given condition becomes true. Very
useful for observing the state of a certain variable during script
execution.
Parameters:
condition - an expression that evaluates to false or true.
Remarks:
- The condition is evaluated after each instruction. Therefore a
conditional breakpoint slows down script execution remarkably and
inflates the compiled code; the given condition should be a simple
comparision and not a complicated formula.
- Breakpoints can only be set in the development engine, not in the
release engine.
- If [Esc] is pressed while the source debugger is active, the
conditional breakpoint is reset. The next break_on instruction
reactivates the breakpoint.
Example:
breakpoint_on(camera.genius == NULL);
// activates the debugger as soon as the camera genius is set to zero
// by any instruction.
phent_setmaxspeed(entity, var maxLinear, var maxAngular);
If an object moves faster than the specified limit it will be stopped
(its velocity gets set to 0). If an object rotates with an angular
speed faster than the specified maxAngular limit, it will stop
spinning (angular velocity will be reset to 0).
By default objects have no speed limit assigned to them, which can
lead to problems of an object leaving the level or showing other
unintended behavior. Setmaxspeed acts as a safety net to reduce this
problem by halting an object if it goes beyond the specified speed
limits. Because it will be halted abruptly, do not use this command
for slowing down an object, for that purpose use phent_setdamping /
phent_addforce instead.
This function was already available in 6.0, but was omitted in the
documentation.
PH_WHEEL, Parameter 6, range changed for consistency reasons:
nullvector or spring-damper constants in the 0..100000 range, e.g.
(90000,100,0)
c_move, activate_trigger, event_trigger, trigger_range:
If c_move is called with activate_trigger, an nearby entities" event
function is triggered when
a) the sum of the moved entities" trigger_range and the nearby
entities" trigger_range is bigger than the distance between the
c_move target position and the nearby entities" center point.
b) the nearby entities" trigger_range is zero, its passable flag is
set and the c_move target position is inside its bounding box. 

    Object Parameters =====================================================
HBAR,VBAR
was removed and replaced by WINDOW.
view.clip_near
Has now a default value of 10 instead of 15.
For framerate reasons the A5 software clipping of level blocks was
reactivated for A6.
text.red
text.green
text.blue
Gives the color for drawing a TrueType font.
Text colors were already available in 6.0, but were forgotten to
document.
entity.material
can now also be individually set for map entities, thus overriding
the mat_flat and mad_shaded defaults. 

    C-Script variables, pointers, definitions =============================
nexus
Nexus used by the current level, in KB.
Type:
Var, read-only
Remarks:
Indicated in the first value of the "mem" column in the statistics
panel.
time_physics
Time needed in ms/frame for physics calculations.
Type: Var, read-only.
Remarks: This variable is indicated in the last [ms] row of the [D]
panel.
Enable_polycollision
If this variable (default 1) is redefined at o, the new collision
system and the physics engine are disabled. This has the advantage of
slighly faster level loading.
sky_map, cloud_map
These bmap pointers are set to the texture of the level"s sky box
upon level loading. Is automatically set to NULL when a
non-transparent, non-overlay sky dome or sky scene entity is visible.
Panel pointer
The panel pointer is passed as a second parameter to the button
function when a button is clicked, and as first parameter to the
on_click function. This way, the functions can determine which
panel was clicked.
Example:
function redblue(panel);
panel red { x = 10; y = 20; bmap = redmap; on_click = redblue; }
panel blue { x = 10; y = 40; bmap = bluemap; on_click = redblue; }
function redblue(panel);
{
if (panel == red) { print("red clicked!"; }
if (panel == blue) { print("blue clicked!"; }
}
Remarks:
This was already implemented in A5.51 and documented in the
update.txt, but forgotten to take over into the manual.
debug_mode
Variable for controlling the debugger.
Type:
Var, r/w
Range:
2 - Perform a single step ahead.
1 - Debugger is active.
0 - Run until next breakpoint.
-1 - Run and ignore all futher breakpoints.
Remarks:
- This variable is modified by the breakpoint and breakpoint_on
instructions, as well as by the [Esc] and [Space] keys in single
step mode when debug_external is not set.
- By setting this variable at 0 at the beginning or after a wait
instruction, a function can prevent it"s own debugging for security
reasons.
- By setting this variable at 2 through a DLL, the current
instruction is executed, it"s result is copied to debug_result,
debug_mode is set back to 1 and the debugger moves to the next
instruction.
debug_external
Disables the source display and the [Esc] and [Space] keys of the
debugger. Used for debugging through an external DLL.
Type:
var, r/w
Range:
0 - use internal debugger (default).
1 - use external debugger.
debug_result
Contains the result of the last instruction when the debugger is
active.
Type:
var, r/o
plugindir
Gives a folder for engine plugin DLLs. The engine automatically opens
all DLLs copied into this folder, without need for dll_open or
dll_close instructions or for setting a DLL handle.
Type:
Definition.
Default:
"..\acknex_plugins" in development mode,
"" in release mode.
Remarks:
"\" must be given in C notation as "\\". The folder name must not end
with "\".
Example:
plugindir = "plugins"; // look for DLLs in the plugins subfolder.
local vectors
can now also be initialized with default values, just like global
vectors.
Example:
function test()
{
var localvector[3] = 1,2,3;
...
}
The restriction to 3 dimensions still applies.
Main and starter functions
..were started in the order they appeared in the script, which
normally caused the main function to be run after all starter
functions. This is changed now so that the main function always
runs at first.
Path, resource
32 paths or resource files can now be given instead of 16. 

 WED/MED/SED improvements ==============================================
Bones animation                                   (Commercial, Pro)
Bones form the "skeleton" of a model, and are used as an alternative
method for animation. A bone is defined by
- a hinge point that is either located at a fixed position in the
model, or attached to the end of a "parent" bone,
- a pan tilt roll orientation
- a length
- a set of vertices attached to that bone. If the bone moves or
rotates, the attached vertices move or rotate with it.
A model can be animated by changing the orientation or length of a
set of bones. This has the following advantages over hierarchical or
key frame animation:
- Bones animation in MED is easier and faster than animation by moving
vertices.
- Bones animations can affect only parts of the model, and thus can be
combined. For instance, a model can turn his head, shoot and walk
at the same time. The engine combines the three partial animations.
- MDL files are smaller with bones animation than with a
corresponding key frame animation.
MED allows to create and connect bones, attach vertices to them, and
record bones animations.
Creation of bones:
Enter bone creation mode by clicking the [Create Bone] button. Left
clicking into a window creates a bone hinge point. The next left
click connects the hinge point with the click point by a bone.
Further clicks create a connected chain of "child" bones. [Del]
deletes the last bone, and initiates a new bone chain.
Alternatively, bones can be created by clicking and dragging.
Clicking into an existing hinge point attaches the new bone to the
previous one.
Edit the bones by selecting the [Bones Mode] in the Select toolbar.
In [Move] mode you can move the bones by selecting and dragging their
hinges. In [Dependent Move] mode, moving a parent bone moves also all
child bones. In [Independent Move] mode, only the parent bone is
moved.
In [Rotate] mode you can rotate a bone chain by clicking a hinge and
dragging upwards/downwards. Rotating a parent bone also rotates all
child bones when [Dependent Move] is activated.
You can merge two or several hinges the same way as you merge
vertices - put them together, select them and then click the [Merge]
button. This way, several child bones can be attached to the same
parent bone.
Attaching vertices to bones:
Click the [Apply Vertices Mode] button. Vertices already attached to
bones appear blue; free vertices appear yellow. Select a bone by
clicking it"s hinge point. Select some vertices and click the [Apply
Vertices] button. The vertices are now attached to the selected bone
and will move with it. You can remove vertices from a bone by
clicking the [Remove Vertices] button. Continue until all vertices
are blue.
Recording bones animation:
Similar to recording a frame animation. Click the [Animate] button to
switch from bones placement to bones animation mode. Add a frame as
usual with "Edit/Add New Frame". Activate [Use Bones Animation]. Now
select a bone by clicking it"s hinge point. You can move or rotate
the bone to it"s desired position, as described in "Creation of
bones". When finished, add the next frame. For replay, you can toggle
between replaying a normal frame animation, and a bones animation,
with the [Use Bone Animation] button.
For precise animation, select [Bones Properties] and click [Animation
Key] on the panel. You can now change the following values for setting
a bones position and orientation:
[Position] - moves the bone and it"s childs to the desired position.
Note that the parent bone remains attached to the bone,
however it"s not rotated although it looks as if it were.
[Rotate1] - rotates the bone and it"s child bones about the bone
position.
[Rotate2] - rotates only the child bones about the bone position.
[Rotate3] - rotates the bone and the child bones about the bone origin.
If the bones properties panel is not open, you can toggle between the
3 rotate modes by pressing [1], [2], or [3]. The current mode is
indicated in the status line. For rotating a bone, click its hinge
point and move the mouse upwards or downwards.
An example for a complex rotation, ro-arm.mdl, is included in the
beta. By clicking [Remove Bones Animation] the bone is reset to it"s
default position.
The [Disable] flag temporarily excludes the bone from the animation.
The flag is deleted when Animate mode is left.
Playing bones animation:
Just like playing vertex animation, through the ent_animate
instruction. The engine makes no difference between bones and vertex
frames, with the exception that bones animation can be added together
from an arbitrary number of bones animation scenes.
Please note:
- Although vertex and bones animation can be combined within the same
frame, this is not yet supported by the engine. Thus vertex animation
within a bones frame will be ignored. This restriction will be
overcome in a future version.
- If a model has both bones and vertex frames, the vertex frames must
come first, followed by the bones frames. This restriction will be
overcome in a future version.
- Bones animation needs more memory space per entity, and more
rendering time than vertex animation. If you need huge armies of
animated models on the screen, you might prefer vertex animation.
- If a model"s original size will be exceeded by bones animation or
bones scaling or rotation during runtime, the model could be clipped
too early by the viewing frustrum. This has the effect that the model
disappears at the edges of the view despite it should be still
partially visible. To prevent this, you can increase the model"s size
by placing single, unconnected vertices in it"s first frame. All
bones movement and scaling must be within the boundaries set by the
outer vertices in the model"s first frame.
24 bit skins
MED now supports 24 bit TGA skins without alpha channel for models
and terrain. They will be rendered in 24 bit color depth and without
transparency.
Terrain skins
are now mapped from the center of the first texture pixel to the
center of the last texture pixel. This way, terrains can be attached
without seams.
GXL Properties
By right clicking on a MED or WED window and selecting GXL Properties,
view parameters like view depth and DirectX lighting can be adjusted.
Vertex and Bone point size
Can now be set in MED Preferences/Misc. This way it"s easier to
click on bone hinges or vertices on a low resolution display.
GXL2DX8A.DLL
This DLL allocates only one DirectX device per WED/MED session,
instead of one device per window, thus saving resources.
MED plugin folder
MED plugins copied into the med_plugins folder appeat automatically
in the tools menu. The following MED plugin exmples are included:
Akeys.dll
This MED plugin can reset or delete certain or all bones animation
keys.
VEditBox.dll
Allows to shape or distort MED objects by manipulating a rectangular
box around them.
BnTrans.dll
Allows to create bones animation sequences in a sort of sequential
editor.
BkGndPic.dll
Creates animated background pictures for copying a recorded 2D
animation into an animated model.
Asc_exim.dll
Exports and imports MDL models in ASCII format. Example for creating
MDL exporter and importer into other model formats.
All the DLLs above will be available in source code, together with
a semiautomatic DLL creator program, within the upcoming WED/MED
plugin SDK.
New SED features:
- Code Jumper improved, now jumps between
entities/actions/strings/functions/variables/etc.
- Small bug when indenting braces at beginning of lines corrected
- Automatically adding of () and {}
- Change the update interval of the watches
- Change color of commands added
- The current line gets commented/uncommented if no selection has been
made.
- Edit scripts while using the find/replace dialog.
- Debug objects with parameters, for example an entity named myent you
can get the x position adding myent.x to the watches. To debug the
whole entity, just use myent.
- Step over to next source line (F4) and Ignore further breakpoints
added to the debugmenu.
- When SED moves to a specific line due to syntax checker or the
debugger it will only scroll if the line is not visible.
- Test run will not start again if a debug has already been started,
instead it will run until the next breakpoint.
- SED will now disable the source display and the [Esc] and [Space]
keys of the engine built-in debugger.
- Ability to rename watches, by double clicking in the watches
- Change values of the watches during run-time from the debug menu.
- Debugging of the my/you entity
- Toggle/Next/Previous/Clear all bookmark(s)
- Code Completion now shows on top and displays correctly according to font size
- SED will try to open the file where the error had occurred in the Syntax Checker Results
- Does not longer register filetypes at startup, could cause trouble to some systems
- Breakpoints could be removed/added during run-time added. (F9)
- Go to current debugposition added. (F10)
- Watch variable content during run-time, manually add watches from the Debug menu.
- Test run and the syntax checker now uses the whole path from the configuration. This ensures that the "test run" function works even running it from another opened wdl script. So be sure to set the filename with path in the configuration options.
- Test run now removes the * mark in the title as the current file gets saved when using this function
- Syntax check now starts after the game has been executed to get current errors
- Minor changes: Test Run (F5), Syntax Check (F6), Grep renamed to Find In Files and placed at the edit menu (Ctrl+Shift+F), Shortcuts for comment/uncomment lines corrected
- The toolbar icons corrected
- The opendialog now shows up properly in Windows 98
- Added ability to change margin color
- Background color was changed to gray when no color was selected and OK was pressed in the Customize Color dialog
- Larger size of command help providing more help, including another help file.
- Ability to change background color
- Load included files. Option added in the configurations.
- Starting with a blank script is now optional. Also added in the configurations.
- Show line numbers applies to all open documents
- Redo (Ctrl-Y), Commmand Database (Ctrl-D), Replace (Ctrl-H)
- Close All/Save All added
- Commands Database window resized
- Open multiple files at once from the open dialog
- One instance always, with other words, if another file is passed to C-Script Editor it will not start again. But it will open the file in the already opened instance.
- Added grid lines to the Syntax Checker Results
- Help with F1 and check if help file exists
- Highlighted Selected Line added under options and is available by default
- Ability to choose color for the highlight added
- Show Toolbar added to the options menu in order to get the toolbar back if closed.
- Choose of bold font in the Customize Colors dialog.
- Go back to last edit position with Alt-Left
- Multiline highlighting for strings added
- Added cursor position and read mode to status bar
- New XP style menus and change of toolbar imagesizes
- Bigger size of the Command Help font 

 Error Messages ========================================================
E1198: : Bad file
This error message pops up if an entity or level file is damaged and
leads to an engine crash while loading. 

 Miscellaneous =========================================================
Debugging an entity at runtime
Sometimes it"s desirable to check the status of certain entities
during gamesplay for AI debugging and examining what"s going on in a
complicated situation. For this, a new debugging function was
implemented.
Press [Shift-F11]. The game freezes and a cursor appears on the
screen. Click onto an arbitrary entity. The watched pointer will be
set to that entity, causing it"s status display to appear on the
screen. Pressing [Shift-F11] a second time will resume gameplay, but
the status display is permanently updated with the status of the last
clicked entity. If you want to get rid of the status display, click
an empty position while in frozen mode.
Remarks:
This debugging feature was implemented through a few lines of
C-Script "hardwired" in the engine:
function _tog_dbg {
if(key_shift) {
freeze_mode = (freeze_mode == 0); // toggle freeze mode
while(freeze_mode) {
mouse_mode = 2;
mouse_pointer = 2;
mouse_pos.x = pointer.x; // move the mouse pointer
mouse_pos.y = pointer.y;
if(mouse_left) {
watched = mouse_ent;   // set entity to debug
}
wait(1);
}
}
Watched entities
The name of the current model file and vertex frame is now indicated
in the watched panel.
Statistics panel
The statistics panel and the red lines are now activated by [F11]
rather than by [D], which is used for the WASD player control of the
new template scripts.
The 4th and 5th values of the num column indicate the overall number
of entities in the level, and the number of non-culled entities.
Engine startup
If a valid 3D device is not found at startup, the engine now tries
to allocate a device a couple of times in 250 ms intervals. It gives
up when no device was found after 4 tries.
New template scripts
The following scripts can be added to your project to enable new
features (menus, player movement, enemy AIs, etc). Using WED, you can
select the scripts you currently need for your project by selecting
"File->Add Script" and then (using the standard Windows dialog box)
open the script file you want to use.
AI Bipeds
aiDumbBiped01.wdl
aiTerminator01.wdl
Camera Scripts
camera1stPerson01.wdl
camera3rd01.wdl
cameraFree01.wdl
cameraOrbit.wdl
Player
plBiped01.wdl
plBipedHUD01.wdl
plCar01.wdl
plWeapons00.wdl
Misc.
door01.wdl
lift01.wdl
forcefield01.wdl
lensFlare.wdl
menu01.wdl
sky00.wdl
sky01.wdl
startup01.wdl
To switch from the old template scripts to the new template scripts,
copy the template.wdl from the template_6 folder to your data folder.
After that, [New Script] will create a script that contains paths to
the new template scripts, instead of the old ones.
Example:
Create a level with a player.
1) Create a level in WED.
2) Insert a model for your player.
3) Add the "Player Biped" Script (WED: File->Add Script. Select "template_6\code\plBiped01.wdl).
4) Attach "PlBiped01" action to player model.
5) Add a "3rd Person Camera" Script (WED: File->Add Script. Select "template_6\code\camera3rd01.wdl).
6) Rebuild level with Update Entities and Run.
Some of the scripts can be customized (WED-> Resources-> Scripts->
Customize). A brief description of each script in HTM format can be
found in the DOC folder.
Remarks:
Scripts with the same name but different numbers (e.g. sky01 and
sky00) can conflict with each other. At best this can give you
undefined results, at worse it can cause crashing. Don"t add more
then one script with the same name.

======================================================================