Friendly NPC Programming Guide

The creation of each friendly NPC is handled by NPCFactory.json and follows the factory design pattern. Each specific entity follows Composite Pattern which allows components (essential components such as PhysicsComponent, AITaskComponent, AnimationRenderComponent, and specific AI tasks like WanderTask and AvoidTask) to be added to the entity. This allowed for flexibility in building complex objects from simple ones, i.e., an entity.

JSON Configuration

Each NPC type is defined in JSON format from NPCs.json file, with specific attributes such as:

• spritePath: Defines the animation path for the entity.
• animationSpeed: Specifies the speed in which to play the animation.
• soundPath: The directory to the .wav file that plays when you speak to the entity.
• animalName: Specifies the animal's name.
• itemProbability: Specifies the probability in which to drop an item after speaking to the entity. It is important to note that handleConditionalDrop must be used when wanting an animal to drop an item.

An example for this json can be seen below:

  "magpie": {
    "baseHint": [["I LOVE GOLD!!"]],
    "spritePath": "images/friendly_npcs/magpie.atlas",
    "animationSpeed": 0.2,
    "soundPath": ["sounds/aus-magpie.wav"],
    "animalName": "Magpie",
    "itemProbability": 0.0
    }

Sounds and Atlas registration

In order to use sounds and atlas' in the game, they must first be registered with the ResourceService. The sounds for the main game screen are stored in sounds.json and the atlas' are stored in textures.json and read by the FileLoader. It is crucial to add the directories too here, for example:

textures.json Example	sounds.json Example
{ "forestTextureAtlases": [ ..., "images/magpie.atlas", ... ] }	{ "gameSounds": [ ..., "sounds/aus-magpie.wav", ... ] }

Dialogue and Sound Integration

Each friendly entity is equipped with an event listener that triggers the updateText function in DialogueBoxService, ensuring dialogue boxes appear at the right moments during gameplay. The event listener follows the format PauseStart%s, where %s is dynamically replaced by the animal's name, as specified in its respective configuration component.

When the event is triggered, it invokes initiateDialogue, which not only updates the dialogue box but also plays a corresponding sound to simulate the animal "talking." This creates a more immersive experience by synchronising dialogue and sound with the entity's behavior.

Details on how the Entities access the dialogue box can be found here: Service Locator (DialogueBoxService)

Example Entity Creation

Now the magpie's information is stored and registered in the system it is possible to create one and put it on the game map. An example of this is:

  public static Entity createMagpie(Entity target, List<Entity> enemies) {
    BaseFriendlyEntityConfig config = configs.magpie;
    return createFriendlyNPC(target, enemies, config);
  }

As previously mentioned in the Friendly NPC Guide some entities have the option to drop items. This is done by adding a function call to handleConditionalDrop like in this example:

  private static final NPCConfigs configs =
      FileLoader.readClass(NPCConfigs.class, "configs/NPCs.json");

  ...

  public static Entity createFish(Entity target, List<Entity> enemies) {
    BaseFriendlyEntityConfig config = configs.fish;
    Entity fish = createFriendlyNPC(target, enemies, config);
    handleConditionalDrop(fish, target);
    return fish;
  }

This adds an event listener to the specific entity that listens for the completion of a pause interaction, triggering the item drop once the interaction is finished.

UML of Entity Creation

As there are so many dependencies in creating a friendly entity, a UML which can be seen below was developed:

All methods are well outlined in the JavaDocs, so if any clarification on what a method does is needed, it is recommended to look there.

Additionally, as previously mentioned, entities are spawned from the file ForestGameArea. Entity Conversion also has some new methods in responsible for generating new friendly entities. These process' dependencies can be seen below in the partial UML diagram:

Testing

Each entity's testing guide, which is focused in NPC Factory and the classes and file that it uses, may be seen below:

NPC	Testing Guide Link
Cow	Cow Testing Guide
Lion	Lion Testing Guide
Turtle	Turtle Testing Guide
Snake	Snake Testing Guide
Eagle	Eagle Testing Guide
Fish	Fish Testing Guide
Magpie	Magpie Testing Guide