A Guide To Activities

Activities are based on rules, so you should read the rule guide beforehand.
The main class Activity is a subclass of Effect, which means it is used as a normal effect for every instance of Physical. Activities are controlled by a Soul in that the Soul manages different activities and switches them on incoming ActivityEvents.
Naturally this means, that every Activity must have its own corresponding ActivityEvent class. We'll look later at StartFishingActivity for a possible implementation.
The Soul guarantees, that only one activity is in effect at any time. If it receives a StopActivity event or before any activity is active, a DefaultActivity is provided (which does nothing).
Once an activity is put into the effects collection of a physical, it receives events just like other effects and tries to find a rule from its RuleSet that wants to fire on this event (Basically the same happens within NPCSoul).
If a rule is chosen, the activity delivers its actions as usual.
But the activity has also the possibility to add filters or other effects to the parent physical. Just as an example, you could write a filter that prevents movements while you are doing the activity. Or the other way around: Add a filter, that stops the activity, when a MoveEvent comes around.

I'll take a quick look now at relevant methods for the happy creator of Activities.

The Activity Class

public void init(RuleSet rs, Soul soul);

public void startActivity(ActivityEvent ae)

public void stopActivity()

public abstract void add/removeFilters()

That is all there is to the Activities methods. Look at the API documentation for the messy details.

An Example

public class FishingActivity extends Activity {
 
  /** Since the Fishing rule is removed, after it found a fish. The rule
    must be inserted again with startActivity. Otherwise do it in init() 
    **/
  public void startActivity(ActivityEvent ae) {
    rs.removeAllRules();
    rs.addRule(Fishing.class);
    super.startActivity(ae);
  }
...

To get the activity to work with a NPCSoul for example, we take a look at the BartenderNPC again:

public class BartenderNPC extends NPCSoul {
  Bartending r;
  public BartenderNPC(Clock clock, Physical c) {
    super(clock,c);
    r = (Bartending)rs.addRule(Bartending.class);
    r.setPriority(200);
    rs.addRule(StartStopActivity.class).setPriority(300);
    loadActivity(FishingActivity.class);
  }
...

public class StartFishingEvent extends ActivityEvent {
        public StartFishingEvent(Active listener, Item source) {
                super(listener, source);
        }
        
        public StartFishingEvent(ItemHeader source) {
                super(source);
        }

        public String getName() {
          return "fishing";
        }

        public Class getActivityClass() {
          return FishingActivity.class;
        }
}

Some Tips

 You should take a look at all the rules you use in an activity to see if they depend on a completely initialized world to function ! As in the example above, when running through the constructor of BartenderNPC the game world probably isn't created completely. Since the activity is loaded and initialized there, you should take care of when you insert the rules.

 It's better if you play it safe by loading activities in doBirth() of NPCSoul. This method is called when the clock starts running and that hopefully means, the world is completely there.

Another thing to take care of is to provide the correct source of the event that starts an activity. It must be the soul itself, since the source is used to start the activity in the execute() method.

If you don't care about rules, you can also subclass processEvent() of activity and provide your own implementation. This is of course not recommended.

I hope you got the idea. If you have suggestions to make more out of activites, don't hesitate.