RuTh's  RuThLEss  HomEpAgE


3D Game DesignEnglish
Programming Links
* INDEX * 3D game to-do list * 3D Engine to-do list ( chapter 1, 2, 3, 4, 5, 6, 7 ) *
* projection formula * transformation matrices * Bresenham algorithm * Scanline Polygonfill algorithm *
* Spieldesign / game design * Troubleshooting 3D * Irrlicht 3D engine * Blender for Beginners *

Getting started with Irrlicht in Xcode

This tutorial uses

  • The Irrlicht 1.0 3D engine (creates a folder called irrlicht-1.0).

  • Xcode 2.4 IDE which is delivered as part of Mac OS 10.4 "Tiger". (You can find it in /Developer/Applications/. If not, install it manually from the System CD.)

  • A graphic file as texture (e.g. shuttle1.jpg)

  • A mesh object (e.g. shuttle.obj, shuttle.mtl, ...), for instance download this incredible sample object and unzip it.

  • Sooner or later, you will want to download and install a mesh editor to create an object of your own. Here are your choices:

    • ArtOfIllusion -- free; easy and intuitive to learn for beginners; can do preview rendering, bones and animation; good material and texture editor; limited number of formats.
    • Blender -- free; advanced; not intuitive to learn (Blender tutorial); lots of formats and millions of features; can do preview rendering, bones and animation.
    • Wings3D -- free; no preview rendering, no animations.

  1. Building the Irrlicht Library for MacOSX

    1. Look into the folder irrlicht-1.0/lib/Mac OS X/. If it is empty, you need to build the missing Irrlicht library libMacOSX.a from the sources.

    2. Open irrlicht-1.0/source/Irrlicht/MacOSX/MacOSX.Xcodeproj in Xcode.

    3. Set Active target to MacOSX

    4. Set Active Build Configuration to Release. (not Debug!)

    5. Choose Build>Build from the menu. (Not Build>Build&Run! It's a library, there is nothing to run.)

    6. Wait for the library to be created. This can take a few minutes. Ignore the warnings about type void*.

    7. The file will be created in irrlicht-1.0/source/Irrlicht/MacOSX/build/Release/libMacOSX.a

  2. Setting Up the Carbon Project

    1. Create a new empty project: File>New Project>Empty Project. Then click Next. Give it any name you want and click Finish. I name mine shuttle.

    2. To create a new target, choose Project -> New Target. Select Carbon>Application (not Cocoa!). Click Next and give the target a name. (I named the target shuttle too). Click Finish and close the Target Info window.

    3. Set Active Build Configuration to Release.

    4. Go to Project>Edit Project Settings, and select the General tab. Make sure Cross-Develop Using Target SDK... is set to the SDK you want to use. I want to use "MacOS X 10.4 (Universal)", so I set it to /Developer/SDKs/MacOSX10.4u.sdk

    5. Then in the same window, go to the Build tab and set the Header Search Paths property to your Irrlicht's include folder, e.g. /Applications/irrlicht-1.0/include/. If you're like me too lazy to type, open the irrlicht-1.0 window in the Finder, then go back to Xcode and double-click the value field, then drag&drop the include folder from the Finder into the value field. (In exactly that order.)

    6. Close the Project Info window, we are finished here.

  3. Adding libraries

  4. Next we add the necessary frameworks and libraries to our new application.

    1. In the Groups&Files column on the left hand side, identify your project's main node. Select it, then choose Project>Add to Project from the menu. In the dialog, scroll to the /System/Library/Frameworks folder. Add Carbon, Cocoa and of course OpenGL. Select them (Note you can select the three of them simultaneously by keeping the Apple key pressed when selecting) and finally click Add.

      In the next dialog, click Add again to add the frameworks to your target. You don't need to check the box to copy over the files into your project.

    2. Now add the libMacOSX.a file the same way you added the framework: Select Project>Add to Project and add the library at irrlicht-1.0/source/Irrlicht/MacOSX/build/Release/libMacOSX.a.

    3. Note how the libraries automatically show up under your project's Target entry.

    4. Add the /irrlicht-1.0/source/Irrlicht/MacOSX/build/MainMenu.nib to the project the same way. It provides a MacOS menu so you can quit the application.

    5. Last, we prepare our resources (textures and objects). Choose File>New Group from the menu to create a folder inside your project. Name the folder Resources. Drag and drop the files shuttle.obj, shuttle.mtl, and shuttle1.jpg and shuttle2.jpg from the Finder into this Resources folder in Xcode.

  5. Writing and Running the Main Method

    1. Choose File>New File from the menu, select BSD/C++ File and click Next. Uncheck Also create .h. Name the new file main.cpp and click Finish.

    2. Copy and paste the following sample code. [Note: There is a better way to load the right textures, see below.]

      #include <OpenGL/OpenGL.h>
      #include <irrlicht.h>
      #include <iostream>
      using namespace irr;
      #pragma comment(lib, "libMacOSX.a")
      char * resPath( char** argv, char* file )
          // returns the path to the "Resources" directory
      	char	tempPath[1024];
      	strncpy( tempPath, argv[0], 1023 );
      	int	x = strlen(tempPath) -1;
      	while( tempPath[x] != '/' && x > 0 )
      		tempPath[x--] = 0;
      	strncat( tempPath, "../Resources/", 1023 );
      	return strncat( tempPath, file, 1023 );
      int main(int argc, char** argv)
          // start up the engine using Open GL
      	IrrlichtDevice *device = createDevice(video::EDT_OPENGL,core::dimension2d<s32>(640,480),16,false);
      	video::IVideoDriver* driver = device->getVideoDriver();
      	// Create a scene
      	scene::ISceneManager* scenem = device->getSceneManager();
      	// Create camera and light in the scene
      	scenem->addCameraSceneNodeFPS(0,10,10,-1,0,0,false); // or addCameraSceneNodeMaya() 
      	// Create an object node in scene
      	scene::ISceneNode* node =
      	// Add material & texture to the node -- Better solution: see below
      	if (node)
      		node->setMaterialFlag(video::EMF_LIGHTING, true);
      		node->setMaterialTexture( 0, driver->getTexture(resPath(argv,"shuttle1.jpg")) );
      	int lastFPS = -1; // calculate frames per second
      	while(device->run() && driver && device->isWindowActive())
      		// BEGIN displaying scene
      		driver->beginScene(true, true, video::SColor(0,100,100,100)); // darkgray
      		// END displaying scene
      		// display frames per second
      		int fps = driver->getFPS();
      		if (lastFPS != fps)
      			core::stringw str = L"Hello Mac [";
      			str += driver->getName();
      			str += "] FPS:";
      			str += fps;
      			lastFPS = fps;
       	return 0;
    3. If you use a different sample, make sure to include the following three lines:

      • #include <OpenGL/OpenGL.h>
      • #pragma comment(lib, "libMacOSX.a")
      • IrrlichtDevice *device = createDevice(video::EDT_OPENGL,core::dimension2d<s32>(640,480));
    4. Make sure you have Release selected as Active Build Configuration and go to Build->Build and Run to run the application.

    5. When the window comes up, use the mouse and the arrow keys to navigate until you see this utterly incredible 3D object.

    6. To quit press Apple-Q.

Loading OBJ files with MTL textures

  1. Learn more about loading OBJ and MTL files into Irrlicht. Download and install the MTL loader files as described in their readme.txt.

  2. You will need to rebuild the irrlicht library to add this piece of functionality (see first section about irrlicht-1.0/lib/Mac OS X/). Some of the files coming with the MTL loader replace existing source files, but COBJMeshFileLoader itself is new, and Xcode does not know where to find it. So drag and drop the two files COBJMeshFileLoader.h and COBJMeshFileLoader.cpp from the Finder to Xcode into the MacOS/MacOS/ group folder.

  3. Clean and build the library and close it on success.

  4. Open your project, and remove the line

    node->setMaterialTexture( 0, driver->getTexture(resPath(argv,"shuttle1.jpg")) );
    Clean, build and run your application to see the effect. Now you can have more than one texture in an object.


Thanks to the Irrlicht crew for their cool library

Thanks to Uli for the Xcode and C crashcourses!

Thanks to several developers (e.g. osxus3r) on the Irrlicht forum who posted useful Irrlicht+Xcode tips. (This MacOS tutorial is partially a summary of those.)

Thanks to loonychewy for the spiffy MTL loader