@c -*-texinfo-*-
@node HOWTO Level Loading, XML File Format, Map Loader, Map Loader
@subsection Loading a Level
@cindex @code{iLoader}
@cindex loading level

This section describes how you can load a level in your game.

@subsubheading Getting the Level Loader Plugin

To load a level you need the level loader plugin. There are two
ways to make sure you have this plugin in your application. You can put
a line in your config file like this:

@example
System.Plugins.iLoader = crystalspace.level.loader
@end example

Or you can add the following line to the call to
@code{csInitializer::RequestPlugins()} in your @code{main()} function:

@example
CS_REQUEST_LEVELLOADER,
@end example

To finally be able to use the level loader in your application you
need to do:

@example
csRef<iLoader> level_loader = csQueryRegistry<iLoader> (object_reg);
@end example

When you don't need it anymore you must call @code{level_loader->DecRef ()}.

@subsubheading Loading a Map

Loading a map is simple. You just do:

@example
VFS->ChDir ("/lev/mymap");
level_loader->LoadMapFile ("world");
engine->Prepare ();
@end example

This will first set the current directory to the right @sc{vfs} dir
(@pxref{VFS}) and then it will load the map file which is called 'world' (this
is not a requirement).

Note that this will clear all other geometry that might have been
loaded in the engine before. If you don't want that then you need to
set the second parameter of @code{LoadMapFile} to @code{false}.

The line @code{engine->Prepare()} will make sure that everything that
is loaded is correctly set up (i.e. materials and texture will be registered,
lightmaps will be loaded from the cache, ...).

@subsubheading Include Files

The include files useful for this section are:

@example
#include <isys/vfs.h>
#include <imap/loader.h>
#include <iengine/engine.h>
@end example
