Re: Setting Actions

[Gervase Lam]

I haven't explored very far with the Pingus code.  As a result, I found 
these questions tough to answer.  The only way I could find out the 
answers to your questions was by using the debugger to stop Pingus at 
strategic points in the code and then printing out a stack trace.

I only look at things on a need to know basis.  If it works well for some 
of my colleagues at work, it'll also work for me.

> From: John August
> Subject: Setting Actions
> Date: Saturday 01 May 2004 02:36 am

> I'm now wondering how the click for an action translates to the action
> state for a pingu.  We know that Pingu::request_set_action (PinguAction*
> act) sets a given action.  But how is this called ?

This is handled by the PlayField class/object.  A small part of its job is 
to keep an eye on what Pingu the mouse cursor is on top of.  In other 
words, it sort of marries up the Pingus' in-level co-ordinates with the 
mouse's on-screen co-ordinates.

When the primary button of the mouse is clicked, 
PlayField::on_primary_button_press() is called.  If the PlayField deems 
that the mouse is over a Pingu, it calls Pingu::request_set_action() for 
that Pingu.

I think the above is correct.  All this over simplifies the role of 
PlayField.  I initially thought it is your view of a Pingus level.  But it 
is actually a collection of views.  This I don't understand at all.

> Presumably, when the button is clicked on one of the actions on the list
> to the left of the screen, the "current action to set" is set to the one
> you click on.

Sort of, I suppose.  From what I gather, looking at 
PlayField::on_primary_button_press(), there is a "buttons" object.  In 
order to find out what action a Pingu should get as a result of clicking 
on a Pingu, PlayField::on_primary_button_press() asks the buttons object 
what is the currently selected action.

> We have the question of how this list is set up ?

The "server" object has associated with it an ActionHolder object, which 
contains the number of each of the actions available for the level.  When 
created, the ActionHolder object uses the PLF object (basically the *.plf 
now *.pingus file) to find out what the number of actions should be.

> And how does the
> program keep count of the number of actions remaining, which updates to
> the screen, and stops you from setting more than the allowed number of
> bombers, or whatever ?

This initially got me for a while, though it turned out to be the easiest 
question to answer.  Before calling Pingu::request_set_action(), 
Server::send_pingu_action_event() tries to take away one of the available 
number of actions by calling ActionHolder::pop_action().

The call returns false if there is no more of the requested action to be 
subtracted.  Otherwise the requested action was successfully subtracted, 
in which case the action is applied on to the Pingu.

I had to do a little bit of guess work while looking at the code.  Some 
more comments in the code would have been nice, especially for the 
PlayField class.  With more of the right comments, Doxygen could be used 
to churn out the appropriate documentation.

Thanks,
Gervase.