Updating Ultimate 3D projects

Whenever a new version of Ultimate 3D gets released some scripts have changed within this version and others may have been added. For this reason you need to change them in your project if you want to update the project to a newer version of Ultimate 3D. This tutorial guides you through this process for every version. Just find the sub-chapter that matches your case and follow the steps. If you need to update from a very outdated version you can also chain the update steps, to get for example from Ultimate 3D 2.0 beta 3 to Ultimate 3D 2.0 final. Since I always do my best to keep the downwards compatibility the process of updating usually does not take more than fifteen minutes.

Updating an Ultimate 3D 2.1 beta project to Ultimate 3D 2.1 final

The update process from Ultimate 3D 2.1 beta to Ultimate 3D 2.1 final is very easy and completely optional. If you do not intend to use the new features you do not have to perform the update process. In this case it is sufficient to replace the old dll with the new one. It is recommended to perform the update though, since it is a very simple process. Just update the Init() script and add SaveTerrainHeightMap(...), CopyVector(...), NormalizeVector(...) and TransformVectorEx(...) and you are done.

Updating an Ultimate 3D 2.0 final project to Ultimate 3D 2.1 beta

Ultimate 3D 2.1 has many smaller new features and a basically new collision detection and collision response system. Therefore quite many scripts need to be added, some need to be modified and some (related to collision detection) need to be deleted. You will probably have to rewrite most of your collision detection and collision response code, but with the new functions this is very easy.

Here is a list of all scripts that need to be added. All these scripts are contained within the NewScripts.gml file, which comes with the SDK of Ultimate 3D 2.1, so you can import this scripts file to add them automatically.

• SwitchBackgroundMode(...)
• GetBoneCount()
• GetBoneParent(...)
• StartPoseInterpolation(...)
• CopyAnimation(...)
• SetModelMaterialSpecular(...)
• SetObjectSolidity(...)
• AttemptMoveToPosition(...)
• CheckSweptEllipsoidIntersection(...)
• GetTriangleIntersectionCount(...)
• GetIntersectionTime(...)
• GetIntersectionPosition(...)
• GetIntersectedTriangleNormal(...)
• GetPushAwayVector(...)
• CheckRayIntersection(...)
• GetIntersectedMaterialIndex(...)
• GetTextureStrengthAtPosition(...)
• DeformTerrain(...)
• CreateTerrainDecal(...)
• SetParticleRotation(...)
• SwitchAdditiveBlending(...)
• SetRoomVisibilityEnforcement(...)
• SetRoomAmbient(...)
• GetMeshOccurrenceCount(...)
• GetMeshOccurrenceTransformation(...)
• InterpolateMatrices(...)
• GetMatrixEntry(...)
• CoordToScreen(...)
• CheckBoundingBoxVisibility(...)
• CalculateVectorDifference(...)
• CalculateVectorLongitude(...)
• CalculateVectorLatitude(...)
• ComputeMatrixTranslation(...)
• ComputeMatrixScaling(...)
• ApplyTransformationMatrix(...)
• GetDrawnTriangleCount()
• GetDrawCallCount()
• SetMipMapFilter(...)

Here is a list of all scripts that need to be replaced by newer versions:

• Step()
• SetAmbient(...)
• LightPoint()
• LightDirectional()
• LightSpot()
• SmoothNormals(...)
• SetModelMaterialEmissive(...)
• CreateTerrain()
• AddTerrainTexture(...)
• CreateParticleSystem()
• ParticleSystemStep(...)
• MoveCamera()
• SwitchWireFrameMode(...)
• Init()
• InitializeLightVariables() (Game Maker 6.0 and higher only)

For some of these functions the use has changed as well. SmoothNormals(...) and AddTerrainTexture(...) have an additional parameter now, but if you ignore this parameter reasonable default values will be used. SwitchWireFrameMode(...) does no longer enable or disable wireframe mode for all objects in the scene. Now it enables or disables it exceptionally for the object, which has called the function. Make sure that you regard these interface changes, when you update your project. Finally here is a list of the scripts, which need to be deleted:

• GetDistanceToModel(...)
• GetDistanceToPrimitive(...)
• GetDistanceToAnyPrimitive(...)
• GetDistanceToTerrain(...)
• CoordToScreenX(...)
• CoordToScreenY(...)
• CoordToScreenZ(...)

Do not feel shocked about that though. There still is a function to perform a ray-mesh intersection test for all these object types and it is even more versatile than the old functions, since it can automatically do the ray-tracing test for a predefined set of solid objects. The new function is called CheckRayIntersection(...). Anyway, for collision detection and collision response there is an even better solution now. You can read about it in the rewritten help file chapter about this topic. It is a lot more reliable, easier to use and under the right circumstances even more efficient than the old method.

CoordToScreenX/Y/Z(...) have been replaced by a vector based version called CoordToScreen(...) now. Instead of calling three different functions, you call only one function, which returns a vector now.

Other than that there are some really minor changes. If you want to make room zero invisible you have to use SetRoomVisibilityEnforcement(...) instead of SetRoomVisibility(...) now. Terrain height maps are interpreted differently now, to add support for 32-bit height maps. If your terrain height map is not exactly grayscale you will get undesired results. The red channel of the height map has a very strong influence on the results now. If your height maps are perfect grayscale, you will not get any problems with the new way the data is interpreted in.

One last thing, that needs to be said here is that the order of inverse tangent space matrices has changed. In Ultimate 3D 2.0 final the normals got overwritten by the second column of the matrices and the third texture coordinate set got overwritten by the third column. Now the normals get overwritten by the third column and the third texture coordinate set gets overwritten by the second column. The great advantage of this is that the third column of the inverse tangent space matrices usually equals the normals. For this reason you can have materials, which use per pixel lighting and others which do not use it on one mesh at the same time now. Despite you do not need to call RecalculateNormals() if you disable per pixel lighting. This means, that if you are using vertex shaders, which use inverse tangent space matrices you need to swap v3 and v9. If you have exported Ultimate 3D model files with inverse tangent space matrices with recent versions of Ultimate 3D 2.0 you either have to reexport them or you have to call AddInverseTangentSpaceMatrices() after loading them.

Updating an Ultimate 3D 2.0 RC project to Ultimate 3D 2.0 final

Since Ultimate 3D 2.0 final does not have any new feature the only scripts that have to be updated are GetObjectTransformation() and Destroy(). Anyway it's recommended to update/add also the following scripts if you are using Game Maker 6.0 or higher. This will make it possible to use Ultimate 3D without the Game Maker option "Treat uninitialized variables as value 0". The following scripts need to be updated for this purpose:

• CreateWall()
• CreateFloor()
• CreateCube()
• Create2D()
• CreatePolygon()
• LightDirectional()
• LightPoint()
• LightSpot()
• LoadMesh()
• CreatePrimitiveFromModel()
• CreateEmptyMesh()
• ApplyParallaxAndBumpMapping()
• SetMaterialEffectLightSource()
• CreateTerrain()
• CalculateTerrainLightMap(..,)
• CreateParticleSystem()
• MoveCamera()
• CreatePostScreenShader()
• Init()

  Despite the following four scripts need to be added to the "Private functions" group:

• InitializePrimitiveVariables()
• InitializeLightVariables()
• InitializeVariable()
• InitializeVariableGlobal()

Another optional update includes some changes to the code of the control object. The code in the destroy event and in the game end event should be updated and the code in the room end event should be added to make Ultimate 3D work properly with room changing.

Updating an Ultimate 3D 2.0 beta 3 project to Ultimate 3D 2.0 RC

Ultimate 3D 2.0 RC is what Ultimate 3D 2.0 was originally meant to be like. Since the development of Ultimate 3D 2.0 took a lot longer than expected, the beta versions were released with some missing features to reduce the delay of the release. These have been added now. To be able to use them you will have to update your Game Maker project a bit. So take five minutes to read this chapter, spend another ten minutes on doing what it says, and you can start using Ultimate 3D 2.0 RC with all its new features.

The first thing you have to do is download the most current SDK from Ultimate3D.org. Once you've got it you can replace the Ultimate3D.dll of Ultimate 3D 2.0 beta 3 in your project with the one from the release candidate. Right after that nothing will be working at all. First you have to replace a couple of scripts with their most current versions. Just open the old BasicGM5.gmd (resp. BasicGM6.gm6 or BasicGM7.gmk) and your Game Maker project, open the scripts that need to be replaced, and copy their new contents from the new version to the old one. Here's a list of all scripts that need to be replaced by newer versions:

• CreatePrimitiveFromModel(...)
• PreloadMesh(...)
• LoadMesh()
• AddFrame(...)
• Step()
• Destroy()
• Init()
• SetFilter()
• GetBoneTransformation()
• CreateTerrain()
• DrawText()
• CreateCube()
• DrawTex()
• DrawTexEx()
• RenderToCubeTexture()
• GetObjectTransformation()
• MoveCamera()
• SetObjectRoom()

Next you have to add the new scripts, to be able to use the new features. Again here is a list of them.

• ExportToU3DFile(...)
• SwitchAlphaBlending(...)
• SetBoneFrame(...)
• GetDistanceToTerrain(...)
• SetCustomTerrainLightMap(...)
• GetClippingPlaneSupport()
• SwitchWireFrameMode(...)
• UpdateSkeleton()
• ReleaseModel(...)
• AddTextureCoordinateSetsFromModel(...)
• ComputeMatrixRotationAngles(...)
• GetRayTracingNormal(...)
• ScreenCoordToVector(...)
• Everything in the group "Shadow and post screen shader functions":
• GetShadowSupport()
• SwitchShadows(...)
• SwitchShadowCasting(...)
• CreateShadowOptimizedGeometry(...)
• SwitchShadowReceiving(...)
• CreatePostScreenShader()
• SetPSSTexture(...)
• SetPSSVSConstant(...)
• SetPSSPSConstant(...)
• SetPSSFilter(...)
• The portal engine functions:
• SwitchPortalEngine(...)
• GetObjectRoom()
• GetRoomVisibility(...)
• CreatePortal(...)
• SetPortal(...)
• OpenPortal(...)
• DestroyPortal(...)

All of these scripts are available in an exported Game Maker script file, which comes with the SDK. Using this can save you some time adding them. Depending on the file you based your work on, you may have to add GetBoneTransformation(...), because this script was missing in some of the Game Maker files that came with Ultimate 3D 2.0 beta 3. Also, you should delete LoadAnimated3DS(), because it's just an outdated remnant from older versions of Ultimate 3D. It does nothing but call LoadMesh() anyway. Once you've done all these things your Ultimate 3D project should be working fine and you can start using the features of Ultimate 3D 2.0 RC.

Updating an Ultimate 3D 1.31 project to Ultimate 3D 2.0 beta 1

Ultimate 3D 2.0 is a complete remake of Ultimate 3D. There's no single line of code that's the same as in Ultimate 3D 1.31. For this reason it was not possible to keep everything the same. There's a couple of things that changed because the old solutions were not user-friendly enough, a couple of things that changed because the new features required these changes and a couple of things that just got removed to increase the performance of Ultimate 3D. This text will list all these changes and give a detailed step-by-step description on how to update projects from Ultimate 3D 1.31 to Ultimate 3D 2.0. It may take an hour or two to convert your project.

Regarding the features that are part of the novice section of Ultimate 3D almost nothing has changed. The only changes are that cube objects get defined differently and that the light is calculated in a more natural way. A few variables have also been added for primitive objects and LoadAnimated3DS() does not exist anymore (it's LoadMesh() now). The meaning of the variables rotx, roty and rotz have changed for camera objects and light sources. These variables now work exactly in the same way as the corresponding variables of primitive objects and models. Also, you can not use vertex shaders for primitive objects anymore which was a necessary change to make the primitive renderer much more efficient.

Most features in the advanced section did not exist in Ultimate 3D 1.31 so there is not much that could have changed. The particle effects system is completely new and the parameters of the ray tracing functions have changed a bit, due to the change of the meaning of the variables rotx and roty for camera objects. It works all in the same way now. That means that a value of 90 for rotx would make the camera look straight down. But let's get to converting projects now.

Step one: Replace and add all scripts

Realizing this part is really boring and will take a lot of time. But when you are done with this, your project is almost ready for Ultimate 3D 2.0. I recommend opening the new BasicGM5.gmd/gm6 and your Ultimate 3D 1.31 project in two instances of Game Maker and placing their windows at the left and the right half of the screen. The first thing you have to do to get the new scripts into your project, is delete the following old scripts that do not exist anymore:

• CreateParticleSystem()
• DestroyParticle(...)
• GetParticleColorR/G/B/A(...)
• GetParticleNumber(...)
• GetParticlePosX/Y/Z(...)
• GetParticleSize(...)
• GetVSSupport()
• LoadAnimated3DS()
• LoadVS(...)
• SetParticleColor(...)
• SetParticleNumber(...)
• SetParticlePos(...)
• SetParticleColorEnd(...)
• SetParticleColorStart(...)
• SetParticleSize(...)
• SetParticlesLifetime(...)
• SetParticlesMovement(...)
• SetParticlesMovementInc(...)
• SetParticlesMovementOut(...)
• SetParticleSystemBase(...)
• SetViewport(...)
• SetVS(...)
• SetVSConstant(...)

Next you have to rename the following scripts to the given new names:

• collision_h() to CollisionH()
• collision_model() to CollisionTerrainModel()
• collision_v() to CollisionV()
• collision_z() to CollisionZ()
• GetMaterialNumber(...) to GetMaterialIndex(...)
• move(...) to Move(...)
• SetMaterialSphereMap(...) to SetMaterialEnvironmentMap(...)
• Snapshot(...) to TakeScreenshot(...)
• SnapshotEx(...) to TakeScreenshotEx(...)

When you are done with these changes you should try to run your game once using the old dll of Ultimate 3D 1.31 to see which parts of the program will have to be changed or remade. If you have particle systems made with Ultimate 3D 1.31 it will be easiest to delete and remake them completely. If you are using vertex shaders for primitive objects in your project, you'll have to find a way to get the same effect without shaders, or you'll have to replace the primitive objects with model objects. When you are done with this the game should be working.

Now the really annoying part follows. You have to open every single script in the new BasicGM5.gmd/gm6 file, copy its contents, and replace the contents of the corresponding script in your project with this code. If the script is not part of the old version of Ultimate 3D you have to create it. You should redo the group structure as well. It's not that much work to create it but it will make everything a bit easier.

Step two: Changing objects

When you are done with replacing and adding all scripts you can run the game again using the new dll, but the result will not be that motivating. You will not see anything. But do not worry, that's quite easy to fix. You simply have to change the function calls that are done by the control object. In the end-step-event you will find a call to MoveCamera() and a call to the Game Maker function external_call(...). You've got to replace these two calls with the following piece of code after removing the if statement that's above these calls:

In the begin step event you have to remove the if statement again and you have to replace the call to external_call(...) with the following:

You also have to replace the stuff in the destroy event and the game end event with the following piece of code:

When you are done with these changes you can run the game again and there should be some visible results. But some things may be a bit weird. The camera probably will not behave in the desired way and the collision detection may not be working correctly. This is due to the changed meaning of the variables rotx, roty and rotz and the parameters of GetDistanceToModel(...) and Move(...). There is no hint I could help you with in this context. You simply have to search for the codes that use these variables or functions and correct them. In many cases adding a few minuses will be all you have to do. Another thing you have to do is update any cube objects you might have. To see how they work now, please refer to the chapter about primitive objects.

There's also a couple of really small changes:

• control.range has changed to camera.max_range
• global.fall and global.speed (the variables that can be used to make camera objects jump or fall) have changed to camera.falling and camera.falling_speed
• global.x and global.y (the output variables of GetMousePos(...)) have changed to global.mouse_x and global.mouse_y
• Environment mapping additive works now. This means that a black environment map would not change anything at all while a white environment map would strongly brighten up everything.
• The Alpha parameter of DrawTex(...) now takes values in the range from 0 to 255 instead of values in the range from 0 to 1.

When you are done with these changes everything should be working and your project is ready for use with Ultimate 3D 2.0. If there are still problems left, please post them on the Ultimate 3D Community.

Converting an Ultimate 3D project from Game Maker 5.x to Game Maker 6.0 or higher

Due to the lack of downwards-compatibility of Game Maker 6.0 you need to update some scripts when you convert an Ultimate 3D project from Game Maker 5.x to Game Maker 6.0 or higher. Despite several scripts differ, because the Game Maker 6.0 version of Ultimate 3D is made to work without the "Treat uninitialized variable as value 0" option. Those should be replaced by the correct versions, too. Here's a list of all scripts that need to be replaced by the corresponding Game Maker 6.0 versions from the BasicGM6.gm6 (resp. BasicGM7.gm7):

• MoveCamera()
• SetSoundPosition()
• Init()
• CreateWall()
• CreateFloor()
• CreateCube()
• Create2D()
• CreatePolygon()
• LightDirectional()
• LightPoint()
• LightSpot()
• LoadMesh()
• CreatePrimitiveFromModel()
• CreateEmptyMesh()
• ApplyParallaxAndBumpMapping()
• SetMaterialEffectLightSource()
• CreateTerrain()
• CalculateTerrainLightMap(...)
• CreateTerrainDecal()
• CreateParticleSystem()
• CreatePostScreenShader()

Furthermore the following four scripts need to be added to the "Private functions" group:

• InitializePrimitiveVariables()
• InitializeLightVariables()
• InitializeVariable()
• InitializeVariableGlobal()

Despite some code within objects needs to be changed. The pieces of code in the BasicGM5.gmd which need to be modified to work with Game Maker 6.0 or higher are part of the room end event of the control object and the step event of the camera.

© Christoph Peters. Some rights reserved.