Contributing – Irrlicht Engine - A free open source 3D engine

Contributing

Irrlicht is easy to use, has minimal external dependencies and is easy to read. We hope this encourages you to dive into the source code and make interesting and useful changes, then share these changes with the community.

Reporting bugs

If you think you have found a bug, the first thing you should do is post to the bug reports forum. To make a good bug report,

  • Tell us what version of the engine you’re using
  • Provide a description of what you expected to happen
  • Provide a description of what actually happened, including a screenshot if it’s a graphical problem
  • The absolute bare minimum code that will reproduce the problem
  • Any media (textures, 3D models, etc) required to reproduce the problem

Once you’re sure that it’s a bug, open a bug report on our bug tracker and include a link to the forum post.

Getting the development code

You can get the latest unstable code from our SVN repository, you’ll need a Subversion client first though. Windows users can use TortoiseSVN, OSX users svnX, Debian / Ubuntu users just type sudo apt-get install subversion at the command line.

Once you have SVN installed, you can get the latest development code here:

svn://svn.code.sf.net/p/irrlicht/code/trunk

Warning: this is often unstable and represents the next major release, there will be API changes between this release and the current stable release.

The latest 1.8.x branch is here, it represents the next bugfix release (1.8.1).

svn://svn.code.sf.net/p/irrlicht/code/branches/releases/1.8

And the experimental OpenGL ES driver is here:

svn://svn.code.sf.net/p/irrlicht/code/branches/ogl-es

Enhancing Irrlicht

If you are creating a patch for Irrlicht and want it to be merged with the development branch, please try to follow these rules:

  • If possible please start by contributing something small, for example a bug fix. If you start with something large and complex then it may take a long time for the developers to review it (and you!).
  • Don’t add dependencies to other libraries or at least only if really, really necessary.
    • Don’t use the STL, use the Irrlicht built in containers instead.
    • Don’t use platform specific functions, use the internal os:: namespace for that if there is no other way to do what you need.
    • If your patch requires some external library, make sure it can be cleanly disabled in IrrCompileConfig.h
  • Always keep in mind that Irrlicht must be compileable on lots of different platforms and with several compilers.
    • Don’t use special compiler extensions and try to adhere to standard C++.
    • Use the Irrlicht types like f32 and u32 defined in irrTypes.h.
  • Try not to break the existing interface if it is not really necessary. Only change current behaviour of the engine if necessary. People should be able to upgrade to new Irrlicht engine versions as easily as possible. If you really must change the interface then make sure you discuss it in the Open Discussion forum beforehand.
  • Try to adhere to the existing Irrlicht code style.
    • Interfaces visible from outside start with I (e.g. ISceneManager), implementations with C (CSceneManager), structures which only hold data with S (S3DVertex).
    • Methods start with a lower case letter, member variables with an uppercase letter. (e.g. ISceneManager::addTestSceneNode(), CSceneManager::ListOfSceneNodes ).
    • Public methods of interfaces have default parameters where useful.
    • Add doxygen documentation to new or changed methods, and document your changes in changes.txt.
    • Use the C++ line breaking style, not the one used by Java coders:
      Good Bad
      for(foo)
      {
         // bar    
      }
      for(foo) {
        // bar
      }
    • There are some other few rules, but the ones above are the most important ones, for example it is a good idea to use spaces, newlines and tabs as often as possible. Just try to make your code look like the existing one.
  • Always check for errors, prevent crashes and wrong behaviour by validating pointers (check if they are not null) and input parameters. Log an error message and keep on running instead of stopping execution at all cost. There are of course exceptions like performance critical code like triangle rasterization in software mode.

That’s it, have fun coding.

Submitting the code

When you’re done with your code, submit it to the patch tracker and post it to the Open Discussion or Bug Reports forum explaining your submission. If you don’t get a response, feel free to give an active developer an email explaining your changes.