Welcome to the Torque Game Engine 1.4 for MacOSX! This file contains instructions that you WILL NEED in order to develop with Torque on the Mac. Contents: 1) General Notes 1.1) Supported Versions of Mac OS 1.2) Recommended Development Tools 1.3) A Two Button Mouse is Recommended 1.4) Some Shortcut Keys Conflict with Expose 2) Initial Setup, Tips & Goodies 2.1) Getting Debugging to Work 2.1.1) For Xcode2.1+ 2.2) Script Editing in Xcode 2.2.1) Installing .cs Language Definitions in Xcode 2.3) Putting Game Content Inside the App Bundle 3) Known issues 1) General Notes --------------------------------------------------------------------------- 1.1) Supported Versions of Mac OS Recent versions of Torque on Macintosh require MacOS 10.2 or later to run, but MacOS 10.4 or better is recommended for development. Attempting to support older versions of the MacOS is not recommended. 1.2) Recommended Development Tools Only the Xcode 2.1 format project file is currently being kept up to date. Previous projects aren't guaranteed to work properly, and may have issues not listed herein. Thus, Xcode is the recommended development environment. Older deprecated project files are in the "old build projects" folder. It is of course possible to use any development environment that can produce a Macintosh application, and can use the standard BSD & MacOSX headers and frameworks. Xcode 2.3 or better is recommended for development. You should always use the latest version of Xcode when developing with Torque. 1.3) A Two Button Mouse is Recommended The Torque editors are usually designed to work with a two button mouse. If you don't already have one, we strongly recommend getting one. Most USB mice work quite well with MacOSX. 1.4) Some Shortcut Keys Conflict with Expose MacOSX has a window management feature called Expose, which happens to use the same F-keys that the Torque editors use. In fullscreen mode, there is no conflict. In windowed mode, you can work around the conflict by holding down the command key and hitting the appropriate function key. Thus, to open the Torque Game Builder level builder when in windowed mode, hit cmd-F9 instead of just F9. 2) Initial Setup, Tips & Goodies --------------------------------------------------------------------------- 2.1) Getting Debugging to Work 2.1.1) For Xcode2.1+ ---------------------------------------- There are 2 script files embedded in the build targets, that will run each time the targets are built. One of them attempts to repair broken symbolic links in the bundled OpenAL and xiph.org frameworks. The other performs some critical setup on the torque/pb/build folder. If this 2nd script: "Fix Build Products Path" fails for any reason, Xcode will probably fail to run or debug the application, giving the error: "No launchable executable at path". The "Fix Build Products Path" script creates a symbolic links ( aliases ) to the "../../example" directory. If you are using a different directory name than "example", you can edit the script replace "example" with your directory like this: - launch the Xcode project. - locate the Targets group in the list on the left hand side. - click the triangle next to Targets, so that it opens the Targets group. - for each target in the group, - click the triangle next to the target, so that it opens the target. - locate the build phase "Fix Build Products Path" - double click "Fix Build Products Path" - in the new window that opens, replace every occurrence of "example" with the name of your game directory. ---------------------------------------- Your project should now directly build the target executable directly into the runtime folder, which also means it is properly located for running or debugging from within Xcode / Project Builder. 2.2) Script Editing in Xcode The Xcode project file now contains references to the script files. This makes searching more complete, and provides a decent script editor. 2.2.1) Installing .cs Language Definitions in Xcode ---------------------------------------- - open the "torque/pb/script editing" folder. - locate the Torque.pbfilespec and Torque.pblangspec files therein. - locate the directory /Library/Application Support/Xcode/Specifications/ - create the Specifications directory if it does not exist. - install the .pbfilespec and .pblangspec files in Specifications/ . - quit and restart Xcode. 2.3) Putting Game Content Inside the App Bundle The engine will assume that game content is beside the main.cs file. It will look first in YourGame.app/Contents/Resources, then it will look in the folder where YourGame.app resides for a file named 'main.cs'. So, when you are ready to distribute your game, you should place the game content inside the application bundle like this: - in the Finder, control-click(or right-click) on your built application. - choose 'Show Package Contents'. - a new window will open, with one folder: 'Contents'. - Navigate to the Contents/Resources folder. - copy all your game files (main.cs, common/, etc) into Contents/Resources. - run the game & test all functionality. 3) Known issues --------------------------------------------------------------------------- - No external console window. in debug in Xcode, printfs go to the debug console pane. At some point, we'll likely create a simple console library to be used when a tertiary console window is needed. In the mean time, you can open the console.log file using the Console application. Console will automatically 'tail' the file, always displaying the most current contents. - ADDENDUM: A working input / output console may be used if you manually launch the Torque app directly from the commandline. It's just like the console window you can pull down in game. Whether or not this console starts is controlled with a preference, and can be easily turned off in Release mode. - OSX handles cmdline args like the PC, if you launch it from the cmdline. Note that this means that you can add args in the project file for debug vs release, etc. Take a peek at "example/Launch using show mod.command" in a text editor to see how you can use cmdline args from an external script. The maccmdline.txt workaround still works, if you prefer. - mac performance vs the PC has improved greatly. There is still ground to gain performance here, but it may not be a good investment of time. As a general rule, only consider optimization when you're done with everything else. - As of TGB 1.1.1, and TGE 1.4.2, the Mac platform code has been almost totally rewritten. Much of the code now uses standard POSIX interfaces where they exist. The platform attempts to maintain support for versions 10.2 - 10.4u of MacOSX. Event handling and windowing code is much, much cleaner. - Many little niceties have been added to try to make Torque more Mac like. - Old OS9 code has been removed. - Code that uses deprecated APIs have been removed, except where Apple has not provided a viable replacement, or where support for 10.2 depends on old APIs. - The mac platform is multithreaded, to take advantage of multiple core Intel hardware, and multiple processor hardware in general. - Functionality is now better organized into separate files. This means that macCarbWindow.cc is no longer the random code dumping ground it was before. - Debugging is easier, as many randomly placed globals have been snipped or reorganized into platState. - Wide screen displays are supported. - Window resizing is supported. - Better multiple monitor support. - Better OpenGL setup & features detection. - Alerts work in fullscreen mode now. - Better support for Mac cut / copy / paste etc shortcuts. - Basically, a normal sane human can read & understand the code now. So read away! Yes, you. Get going! This is new code, so there will be bugs. Please report bugs / odd behavior on the *private* Mac forums as you find them.