Ultimate 3D 2.1 Game Maker extension package

The extension package for Ultimate 3D, which can be obtained from Ultimate3D.org, offers all the functionality that is needed to use Ultimate 3D with Game Maker 7.0. To be more precise it contains the Ultimate3D.dll, all functions that are explained within this help file and two action libraries. Its use can ease the work with Ultimate 3D and makes it more comfortable.

Warning: The extension package is very new and therefore it hasn't gone through a long beta testing phase as the normal version of Ultimate 3D has. Although I have tested all components of the package carefully it is probably safer to use the normal version. You should also note that people who do not have the extension installed will not be able to view your project files correctly, if you are using the extension.


Getting started with the extension

There are several things Ultimate 3D always needs, which can not be included into the extension package. For this reason the extension package comes with a BasicGEX.gmk, which contains these things. Obviously the first thing you need to do to be able to use the extension is installing it through Game Maker's extension package manager. Once you've done that the BasicGEX.gmk will be working and it will show you the same things as the BasicGM7.gmk from the SDK. You should base your projects upon this file. If you do not want to do so you will have to copy the control object and the Ultimate3DOptions() script from the BasicGEX.gmk to your project and you'll have to set up the primary room correctly (as explained in Getting started).


The action libraries

The action libraries offer access to the most basic features from the novice section of Ultimate 3D. Do not expect to get very far with them. Using these user-friendly libraries does not compensate a thorough study of this help file. Do not expect to be able to use Ultimate 3D without being able to write code in the GML. The action libraries can save you some work, as they contain actions that are needed very often (like Step() and Destroy()), but they are not meant to make all features of Ultimate 3D accessible and they do not do so.

There are two libraries, the first one called U3D main, the second one called U3D misc. U3D main contains several actions to manage objects, create objects and change the environment. U3D misc. contains actions for modifying and transforming objects, for drawing 2D graphics and several other. What follows is an explanation of every action.


U3D main

Illustration not available Load texture
This action loads a texture from a given file and associates it with an integer texture index. For more information refer to the description of LoadTexture(...).

Illustration not available Step
Ultimate 3D associates Ultimate 3D objects (e.g. a single wall, a single billboard or a single model) with instances of Game Maker objects. These Game Maker objects have several variables that can be used to modify the Ultimate 3D object. This action transmits the data of these variables to Ultimate 3D. It should be placed in the step event of every Game Maker object, which is associated with an Ultimate 3D object, unless it's a camera. This action maps to Step().

Illustration not available Destroy
Destroys the Ultimate 3D object that is associated with this Game Maker object. To reach that Ultimate 3D objects get destroyed when the instances they are associated with get destroyed you should place this in the destroy event of every Game Maker object that is associated with an Ultimate 3D object. This action maps to Destroy().

Illustration not available Associate with primary camera
Sets up some variables and associates this object with the primary camera. To be more precise it sets the variables height and view to the given values, the viewport variables to match the primary view of Game maker, min_range to 1, max_range to 100000 and number to 0 and calls MoveCamera(...) after that.

Illustration not available Camera step
This action is the pendant to step for cameras. It transmits all information, which is saved within variables, from the Game Maker instance to the Ultimate 3D camera object. It should be placed in every step event of a camera object. Maps to MoveCamera().

Illustration not available Create wall
This action creates a wall from the position x, y, z to the position x+x2, y+y2, z+height with the texture with the given index and associates it with this Game Maker instance. It does this by setting up the variables x2, y2, height and texture and calling CreateWall() after that.

Illustration not available Create floor
This action creates a wall from the position x, y, z to the position x+width, y+height, z with the texture with the given index and associates it with this Game Maker instance. It does this by setting up the variables width, height and texture and calling CreateFloor() after that.

Illustration not available Create cube
This action creates a cube from the position x, y, z to the position x+width, y+height, z+depth with the texture with the given index and associates it with this Game Maker instance. It does this by setting up the variables width, height, depth2 and texture and calling CreateCube() after that.

Illustration not available Create billboard
This action creates a billboard with origin x, y, z the given width and height, the given relative billboard origin and the texture with the given index and associates it with this Game Maker instance. It does this by setting up the variables width, height, originx, originy and texture and calling Create2D() after that.

Illustration not available Create model
This action creates a model object from the given *.3ds, *.an8, *.md2, *.ms3d, *.u3d or *.x file and associates it with this instance. It does this by setting up the variable file and calling LoadMesh().

Illustration not available Create light directional
This action creates a directional light source with the given lighting direction and light color and associates it with this instance. It does this by setting up the variables r, g, b, rotx and roty and calling LightDirectional().

Illustration not available Create light point
This action creates a point light source with the given range and light color and associates it with this instance. It does this by setting up the variables r, g, b and range and calling LightPoint().

Illustration not available Create light point
This action creates a spot light source with the given lighting direction, range, lighting angle and light color and associates it with this instance. It does this by setting up the variables r, g, b and range, rotx, roty and deg and calling LightPoint().

Illustration not available Set ambient lighting
This action changes the intensity and color of the ambient lighting. Ambient lighting effects all objects with the same strength, independent from their position. This action maps to SetAmbient(...).

Illustration not available Set fog properties
This action sets up fog with the given color that starts at the given start distance and ends at the given end distance. At the end distance everything will have the fog color. This action maps to SetFog(...).

Illustration not available Disable fog
This action disables fog completely. It maps to DisableFog().

Illustration not available Set solid background color
This action sets up a solid background color and disables the sky sphere/sky cube in case it was used before.

Illustration not available Load sky sphere
This action loads a sky sphere from a given image file and uses it as a background. It maps to LoadBackground(...).


U3D misc.

Illustration not available Create instance 3D
This action extends Game Maker's instance creation action with an additional parameter allowing you to specify the z-position of the object. If relative is checked the coordinates will be interpreted relative to the coordinates of this instance, meaning that they will be added together.

Illustration not available Move through 3D angles
This action moves the object in 3D space using angles. For more information have a look at the description of the function Move(...).

Illustration not available Move through 3D coordinates
This action moves the object in 3D space using the given three coordinates. If relative is not checked the object gets set to the given position, otherwise the given coordinates get added to the current coordinates. This action will not effect the Ultimate 3D object unless the step action is placed in step event.

Illustration not available Rotate using Euler angles
This action rotates the object using the given three Euler angles. If relative is not checked the objects variables rotx, roty and rotz get set to the given values, otherwise the given angles get added to rotx, roty and rotz. This action will not effect the Ultimate 3D object unless the step action is placed in step event.

Illustration not available Scale object
This action scales the object using the given scaling factor. If relative is not checked the objects variables scalx, scaly and scalz get set to the given value, otherwise scalx, scaly and scalz get multiplied by the given values. This action will not effect the Ultimate 3D object unless the step action is placed in step event.

Illustration not available Set animation speed and animation area
This action sets the speed of the animation and defines the beginning frame and the ending frame of the animation cycle. The beginning and ending frame are optional, so you can have a 0 there if you want to play the complete animation. If relative is not checked the variable frame gets set to the negate of the given animation speed, otherwise frame gets subtracted by the animation speed. In both cases the variables first_frame and last_frame get set to the given values. This action will not effect the Ultimate 3D object unless the step action is placed in step event.

Illustration not available Draws a texture to the screen
This action draws the texture with the given index at the given position using the given scaling, rotation and transparency. For more information refer to the description of DrawTex(...).

Illustration not available Load and prepare true type font
This action loads the true type font with the given name and prepares it for efficient text drawing. The resulting font will be associated with the given index and will have the given text size, will be bold or italic if requested and will have the given color. For more information refer to the description of SetFont(...).

Illustration not available Use a prepared true type font to draw text
Uses the font with the given index to draw the given text at the given position. For more information have a look at the description of DrawText(...).

Illustration not available Take screenshot
Takes a screenshot of the Ultimate 3D view port and saves it to the given bitmap file.



© Christoph Peters. Some rights reserved.

Creative Commons License XHTML 1.0 Transitional