CLTool - A course and library cloaking device for PGA Championship Golf 2000

Version 2.0, released November 27:th, 2004
For release information, please see the included readme.txt file
This document was last updated on November 27:th, 2004

Table of contents

License agreement
Background
A solution
The CLTool main screen and how to operate it
A little on default libraries
Setting the default library
The context menu
Stock object protection
Design project features
Other functions
A few words of caution
Uninstalling CLTool
Support
Credits

License agreement

It's simple: CLTool is the intellectual property of me, Jörgen Ekroth. (j.ekroth@telia.com) CLTool is 100% freeware, and you may use it as you see fit, for your own pleasure. CLTool may however not be placed on web servers or included on media such as CD-ROMs targeted for purchase without my permission.

This program is not endorsed by or affiliated with Sierra, or its licensors. Trademarks are the property of their respective owners. Game content and materials copyright Sierra Inc. and its licensors. All Rights Reserved.

Background

The PGA Championship Golf 2000 golf sim relies heavily on course libraries, which in essence is a container for graphics combined with related property values. A PGA course will require at least one library, but most often, courses use more than one library. If all available libraries were the ones shipped with the game, this would not be an issue, but the PGA game is flexible, and lets us create our own libraries as we see fit. This is a very nice feature, because it allows new and improved graphics to be used in our courses. The problem is that each library needs to be installed in order to be used. It is not really a problem for people who only play the game, but for course architects who use the course designer tool, it will slowly become a problem as the number of installed libraries grows and grows. After a certain number of installed libraries, the architect becomes slower, unstable, and crashes more often. It can also be very time consuming to scroll through the many tabs in the library view to find the library you are looking for, and when changing texture properties, the list of available textures soon becomes endless.

A solution

CLTool offers a solution to this problem by giving the designer an option to hide one or more libraries by moving the associated installation information out of the PGA configuration database and save it in a temporary area. The physical files are not moved, they stay where they are. The same option is given for courses too, but having many installed courses is not really an issue for the course designers. The option was included because the technique is identical.

The CLTool main screen and how to operate it

The CLTool main screen
Figure 1 - The CLTool main screen

The program has the ability to cloak both libraries and courses. You switch between the two categories by using the tab at the top of the screen. The sub-screens for cloaking courses and libraries are identical from both a visual and functional perspective. Please note that the course cloaking functionality is disabled as default, but can be enabled through the context menu.

To cloak a course or library, simply select it in the left list and press "Cloak >>". To uncloak courses or libraries, select one or more items in the right list and press "<< Uncloak". It is as simple as that. You can select multiple items by either dragging the mouse down the list while holding the left button mouse pressed, or by holding down either the shift or ctrl keys on the keyboard and clicking on items. This is standard Windows behaviour, so you will get the hang of it very quickly.

When you select items in one list, any selections made in the other list are de-selected. This is just to minimise the confusion factor.

Stock courses and libraries are prefixed with a "+" in the lists, to help distinguish them from custom courses and libraries.

A little on default libraries

CLTool has the ability to change the default library, and also warns when you are trying to cloak the default library. So, what is actually the default library?

The default library is the library from which the textures and objects for a new course is taken. Each time the architect starts up, it creates an empty course named "Untitled" with a base shape using the first rough texture from the default library, and the default library panorama. All shapes are also assigned the first fairway texture from the default library. This implies that the library you choose as default library must contain at least:

  • One texture marked as rough.
  • One texture marked as fairway.
  • A panorama.

If any of the above conditions is not met, the architect picks the first available library that has the three necessary items. If no library fulfills the default library conditions, the architect will not start up properly. Normally, the default library is the Pebble Beach library, but it might also be another library depending on earlier happenings. (The Pebble Beach library might have been uninstalled or cloaked, or has become invalid for some reason)

Setting the default library

To set the default library, switch to the library tab in the main view and double-click on a library in the visible library list. This will bring up a property window. To the right, there will be a button labeled "Set as default". Simply press it, read the warning message carefully. If you feel comfortable about using the selected library as your default library, press "Yes". That is it. From now on, all new courses will use the selected library as a base.

If you want a cloaked library to be your default library, just uncloak it, and follow the above procedure. (CLTool does not allow a cloaked library to be your default library for safety reasons)

NOTE - The stock object protection prevents you from setting default libraries. To bypass this, you can switch off stock protection if you want.

The context menu

To avoid cluttering up the main window with too many buttons, the commands that are rarely used have been placed in a context menu that pops up when you right-click the main window. (Note that you cannot right-click on a button, tab, or list box, but all other parts of the window should work) The context menu looks like this:

The context menu
Figure 2 - The CLTool context menu

The commands in the context menu are:
  • Uncloak all courses and libraries
  • Cloak all custom courses and libraries - Leaves only the courses and libraries that came with the game visible. This command is preferrably used when you are about to reinstall PGA. After a completed reinstallation, you can use the above command to reinstall all your custom courses and libraries.
  • Uninstall CLTool - Uncloaks any cloaked courses and libraries, and removes all CLTool registry entries.

There are also five program options in the context menu. These are:

  • Delete swap files when cloaking libraries - Mark this if you want CLTool to delete swap files (.lsw) associated with a library when cloaking it.
  • Delete swap files when cloaking courses - Mark this if you want CLTool to delete swap files (.swp) associated with a course when cloaking it.
  • Delete course debris files when cloaking courses - Mark this if you want CLTool to delete course debris files (.dbr) associated with a course when cloaking it.
  • Protect stock objects - Mark this if you wish to avoid cloaking stock courses and libraries. See stock object protection for more information.
  • Allow cloaking of courses - Mark this if you wish to enable cloaking of courses.

Stock object protection

The stock object protection is a way to ensure that all stock items always are available to the game and architect. The function prevents courses and libraries from being cloaked, even though they might be selected for a cloaking operation. This option is initially enabled, but can be switched off for full control. Please note that disabling the stock object protection will allow CLTool to perform potentially dangerous operations. Most courses rely on stock libraries, so cloaking them may render virtually all courses unplayable. It may also affect the architect in a negative way, and may even prevent the architect from starting up properly. Be very careful when disabling this option!

When the stock object protection is enabled, the status line indicates this by displaying the characters "SP" in the left corner.

Design project features

CLTool is equipped with a design project tab. This tab gives designers the possibility to add their architect documents, and operate on them. You can add, modify and remove existing projects, which are basically just links to your architect files.

You create a new project by clicking the New... button. That brings up the following dialog box:

The New project... dialog box
Figure 3 - The New project... dialog box

Type a name for your project, and then click the browse button to navigate to your architect document. Finally click Ok. Now CLTool will read the architect document and collect information on what libraries are referenced in terms of textures, objects, sounds, panorama etc. TIP: By leaving the name field blank and only selecting an architect file, CLTool will automatically populate the name field with the course name registered inside the architect file.

To view information on a project, just double-click the entry in the project list, and CLTool will display the project property dialog:

The project property dialog box
Figure 4 - The project property dialog box

Here you can see various information, such as the point count and the number of referenced libraries. You also have a few command buttons available:
  • Uncloak libs - This command uncloaks all cloaked libraries that are referenced by the architect document.
  • Cloak others - This command cloaks all visible libraries that are not in use by the architect document
  • Fix sticky - This command enables you to clean your architect file from so called "sticky libraries". Sticky libraries are libraries that you have used when you plant objects on your course. Even if you delete an object from the course, the CA will always remember the object, and sometimes issues warnings about missing libraries, even though the libraries are not referenced anymore. This can be especially annoying if the objects originate from custom libraries that you have uninstalled.
  • Lib details - This command enables you to view which objects from a certain library are in use on your course
When you click the "Fix sticky" button, CLTool will ask you to save the cleaned architect document in a new file. It will not accept to overwrite the current architect file. If you want to do that, save the cleaned file, then use the Windows Explorer to remove the old file and rename the new one. A word of caution though - Make sure you try to open the new file in the course architect first, to make sure it is ok.

When you click the "Lib details" button, CLTool will display a dialog box similar to this one:

The detailed library info dialog box
Figure 4 - The detailed library info dialog box

You can expand each library by clicking the "+". For every library you will see what objects are in use. For textures, sounds and objects, you can also see which items are in use. CLTool will display the ordinals, starting with 0 (zero) for the first item shown in the library view in the course architect. Counting starts at the top left thumbnail, which is item 0, the next one to the right is 1 and so on.

NOTE: The texture numbers may sometimes be incorrect for stock libraries, since there are textures that are not shown in the library view in the architect. (Non-surface textures) Texture numbers in custom libraries should always be correct though.

Sticky items are indicated by an asterisk following the item number. (Only objects have the habit of becoming sticky once you delete them, sounds, textures and panoramas never become sticky)

To remove a design project from the list, simply click the "Delete" button in the project view.

To rename a project, or pick a new architect file, click the "Update" button. Please note that you cannot switch to a completely different architect file since a design project is identified by the course GUID. (Global Unique IDentifier) This also means that you can have only one design project for an architect document.

Other functions

CLTool has a few other functions built into it. These are:
  • The ability to show properties for a course or library. Properties include the name and the file name, and for courses, the associated video, music, text and splash screen. To display the properties, simply double-click on a list item. The properties for a course also includes which libraries the course is using. In a similar fashion, the properties for a library includes which courses that use the library. In the property dialog for a course, you will also find an "Uncloak libs" button. When you press this button, all libraries that are associated with the course will be uncloaked. If the properties are for a visible library, there will also be a button for setting the library to be your default library.
  • Automatic delete of swap files associated with a course or library. When a course or library is cloaked, the corresponding swap files are removed from disk. As the course or library is no longer part of the PGA installation, the swap files are of no value, and could even cause problems, so CLTool simply removes them. The swap files will be re-created as soon as the course or library is uncloaked, and used by the architect or game engine. This function is configurable See the context menu for more information.
  • A HTML help function that displays this document. At start-up, CLTool tries to detect how to start the default web browser, and if this detection is successful, the help button will be enabled. Clicking the help button will launch the browser and display this document.

A few words of caution

Even if CLTool is a fairly straightforward and easy-to-use tool, there are a few things to keep in mind:
  • When using CLTool to cloak courses and libraries, you will experience problems when trying to play a course that uses one or more cloaked libraries. Use the course property function described above, and uncloak all associated libraries before playing the course.
  • When making changes to the registry, either through the PGA Course Manager, manually, or by using registry scripts, there is always a risk of causing inconsistency. You can for example cloak a course using CLTool, and then re-install it through the PGA Course Manager. The course will then exist both in the cloaked registry that CLTool uses, and in the PGA registry. To resolve this situation, CLTool performs a check every time the program is started, and automatically removes all cloaked course and library entries that are also present in the PGA registry.
  • Architect files, or .ACH-files, are affected by cloaking libraries. CLTool does not have the capability to read architect files, so it is entirely up to the user to make sure that the relevant libraries are visible when opening an architect file.
  • Never run CLTool while any of the PGA tools are active, such as the game, the architect, the course manager or the library creator. (The latest release of CLTool will automatically detect this, and refuse to start, or complete a cloaking or uncloaking command) The risk of causing registry inconsistencies is extremely large under such circumstances, and it may even cause permanent damage to your PGA installation.

Uninstalling CLTool

You uninstall CLTool through the uninstall command on the context menu. This will automatically uncloak all cloaked courses and libraries, and delete all registry keys associated with CLTool. After that, run the uninstall utility present in the CLTool start menu folder.

Support

CLTool comes free of charge, and also free of support. ;-) Well, maybe not, but I cannot guarantee that I have the time to assist if problems should arise. Send a mail to j.ekroth@telia.com, including a description of the error you are experiencing, and info on which version of Windows you have, and I'll see what I can do.

Credits

I'd like to take the opportunity to thank Dale Deputy at Headgate Studios for the most kind and generous help in assisting me through the PGA course architect document format. Without your help, the design functionality in CLTool would not have been possible.