Sprint 2 Main Character Interaction and Movement Animations - UQdeco2800/2021-ext-studio-2 GitHub Wiki

Contents

Animation Implementation and Controls

An AnimationRenderComponent is used to define all the animations of the character, their playmode, and FPS.

PlayerFactory.java

    AnimationRenderComponent mpcAnimator = createAnimationComponent("images/mpc/mpcAnimation.atlas");
        mpcAnimator.addAnimation("main_player_run", 0.1f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_walk", 0.5f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_front", 1f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_jump", 2.5f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_attack", 1f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_crouch", 1f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_right", 1f, Animation.PlayMode.LOOP);
        mpcAnimator.addAnimation("main_player_pickup",0.125f,Animation.PlayMode.LOOP);

Key event triggers are defined in KeyboardPlayerInputComponent.java

public boolean keyDown(int keycode) {
    switch (keycode) {

      case Keys.S:
      case Keys.DOWN:
        entity.getEvents().trigger(("crouch"));
        return true;
      case Keys.D:
      case Keys.RIGHT:
        walkDirection.add(Vector2Utils.RIGHT);
        triggerWalkEvent();
        entity.getEvents().trigger(("walkRight"));
        return true;
      case Keys.SPACE:
        entity.getEvents().trigger("attack");
        return true;
      case Keys.W:
      case Keys.UP:
        entity.getEvents().trigger(("jump"));
        return true;
      default:
        return false;
    }
  }

The listeners implemented here lookout for trigger events and run the corresponding functions in PlayerAnimationController.java. These functions are discussed in detail in the following sections of the wiki.

public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        entity.getEvents().addListener("walkRight", this::animateRight);
        entity.getEvents().addListener("crouch", this::animateCrouch);
        entity.getEvents().addListener("stopCrouch", this::animateWalk);
        entity.getEvents().addListener("attack", this::animateAttack);
        entity.getEvents().addListener("stopAttack", this::animateWalk);
        entity.getEvents().addListener("jump", this::animateJump);
        entity.getEvents().addListener("stopJump", this::animateWalk);
        entity.getEvents().addListener("itemPickUp", this::animatePickUp);
        entity.getEvents().addListener("stopPickUp", this::animateWalk);
        entity.getEvents().addListener("startMPCAnimation", this::animateWalk);
        entity.getEvents().addListener("stopMPCAnimation", this::preAnimationCleanUp);
    }

Each time an animation event is triggered, a helper function is used to clear any existing textures or stop an already running animation.

/**
     * Helper function to stop all animations and trigger walking animation
     */

    private void animateWalk() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_walk");
    }

/**
     * Helper function to dispose texture (if it exists) and stop all prior running animations.
     */

    private void preAnimationCleanUp() {
        if(texturePresent) {
            animator.getEntity().getComponent(TextureRenderComponent.class).dispose();
            texturePresent = false;
        }
        animator.stopAnimation();
    }

The main player character can be controlled using the WASD keys or the arrow keys. Below is a table including descriptions and controls of how to manipulate the main character.

Key Map

Action Key Control Comment
Jump W / UP Implemeted
Walk Default movement Implemented
Run Right D / RIGHT Implemeted
Run Left A / LEFT Deprecated
Crouch S / DOWN Implemeted
Attack SPACE Implemeted
Item PickUp X Implemeted
Use Item E Future Sprints
Switch Item To be determined Future Sprints

Refactoring Implementation to Controller Pattern

In sprint 1, the animations were handled by methods in PlayerActions.java. For sprint 2, the animations are entirely implemented in PlayerAnimationController.java using the Controller Pattern. Each animation is handled by its respective method, which is run once a event trigger is picked up by the attached listeners.

Existing Implementation (Sprint 1 - PlayerActions.java)

/**
   * Updates the player sprite to turn right
   */
  boolean walkLeft;

  void walkRight() {
    if(walkLeft) {
      walkLeft = false;
      Sound turnSound = ServiceLocator.getResourceService().getAsset("sounds/turnDirection.ogg", Sound.class);
      turnSound.play();
    }
    animator.getEntity().setRemoveTexture();
    animator.stopAnimation();
    animator.startAnimation("main_player_run");
    Sound turnSound = ServiceLocator.getResourceService().getAsset("sounds/turnDirection.ogg", Sound.class);
    turnSound.play();
  }

  void stopWalkRight() {
    animator.stopAnimation();
    animator.startAnimation("main_player_walk");

  }

Refactored Implementation (Sprint 2 - PlayerAnimationController.java)

public class PlayerAnimationController extends Component {
    AnimationRenderComponent animator;
    private boolean texturePresent = true;


    @Override
    public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        entity.getEvents().addListener("walkRight", this::animateRight);
        entity.getEvents().addListener("crouch", this::animateCrouch);
        entity.getEvents().addListener("stopCrouch", this::animateWalk);
        entity.getEvents().addListener("attack", this::animateAttack);
        entity.getEvents().addListener("stopAttack", this::animateWalk);
        entity.getEvents().addListener("jump", this::animateJump);
        entity.getEvents().addListener("stopJump", this::animateWalk);
        entity.getEvents().addListener("itemPickUp", this::animatePickUp);
        entity.getEvents().addListener("stopPickUp", this::animateWalk);
        entity.getEvents().addListener("startMPCAnimation", this::animateWalk);
        entity.getEvents().addListener("stopMPCAnimation", this::preAnimationCleanUp);
    }

    /**
     *  Makes the player pickup items
     */
    private void animatePickUp() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_pickup");
    }
    /**
     * Makes the player crouch.
     */

    private void animateCrouch() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_crouch");

    }

    /**
     * Makes the player run to the right.
     */

    private void animateRight() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_run");
    }

    /**
     * Makes the player attack.
     */

    private void animateAttack() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_attack");
    }

    /**
     * Makes the player jump.
     */

    private void animateJump() {
         preAnimationCleanUp();
         animator.startAnimation("main_player_jump");
    }

    /**
     * Helper function to stop all animations and trigger walking animation
     */

    private void animateWalk() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_walk");
    }

    /**
     * Helper function to dispose texture (if it exists) and stop all prior running animations.
     */

    private void preAnimationCleanUp() {
        if(texturePresent) {
            animator.getEntity().getComponent(TextureRenderComponent.class).dispose();
            texturePresent = false;
        }
        animator.stopAnimation();
    }


}

Attack Animation

The MPC attack interaction is mapped to the spacebar. Once the attack action is triggered, the attack animation is run.

PlayerFactory.java

    AnimationRenderComponent mpcAnimator = createAnimationComponent("images/mpc/mpcAnimation.atlas");
        ...
        mpcAnimator.addAnimation("main_player_attack", 1f, Animation.PlayMode.LOOP);
        ...

The listeners implemented here lookout for trigger events and run the corresponding functions in PlayerAnimationController.java

public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        ...
        entity.getEvents().addListener("attack", this::animateRight);
        entity.getEvents().addListener("stopAttack", this::animateWalk);
        ...

PlayerAnimationController.java

/**
     * Makes the player attack.
     */

    private void animateAttack() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_attack");
    }

Jump Animation

Jumping

To initiate the jump movement and animation of the player, 'W' or Arrow Key 'UP' is used to trigger the movement and the animation.

PlayerFactory.java

    AnimationRenderComponent mpcAnimator = createAnimationComponent("images/mpc/mpcAnimation.atlas");
        ...
        mpcAnimator.addAnimation("main_player_jump", 2.5f, Animation.PlayMode.LOOP);
        ...

The listeners implemented here lookout for trigger events and run the corresponding functions in PlayerAnimationController.java

public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        ...
        entity.getEvents().addListener("jump", this::animateJump);
        entity.getEvents().addListener("stopJump", this::animateWalk);
        ...

PlayerActions.java

/**
   * Makes the player jump
   */

  void jump() {
    Sound jumpSound = ServiceLocator.getResourceService().getAsset("sounds/jump.ogg", Sound.class);
    jumpSound.play();

    Body body = physicsComponent.getBody();
    body.applyForceToCenter(0, 400f, true);
  }

PlayerAnimationController.java

/**
     * Makes the player jump.
     */

    private void animateJump() {
         preAnimationCleanUp();
         animator.startAnimation("main_player_jump");
    }

Crouch Animation

The MPC Crouch interaction is mapped to the S/Arrow `Down` keys. Once the crouch action is triggered, the crouch animation is run.

PlayerFactory.java

    AnimationRenderComponent mpcAnimator = createAnimationComponent("images/mpc/mpcAnimation.atlas");
        ...
        mpcAnimator.addAnimation("main_player_crouch", 1f, Animation.PlayMode.LOOP);
        ...

The listeners implemented here lookout for trigger events and run the corresponding functions in PlayerAnimationController.java

public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        ...
        entity.getEvents().addListener("crouch", this::animateCrouch);
        entity.getEvents().addListener("stopCrouch", this::animateWalk);
        ...

PlayerAnimationController.java

/**
     * Makes the player crouch.
     */

    private void animateCrouch() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_crouch");
        
    }

Item Pick Up

ItemPickUp

According to the game map, the Item Pick Up animation is configured to be triggered using the KeyBoard Key 'X'. Once the animation is triggered, the static texture (if not removed) and all the previous animations are removed from the game area and replaced with an AnimationRenderComponent that triggers item pickup animation. As a result, the particular item texture is removed from the game.

PlayerFactory.java

    AnimationRenderComponent mpcAnimator = createAnimationComponent("images/mpc/mpcAnimation.atlas");
        ...
        mpcAnimator.addAnimation("main_player_crouch", 1f, Animation.PlayMode.LOOP);
        ...

The listeners implemented here lookout for trigger events and run the corresponding functions in PlayerAnimationController.java

public void create() {
        super.create();
        animator = this.entity.getComponent(AnimationRenderComponent.class);
        ...
        entity.getEvents().addListener("itemPickUp", this::animatePickUp);
        entity.getEvents().addListener("stopPickUp", this::animateWalk);
        ...

PlayerAnimationController.java

    /**
     *  Makes the player pick up items
     */
    private void animatePickUp() {
        preAnimationCleanUp();
        animator.startAnimation("main_player_pickup");
    }

Texture Atlases

The atlas that was used for creating the animations was generated using a texture packer. The atlas has player representations in the following states:

  1. Standing (facing right, static)
  2. Standing (facing forward, static)
  3. Walking (facing right, animated)
  4. Running (facing right, animated)
  5. Attack (facing right, animated)
  6. Crouch (facing right, animated)
  7. Jump (facing right, animated)
  8. Item PickUp (facing right, animated)

Generated Texture pack

mpcAnimation.png mpcAnimation.png

Testing

Considering it is hard to test whether an animation plays because of it's visual nature,unit tests were written to verify and validate the generated texture atlas and animation packs instead. The tests check that all the expected animations actually exist in the atlas, in order to catch bugs when editing/renaming/deleting animations. PlayerAnimationAtlasTest.java

@ExtendWith(GameExtension.class)
class PlayerAnimationAtlasTest {


    @Test
    void shouldLoadTextureAtlases() {
        String asset1 = "test/files/mpcAnimation.atlas";
        String asset2 = "test/files/test2.atlas";
        String[] textures = {asset1, asset2};


        AssetManager assetManager = new AssetManager();
        ResourceService resourceService = new ResourceService(assetManager);
        resourceService.loadTextureAtlases(textures);

        assetManager.load(asset1, TextureAtlas.class);
        assetManager.load(asset2, TextureAtlas.class);

        TextureAtlas atlas = new TextureAtlas(Gdx.files.internal(asset1));
        AnimationRenderComponent testAnimator = new AnimationRenderComponent(atlas);

        ObjectSet<Texture> texture = atlas.getTextures();
        String tex = texture.toString();
        assertEquals("{test/files/mpcAnimation.png}",tex);

        testAnimator.addAnimation("main_player_run", 1f);
        assertTrue(testAnimator.hasAnimation("main_player_run"));
        ...
        assertNotNull(atlas.findRegion("main_player_run"));
        assertTrue(testAnimator.hasAnimation("main_player_run"));

Generated Texture atlas

mpcAnimation.atlas

mpcAnimation.png
size: 4096, 2048
format: RGBA8888
filter: Nearest, Nearest
repeat: none
main_player_attack
  rotate: false
  xy: 2, 1089
  size: 542, 542
  orig: 542, 542
  offset: 0, 0
  index: 1
main_player_attack
  rotate: false
  xy: 2, 545
  size: 542, 542
  orig: 542, 542
  offset: 0, 0
  index: 3
main_player_attack
  rotate: false
  xy: 546, 1089
  size: 542, 542
  orig: 542, 542
  offset: 0, 0
  index: 2
main_player_crouch
  rotate: false
  xy: 3262, 1090
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 2
main_player_crouch
  rotate: false
  xy: 3261, 547
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 1
main_player_front
  rotate: false
  xy: 1088, 3
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: -1
main_player_jump
  rotate: false
  xy: 546, 546
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 2
main_player_jump
  rotate: false
  xy: 2176, 1090
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 1
main_player_jump
  rotate: false
  xy: 1632, 547
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 3
main_player_pickup
  rotate: false
  xy: 2, 2
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 1
main_player_pickup
  rotate: false
  xy: 1633, 1090
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 3
main_player_pickup
  rotate: false
  xy: 1089, 546
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 2
main_player_pickup
  rotate: false
  xy: 2718, 547
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 4
main_player_right
  rotate: false
  xy: 1631, 3
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: -1
main_player_run
  rotate: false
  xy: 2719, 1090
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 2
main_player_run
  rotate: false
  xy: 2175, 547
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 1
main_player_walk
  rotate: false
  xy: 1090, 1090
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 2
main_player_walk
  rotate: false
  xy: 545, 2
  size: 541, 541
  orig: 541, 541
  offset: 0, 0
  index: 1

UML Diagrams

Class Diagram

Player Factory + PlayerActions + PlayerAnimationController + KeyboardPlayerInputComponent

**Player Animation Manager Classes **

Sequence Diagrams

animateAttack

animateCrouch

animateWalk

animateRight

animateJump

animatePickUp

PlayerActions - create()

PlayerAnimationController - create()

Relevant Files

mpcAnimation.atlas

mpcAnimation.png

PlayerFactory.java

PlayerActions.java

PlayerAnimationController.java

KeyboardPlayerInputComponent.java

PlayerAnimationAtlasTest.java

⚠️ **GitHub.com Fallback** ⚠️