Re: Description Document, v.01

[Ingo Ruhnke]

John August <address@hidden> writes:

> StartScreen::StartScreen(PLFHandle arg_plf)
>   : plf(arg_plf)
> {
>   StartScreenComponent* comp = new StartScreenComponent(plf);
>   gui_manager->add(comp);
>   gui_manager->add(new StartScreenOkButton(this));
>   gui_manager->add(new StartScreenAbortButton(this));
> }
> 
> I'm not sure how the arg_plf relates to plf, or how the "true" in the
> call relates to plf(arg_plf) , but note that calls are made to
> StartScreenComponent, StartScreenOkButton and StartScreenAbortButton.

The 'arg_' prefix is just a naming convention to seperate and argument
variable from a member variable, thus avoiding naming
conflicts/confusion. In the Pingus Code both 'arg_' prefix and '_'
suffix are used for that, ie 'plf_' or 'arg_plf' mean the same.

> The relevant StartScreenComponent method appears to be :
> 
> StartScreenComponent::StartScreenComponent(PLFHandle p)
>   : plf(p)
> {
>   background = Sprite("menu/startscreenbg", "core");
>   background.set_align_center();
>   time_str = GameTime::ticks_to_realtime_string(plf->get_time());
> }
> 
> But I'm not sure how the PLFHandle (presumably, Pingus Level File Handle)
> is dealt with by the code below. Perhaps only when the screen is generated ?

The PLFHandle is just a pointer to a PLF object, thus holding all the
information needed for a level, gameobjects, time, name, etc.
Startscreen uses it to present that information and passes it further
down to the PingusGameSession, which then starts the level.

> An important part of startup is to load in the worldmap in
> worldmap/level_dot.cxx, called from [?] [what does level_dot mean?]
>
> Files in the worldmap and worldobs directory are called as part of the
> process of parsing the level description file.

The worldmap is completly seperated from the level startup code, all
it does is to provide a fancy way to start of GameSessions (ie. these
nifty island graphic), nothing more. It has nothing todo with loading
the levels. Levels can be loaded without using the worldmap.

> Worldobjs includes active objects, such as a conveyor belt and spike.
> Worldmap are the routines which set up the world.

Wrong, as said Worldmap is there for presenting the island, not the
level. For the level there is the World class.

> # Parsing the xml file 
> 
> [where this section fits in, and where it is called from, is not known ]
> 
> XMLPLF::parse_file() [xml_plf.cxx] coordinates the main parsing of the xml 
> file.
> It does things like load up the action bar from the <action-list> segment of
> the xml description.

parse_file() just gets the level information from the xml file, it has
nothing todo with setting up the action bar itself. Thats all done in
Client.
 
> It is itself called by XMLPLF:XMLPLF in the same file, which is itself called
> from PLF::create [plf.cxx], and this is called from [?]

You don't have to care much about what it is called from, only what
calling it actually does. In this case it reads a level file and fills
a PLF object with the given information. PLF::create() is a simple
dispatch function to allow the use of different level formats, not
needed at the moment, but what needed at the point where pingus
switched from .plf to .xml.
 
> It is clear how a walker turns into a faller; it is not clear how a faller
> turns into a floater - there is no reference to Floater in the faller.cxx
> code, apart from a graphic add-on.

It is turned into a floater by request_fall_action(), ie. the floater
action isn't hardwired, but it simply registered itself in Pingu class
as fall_action, thus getting triggered on fall events.

> It is in the (ClanLib) file Display/Input/X11/mouse_x11.cpp that the routine
> make contact with the underlying XWindow.

Rather unimportant thingy, diving into clanlib internals, unless
necessary for fixing something, will just cause confusion.
 
> There is a time delay in dealing with events, as the events are only updated
> as rapidly as this is called.
> 
> For some reason, the graphics updates without any noticeable time delay -
> eg ticks appear on the button boxes, or the button boxes are highlighted.

Pingus runs at something like 20-30 frames, thus leading to a call of
keep_alive() every 30-50ms, since human have a hard time noticing
anything below 100ms as delay it isn't much noticable at all.

-- 
WWW:      http://pingus.seul.org/~grumbel/ 
JabberID: address@hidden 
ICQ:      59461927