From TDN

Contents 1 Getting Started 1.1 Supported versions of Mac OS 1.2 Required Development Tools 2 Building and Running 2.1 Building Torque in Xcode 2.2 Resolving Link Errors 3 Debugging 3.1 Debugging the Tools 3.2 Debugging the Game 4 Script Editing 4.1 Editing Scripts in Xcode 4.2 Other editors 5 Publishing 5.1 Customizing the Torque Application 5.2 Stripping the Executable to Reduce Its Size 5.3 Putting Content Inside the App Bundle 6 Known Issues 7 Getting Help

Getting Started

Supported versions of Mac OS

- For development:
MacOS 10.4 or better is recommended for development. Building and debugging the Torque app requires development tools that are supported only on 10.4. Building and debugging Torque on previous versions of MacOS is possible

- For Publishing
Torque games can be played on MacOS 10.3.9 and later. Support for MacOS 10.2.8 is possible with some platform code modifications. Attempting to support older versions of the MacOS is possible but not recommended.

Required Development Tools

- MacOSX vesion 10.4.x
- Xcode 2.4.1
- A two button mouse

Building and Running

Building Torque in Xcode

1. Tell Xcode to show you the build log when you build Torque. Open the Xcode preferences. Choose 'Building' from the row of icons at the top of the preferences window. Under "Build Results Window", set "Open during builds:" to "Always".
2. Choose a target. You'll probably want to build the debug targets, to start with. In the Project menu, under "Set active target", choose "Torque Game Builder Debug".
3. Hit the build button. In the Build menu, choose 'Build'.
4. Xcode will build the Torque application. This will take several minutes.
5. If there are no errors, run the app! In the Build menu, choose 'Build and Run'.

Note: If you compile and you get an error about cIEditor not found. Just delete those from the project and it will compile

Resolving Link Errors

Link errors happen when a piece of C++ code calls another piece of C++ code that a header file talks about, but that Xcode cannot find. They happen when files are missing from the Xcode project, or when a file is included in one target in the Xcode project file, but not another. Fixing a link error is usually pretty straightforward: figure out which symbol is missing, find the file that defines that symbol, and make sure that file is included in the build.

Sometimes Xcode's build results window isn't very good at telling you exactly which symbols it can't find. The information is there, we just have to ask Xcode to show it to us:

1. Show the build results window. Under the Build menu, choose 'Build Results'.
2. Show the detailed build log. The Build Results window has two panes. In the upper pane, in the lower left corner of that pane, are four buttons: a check mark, a yellow triangle, some dotted lines, and a black triangle. Click the button with the dotted lines, and a new pane containing the full, raw build log will be shown.
3. In the upper pane, click the red error text.
4. Xcode will highlight the corresponding section of the raw build log for you.
5. You will see which symbols are missing, and which files reference tried to use the missing symbols.

Notes: - A "symbol" can be either a function or method, or a global variable or class variable. - GCC 3.3, which is used to compile PPC builds, will use the c++ mangled symbol names. The command line program 'c++filt' can unmangle them for you.

Debugging

Debugging the Tools

1. Set the active target to Torque Game Builder Debug. In the Project menu, under 'Set Active Target', choose 'Torque Game Builder Debug'.
   
2. Make sure the active executable is also set to 'Torque Game Builder Debug'. In the Project menu, under 'Set Active Executable', choose 'Torque Game Builder Debug'.
   
3. In the Build menu, choose Build and Debug.
   
4. Torque will run in debug mode, and will break into the Xcode debugger when a breakpoint is hit, or when the C++ method Platform::debugBreak() is called, or when the script function debug() is called.
   

Debugging the Game

1. Set the active target to TGBGame Debug. In the Project menu, under 'Set Active Target', choose 'TGBGame Debug'.
   
2. Make sure the active executable is also set to 'TGBGame Debug'. In the Project menu, under 'Set Active Executable', choose 'TGBGame Debug'.
   
3. In the Build menu, choose Build and Debug'.
   
4. The TGB player will start, and will immediately ask you to locate the main.cs file for the game project you want to debug.
   
5. Browse to your game project's folder.
   
6. Choose the main.cs file it contains.
   
7. Torque will run in debug mode, and will break into the Xcode debugger when a breakpoint is hit, or when the C++ method Platform::debugBreak() is called, or when the script function debug() is called.
   

Script Editing

Editing Scripts in Xcode

Xcode does not know how to deal with Torque script files without some help.

The good news is that Xcode's syntax highlighting and file handling facilities are extendable by plugins. We've created a plugin to activate Xcode's syntax highlighting and function popup. I use it every day.

The bad news is that the plugin interface is not documented or supported by Apple. In practice this means that the function popup isn't perfect, and will occasionally miss some things.

An installer for the plugin is included with TGB, in the Xcode folder, in the 'script editing' folder.

1. Open the Torque Game Builder/engine/compilers/Xcode/script editing/ folder.
2. Open the file 'Install TorqueScript for Xcode.pkg.zip'.
3. The finder will unzip the archive.
4. Open the installer file 'Install TorqueScript for Xcode.pkg'.
5. Install the files to the default location.
6. Quit Xcode if it is open.
7. Open your project file in Xcode.
8. Add your game's game scripts to the Xcode project, either by dragging them in from the Finder, or by choosing 'Add to Project...' from the Project menu in Xcode.

Note: You can also open *.cs, *.gui and *.mis files in Xcode by double-clicking them in the Finder.

Other editors

TextMate is a text editor favored and recommended by several happy Mac Torque users.

Publishing

Customizing the Torque Application

Before publishing and distributing a game with Torque, you'll probably want to make sure that you have properly prepared the game for distribution.

You'll need:

• A 128x128 pixel icon for your application. Read about creating proper high-quality Mac icons in Apple's HIG guidelines.
• A unique bundle identifier in the form of a Java-style package name. For example, com.mycompany.myGame .
• A unique bundle signature, in the form of a four character code. For example, 'GG2g'. Any characters from the MacRoman encoding may be used. Apple reserves for their own use all signatures that are all lowercase. You may register your chosen bundle signature (also known as a 'creator code') with Apple on their site, once your game is finished: http://developer.apple.com/datatype/creatorcode.php

Create the icon as described in the Apple documentation. Then replace the file 'Torque Game Builder/engine/source/platformMacCarb/tgb.icns' with your new icns icon file.

Replace the default bundle identifier and bundle signature with your own:

1. In the Project menu, under 'Set Active Target', choose 'TGBGame'.
2. In the Project menu, choose 'Edit Active Target "TGBGame"'.
3. A new window will appear. This is the Target Inspector window.
4. Click the 'Properties' tab.
5. In the 'Identifier:' field, type your Java style package name.
6. In the 'Creator:' field, type your registered creator code.
7. Update the 'Version' field.

Note: do not change the 'Type:' field, and do not change the 'Executable:' field, unless you also change 'Product Name' in the build settings under the 'Build' tab in the Target Inspector.

Note: do not modify the tools executable, modify the game executable.

Stripping the Executable to Reduce Its Size

Before publishing and distributing a game with Torque, you'll probably want to make sure that all debugging symbols are stripped from the application. Doing so will greatly reduce the size of the application you distribute. This is especially important for distributing via the internet.

1. In the Project menu, under 'Set Active Target', choose 'TGBGame'.
2. In the Project menu, choose 'Edit Active Target "TGBGame"'.
3. A new window will appear. This is the Target Inspector window.
4. Click the 'Build' tab.
5. In the list of build settings, check 'Deployment Postprocessing' to activate stripping.
6. Xcode will run the console command 'strip -u -r' on your application, the next time it builds it.

Putting Content Inside the App Bundle

Well made Mac applications carry any extra files they need inside their app bundle. This greatly enhances user experience and greatly simplifies your installation process. The application and all it's resources are encapsulated, so that the user may have the illusion of dealing with only 1 file when they deal with your game. See Application Bundles on Apple's developer documentation site.

Torque requires the game scripts and other resources to be in the Resources folder inside the application bundle, in order for it to find them. Torque looks for the main.cs file to determine whether it should look inside or outside it's bundle for the game data files.

1. In TGB, in the File menu, choose 'Build Project...'.
2. Change the target platform to Mac.
3. Torque will place the TGB game application, the common scripts, and your game script in a folder, and show you that folder in the Finder.
4. Right-click (or control click) the game application, and choose 'Show Package Contents'.
5. The innards of the application bundle will be shown to you in a new window in the Finder.
6. Open the Contents folder. Inside that folder open the Resources folder.
7. Back in the window that contains your game, select everything but the game application.
8. Drag the selected files into the Resources folder.
9. Test your game.

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. Note: 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.

- MacOSX 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. The maccmdline.txt workaround still works, if you prefer. For debugging purposes, you may set command line args on the active executable in Xcode.

- Background sleep time. The amount of time that Torque takes up when in the background or the foreground can be controlled by a pair of preferences: $pref::backgroundSleepTime controls processor time usage when in the background, and $pref::timeManagerProcessInterval controls processor time usage when in the foreground. Both of these prefs are times in milliseconds. Both can be edited in Torque Game Builder from a preferences dialog, but must be set manually via script for your game.

- Delays when activating Torque. When bringing torque from background to foreground when sleep time is set to a large number, Torque will not activate until the background sleep time interval has passed. This is a known issue.

- Crashing in OpenAL loading code when Torque launches. There is a random crash when launching Torque, in the OpenAL framework, in the loading code. This is probably a bug in the particular version of OpenAL that we are shipping. The crash is very rare, and will not be seen by most users. The media frameworks should be updated and tested. This is a known issue.

- Moving a Mac Torque app to a Windows computer increases the file size. Mac frameworks contain symbolic links that point to files within the framework. The symbolic links are sometimes transformed into full copies when moving the framework to a file system that does not support symlinks, such as a windows file system. This results in duplicated files inside the framework, which increases application file size. This can be worked around by using static libs instead of frameworks for the media libraries. This is a known issue.

Getting Help

The GarageGames community is a great resource for getting help with your game dev problems.

Before you ask, check out the following resources:
- The Torque documentation that ships with TGB
- Search the garagegames.com forums here: http://search.garagegames.com/
- Search TDN on search.garagegames.com by prefixing your search with the google search filter: "site:tdn.garagegames.com".

If you can't find an answer, post your question on the GarageGames forums! Mac specific questions are best handled here:
Torque SDK Private Forums / Mac

Or here:
Torque Game Builder (TGB) Private Forums / C++ Engine

Non Mac-specific TGB questions should be posted in the appropriate forum here:
Torque Game Builder (TGB) Private Forums