OpenB3D standard Blitz3D functions

entity - entity handle

length -

Description:

Creates an animation sequence for an entity. This must be done before any animation keys set by SetAnimKey can be used in an actual animation however this is optional. You may use it to "bake" the frames you have added previously using SetAnimKey.

Returns the animation sequence number added.

source_mesh - source mesh handle

dest_mesh - destination mesh handle

Description:

Adds the source mesh to the destination mesh.

AddMesh works best with meshes that have previously only had mesh commands used with them.

So if you want to manipulate a mesh before adding it to another mesh, make sure you use ScaleMesh, PositionMesh, PaintMesh etc rather than ScaleEntity, PositionEntity, EntityTexture etc before using AddMesh.

However, something to be aware of when using commands such as RotateMesh is that all mesh commands work from a global origin of 0,0,0. Therefore it is generally a good idea to scale and rotate a mesh before positioning it, otherwise your mesh could end up in unexpected positions. Also, when using AddMesh, the origin of the new all-in-one mesh will be set at 0,0,0.

After using AddMesh, the original source_mesh will still exist, therefore use FreeEntity to delete it if you wish to do so.

surface - surface handle

v0 - index number of first vertex of triangle

v1 - index number of second vertex of triangle

v2 - index number of third vertex of triangle

Description:

Adds a triangle to a surface and returns the triangle's index number, starting from 0.

The v0, v1 and v2 parameters are the index numbers of the vertices created using AddVertex.

Depending on how the vertices are arranged, then the triangle will only be visible from a certain side. Imagine that a triangle's vertex points are like dot-to-dot pattern, each numbered v0, v1, v2. If these dots, starting from v0, through to V2, form a clockwise pattern relative to the viewer, then the triangle will be visible. If these dots form an anti-clockwise pattern relative to the viewer, then the triangle will not be visible.

The reason for having one-sided triangles is that it reduces the amount of triangles that need to be rendered when one side faces the side of an object which won't be seen (such as the inside of a snooker ball). However, if you wish for a triangle to be two-sided, then you can either create two triangles, using the same set of vertex numbers for both but assigning them in opposite orders, or you can use CopyEntity and FlipMesh together.

surface - surface handle

x# - x coordinate of vertex

y# - y coordinate of vertex

z# - z coordinate of vertex

u# (optional) - u texture coordinate of vertex

v# (optional) - v texture coordinate of vertex

w# (optional) - w texture coordinate of vertex - not used, included for future expansion

Description:

Adds a vertex to the specified surface and returns the vertices' index number, starting from 0.

x,y,z are the geometric coordinates of the vertex, and u,v,w are texture mapping coordinates.

A vertex is a point in 3D space which is used to connect edges of a triangle together. Without any vertices, you can't have any triangles. At least three vertices are needed to create one triangle; one for each corner.

The optional u, v and w parameters allow you to specify texture coordinates for a vertex, which will determine how any triangle created using those vertices will be texture mapped. The u, v and w parameters specified will take effect on both texture coordinate sets (0 and 1). This works on the following basis:

The top left of an image has the uv coordinates 0,0. The top right has coordinates 1,0 The bottom right is 1,1. The bottom left 0,1.

Thus, uv coordinates for a vertex correspond to a point in the image. For example, coordinates 0.9,0.1 would be near the upper right corner of the image.

So now imagine you have a normal equilateral triangle. By assigning the bottom left vertex a uv coordinate of 0,0, the bottom right a coordinate of 1,0 and the top centre 0.5,1, this will texture map the triangle with an image that fits it.

When adding a vertex its default color is 255,255,255,255.

entity - entity handle

vector_x# - vector x

vector_y# - vector y

vector_z# - vector z

axis - axis of entity that will be aligned to vector

1: x-axis

2: y-axis

3: z-axis

rate# (optional) - rate at which entity is aligned from current orientation to vector orientation. Should be in the range 0 to 1, 0 for smooth transition and 1 for 'snap' transition. Defaults to 1.

Description:

Aligns an entity axis to a vector.

red# - red ambient light value

green# - green ambient light value

blue# - blue ambient light value

The green, red and blue values should be in the range 0-255. The default ambient light colour is 127,127,127.

Description:

Sets the ambient lighting colour.

Ambient light is a light source that affects all points on a 3D object equally. So with ambient light only, all 3D objects will appear flat, as there will be no shading.

Ambient light is useful for providing a certain level of light, before adding other lights to provide a realistic lighting effect.

An ambient light level of 0,0,0 will result in no ambient light being displayed.

See also: CreateLight.

entity - entity handle

mode (optional) - mode of animation.

0: stop animation

1: loop animation (default)

2: ping-pong animation

3: one-shot animation

speed# (optional) - speed of animation. Defaults to 1.

sequence (optional) - specifies which sequence of animation frames to play. Defaults to 0.

transition# (optional) - used to tween between an entities current position rotation and the first frame of animation. Defaults to 0.

Description:

Animates an entity.

More info about the optional parameters:

speed# - a negative speed will play the animation backwards.

sequence - Initially, an entity loaded with LoadAnimMesh will have a single animation sequence. More sequences can be added using either LoadAnimSeq or AddAnimSeq. Animation sequences are numbered 0,1,2...etc.

transition# - A value of 0 will cause an instant 'leap' to the first frame, while values greater than 0 will cause a smooth transition.

entity - entity handle

Description:

Returns true if the specified entity is currently animating.

entity - entity handle

Description:

Returns the length of the specified entity's current animation sequence.

entity - entity handle

Description:

Returns the specified entity's current animation sequence.

entity - entity handle

Description:

Returns the current animation time of an entity.

enable - True to enable fullscreen antialiasing, False to disable.

The default AntiAlias mode is False.

Description:

Enables or disables fullscreen antialiasing.

Fullscreen antialiasing is a technique used to smooth out the entire screen, so that jagged lines are made less noticeable.

Some 3D cards have built-in support for fullscreen antialiasing, which should allow you to enable the effect without much slowdown. However, for cards without built-in support for fullscreen antialiasing, enabling the effect may cause severe slowdown.

brush - brush handle

alpha# - alpha level of brush

Description:

Sets the alpha level of a brush.

The alpha# value should be in the range 0-1. The default brush alpha setting is 1.

The alpha level is how transparent an entity is. A value of 1 will mean the entity is non-transparent, i.e. opaque. A value of 0 will mean the entity is completely transparent, i.e. invisible. Values between 0 and 1 will cause varying amount of transparency accordingly, useful for imitating the look of objects such as glass and ice.

An BrushAlpha value of 0 is especially useful as Blitz3D will not render entities with such a value, but will still involve the entities in collision tests. This is unlike HideEntity, which doesn't involve entities in collisions.

brush - brush handle

blend -

1: alpha (default)

2: multiply

3: add

Description:

Sets the blending mode for a brush.

brush - brush handle

red# - red value of brush

green# - green value of brush

blue# - blue value of brush

Description:

Sets the colour of a brush.

The green, red and blue values should be in the range 0-255. The default brush color is 255,255,255.

Please note that if EntityFX or BrushFX flag 2 is being used, brush colour will have no effect and vertex colours will be used instead.

brush - brush handle

fx -

0: nothing (default)

1: full-bright

2: use vertex colors instead of brush color

4: flatshaded

8: disable fog

16: disable backface culling

Description:

Sets miscellaneous effects for a brush.

Flags can be added to combine two or more effects. For example, specifying a flag of 3 (1+2) will result in a full-bright and vertex-coloured brush.

brush - brush handle

shininess# - shininess of brush

Description:

Sets the specular shininess of a brush.

The shininess# value should be in the range 0-1. The default shininess setting is 0.

Shininess is how much brighter certain areas of an object will appear to be when a light is shone directly at them.

Setting a shininess value of 1 for a medium to high poly sphere, combined with the creation of a light shining in the direction of it, will give it the appearance of a shiny snooker ball.

brush - brush handle

texture - texture handle

frame (optional) - texture frame. Defaults to 0.

index (optional) - texture index. Defaults to 0.

Description:

Assigns a texture to a brush.

The optional frame parameter specifies which animation frame, if any exist, should be assigned to the brush.

The optional index parameter specifies texture layer that the texture should be assigned to. Brushes have up to four texture layers, 0-3 inclusive.

camera - camera handle

red# - red value of camera background color

green# - green value of camera background color

blue# - blue value of camera background color

Description:

Sets camera background color. Defaults to 0,0,0.

camera - camera handle

cls_color - true to clear the color buffer, false not to

cls_zbuffer - true to clear the z-buffer, false not to

Description:

Sets camera clear mode.

camera - camera handle

red# - red value of value

green# - green value of fog

blue# - blue value of fog

Description:

Sets camera fog color.

camera - camera handle

mode -

0: no fog (default)

1: linear fog

Description:

Sets the camera fog mode.

This will enable/disable fogging, a technique used to gradually fade out graphics the further they are away from the camera. This can be used to avoid 'pop-up', the moment at which 3D objects suddenly appear on the horizon.

The default fog colour is black and the default fog range is 1-1000, although these can be changed by using CameraFogColor and CameraFogRange respectively.

Each camera can have its own fog mode, for multiple on-screen fog effects.

camera - camera handle

near# - distance in front of camera that fog starts

far# - distance in front of camera that fog ends

Description:

Sets camera fog range.

The near parameter specifies at what distance in front of the camera that the fogging effect will start; all 3D object before this point will not be faded.

The far parameter specifies at what distance in front of the camera that the fogging effect will end; all 3D objects beyond this point will be completely faded out.

camera - camera handle

viewport_x# - 2D viewport coordinate

viewport_z# - 2D viewport coordinate

Description:

Picks the entity positioned at the specified viewport coordinates.

Returns the entity picked, or 0 if none there.

An entity must have its EntityPickMode set to a non-0 value value to be 'pickable'.

See also: EntityPick, LinePick, CameraPick, EntityPickMode.

camera - camera handle

x# - world coordinate x

y# - world coordinate y

z# - world coordinate z

Description:

Projects the world coordinates x,y,z on to the 2D screen.

camera - camera handle

mode - projection mode:

0: no projection - disables camera (faster than HideEntity)

1: perspective projection (default)

2: orthographic projection

Description:

Sets the camera projection mode.

The projection mode is the the technique used by Blitz to display 3D graphics on the screen. Using projection mode 0, nothing is displayed on the screen, and this is the fastest method of hiding a camera. Using camera projection mode 1, the graphics are displayed in their 'correct' form - and this is the default mode for a camera. Camera projection mode 2 is a special type of projection, used for displaying 3D graphics on screen, but in a 2D form - that is, no sense of perspective will be given to the graphics. Two identical objects at varying distances from the camera will both appear to be the same size. Orthographic projection is useful for 3D editors, where a sense of perspective is unimportant, and also certain games.

Use 'CameraZoom' to control the scale of graphics rendered with orthographic projection. As a general rule, using orthographic projection with the default camera zoom setting of 1 will result in graphics that are too 'zoomed-in' - changing the camera zoom to 0.1 should fix this.

One thing to note with using camera project mode 2, is that terrains will not be displayed correctly - this is because the level of detail algorithm used by terrains relies on perspective in order to work properly.

camera - camera handle

near - distance in front of camera that 3D objects start being drawn

far - distance in front of camera that 3D object stop being drawn

Description:

Sets camera range.

Try and keep the ratio of far/near as small as possible for optimal z-buffer performance. Defaults to 1,1000.

camera - camera handle

x - x coordinate of top left hand corner of viewport

y - y coordinate of top left hand corner of viewport

width - width of viewport

height - height of viewport

Description:

Sets the camera viewport position and size.

The camera viewport is the area of the 2D screen that the 3D graphics as viewed by the camera are displayed in.

Setting the camera viewport allows you to achieve spilt-screen and rear-view mirror effects.

camera - camera handle

zoom# - zoom factor of camera

Description:

Sets zoom factor for a camera. Defaults to 1.

None.

Description:

Clears the collision information list.

Whenever you use the Collisions command to enable collisions between two different entity types, information is added to the collision list. This command clears that list, so that no collisions will be detected until the Collisions command is used again.

The command will not clear entity collision information. For example, entity radius, type etc.

surface - surface handle

clear_verts (optional) - true to remove all vertices from the specified surface, false not to. Defaults to true.

clear_triangles (optional) - true to remove all triangles from the specified surface, false not to. Defaults to true.

Description:

Removes all vertices and/or triangles from a surface.

This is useful for clearing sections of mesh. The results will be instantly visible.

After clearing a surface, you may wish to add vertices and triangles to it again but with a slightly different polygon count for dynamic level of detail (LOD).

None.

Description:

Clears the current texture filter list.

entities (optional) - True to clear all entities, False not to. Defaults to true.

brushes (optional) - True to clear all brushes, False not to. Defaults to true.

textures (optional) - True to clear all textures, False not to. Defaults to true.

Description:

Clears all entities, brushes and/or textures from the screen and from memory.

As soon as you clear something, you will not be able to use it again until you reload it. Trying to do so will cause a runtime error.

This command is useful for when a level has finished and you wish to load a different level with new entities, brushes and textures.

entity - entity handle

index - index of collision

Description:

Returns the other entity involved in a particular collision. Index should be in the range 1...CountCollisions( entity ), inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the x component of the normal of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the y component of the normal of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the z component of the normal of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

src_type - entity type to be checked for collisions.

dest_type - entity type to be collided with.

method - collision detection method.

1: ellipsoid-to-ellipsoid collisions

2: ellipsoid-to-polygon collisions

3: ellipsoid-to-box collisions

response - what the source entity does when a collision occurs.

1: stop

2: slide1 - full sliding collision

3: slide2 - prevent entities from sliding down slopes

Description:

Enables collisions between two different entity types.

Entity types are just numbers you assign to an entity using EntityType. Blitz then uses the entity types to check for collisions between all the entities that have those entity types.

Blitz has many ways of checking for collisions, as denoted by the method parameter. However, collision checking is always ellipsoid to something. In order for Blitz to know what size a source entity is, you must first assign an entity radius to all source entities using EntityRadius.

In the case of collision detection method 1 being selected (ellipsoid-to-ellipsoid), then the destination entities concerned will need to have an EntityRadius assigned to them too. In the case of method 3 being selected (ellipsoid-to-box), then the destination entities will need to have an EntityBox assigned to them. Method 2 (ellipsoid-to-polygon) requires nothing to be assigned to the destination entities.

Not only does Blitz check for collisions, but it acts upon them when it detects them too, as denoted by the response parameter. You have three options in this situation. You can either choose to make the source entity stop, slide or only slide upwards.

All collision checking occurs, and collision responses are acted out, when UpdateWorld is called.

Finally, every time the Collision command is used, collision information is added to the collision information list. This can be cleared at any time using the ClearCollisions command.

See also: EntityBox, EntityRadius, Collisions, EntityType, ResetEntity.

entity - entity handle

index - index of collision

Description:

Returns the handle of the surface belonging to the specified entity that was closest to the point of a particular collision.

Index should be in the range 1...CountCollisions( entity ), inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the time taken to calculate a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the index number of the triangle belonging to the specified entity that was closest to the point of a particular collision.

Index should be in the range 1...CountCollisions( entity ), inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the world x coordinate of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the world y coordinate of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

index - index of collision

Description:

Returns the world z coordinate of a particular collision.

Index should be in the range 1...CountCollisions( entity ) inclusive.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - Entity Handle

parent (optional) - Entity that will act as Parent to the copy.

Description:

Creates a copy of an entity and returns the handle of the newly created copy. This is a new entity instance of an existing entity's mesh! Anything you do to the original Mesh (such as RotateMesh) will effect all the copies. Other properties (such as EntityColor, Position etc.) since they are 'Entity' properties, will be individual to the copy.

If a parent entity is specified, the copied entity will be created at the parent entity's position. Otherwise, it will be created at 0,0,0.

mesh - handle of mesh to be copied

parent (optional) - handle of entity to be made parent of mesh

Description:

Creates a copy of a mesh and returns the newly-created mesh's handle.

The difference between CopyMesh and CopyEntity is that CopyMesh performs a 'deep' copy of a mesh.

CopyMesh is identical to performing new_mesh=CreateMesh() : AddMesh mesh,new_mesh.

entity - entity handle

Description:

Returns the number of children of an entity.

entity - entity handle

Description:

Returns how many collisions an entity was involved in during the last UpdateWorld.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

mesh - mesh handle

Description:

Returns the number of surfaces in a mesh.

Surfaces are sections of mesh. A mesh may contain only one section, or very many.

See also: GetSurface.

surface - surface handle

Description:

Returns the number of triangles in a surface.

surface - surface handle

Description:

Returns the number of vertices in a surface.

red# (optional) - brush red value

green# (optional) - brush green value

blue# (optional) - brush blue value

Description:

Creates a brush and returns a brush handle.

The optional green, red and blue values allow you to set the colour of the brush. Values should be in the range 0-255. If omitted the values default to 255.

A brush is a collection of properties such as Colour, Alpha, Shininess, Texture etc that are all stored as part of the brush. Then, all these properties can be applied to an entity, mesh or surface at once just by using PaintEntity, PaintMesh or PaintSurface.

When creating your own mesh, if you wish for certain surfaces to look differently from one another, then you will need to use brushes to paint individual surfaces. Using commands such as EntityColor, EntityAlpha will apply the effect to all surfaces at once, which may not be what you wish to achieve.

See also: LoadBrush.

parent (optional) - parent entity of camera

Description:

Creates a camera entity and returns its handle.

Without at least one camera, you won't be able to see anything in your 3D world. With more than one camera, you will be to achieve effect such as split-screen modes and rear-view mirrors.

A camera can only render to the backbuffer. If you wish to display 3D graphics on an image or a texture then copy the contents of the backbuffer to the appropriate buffer.

The optional parent parameter allow you to specify a parent entity for the camera so that when the parent is moved the child camera will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the camera being created at position 0,0,0 rather than at the parent entity's position.

segments (optional) - cone detail. Defaults to 8.

solid (optional) - true for a cone with a base, false for a cone without a base. Defaults to true.

parent (optional) - parent entity of cone

Description:

Creates a cone mesh/entity and returns its handle.

The cone will be centred at 0,0,0 and the base of the cone will have a radius of 1.

The segments value must be in the range 3-100 inclusive, although this is only checked in debug mode. A common mistake is to leave debug mode off and specify the parent parameter (usually an eight digit memory address) in the place of the segments value. As the amount of polygons used to create a cone is exponentially proportional to the segments value, this will result in Blitz trying to create a cone with unimaginable amounts of polygons! Depending on how unlucky you are, your computer will then crash.

Example segments values (solid=true): 4: 6 polygons - a pyramid 8: 14 polygons - bare minimum amount of polygons for a cone 16: 30 polygons - smooth cone at medium-high distances 32: 62 polygons - smooth cone at close distances

The optional parent parameter allow you to specify a parent entity for the cone so that when the parent is moved the child cone will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the cone being created at position 0,0,0 rather than at the parent entity's position.

See also: CreateCube, CreateSphere, CreateCylinder.

[parent] (optional) - This allows you to set the parent entity of Cube.

Description:

Creates a cube mesh/entity and returns its handle.

The cube will extend from -1,-1,-1 to +1,+1,+1.

The optional parent parameter allow you to specify a parent entity for the cube so that when the parent is moved the child cube will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the cube being created at position 0,0,0 rather than at the parent entity's position.

Creation of cubes, cylinders and cones are a great way of getting scenes set up quickly, as they can act as placeholders for more complex pre-modeled meshes later on in program development.

See also: CreateSphere, CreateCylinder, CreateCone.

segments (optional) - cylinder detail. Defaults to 8.

solid (optional) - true for a cylinder, false for a tube. Defaults to true.

parent (optional) - parent entity of cylinder

Description:

Creates a cylinder mesh/entity and returns its handle.

The cylinder will be centred at 0,0,0 and will have a radius of 1.

The segments value must be in the range 3-100 inclusive, although this is only checked in debug mode. A common mistake is to leave debug mode off and specify the parent parameter (usually an eight digit memory address) in the place of the segments value. As the amount of polygons used to create a cylinder is exponentially proportional to the segments value, this will result in Blitz trying to create a cylinder with unimaginable amounts of polygons! Depending on how unlucky you are, your computer may then crash.

Example segments values (solid=true): 3: 8 polygons - a prism 8: 28 polygons - bare minimum amount of polygons for a cylinder 16: 60 polygons - smooth cylinder at medium-high distances 32: 124 polygons - smooth cylinder at close distances

The optional parent parameter allow you to specify a parent entity for the cylinder so that when the parent is moved the child cylinder will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the cylinder being created at position 0,0,0 rather than at the parent entity's position.

See also: CreateCube, CreateSphere, CreateCone.

type (optional) - type of light

1: directional (default)

2: point

3: spot

parent (optional) - parent entity of light

Description:

Creates a light.

Lights work by affecting the colour of all vertices within the light's range. You need at to create at least one light if you wish to use 3D graphics otherwise everything will appear flat.

The optional type parameter allows you to specify the type of light you wish to create. A value of 1 creates a directional light. This works similar to a sun shining on a house. All walls facing a certain direction are lit the same. How much they are lit by depends on the angle of the light reaching them. Directional lights have infinite 'position' and infinite range.

A value of 2 creates a point (or omni) light. This works a little bit like a light bulb in a house, starting from a central point and gradually fading outwards.

A value of 3 creates a spot light. This is a cone of light. This works similar to shining a torch in a house. It starts with an inner angle of light, and then extends towards an outer angle of light. You can adjust the angles of a 'spot' light with the LightConeAngles command.

The optional parent parameter allow you to specify a parent entity for the light so that when the parent is moved the child light will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the light being created at position 0,0,0 rather than at the parent entity's position.

Other notes: There is a DirectX limit on the number of lights available per scene - this is either 8 or 16 depending on your video card, but you should always assume 8.

Also, you should remember that each light added effects the rendering speed.

Lights do not cast shadows, like they do in real life.

Most games get around these issues by the use of a pre-calculated 'baked' lightmap texture for the static geometry in the scene.

Other lighting techniques include: adjusting vertex colors, dynamic shadows, and/or dynamic lights (ie. moving the lights around in the scene as they are needed).

See also: LightRange, LightColor, LightConeAngles, AmbientLight.

parent (optional) - This optional parameter allows you to specify another entity which will act as the parent to this mesh.

Description:

Create a 'blank' mesh entity and returns its handle.

When a mesh is first created it has no surfaces, vertices or triangles associated with it.

To add geometry to this mesh, you will need to:

CreateSurface() ; To make a surface AddVertex ; You will need to add at least 3 to make a Triangle AddTriangle ; This will add a triangle by connecting the Vertices (points) you added to the mesh.

parent (optional) - parent entity of pivot

Description:

Creates a pivot entity.

A pivot entity is an invisible point in 3D space that's main use is to act as a parent entity to other entities. The pivot can then be used to control lots of entities at once, or act as new centre of rotation for other entities.

To enforce this relationship; use EntityParent or make use of the optional parent entity parameter available with all entity load/creation commands.

Indeed, this parameter is also available with the CreatePivot command if you wish for the pivot to have a parent entity itself.

sub_divs (optional) - sub divisions of plane. Should be in the range 1-16. The default value is 1.

parent (optional) - parent entity of plane

Description:

Creates a plane entity and returns its handle.

A plane entity is basically a flat, infinite 'ground'. It is useful for outdoor games where you never want the player to see/reach the edge of the game world.

The optional sub_divs parameter determines how many sub divisions of polygons the plane will have. Although a plane is flat and so adding extra polygons will not make it smoother, adding more polygons will allow more vertices to be lit for more detailed lighting effects.

The optional parent parameter allows you to specify a parent entity for the plane so that when the parent is moved the child plane will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the plane being created at position 0,0,0 rather than at the parent entity's position.

See also: CreateMirror.

segments (optional) - sphere detail. Defaults to 8.

parent (optional) - parent entity of sphere

Description:

Creates a sphere mesh/entity and returns its handle.

The sphere will be centred at 0,0,0 and will have a radius of 1.

The segments value must be in the range 2-100 inclusive, although this is only checked in debug mode. A common mistake is to leave debug mode off and specify the parent parameter (usually an eight digit memory address) in the place of the segments value. As the amount of polygons used to create a sphere is exponentially proportional to the segments value, this will result in Blitz trying to create a sphere with unimaginable amounts of polygons! Depending on how unlucky you are, your computer will then crash.

Example segments values: 8: 224 polygons - bare minimum amount of polygons for a sphere 16: 960 polygons - smooth looking sphere at medium-high distances 32: 3968 polygons - smooth sphere at close distances

The optional parent parameter allow you to specify a parent entity for the sphere so that when the parent is moved the child sphere will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the sphere being created at position 0,0,0 rather than at the parent entity's position.

See also: CreateCube, CreateCylinder, CreateCone.

parent (optional) - parent entity of sprite

Description:

Creates a sprite entity and returns its handle. Sprites are simple flat (usually textured) rectangles made from two triangles. Unlike other entity objects they don't actually have a mesh that can be manipulated.

The sprite will be positioned at 0,0,0 and extend from 1,-1 to +1,+1.

Sprites have two real strengths. The first is that they consist of only two polygons; meaning you can use many of them at once. This makes them ideal for particle effects and 2D-using-3D games where you want lots of sprites on-screen at once.

Secondly, sprites can be assigned a view mode using SpriteViewMode. By default this view mode is set to 1, which means the sprite will always face the camera. So no matter what the orientation of the camera is relative to the sprite, you will never actually notice that they are flat; by giving them a spherical texture, you can make them appear to look no different than a normal sphere.

The optional parent parameter allow you to specify a parent entity for the sprite so that when the parent is moved the child sprite will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the sprite being created at position 0,0,0 rather than at the parent entity's position.

Note: Sprites have their own commands for rotation and scaling.

See also: LoadSprite, RotateSprite, ScaleSprite, HandleSprite, SpriteViewMode, PositionEntity, MoveEntity, TranslateEntity, EntityAlpha, FreeEntity.

mesh - mesh handle

brush (optional) - brush handle

Description:

Creates a surface attached to a mesh and returns the surface's handle.

Surfaces are sections of mesh which are then used to attach triangles to. You must have at least one surface per mesh in order to create a visible mesh, however you can use as many as you like. Splitting a mesh up into lots of sections allows you to affect those sections individually, which can be a lot more useful than if all the surfaces are combined into just one.

grid_size - no of grid squares along each side of terrain, and must be a power of 2 value, e.g. 32, 64, 128, 256, 512, 1024.

parent (optional) - parent entity of terrain

Description:

Creates a terrain entity and returns its handle.

The terrain extends from 0,0,0 to grid_size,1,grid_size.

A terrain is a special type of polygon object that uses real-time level of detail (LOD) to display landscapes which should theoretically consist of over a million polygons with only a few thousand. The way it does this is by constantly rearranging a certain amount of polygons to display high levels of detail close to the viewer and low levels further away.

This constant rearrangement of polygons is occasionally noticeable however, and is a well-known side-effect of all LOD landscapes. This 'pop-in' effect can be reduced in lots of ways though, as the other terrain help files will go on to explain.

The optional parent parameter allows you to specify a parent entity for the terrain so that when the parent is moved the child terrain will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the terrain being created at position 0,0,0 rather than at the parent entity's position.

See also: LoadTerrain.

width - width of texture

height - height of texture

flags (optional) - texture flag:

1: Color (default)

2: Alpha

4: Masked

8: Mipmapped

16: Clamp U

32: Clamp V

64: Spherical environment map

128: Cubic environment map

256: Store texture in vram

512: Force the use of high color textures

frames (optional) - no of frames texture will have. Defaults to 1.

Description:

Creates a texture and returns its handle.

Width and height are the size of the texture. Note that the actual texture size may be different from the width and height requested, as different types of 3D hardware support different sizes of texture.

The optional flags parameter allows you to apply certain effects to the texture. Flags can be added to combine two or more effects, e.g. 3 (1+2) = texture with color and alpha maps.

Here some more detailed descriptions of the flags:

1: Color - colour map, what you see is what you get.

2: Alpha - alpha map. If an image contains an alpha map, this will be used to make certain areas of the texture transparent. Otherwise, the colour map will be used as an alpha map. With alpha maps, the dark areas always equal high-transparency, light areas equal low-transparency.

4: Masked - all areas of a texture coloured 0,0,0 will not be drawn to the screen.

8: Mipmapped - low detail versions of the texture will be used at high distance. Results in a smooth, blurred look.

16: Clamp u - Any part of a texture that lies outsides the U coordinates of 0-1 will not be drawn. Prevents texture-wrapping.

32: Clamp v - Any part of a texture that lies outsides the v coordinates of 0-1 will not be drawn. Prevents texture-wrapping.

64: Spherical environment map - a form of environment mapping. This works by taking a single image, and then applying it to a 3D mesh in such a way that the image appears to be reflected. When used with a texture that contains light sources, it can give some meshes such as a teapot a shiny appearance.

128: Cubic environment map - a form of environment mapping. Cube mapping is similar to spherical mapping, except it uses six images each representing a particular 'face' of an imaginary cube, to give the appearance of an image that perfectly reflects its surroundings.

When creating cubic environment maps with the CreateTexture command, cubemap textures *must* be square 'power of 2' sizes. See the SetCubeFace command for information on how to then draw to the cubemap.

When loading cubic environments maps into Blitz using LoadTexture, all six images relating to the six faces of the cube must be contained within the one texture, and be laid out in a horizontal strip in the following order - left, forward, right, backward, up, down. The images comprising the cubemap must all be power of two sizes.

Please note that not some older graphics cards do not support cubic mapping. In order to find out if a user's graphics card can support it, use GfxDriverCaps3D .

256: Store texture in vram. In some circumstances, this makes for much faster dynamic textures - ie. when using CopyRect between two textures. When drawing to cube maps in real-time, it is preferable to use this flag.

512: Force the use of high color textures in low bit depth graphics modes. This is useful for when you are in 16-bit color mode, and wish to create/load textures with the alpha flag - it should give better results.

Once you have created a texture, use SetBuffer TextureBuffer to draw to it. However, to display 2D graphics on a texture, it is usually quicker to draw to an image and then copy it to the texturebuffer, and to display 3D graphics on a texture, your only option is to copy from the backbuffer to the texturebuffer.

See also: LoadTexture, LoadAnimTexture.

src_entity - source entity handle

dest_entity - destination entity handle

Description:

Returns the pitch angle, that src_entity should be rotated by in order to face dest_entity.

This command can be used to be point one entity at another, rotating on the x axis only.

See also: DeltaYaw.

src_entity - source entity handle

dest_entity - destination entity handle

Description:

Returns the yaw angle, that src_entity should be rotated by in order to face dest_entity.

This command can be used to be point one entity at another, rotating on the y axis only.

See also: DeltaPitch.

Entity - entity handle

Alpha# - alpha level of entity

Description:

Sets the entity alpha level of an entity.

The alpha# value should be in a floating point value in the range 0-1. The default entity alpha setting is 1.

The alpha level is how transparent an entity is. A value of 1 will mean the entity is opaque. A value of 0 will mean the entity is completely transparent, i.e. invisible. Values between 0 and 1 will cause varying amount of transparency. This is useful for imitating the look of objects such as glass and other translucent materials.

An EntityAlpha value of 0 is especially useful as Blitz3D will not render entities with such a value, but will still involve the entities in collision tests. This is unlike HideEntity, which doesn't involve entities in collisions.

Entity - Entity handle

Blend - Blend mode of the entity.

1: Alpha (default)

2: Multiply

3: Add

Description:

Sets the blending mode of an entity. This blending mode determines the way in which the new RGBA of the pixel being rendered is combined with the RGB of the background.

To calculate the new RGBA of the pixel being rendered, the texture RGBA for the pixel (see TextureBlend for more information on how the texture RGBA is calculated) is taken, its alpha component multiplied by the entities/brushes (where applicable) alpha value and its color compentent multiplied by the entities/brushes colour. This is the RGBA which will then be blended into the background pixel, and how this is done depends on the EntityBlend value.

Alpha: This blends the pixels according to the Alpha value. This is rougly done to the formula:

Rr = ( An * Rn ) + ( ( 1.0 - An ) * Ro ) Gr = ( An * Gn ) + ( ( 1.0 - An ) * Go ) Br = ( An * Bn ) + ( ( 1.0 - An ) * Bo )

Where R = Red, G = Green, B = Blue, n = new pixel colour values, r = resultant colour values, o = old pixel colour values.

Alpha blending is the default blending mode and is used with most world objects.

Multiply: This blend mode will darken the underlying pixels. If you think of each RGB value as being on a scale from 0% to 100%, where 0 = 0% and 255 = 100%, the multiply blend mode will multiply the red, green and blue values individually together in order to get the new RGB value, roughly according to:

Rr = ( ( Rn / 255.0 ) * ( Ro / 255.0 ) ) * 255.0 Gr = ( ( Gn / 255.0 ) * ( Go / 255.0 ) ) * 255.0 Br = ( ( Bn / 255.0 ) * ( Bo / 255.0 ) ) * 255.0

The alpha value has no effect with multiplicative blending. Blending a RGB value of 255, 255, 255 will make no difference, while an RGB value of 128, 128, 128 will darken the pixels by a factor of 2 and an RGB value of 0, 0, 0 will completely blacken out the resultant pixels. An RGB value of 0, 255, 255 will remove the red component of the underlying pixel while leaving the other color values untouched.

Multiply blending is most often used for lightmaps, shadows or anything else that needs to 'darken' the resultant pixels.

Add: Additive blending will add the new color values to the old, roughly according to:

Rr = ( Rn * An ) + Ro Gr = ( Gn * An ) + Go Br = ( Bn * An ) + Bo

The resultant RGB values are clipped out at 255, meaning that multiple additive effects can quickly cause visible banding from smooth gradients.

Additive blending is extremely useful for effects such as laser shots and fire.

See also: TextureBlend, EntityAlpha.

entity - entity handle#

x# - x position of entity's collision box

y# - y position of entity's collision box

z# - z position of entity's collision box

width# - width of entity's collision box

height# - height of entity's collision box

depth# - depth of entity's collision box

Description:

Sets the dimensions of an entity's collision box.

See also: EntityRadius, Collisions, EntityType.

entity - a valid entity handle

Description:

Returns a string containing the class of the specified entity.

Possible return values are:

Pivot Light Camera Mirror Listener Sprite Terrain Plane Mesh MD2 BSP

Note that the command will fail if a valid entity handle is not supplied, and will not just return an empty string.

entity - entity handle

type - type of entity

Description:

Returns the handle of the entity of the specified type that collided with the specified entity.

See also: CollisionX, CollisionY, CollisionZ, CollisionNX, CollisionNY, CollisionNZ, CountCollisions, EntityCollided, CollisionTime, CollisionEntity, CollisionSurface, CollisionTriangle.

entity - entity handle

Red# - red value of entity

Green# - green value of entity

Blue# - blue value of entity

Description:

Sets the color of an entity.

The Red, Green and Blue values should be in the range 0-255 with 0 being darkest and 255 brightest. The default entity color is 255,255,255 (White).

src_entity - source entity handle

dest_entity - destination entity handle

Description:

Returns the distance between src_entity and dest_entity.

entity - entity handle

fx -

0: nothing (default)

1: full-bright

2: use vertex colors instead of brush color

4: flatshaded

8: disable fog

16: disable backface culling

32: force alpha-blending

Description:

Sets miscellaneous effects for an entity.

Flags can be added to combine two or more effects. For example, specifying a flag of 3 (1+2) will result in a full-bright and vertex-coloured brush.

Flag 32, to force alpha-blending, must be used in order to enable vertex alpha (see VertexColor).

See also: VertexColor.

entity - entity handle

camera - camera handle

Description:

Returns true if the specified entity is visible to the specified camera.

If the entity is a mesh, its bounding box will be checked for visibility.

For all other types of entities, only their centre position will be checked.

entity - entity handle

Description:

Returns the name of an entity. An entity's name may be set in a modelling program, or manually set using NameEntity.

See also: NameEntity.

entity - entity handle

order - order that entity will be drawn in

Description:

Sets the drawing order for an entity.

An order value of 0 will mean the entity is drawn normally. A value greater than 0 will mean that entity is drawn first, behind everything else. A value less than 0 will mean the entity is drawn last, in front of everything else.

Setting an entity's order to non-0 also disables z-buffering for the entity, so should be only used for simple, convex entities like skyboxes, sprites etc.

EntityOrder affects the specified entity but none of its child entities, if any exist.

entity - entity handle

parent - parent entity handle

global (optional) - true for the child entity to retain its global position and orientation. Defaults to true.

Description:

Attaches an entity to a parent.

Parent may be 0, in which case the entity will have no parent.

entity - entity handle

range# - range of pick area around entity

Description:

Returns the nearest entity 'ahead' of the specified entity. An entity must have a non-zero EntityPickMode to be pickable.

See also: EntityPick, LinePick, CameraPick, EntityPickMode.

entity - entity handle

pick_geometry - type of geometry used for picking:

0: Unpickable (default)

1: Sphere (EntityRadius is used)

2: Polygon

3: Box (EntityBox is used)

obscurer (optional) - True to determine that the entity 'obscures' other entities during an EntityVisible call. Defaults to True.

Description:

Sets the pick mode for an entity.

The optional obscurer parameter is used with EntityVisible to determine just what can get in the way of the line-of-sight between 2 entities. This allows some entities to be pickable using the other pick commands, but to be ignored (i.e. 'transparent') when using EntityVisible. So, its very much EntityVisible specific.

Please note that only Sphere and Box picking will work with Blitz3D sprites. For polygon picking, you will need a valid mesh.

See also: EntityPick, LinePick, CameraPick, EntityPickMode.

entity - name of entity that will have pitch angle returned

global (optional) - true if the pitch angle returned should be relative to 0 rather than a parent entity's pitch angle. False by default.

Description:

Returns the pitch angle of an entity.

The pitch angle is also the x angle of an entity.

entity - entity handle

x_radius# - x radius of entity's collision ellipsoid

y_radius# (optional) - y radius of entity's collision ellipsoid. If omitted the x_radius# will be used for the y_radius#.

Description:

Sets the radius of an entity's collision ellipsoid.

An entity radius should be set for all entities involved in ellipsoidal collisions, which is all source entities (as collisions are always ellipsoid-to-something), and whatever destination entities are involved in ellipsoid-to-ellipsoid collisions (collision method No.1).

See also: EntityBox, Collisions, EntityType.

entity - name of entity that will have roll angle returned

global (optional) - true if the roll angle returned should be relative to 0 rather than a parent entity's roll angle. False by default.

Description:

Returns the roll angle of an entity.

The roll angle is also the z angle of an entity.

Entity - entity handle

Shininess# - shininess of entity

Description:

Sets the specular shininess of an entity.

The shininess# value should be a floting point number in the range 0-1. The default shininess setting is 0.

Shininess is how much brighter certain areas of an object will appear to be when a light is shone directly at them.

Setting a shininess value of 1 for a medium to high poly sphere, combined with the creation of a light shining in the direction of it, will give it the appearance of a shiny snooker ball.

entity - entity handle

texture - texture handle

frame (optional) - frame of texture. Defaults to 0.

index (optional) - index number of texture. Should be in the range to 0-7. Defaults to 0.

Description:

Applies a texture to an entity.

The optional frame parameter specifies which texture animation frame should be used as the texture.

The optional index parameter specifies which index number should be assigned to the texture. Index numbers are used for the purpose of multitexturing. See TextureBlend.

A little note about multitexturing and slowdown. Graphics cards support a maximum amount of textures per object, which can be used with very little, if any, slowdown. For most cards this is two, but for a GeForce3 it is four. However, once you use more than this amount, Blitz will emulate the effect itself by duplicating objects and textures. Obviously, this may then cause slowdown.

entity - entity handle

collision_type - collision type of entity. Must be in the range 0-999.

recursive (optional) - true to apply collision type to entity's children. Defaults to false.

Description:

Sets the collision type for an entity.

A collision_type value of 0 indicates that no collision checking will occur with that entity. A collision value of 1-999 will mean collision checking will occur.

See also: Collisions, GetEntityType, EntityBox, EntityRadius.

src_entity - source entity handle

dest_entity - destination entity handle

Description:

Returns true if src_entity and dest_entity can 'see' each other.

entity = handle of Loaded or Created Entity

global = True for Global coordinates, False for Local. Optional, defaults to False.

Description:

The X-coordinate of the entity. If the global flag is set to False then the parent's local coordinate system is used.

NOTE: If the entity has no parent then local and global coordinates are the same. In this case you can think of the 3d world as the parent.

Global coordinates refer to the 3d world. Blitz 3D uses a left-handed system:

X+ is to the right Y+ is up Z+ is forward ( into the screen )

Every entity also has its own Local coordinate system.

The global system never changes. But the local system is carried along as an entity moves and turns.

This same concept is used in the entity movement commands:

MoveEntity entity, 0,0,1

No matter what the orientation this moves one unit forward.

entity = handle of Loaded or Created Entity

global = True for Global coordinates, False for Local. Optional, defaults to False.

Description:

The Y-coordinate of the entity. If the global flag is set to False then the parent's local coordinate system is used.

See EntityX() for an overview of Local and Global coordinates.

entity - name of entity that will have yaw angle returned

global (optional) - true if the yaw angle returned should be relative to 0 rather than a parent entity's yaw angle. False by default.

Description:

Returns the yaw angle of an entity.

The yaw angle is also the y angle of an entity.

entity = handle of Loaded or Created Entity

global = True for Global coordinates, False for Local. Optional, defaults to False.

Description:

The Z-coordinate of the entity. If the global flag is set to False then the parent's local coordinate system is used.

See EntityX() for an overview of Local and Global coordinates.

entity - entity handle

first_frame - first frame of anim sequence to extract

last_frame - last frame of anim sequence to extract

anim_seq (optional) - anim sequence to extract from. This is usually 0, and as such defaults to 0.

Description:

This command allows you to convert an animation with an MD2-style series of anim sequences into a pure Blitz anim sequence, and play it back as such using Animate.

entity - entity handle

child_name$ - child name to find within entity

Description:

Returns the first child of the specified entity with name matching child_name$.

mesh - mesh handle

brush - brush handle

Description:

Attempts to find a surface attached to the specified mesh and created with the specified brush. Returns the surface handle if found or 0 if not.

See also: CountSurfaces, GetSurface.

mesh - mesh handle

x# - x position of mesh

y# - y position of mesh

z# - z position of mesh

width# - width of mesh

height# - height of mesh

depth# - depth of mesh

uniform (optional) - if true, the mesh will be scaled by the same amounts in x, y and z, so will not be distorted. Defaults to false.

Description:

Scales and translates all vertices of a mesh so that the mesh occupies the specified box.

Do not use a width#, height# or depth# value of 0, otherwise all mesh data will be destroyed and your mesh will not be displayed. Use a value of 0.001 instead for a flat mesh along one axis.

See also: ScaleMesh, ScaleEntity.

mesh - mesh handle

Description:

Flips all the triangles in a mesh.

This is useful for a couple of reasons. Firstly though, it is important to understand a little bit of the theory behind 3D graphics. A 3D triangle is represented by three points; only when these points are presented to the viewer in a clockwise-fashion is the triangle visible. So really, triangles only have one side.

Normally, for example in the case of a sphere, a model's triangles face the inside of the model, so it doesn't matter that you can't see them. However, what about if you wanted to use the sphere as a huge sky for your world, i.e. so you only needed to see the inside? In this case you would just use FlipMesh.

Another use for FlipMesh is to make objects two-sided, so you can see them from the inside and outside if you can't already. In this case, you can copy the original mesh using CopyEntity, specifying the original mesh as the parent, and flip it using FlipMesh. You will now have two meshes occupying the same space - this will make it double-sided, but beware, it will also double the polygon count!

The above technique is worth trying when an external modelling program has exported a model in such a way that some of the triangles appear to be missing.

brush - brush handle

Description:

Frees up a brush.

EntityHandle - Handle returned by an Entity creating function such as CreateCube(), CreateLight(), LoadMesh() etc.

Description:

FreeEntity will free up the internal resources associated with a particular entity and remove it from the scene.

This command will also free all children entities parented to the entity.

Note that the variable holding the handle (and any variables referencing children handles) are not reset as it is up to the Blitz programmer to zero or ignore their contents following a call to FreeEntity().

texture - texture handle

Description:

Frees up a texture from memory.

Freeing a texture means you will not be able to use it again; however, entities already textured with it will not lose the texture.

brush - brush handle

index (optional) - index of texture applied to brush, from 0-7. Defaults to 0.

Description:

Returns the texture that is applied to the specified brush.

The optional index parameter allows you to specify which particular texture you'd like returning, if there are more than one textures applied to a brush.

You should release the texture returned by GetBrushTexture after use to prevent leaks! Use FreeTexture to do this.

To find out the name of the texture, use TextureName

See also: TextureName, FreeTexture, GetEntityBrush, GetSurfaceBrush.

entity - entity handle

index - index of child entity. Should be in the range 1...CountChildren( entity ) inclusive.

Description:

Returns a child of an entity.

entity - entity handle

Description:

Returns a brush with the same properties as is applied to the specified entity.

If this command does not appear to be returning a valid brush, try using GetSurfaceBrush instead with the first surface available.

Remember, GetEntityBrush actually creates a new brush so don't forget to free it afterwards using FreeBrush to prevent memory leaks.

Once you have got the brush handle from an entity, you can use GetBrushTexture and TextureName to get the details of what texture(s) are applied to the brush.

See also: GetSurfaceBrush, FreeBrush, GetBrushTexture, TextureName.

entity - entity handle

Description:

Returns the collision type of an entity as set by the EntityType command.

See also: EntityType, EntityBox, EntityRadius, Collisions, ResetEntity.

entity - entity handle

row - matrix row index

column - matrix column index

Description:

Returns the value of an element from within an entity's transformation matrix.

The transformation matrix is what is used by Blitz internally to position, scale and rotate entities.

GetMatElement is intended for use by advanced users only.

entity - entity handle

Description:

Returns an entity's parent.

mesh - mesh handle

index - index of surface

Description:

Returns the handle of the surface attached to the specified mesh and with the specified index number.

Index should be in the range 1...CountSurfaces( mesh ), inclusive.

You need to 'get a surface', i.e. get its handle, in order to be able to then use that particular surface with other commands.

See also: CountSurfaces, FindSurface.

surface - surface handle

Description:

Returns a brush with the same properties as is applied to the specified mesh surface.

If this command does not appear to be returning a valid brush, try using GetEntityBrush instead.

Remember, GetSurfaceBrush actually creates a new brush so don't forget to free it afterwards using FreeBrush to prevent memory leaks.

Once you have got the brush handle from a surface, you can use GetBrushTexture and TextureName to get the details of what texture(s) are applied to the brush.

See also: GetEntityBrush, FreeBrush, GetSurface, GetBrushTexture, TextureName.

sprite - sprite handle. Not to be confused with HandleSprite - ie. the handle used to position the sprite, rather than the sprite's actual handle

Description:

Sets a sprite handle. Defaults to 0,0.

A sprite extends from -1,-1 to +1,+1.

See also: LoadSprite, CreateSprite.

entity - entity handle

Description:

Hides an entity, so that it is no longer visible, and is no longer involved in collisions.

The main purpose of hide entity is to allow you to create entities at the beginning of a program, hide them, then copy them and show as necessary in the main game. This is more efficient than creating entities mid-game.

If you wish to hide an entity so that it is no longer visible but still involved in collisions, then use EntityAlpha 0 instead. This will make an entity completely transparent.

HideEntity affects the specified entity and all of its child entities, if any exist.

light - light handle

red# - red value of light

green# - green value of light

blue# - blue value of light

Description:

Sets the color of a light.

An r,g,b value of 255,255,255 will brighten anything the light shines on.

An r,g,b value of 0,0,0 will have no affect on anything it shines on.

An r,g,b value of -255,-255,-255 will darken anything it shines on. This is known as 'negative lighting', and is useful for shadow effects.

See also: CreateLight, LightRange, LightConeAngles.

light - light handle

inner_angle# - inner angle of cone

outer_angle# - outer angle of cone

Description:

Sets the 'cone' angle for a 'spot' light.

The default light cone angles setting is 0,90.

See also: CreateLight, LightRange, LightColor.

light - light handle

range# - range of light (default: 1000.0)

Description:

Sets the range of a light.

The range of a light is how far it reaches. Everything outside the range of the light will not be affected by it.

The value is very approximate, and should be experimented with for best results.

See also: CreateLight, LightColor, LightConeAngles.

x# - x coordinate of start of line pick

y# - y coordinate of start of line pick

z# - z coordinate of start of line pick

dx# - distance x of line pick

dy# - distance y of line pick

dz# - distance z of line pick

radius (optional) - radius of line pick

Description:

Returns the first entity between x,y,z to x+dx,y+dy,z+dz.

See also: EntityPick, LinePick, CameraPick, EntityPickMode.

entity - entity handle

filename$ - filename of animated 3D object

Description:

Appends an animation sequence from a file to an entity.

Returns the animation sequence number added.

texture_file$ - filename of texture

flags - brush flags

flags (optional) - flags can be added to combine effects:

1: Color

2: Alpha

4: Masked

8: Mipmapped

16: Clamp U

32: Clamp V

64: Spherical reflection map

u_scale - brush u_scale

v_scale - brush v_scale

Description:

Creates a brush, loads and assigns a texture to it, and returns a brush handle.

text_file$ - filename of image file to be used as sprite

tex_flag (optional) - texture flag:

1: Color

2: Alpha

4: Masked

8: Mipmapped

16: Clamp U

32: Clamp V

64: Spherical reflection map

parent - parent of entity

Description:

Creates a sprite entity, and assigns a texture to it.

See also: LoadSprite, RotateSprite, ScaleSprite, HandleSprite, SpriteViewMode, PositionEntity, MoveEntity, TranslateEntity, EntityAlpha, FreeEntity.

file$ - filename of image file to be used as height map

parent (optional) - parent entity of terrain

Description:

Loads a terrain from an image file and returns the terrain's handle.

The image's red channel is used to determine heights. Terrain is initially the same width and depth as the image, and 1 unit high.

Tips on generating nice terrain:

* Smooth or blur the height map * Reduce the y scale of the terrain * Increase the x/z scale of the terrain * Reduce the camera range

When texturing an entity, a texture with a scale of 1,1,1 (default) will be the same size as one of the terrain's grid squares. A texture that is scaled to the same size as the size of the bitmap used to load it or the no. of grid square used to create it, will be the same size as the terrain.

The optional parent parameter allows you to specify a parent entity for the terrain so that when the parent is moved the child terrain will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent.

Specifying a parent entity will still result in the terrain being created at position 0,0,0 rather than at the parent entity's position.

A heightmaps dimensions (width and height) must be the same and must be a power of 2, e.g. 32, 64, 128, 256, 512, 1024.

See also: CreateTerrain.

mesh - mesh handle

Description:

Returns the depth of a mesh. This is calculated by the actual vertex positions and so the scale of the entity (set by ScaleEntity) will not have an effect on the resultant depth. Mesh operations, on the other hand, will effect the result.

See also: MeshWidth, MeshHeight.

mesh_a - mesh_a handle

mesh_b - mesh_b handle

Description:

Returns true if the specified meshes are currently intersecting.

This is a fairly slow routine - use with discretion...

This command is currently the only polygon->polygon collision checking routine available in Blitz3D.

mesh - mesh handle

Description:

Returns the height of a mesh. This is calculated by the actual vertex positions and so the scale of the entity (set by ScaleEntity) will not have an effect on the resultant height. Mesh operations, on the other hand, will effect the result.

See also: MeshWidth, MeshDepth.

mesh - mesh handle

Description:

Returns the width of a mesh. This is calculated by the actual vertex positions and so the scale of the entity (set by ScaleEntity) will not have an effect on the resultant width. Mesh operations, on the other hand, will effect the result.

See also: MeshHeight, MeshDepth.

terrain - terrain handle

grid_x - grid x coordinate of terrain

grid_y - grid y coordinate of terrain

height# - height of point on terrain. Should be in the range 0-1.

realtime (optional) - True to modify terrain immediately. False to modify terrain when RenderWorld in next called. Defaults to False.

Description:

Sets the height of a point on a terrain.

entity - name of entity to be moved

x# - x amount that entity will be moved by

y# - y amount that entity will be moved by

z# - z amount that entity will be moved by

Description:

Moves an entity relative to its current position and orientation.

What this means is that an entity will move in whatever direction it is facing. So for example if you have an game character is upright when first loaded into Blitz3D and it remains upright (i.e. turns left or right only), then moving it by a z amount will always see it move forward or backward, moving it by a y amount will always see it move up or down, and moving it by an x amount will always see it strafe.

See also: TranslateEntity, PositionEntity, PositionMesh.

entity - entity handle

name$ - name of entity

Description:

Sets an entity's name.

See also: EntityName.

entity - entity handle

brush - brush handle

Description:

Paints a entity with a brush.

The reason for using PaintEntity to apply specific properties to a entity using a brush rather than just using EntityTexture, EntityColor, EntityShininess etc, is that you can pre-define one brush, and then paint entities over and over again using just the one command rather than lots of separate ones.

mesh - mesh handle

brush - brush handle

Description:

Paints a mesh with a brush.

This has the effect of instantly altering the visible appearance of the mesh, assuming the brush's properties are different to what was was applied to the surface before.

The reason for using PaintMesh to apply specific properties to a mesh using a brush rather than just using EntityTexture, EntityColor, EntityShininess etc, is that you can pre-define one brush, and then paint meshes over and over again using just the one command rather than lots of separate ones.

See also: PaintEntity, PaintSurface.

surface - surface handle

brush - brush handle

Description:

Paints a surface with a brush.

This has the effect of instantly altering the visible appearance of that particular surface, i.e. section of mesh, assuming the brush's properties are different to what was applied to the surface before.

See also: PaintEntity, PaintMesh.

None.

Description:

Returns the entity 'picked' by the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

Returns 0 if no entity was picked.

None.

Description:

Returns the x component of the normal of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the y component of the normal of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the z component of the normal of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the handle of the surface that was 'picked' by the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the time taken to calculate the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the index number of the triangle that was 'picked' by the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

None.

Description:

Returns the world x coordinate of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

The coordinate represents the exact point of where something was picked.

See also: PickedY, PickedZ.

None.

Description:

Returns the world y coordinate of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

The coordinate represents the exact point of where something was picked.

See also: PickedX, PickedZ.

None.

Description:

Returns the world z coordinate of the most recently executed Pick command. This might have been CameraPick, EntityPick or LinePick.

The coordinate represents the exact point of where something was picked.

See also: PickedX, PickedY.

entity - entity handle

target - target entity handle

roll# (optional) - roll angle of entity

Description:

Points one entity at another.

The optional roll parameter allows you to specify a roll angle as pointing an entity only sets pitch and yaw angles.

If you wish for an entity to point at a certain position rather than another entity, simply create a pivot entity at your desired position, point the entity at this and then free the pivot.

entity - name of entity to be positioned

x# - x co-ordinate that entity will be positioned at

y# - y co-ordinate that entity will be positioned at

z# - z co-ordinate that entity will be positioned at

global (optional) - true if the position should be relative to 0,0,0 rather than a parent entity's position. False by default.

Description:

Positions an entity at an absolute position in 3D space.

Entities are positioned using an x,y,z coordinate system. x, y and z each have their own axis, and each axis has its own set of values. By specifying a value for each axis, you can position an entity anywhere in 3D space. 0,0,0 is the centre of 3D space, and if the camera is pointing in the default positive z direction, then positioning an entity with a z value of above 0 will make it appear in front of the camera, whereas a negative z value would see it disappear behind the camera. Changing the x value would see it moving sideways, and changing the y value would see it moving up/down.

Of course, the direction in which entities appear to move is relative to the position and orientation of the camera.

See also: MoveEntity, TranslateEntity, PositionMesh.

mesh - mesh handle

x# - x position of mesh

y# - y position of mesh

z# - z position of mesh

Description:

Moves all vertices of a mesh.

See also: PositionEntity, MoveEntity, TranslateEntity.

texture - texture handle

u_position# - u position of texture

v_position# - v position of texture

Description:

Positions a texture at an absolute position.

This will have an immediate effect on all instances of the texture being used.

Positioning a texture is useful for performing scrolling texture effects, such as for water etc.

None.

Description:

Returns the viewport x coordinate of the most recently executed CameraProject.

None.

Description:

Returns the viewport y coordinate of the most recently executed CameraProject.

None.

Description:

Returns the viewport z coordinate of the most recently executed CameraProject.

tween# (optional) - defaults to 1.

Description:

Renders the current scene to the BackBuffer onto the rectangle defined by each cameras CameraViewport( ). Every camera not hidden by HideEntity( ) or with a CameraProjMode( ) of 0 is rendered. Rendering to other buffers is currently not supported by Blitz3D.

The optional tween parameter should only be specified when RenderWorld is used in conjunction with CaptureWorld. CaptureWorld is used to store the 'old' position, rotation and scale, alpha and colour of each entity in the game world, and a tween value of

The use of tweening allows you to render more than one frame per game logic update, while still keeping the display smooth. This allows you to cut down on the CPU time that would be required to update your game logic every render. Note, however, that the bottleneck in almost all 3D applications is the graphics card and the CPU time involved in updating game logic is often very little. A good alternative to render tweening is the use of a delta time, that is, moving your entities each frame depending on the time it took for the program to process and render that frame.

Render tweening is quite an advanced technique, and it is not necessary to use it, so don't worry if you don't quite understand it. See the castle demo included in the mak (nickname of Mark Sibly, author of Blitz3D) directory of the Blitz3D samples section for a demonstration of render tweening.

See also: CaptureWorld, CameraViewport, CameraProjMode.

entity - entity handle

Description:

Resets the collision state of an entity.

See also: EntityBox, EntityRadius, Collisions, EntityType, GetEntityType.

entity - name of the entity to be rotated

pitch# - angle in degrees of pitch rotation

yaw# - angle in degrees of yaw rotation

roll# - angle in degrees of roll rotation

global (optional) - true if the angle rotated should be relative to 0,0,0 rather than a parent entity's orientation. False by default.

Description:

Rotates an entity so that it is at an absolute orientation.

Pitch is the same as the x angle of an entity, and is equivalent to tilting forward/backwards.

Yaw is the same as the y angle of an entity, and is equivalent to turning left/right.

Roll is the same as the z angle of an entity, and is equivalent to tilting left/right.

See also: TurnEntity, RotateMesh.

mesh - mesh handle

pitch# - pitch of mesh

yaw# - yaw of mesh

roll# - roll of mesh

Description:

Rotates all vertices of a mesh by the specified rotation.

See also: RotateEntity, TurnEntity.

sprite - sprite handle

angle# - absolute angle of sprite rotation

Description:

Rotates a sprite.

See also: CreateSprite, LoadSprite.

texture - texture handle

angle# - absolute angle of texture rotation

Description:

Rotates a texture.

This will have an immediate effect on all instances of the texture being used.

Rotating a texture is useful for performing swirling texture effects, such as for smoke etc.

entity - name of the entity to be scaled

x_scale# - x size of entity

y_scale# - y size of entity

z_scale# - z size of entity

global (optional) -

Description:

Scales an entity so that it is of an absolute size.

Scale values of 1,1,1 are the default size when creating/loading entities.

Scale values of 2,2,2 will double the size of an entity.

Scale values of 0,0,0 will make an entity disappear.

Scale values of less than 0,0,0 will invert an entity and make it bigger.

See also: ScaleMesh, FitMesh.

mesh - mesh handle

x_scale# - x scale of mesh

y_scale# - y scale of mesh

z_scale# - z scale of mesh

Description:

Scales all vertices of a mesh by the specified scaling factors.

See also: FitMesh, ScaleEntity.

sprite - sprite handle

x_scale# - x scale of sprite

y scale# - y scale of sprite

Description:

Scales a sprite.

See also: LoadSprite, CreateSprite.

texture - name of texture

u_scale# - u scale

v_scale# - v scale

Description:

Scales a texture by an absolute amount.

This will have an immediate effect on all instances of the texture being used.

entity - entity handle

frame - frame of animation to be used as anim key

pos_key (optional) - true to include entity position information when setting key. Defaults to true.

rot_key (optional) - true to include entity rotation information when setting key. Defaults to true.

scale_key (optional) - true to include entity scale information when setting key. Defaults to true.

Description:

Sets an animation key for the specified entity at the specified frame. The entity must have a valid animation sequence to work with.

This is most useful when you've got a character, or a complete set of complicated moves to perform, and you want to perform them en-masse.

entity - a valid entity handle.

time# - a floating point time value.

anim_seq - an optional animation sequence number.

Description:

SetAnimTime allows you to manually animate entities.

texture - texture

face - face of cube to select. This should be one of the following values:

0: left (negative X) face

1: forward (positive Z) face - this is the default.

2: right (positive X) face

3: backward (negative Z) face

4: up (positive Y) face

5: down (negative Y) face

Description:

Selects a cube face for direct rendering to a texture.

This command should only be used when you wish to draw directly to a cubemap texture in real-time. Otherwise, just loading a pre-rendered cubemap with a flag of 128 will suffice.

To understand how this command works exactly it is important to recognise that Blitz treats cubemap textures slightly differently to how it treats other textures. Here's how it works...

A cubemap texture in Blitz actually consists of six images, each of which must be square 'power' of two size - e.g. 32, 64, 128 etc. Each corresponds to a particular cube face. These images are stored internally by Blitz, and the texture handle that is returned by LoadTexture/CreateTexture when specifying the cubemap flag, only provides access to one of these six images at once (by default the first one, or '0' face).

This is why, when loading a cubemap texture into Blitz using LoadTexture, all the six cubemap images must be laid out in a specific order (0-5, as described above), in a horizontal strip. Then Blitz takes this texture and internally converts it into six separate images.

So seeing as the texture handle returned by CreateTexture / LoadTexture only provides access to one of these images at once (no. 1 by default), how do we get access to the other five images? This is where SetCubeFace comes in. It will tell Blitz that whenever you next draw to a cubemap texture, to draw to the particular image representing the face you have specified with the face parameter.

Now you have the ability to draw to a cubemap in real-time.

To give you some idea of how this works in code, here's a function that updates a cubemap in real-time. It works by rendering six different views and copying them to the cubemap texture buffer, using SetCubeFace to specify which particular cubemap image should be drawn to.

; Start of code

Function UpdateCubeMap( tex,camera )

tex_sz=TextureWidth(tex)

; do left view SetCubeFace tex,0 RotateEntity camera,0,90,0 RenderWorld

; copy contents of backbuffer to cubemap CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

; do forward view SetCubeFace tex,1 RotateEntity camera,0,0,0 RenderWorld CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

; do right view SetCubeFace tex,2 RotateEntity camera,0,-90,0 RenderWorld CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

; do backward view SetCubeFace tex,3 RotateEntity camera,0,180,0 RenderWorld CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

; do up view SetCubeFace tex,4 RotateEntity camera,-90,0,0 RenderWorld CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

; do down view SetCubeFace tex,5 RotateEntity camera,90,0,0 RenderWorld CopyRect 0,0,tex_sz,tex_sz,0,0,BackBuffer(),TextureBuffer(tex)

EndFunction

; End of code

All rendering to a texture buffer affects the currently selected face. Do not change the selected cube face while a buffer is locked.

Finally, you may wish to combine the vram 256 flag with the cubic mapping flag when drawing to cubemap textures for faster access.

See also: CreateTexture, LoadTexture, SetCubeMode.

texture - a valid texture handle

mode - the rendering mode of the cubemap texture:

1: Specular (default)

2: Diffuse

3: Refraction

Description:

Set the rendering mode of a cubemap texture.

The available rendering modes are as follows:

1: Specular (default). Use this to give your cubemapped objects a shiny effect.

2: Diffuse. Use this to give your cubemapped objects a non-shiny, realistic lighting effect.

3: Refraction. Good for 'cloak'-style effects.

See also: CreateTexture, LoadTexture, SetCubeFace.

entity - entity handle

Description:

Shows an entity. Very much the opposite of HideEntity.

Once an entity has been hidden using HideEntity, use show entity to make it visible and involved in collisions again. Note that ShowEntity has no effect if the enitities parent object is hidden.

Entities are shown by default after creating/loading them, so you should only need to use ShowEntity after using HideEntity.

ShowEntity affects the specified entity only - child entities are not affected.

sprite - sprite handle

view_mode - view_mode of sprite

1: fixed (sprite always faces camera - default)

2: free (sprite is independent of camera)

3: upright1 (sprite always faces camera, but rolls with camera as well, unlike mode no.1)

4: upright2 (sprite always remains upright. Gives a 'billboard' effect. Good for trees, spectators etc.)

Description:

Sets the view mode of a sprite.

The view mode determines how a sprite alters its orientation in respect to the camera. This allows the sprite to in some instances give the impression that it is more than two dimensional.

In technical terms, the four sprite modes perform the following changes:

1: Sprite changes its pitch and yaw values to face camera, but doesn't roll. 2: Sprite does not change either its pitch, yaw or roll values. 3: Sprite changes its yaw and pitch to face camera, and changes its roll value to match cameras. 4: Sprite changes its yaw value to face camera, but not its pitch value, and changes its roll value to match cameras.

Note that if you use sprite view mode 2, then because it is independent from the camera, you will only be able to see it from one side unless you use EntityFx flag 16 with it to disable backface culling.

See also: CreateSprite, LoadSprite.

terrain - terrain handle

grid_x - grid x coordinate of terrain

grid_z - grid z coordinate of terrain

Description:

Returns the height of the terrain at terrain grid coordinates x,z. The value returned is in the range 0 to 1.

See also: TerrainY.

terrain - terrain handle

x# - world x coordinate

y# - world y coordinate

z# - world z coordinate

Description:

Returns the interpolated x coordinate on a terrain.

See also: TerrainY, TerrainZ.

terrain - terrain handle

x# - world x coordinate

y# - world y coordinate

z# - world z coordinate

Description:

Returns the interpolated y coordinate on a terrain.

Gets the ground's height, basically.

See also: TerrainX, TerrainZ, TerrainHeight.

terrain - terrain handle

x# - world x coordinate

y# - world y coordinate

z# - world z coordinate

Description:

Returns the interpolated z coordinate on a terrain.

See also: TerrainX, TerrainY.

Texture - Texture handle.

Blend - Blend mode of texture.

0: Do not blend

1: No blend, or Alpha (alpha when texture loaded with alpha flag - not recommended for multitexturing - see below)

2: Multiply (default)

3: Add

4: Dot3

5: Multiply 2

Description:

Sets the blending mode for a texture.

The texture blend mode determines how the texture will blend with the texture or polygon which is 'below' it. Texture 0 will blend with the polygons of the entity it is applied to. Texture 1 will blend with texture 0. Texture 2 will blend with texture 1. And so on.

Texture blending in Blitz effectively takes the highest order texture (the one with the highest index) and it blends with the texture below it, then that result to the texture directly below again, and so on until texture 0 which is blended with the polygons of the entity it is applied to and thus the world, depending on the EntityBlend of the object.

Each of the blend modes are identical to their EntityBlend counterparts.

In the case of multitexturing (more than one texture applied to an entity), it is not recommended you blend textures that have been loaded with the alpha flag, as this can cause unpredictable results on a variety of different graphics cards.

Use EntityTexture to set the index number of a texture.

See also: EntityBlend, EntityTexture.

texture - name of texture

coords -

0: UV coordinates are from first UV set in vertices (default)

1: UV coordinates are from second UV set in vertices

Description:

Sets the texture coordinate mode for a texture.

This determines where the UV values used to look up a texture come from.

match_text$ - text that, if found in texture filename, will activate certain filters

flags - filter texture flags:

1: Color

2: Alpha

4: Masked

8: Mipmapped

16: Clamp U

32: Clamp V

64: Spherical reflection map

128:

256: Store texture in vram

512: Force the use of high color textures

Description:

Adds a texture filter. Any textures loaded that contain the text specified by match_text$ will have the provided flags added.

This is mostly of use when loading a mesh.

By default, the following texture filter is used:

TextureFilter "",1+8

This means that all loaded textures will have color and be mipmapped by default.

texture - texture handle

Description:

Returns the height of a texture.

texture - a valid texture handle

Description:

Returns a texture's absolute filename.

To find out just the name of the texture, you will need to parse the string returned by TextureName. One such function to do this is:

; start of code Function StripPath$(file$)

If Len(file$)>0

For i=Len(file$) To 1 Step -1

mi$=Mid$(file$,i,1) If mi$="\" Or mi$="/" Then Return name$ Else name$=mi$+name$

Next

EndIf

Return name$

End Function ; end of code

See also: GetBrushTexture.

texture - texture handle

Description:

Returns the width of a texture.

None.

Description:

Returns the X component of the last TFormPoint, TFormVector or TFormNormal operation.

See those commands for examples.

None.

Description:

Returns the Y component of the last TFormPoint, TFormVector or TFormNormal operation.

See those commands for examples.

None.

Description:

Returns the Z component of the last TFormPoint, TFormVector or TFormNormal operation.

See those commands for examples.

x#, y#, z# = components of a vector in 3d space

source_entity = handle of source entity, or 0 for 3d world

dest_entity = handle of destination entity, or 0 for 3d world

Description:

Transforms between coordinate systems. After using TFormNormal the new components can be read with TFormedX(), TFormedY() and TFormedZ().

This is exactly the same as TFormVector but with one added feature. After the transformation the new vector is 'normalized', meaning it is scaled to have length 1.

For example, suppose the result of TFormVector is (1,2,2). This vector has length Sqr( 1*1 + 2*2 + 2*2 ) = Sqr( 9 ) = 3.

This means TFormNormal would produce ( 1/3, 2/3, 2/3 ).

x#, y#, z# = coordinates of a point in 3d space

source_entity = handle of source entity, or 0 for 3d world

dest_entity = handle of destination entity, or 0 for 3d world

Description:

Transforms between coordinate systems. After using TFormPoint the new coordinates can be read with TFormedX(), TFormedY() and TFormedZ().

See EntityX() for details about local coordinates.

Consider a sphere built with CreateSphere(). The 'north pole' is at (0,1,0). At first, local and global coordinates are the same. As the sphere is moved, turned and scaled the global coordinates of the point change.

But it is always at (0,1,0) in the sphere's local space.

x#, y#, z# = components of a vector in 3d space

source_entity = handle of source entity, or 0 for 3d world

dest_entity = handle of destination entity, or 0 for 3d world

Description:

Transforms between coordinate systems. After using TFormVector the new components can be read with TFormedX(), TFormedY() and TFormedZ().

See EntityX() for details about local coordinates.

Similar to TFormPoint, but operates on a vector. A vector can be thought of as 'displacement relative to current location'.

For example, vector (1,2,3) means one step to the right, two steps up and three steps forward.

This is analogous to PositionEntity and MoveEntity:

PositionEntity entity, x,y,z ; put entity at point (x,y,z)

MoveEntity entity, x,y,z ; add vector (x,y,z) to current position.

entity - name of entity to be translated

x# - x amount that entity will be translated by

y# - y amount that entity will be translated by

z# - z amount that entity will be translated by

global (optional) -

Description:

Translates an entity relative to its current position and not its orientation.

What this means is that an entity will move in a certain direction despite where it may be facing. Imagine that you have a game character that you want to make jump in the air at the same time as doing a triple somersault. Translating the character by a positive y amount will mean the character will always travel directly up in their air, regardless of where it may be facing due to the somersault action.

See also: MoveEntity, PositionEntity, PositionMesh.

surface - surface handle

triangle_index - triangle index

corner - corner of triangle. Should be 0, 1 or 2.

Description:

Returns the vertex of a triangle corner.

entity - name of entity to be rotated

pitch# - angle in degrees that entity will be pitched

yaw# - angle in degrees that entity will be yawed

roll# - angle in degrees that entity will be rolled

global (optional) -

Description:

Turns an entity relative to its current orientation.

Pitch is the same as the x angle of an entity, and is equivalent to tilting forward/backwards.

Yaw is the same as the y angle of an entity, and is equivalent to turning left/right.

Roll is the same as the z angle of an entity, and is equivalent to tilting left/right.

See also: RotateEntity, RotateMesh.

mesh - mesh handle

Description:

Recalculates all normals in a mesh. This is necessary for correct lighting if you have not set surface normals using 'VertexNormals' commands.

anim_speed# (optional) - a master control for animation speed. Defaults to 1.

Description:

Animates all entities in the world, and performs collision checking.

The optional anim_speed# parameter allows you affect the animation speed of all entities at once. A value of 1 will animate entities at their usual animation speed, a value of 2 will animate entities at double their animation speed, and so on.

For best results use this command once per main loop, just before calling RenderWorld.

x# - x vector length

y# - y vector length

z# - z vector length

Description:

Returns the pitch value of a vector.

Using this command will return the same result as using EntityPitch to get the pitch value of an entity that is pointing in the vector's direction.

See also: VectorYaw, EntityPitch.

x# - x vector length

y# - y vector length

z# - z vector length

Description:

Returns the yaw value of a vector.

Using this command will return the same result as using EntityYaw to get the yaw value of an entity that is pointing in the vector's direction.

See also: VectorPitch, EntityYaw.

surface - surface handle

index - index of vertex

Description:

Returns the alpha component of a vertices color, set using VertexColor

See also: VertexRed, VertexGreen, VertexBlue, VertexColor.

surface - surface handle

index - index of vertex

Description:

Returns the blue component of a vertices color.

surface - surface handle

index - index of vertex

red# - red value of vertex

green# - green value of vertex

blue# - blue value of vertex

alpha# - optional alpha transparency of vertex (0.0 to 1.0 - default: 1.0)

Description:

Sets the color of an existing vertex.

NB. If you want to set the alpha individually for vertices using the alpha# parameter then you need to use EntityFX 32 (to force alpha-blending) on the entity.

See also: EntityFX.

surface - surface handle

index - index of vertex

x# - x position of vertex

y# - y position of vertex

z# - z position of vertex

Description:

Sets the geometric coordinates of an existing vertex.

This is the command used to perform what is commonly referred to as 'dynamic mesh deformation'. It will reposition a vertex so that all the triangle edges connected to it, will move also. This will give the effect of parts of the mesh suddenly deforming.

surface - surface handle

index - index of vertex

Description:

Returns the green component of a vertices color.

surface - surface handle

index - index of vertex

nx# - normal x of vertex

ny# - normal y of vertex

nz# - normal z of vertex

Description:

Sets the normal of an existing vertex.

surface - surface handle

index - index of vertex

Description:

Returns the x component of a vertices normal.

surface - surface handle

index - index of vertex

Description:

Returns the y component of a vertices normal.

surface - surface handle

index - index of vertex

Description:

Returns the z component of a vertices normal.

surface - surface handle

index - index of vertex

Description:

Returns the red component of a vertices color.

surface - surface handle

index - index of vertex

u# - u# coordinate of vertex

v# - v# coordinate of vertex

w# (optional) - w# coordinate of vertex

coord_set (optional) - co_oord set. Should be set to 0 or 1.

Description:

Sets the texture coordinates of an existing vertex.

surface - surface handle

index - index of vertex

coord_set (optional) - UV mapping coordinate set. Should be set to 0 or 1.

Description:

Returns the texture u coordinate of a vertex.

See also: VertexV,

surface - surface handle

index - index of vertex

coord_set (optional) - UV mapping coordinate set. Should be set to 0 or 1.

Description:

Returns the texture v coordinate of a vertex.

See also: VertexU,

surface - surface handle

index - index of vertex

Description:

Returns the texture w coordinate of a vertex.

surface - surface handle

index - index of vertex

Description:

Returns the x coordinate of a vertex.

surface - surface handle

index - index of vertex

Description:

Returns the y coordinate of a vertex.

surface - surface handle

index - index of vertex

Description:

Returns the z coordinate of a vertex.

enable - True to enable wireframe rendering, False to disable.

The default Wireframe mode is False.

Description:

Enables or disables wireframe rendering.

This will show the outline of each polygon on the screen, with no shaded-in areas.

Wireframe mode should only be used for debugging purposes, as driver support is patchy. For the same reason, no support is offered for the wireframe rendering of individual polygon entities.