2D Character Movement Pack

Overview

This pack gives you a fully working 2D player character: run/jump movement with air control, a buffered jump and dash, a 2D melee combo system with hitboxes and damage, a health component with knockback and defense hooks, hit-reaction animations, and lightweight "game feel" effects (hit-stop, camera shake, time slow) — with zero third-party dependencies.

All scripts live under the namespace CloudedStudio.CharacterPack2D and are compiled into their own assembly (CloudedStudio.CharacterPack2D.asmdef), so they won't slow down your project's compile times and won't collide with your own class names.

Package Contents

Quick Start

The fastest path to a moving, jumping, attacking player. Each step is expanded later in its own section — follow the links if something isn't working.

1. Create a player GameObject with a Rigidbody2D (Body Type: Dynamic, Gravity Scale ~3-5, Freeze Rotation Z) and a trigger-free Collider2D for the body.
2. Add CharacterGroundChecker, CharacterMovement, PlayerJump and PlayerController — see Movement & Jump.
3. Add a PlayerInput component (Input System package) and CharacterInputController — see Input Setup.
4. Add an Animator with the required parameters and PlayerAnimationStatesController — see Animator Setup.
5. (Optional) Add CharacterDashRoll for a dash — see Dash / Roll.
6. Build your attack hitboxes as child objects and add CharacterHitboxController + MeleeDamageDealer — see Combat & Hitboxes.
7. Add HealthComponent to the player (and to anything else that should be damageable) — see Health & Damage.
8. (Optional) Add the FX components for hit feedback — see Hit Feedback.

Default Controls

The included demo scenes (Demo/PlayerSampleScene.unity and Demo/PlayerPrototypeSampleScene.unity) ship with a ready-to-use PlayerInputs.inputactions asset. These are the default keyboard bindings:

These bindings are defined entirely inside PlayerInputs.inputactions — open it with the Input Actions editor if you want to add, remove or rebind any of them.

Movement & Jump

Required components

CharacterGroundChecker fields

CharacterMovement fields

PlayerJump / CharacterJump fields

Wire your jump button to call PlayerJump.Jump() on press and PlayerJump.CutJump() on release — this is handled automatically if you use CharacterInputController (see next section).

Input Setup

CharacterInputController bridges Unity's Input System to the movement/jump/dash/attack components. It relies on the PlayerInput component's Send Messages notification behavior, so there is no manual event wiring.

1. Add a PlayerInput component (from the Input System package) to the player GameObject.
2. Set its Behavior to Send Messages.
3. Assign (or create) an Input Actions asset with a Player action map containing these actions:

   Action name	Type	Suggested binding
   Move	Value / Vector2 (2D Vector composite, or a Gamepad stick)	WASD / Left Stick
   Jump	Button — add a "Press" Interaction set to "Press and Release" (see note below)	Space / South Button
   Dash	Button	Left Shift / East Button
   Attack	Button	Left Mouse Button / West Button

4. Add CharacterInputController to the same GameObject. Its reference fields auto-fill via GetComponent on Reset if left empty. Set Action Map Name to match the action map you created above (default: "Player").

Using the Project-wide Input Actions asset

If you assign Unity's Project-wide Actions asset (Project Settings > Input System Package) to PlayerInput, the Inspector will warn:

Project-wide actions asset is not recommended to be used with Player Input
because it is a singleton reference and all actions maps are enabled by
default. You should manually disable all action maps on Start() and
manually enable the default action map.

This happens because the Project-wide asset is a single shared instance, so by default every action map on it (Player, UI, anything else you've defined) is active at once — input meant for a menu could leak into gameplay and vice versa. This is a known Input System behavior, not specific to this pack.

CharacterInputController already handles this for you: on enable, it disables every action map on PlayerInput.actions and re-enables only the one named in its Action Map Name field — exactly the workaround Unity's warning recommends. You can safely ignore the warning once this component is present. If you'd rather not see the warning at all, create a dedicated Input Actions asset for this character instead of using the Project-wide one (Project Settings still lets other systems use their own project-wide actions independently).

Dash / Roll optional

Add CharacterDashRoll to the player (it requires CharacterMovement and CharacterJump on the same GameObject). Triggered automatically by the Dash input action if you're using CharacterInputController, or call CharacterDashRoll.TriggerDash() yourself.

Pressing the opposite direction mid-dash interrupts it early and fires the DashTurn/DashTurnBack Animator triggers (see next section).

Animator Setup

PlayerAnimationStatesController drives your Animator Controller's parameters every frame from movement/combat state, and exposes methods you call from Animation Events to drive hitboxes. Add it to the player alongside an Animator component.

Required parameters

Attacks, turning and running aren't driven by Trigger parameters — PlayerAnimationStatesController calls Animator.Play(...) directly on a relay state for attacks, and on the "Player-Turn" / "Player-TurnBack" / "Player-Run" states for facing changes. Name those states accordingly (or update the corresponding Animator.StringToHash(...) calls in the script if you'd rather use your own names).

Attack States & Movement Lock

Hitbox Animation Events

PlayerAnimationStatesController exposes two generic methods — ActivateHitbox(string hitboxId) and DeactivateHitbox(string hitboxId) — instead of one hardcoded method pair per attack. Add an Animation Event on each attack clip at the frame the hitbox should turn on, pick ActivateHitbox from the function list, and type the hitbox's Id (e.g. Punch01) into the event's string parameter field. Add a second event at the frame it should turn off, picking DeactivateHitbox with the same Id string.

These Id strings match the hitbox Id strings used in Combat & Hitboxes below — they're exactly the same value, just typed into the Animation Event's parameter field instead of a method name.

Combat & Hitboxes

1. Build the hitbox hierarchy

Create one child GameObject per attack under the player, each with a CharacterHitbox component and one or more trigger Collider2D shapes sized for that attack:

CharacterHitbox automatically sets all its colliders to isTrigger = true and starts deactivated; you don't need to disable the colliders by hand.

2. Add the controller and damage dealer

On the player root (same GameObject as PlayerController), add:

CharacterHitboxController auto-collects its CharacterHitbox children if the array is left empty in the Inspector — you only need to drag them in manually if you want a specific subset.

3. Configure damage per attack

On MeleeDamageDealer, set a default damage/knockback/type, then optionally add per-hitbox overrides:

4. Make targets damageable

Any GameObject the hitboxes should affect needs a HealthComponent (or your own component implementing IDamageable) and ideally a Rigidbody2D if you want knockback to apply (HealthComponent implements IKnockbackable already).

Full hit pipeline

CharacterHitbox (OnTriggerEnter2D)
   → CharacterHitboxController.OnAnyHit
       → MeleeDamageDealer.OnAnyHit
           → IDamageable.TakeDamage(DamageInfo)      on the target
           → IKnockbackable.ApplyKnockback(...)      on the target, if it implements it
           → CharacterHitboxController.NotifyHitProcessed(...)
               → anything listening to OnHitProcessed (PlayerHitCounter, HitConnectEffect, ...)

Health & Damage

Add HealthComponent to the player and to any enemy/destructible that should be able to take damage.

Reacting to health events

Other systems should subscribe to events instead of polling — for example a health bar UI:

void Start()
{
    var health = player.GetComponent<HealthComponent>();
    health.OnHealthChanged += (current, max) => healthBar.fillAmount = current / max;
    health.OnDied += info => PlayDeathSequence();
}

Optional: combo / hit sequencing on the player

Invulnerability & defense (extension points)

HealthComponent.TakeDamage automatically checks for an IVariableVulnerability component (e.g. PlayerController, which already implements it via Invulnerable()/Vulnerable()) and an IDefendable component on the same GameObject, if present. Call PlayerController.Invulnerable() during a dash or hit-stun window to make the player immune to damage, then Vulnerable() to restore it. See Extending: Interfaces for how to add your own block/parry component via IDefendable.

Hit Feedback (FX) optional

These add "game feel" on top of the combat pipeline above. None of them are required for combat to function — they only react to events already being fired.

CameraShake2D

A small self-contained shake — no Cinemachine or other camera package required. Add it to whichever Transform should actually move (your Camera, or a Cinemachine virtual camera's Transform if you do use Cinemachine).

Call cameraShake.Shake(amplitude, duration) yourself, or assign it to the fields below so the included effects drive it automatically.

HitImpactEffect player takes damage

Add to the same GameObject as HealthComponent (the player). Plays a brief time-slow plus a camera shake whenever the player takes effective damage.

HitConnectEffect player's attack lands

Add to the same GameObject as CharacterHitboxController (the player). More subtle than HitImpactEffect since it fires far more often — a short hit-stop plus a small shake, and optional VFX prefabs.

PlayerReceiveHitEffect player takes damage, receiver's perspective

Add to the player alongside HealthComponent. Spawns a VFX prefab at (or near) the player when they take damage — distinct from HitConnectEffect, which is the attacker's perspective.

Script Reference

Core

Movement

Player

Combat

Combat/FX

Animations

Extending: Interfaces

The combat system is built around small interfaces in Core/ so you can add new entity types (enemies, breakables, shields) without touching the pack's scripts.

Make something damageable without using HealthComponent

using CloudedStudio.CharacterPack2D.Core;

public class BreakableCrate : MonoBehaviour, IDamageable
{
    [SerializeField] private float maxHealth = 20f;
    private float current;

    public float CurrentHealth => current;
    public float MaxHealth => maxHealth;
    public bool IsDead => current <= 0f;

    private void Awake() => current = maxHealth;

    public float TakeDamage(DamageInfo info)
    {
        float applied = Mathf.Min(info.Amount, current);
        current -= applied;
        if (IsDead) Destroy(gameObject);
        return applied;
    }
}

Add a block/parry component

Implement IDefendable on the same GameObject as HealthComponent — it will be consulted automatically before damage is applied:

using CloudedStudio.CharacterPack2D.Core;

public class ShieldBlock : MonoBehaviour, IDefendable
{
    public bool IsBlocking;
    [Range(0f, 1f)] public float DamageReduction = 1f; // 1 = full block

    public DefenseResult TryDefend(DamageInfo info)
    {
        return IsBlocking
            ? DefenseResult.Success(info.Amount, DamageReduction)
            : DefenseResult.Failed(info.Amount);
    }
}

Custom invulnerability

PlayerController already implements IVariableVulnerability. For a non-player entity, implement it yourself:

using CloudedStudio.CharacterPack2D.Core;

public class EnemyController : MonoBehaviour, IVariableVulnerability
{
    public bool IsInvulnerable { get; private set; }
    public void SetInvulnerable(bool value) => IsInvulnerable = value;
}

Events Cheat Sheet

Troubleshooting

The player won't jump, or jumps inconsistently.

Check that Ground Layer on CharacterGroundChecker includes your ground/platform layers, and that the player's Collider2D isn't set to trigger. If the player sticks to walls during a jump, make sure both PhysicsMaterial2D fields are assigned and Dynamic Friction is enabled.

CharacterInputController's methods never get called.

Confirm the PlayerInput component's Behavior is set to Send Messages, and that your action map's actions are literally named Move, Jump, Dash, Attack (PlayerInput derives the message name — OnMove, etc. — from the action name).

The jump always reaches the same height, even if I tap the button briefly.

This means OnJump is only ever receiving the press, never the release. Confirm with a quick test: temporarily add Debug.Log(value.isPressed) inside CharacterInputController.OnJump — if the Console only ever shows True and never False, the Jump action has no Interaction assigned, which defaults to an implicit Press interaction in Press Only mode (no Canceled phase on release). Add a Press Interaction to the Jump action and set its Trigger Behavior to Press and Release — see the warning in Input Setup.

Hitboxes never deal damage.

Check, in order: the hitbox's Target Layers includes the target's layer; the target has a Rigidbody2D or the hitbox's collider can resolve the target's root GameObject directly; the target has a component implementing IDamageable (e.g. HealthComponent); the Animation Event is actually calling Activate("YourId") at the right frame (scrub the clip in the Animation window to verify).

Animator parameters throw "parameter does not exist" warnings.

Add every parameter listed in Animator Setup to your Animator Controller — PlayerAnimationStatesController sets them every frame regardless of whether your state machine currently uses them.

Damage isn't reduced even though I attached a defense/invulnerability component.

HealthComponent looks up IDefendable / IVariableVulnerability via GetComponent on its own GameObject — make sure your custom component is on the same GameObject as HealthComponent, not a child or parent.

Time.timeScale gets stuck below 1.

This can happen if a GameObject with HitImpactEffect or HitConnectEffect is destroyed mid-effect outside of normal play (e.g. stopping Play Mode while a coroutine is running). Both scripts reset Time.timeScale in OnDestroy, but if you see it stuck after a hard stop, just re-enter and exit Play Mode once.

FAQ

Do I need the Input System package?

Only if you use CharacterInputController. Every other script reacts to plain method calls (Jump(), TriggerDash(), SetMovementInput(...), SetAttack()) — wire those from the legacy Input Manager or your own input solution if you prefer.

Can I use this for an enemy instead of the player?

Movement/jump/dash/combat scripts are not player-locked except PlayerController, PlayerJump, PlayerHitCounter, PlayerHitSequence and PlayerAnimationStatesController, which assume a single controlled character. For an enemy, drive CharacterMovement/CharacterJump/CharacterHitboxController/MeleeDamageDealer directly from your AI script instead of from PlayerController.

How do I add a 5th combo attack?

Increase Combo Length on PlayerController, add the new CharacterHitbox child + Animator state + Animation Events, and add a matching Activate/Deactivate method pair in PlayerAnimationStatesController following the existing pattern.

Why is there no target-lock / lunge-to-enemy system?

That's intentionally out of scope for this pack — it's a general-purpose 2D character controller, not tied to any specific targeting design. Build your own targeting on top of MeleeDamageDealer's pipeline if your game needs it.

Changelog