2D Character Movement Pack

Visão Geral

Este pacote entrega um personagem 2D jogável e completo: movimento de corrida/pulo com controle aéreo, pulo e dash com buffer de input, um sistema de combo corpo-a-corpo 2D com hitboxes e dano, um componente de vida com knockback e ganchos de defesa, animações de reação a hit, e efeitos leves de "game feel" (hit-stop, tremor de câmera, slow motion) — sem nenhuma dependência de terceiros.

Todos os scripts vivem sob o namespace CloudedStudio.CharacterPack2D e são compilados em sua própria assembly (CloudedStudio.CharacterPack2D.asmdef), então eles não vão deixar a compilação do seu projeto mais lenta e não vão colidir com os nomes das suas próprias classes.

Conteúdo do Pacote

Início Rápido

O caminho mais rápido para ter um player que se move, pula e ataca. Cada passo é detalhado depois em sua própria seção — siga os links se algo não funcionar.

1. Crie um GameObject de player com um Rigidbody2D (Body Type: Dynamic, Gravity Scale ~3-5, Freeze Rotation Z) e um Collider2D sem trigger para o corpo.
2. Adicione CharacterGroundChecker, CharacterMovement, PlayerJump e PlayerController — veja Movimento & Pulo.
3. Adicione um componente PlayerInput (pacote Input System) e CharacterInputController — veja Configuração de Input.
4. Adicione um Animator com os parâmetros exigidos e PlayerAnimationStatesController — veja Configuração do Animator.
5. (Opcional) Adicione CharacterDashRoll para ter dash — veja Dash / Rolada.
6. Construa as hitboxes de ataque como objetos filhos e adicione CharacterHitboxController + MeleeDamageDealer — veja Combate & Hitboxes.
7. Adicione HealthComponent ao player (e a qualquer outra coisa que deva poder receber dano) — veja Vida & Dano.
8. (Opcional) Adicione os componentes de FX para feedback de impacto — veja Feedback de Hit.

Controles Padrão

As cenas de demonstração incluídas (Demo/PlayerSampleScene.unity e Demo/PlayerPrototypeSampleScene.unity) já vêm com um asset PlayerInputs.inputactions pronto para uso. Estas são as teclas padrão configuradas:

Esses binds estão definidos inteiramente dentro do PlayerInputs.inputactions — abra-o no editor de Input Actions caso queira adicionar, remover ou remapear alguma tecla.

Movimento & Pulo

Componentes obrigatórios

Campos do CharacterGroundChecker

Campos do CharacterMovement

Campos do PlayerJump / CharacterJump

Conecte seu botão de pulo para chamar PlayerJump.Jump() ao pressionar e PlayerJump.CutJump() ao soltar — isso é feito automaticamente se você usar o CharacterInputController (veja a próxima seção).

Configuração de Input

O CharacterInputController conecta o Input System da Unity aos componentes de movimento/pulo/dash/ataque. Ele depende do comportamento de notificação Send Messages do componente PlayerInput, então não há conexão manual de eventos.

1. Adicione um componente PlayerInput (do pacote Input System) ao GameObject do player.
2. Defina seu Behavior como Send Messages.
3. Atribua (ou crie) um Input Actions asset com um action map Player contendo estas ações:

   Nome da ação	Tipo	Binding sugerido
   Move	Value / Vector2 (composto 2D Vector, ou um stick de gamepad)	WASD / Stick Esquerdo
   Jump	Button — adicione uma Interaction "Press" definida como "Press and Release" (veja o aviso abaixo)	Espaço / Botão Sul
   Dash	Button	Shift Esquerdo / Botão Leste
   Attack	Button	Botão Esquerdo do Mouse / Botão Oeste

4. Adicione CharacterInputController ao mesmo GameObject. Seus campos de referência se preenchem automaticamente via GetComponent no Reset se deixados vazios. Defina Action Map Name para corresponder ao action map criado acima (padrão: "Player").

Usando o Input Actions asset "Project-wide"

Se você atribuir o asset Project-wide Actions da Unity (Project Settings > Input System Package) ao PlayerInput, o Inspector vai exibir o aviso:

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.

Isso acontece porque o asset Project-wide é uma única instância compartilhada, então por padrão todos os action maps que ele contém (Player, UI, qualquer outro que você tenha definido) ficam ativos ao mesmo tempo — um input destinado a um menu poderia "vazar" para o gameplay, e vice-versa. Esse é um comportamento conhecido do Input System, não é específico deste pacote.

O CharacterInputController já trata isso para você: ao ser habilitado, ele desativa todo action map em PlayerInput.actions e reativa apenas o que estiver no campo Action Map Name — exatamente a solução que o aviso da Unity recomenda. Você pode ignorar o aviso com segurança assim que este componente estiver presente. Se preferir não ver o aviso de forma alguma, crie um Input Actions asset dedicado para este personagem em vez de usar o Project-wide (o Project Settings continua permitindo que outros sistemas usem suas próprias actions project-wide de forma independente).

Dash / Rolada opcional

Adicione CharacterDashRoll ao player (exige CharacterMovement e CharacterJump no mesmo GameObject). É acionado automaticamente pela ação de input Dash se você estiver usando o CharacterInputController, ou chame CharacterDashRoll.TriggerDash() você mesmo.

Pressionar a direção oposta no meio do dash o interrompe imediatamente e dispara os triggers de Animator DashTurn/DashTurnBack (veja a próxima seção).

Configuração do Animator

O PlayerAnimationStatesController atualiza os parâmetros do seu Animator Controller a cada frame com base no estado de movimento/combate, e expõe métodos que você chama a partir de Animation Events para controlar as hitboxes. Adicione-o ao player junto com um componente Animator.

Parâmetros obrigatórios

Ataques, virada e corrida não são controlados por parâmetros do tipo Trigger — PlayerAnimationStatesController chama Animator.Play(...) diretamente em um estado de relay para os ataques, e nos estados "Player-Turn" / "Player-TurnBack" / "Player-Run" para as mudanças de direção. Nomeie esses estados de acordo (ou atualize as chamadas correspondentes de Animator.StringToHash(...) no script, se preferir usar seus próprios nomes).

Estados de Ataque & Bloqueio de Movimento

Animation Events de Hitbox

PlayerAnimationStatesController expõe dois métodos genéricos — ActivateHitbox(string hitboxId) e DeactivateHitbox(string hitboxId) — em vez de um par de método fixo por ataque. Adicione um Animation Event em cada clip de ataque no frame em que a hitbox deve ativar, selecione ActivateHitbox na lista de funções, e digite o Id da hitbox (ex.: Punch01) no campo de parâmetro string do evento. Adicione um segundo evento no frame em que deve desativar, selecionando DeactivateHitbox com a mesma string de Id.

Essas strings de Id correspondem às strings Id de hitbox usadas em Combate & Hitboxes abaixo — é exatamente o mesmo valor, só digitado no campo de parâmetro do Animation Event em vez de um nome de método.

Combate & Hitboxes

1. Monte a hierarquia de hitboxes

Crie um GameObject filho por ataque sob o player, cada um com um componente CharacterHitbox e um ou mais shapes de Collider2D em modo trigger, dimensionados para esse ataque:

CharacterHitbox define automaticamente todos os seus colliders como isTrigger = true e começa desativada; você não precisa desabilitar os colliders manualmente.

2. Adicione o controller e o aplicador de dano

Na raiz do player (mesmo GameObject que PlayerController), adicione:

CharacterHitboxController coleta automaticamente seus filhos CharacterHitbox se o array for deixado vazio no Inspector — você só precisa arrastá-los manualmente se quiser um subconjunto específico.

3. Configure o dano por ataque

Em MeleeDamageDealer, defina um dano/knockback/tipo padrão, e opcionalmente adicione overrides por hitbox:

4. Torne os alvos capazes de receber dano

Qualquer GameObject que as hitboxes devam afetar precisa de um HealthComponent (ou seu próprio componente implementando IDamageable) e, idealmente, um Rigidbody2D se você quiser que o knockback se aplique (HealthComponent já implementa IKnockbackable).

Pipeline completo de hit

CharacterHitbox (OnTriggerEnter2D)
   → CharacterHitboxController.OnAnyHit
       → MeleeDamageDealer.OnAnyHit
           → IDamageable.TakeDamage(DamageInfo)      no alvo
           → IKnockbackable.ApplyKnockback(...)      no alvo, se implementado
           → CharacterHitboxController.NotifyHitProcessed(...)
               → qualquer coisa escutando OnHitProcessed (PlayerHitCounter, HitConnectEffect, ...)

Vida & Dano

Adicione HealthComponent ao player e a qualquer inimigo/destrutível que deva poder receber dano.

Reagindo a eventos de vida

Outros sistemas devem assinar eventos em vez de fazer polling — por exemplo, uma UI de barra de vida:

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

Opcional: combo / sequência de hit no player

Invulnerabilidade & defesa (pontos de extensão)

HealthComponent.TakeDamage verifica automaticamente um componente IVariableVulnerability (ex.: PlayerController, que já implementa via Invulnerable()/Vulnerable()) e um componente IDefendable no mesmo GameObject, se presente. Chame PlayerController.Invulnerable() durante uma janela de dash ou hit-stun para tornar o player imune a dano, depois Vulnerable() para restaurar. Veja Estendendo: Interfaces para saber como adicionar seu próprio componente de bloqueio/parry via IDefendable.

Feedback de Hit (FX) opcional

Esses componentes adicionam "game feel" por cima do pipeline de combate acima. Nenhum deles é obrigatório para o combate funcionar — eles apenas reagem a eventos que já são disparados.

CameraShake2D

Um pequeno tremor autocontido — sem necessidade de Cinemachine ou outro pacote de câmera. Adicione à Transform que deve realmente se mover (sua Camera, ou a Transform de uma virtual camera do Cinemachine, caso você o utilize).

Chame cameraShake.Shake(amplitude, duration) você mesmo, ou atribua-o nos campos abaixo para que os efeitos incluídos o acionem automaticamente.

HitImpactEffect player recebe dano

Adicione ao mesmo GameObject que HealthComponent (o player). Toca um breve slow motion mais um tremor de câmera sempre que o player recebe dano efetivo.

HitConnectEffect ataque do player acerta

Adicione ao mesmo GameObject que CharacterHitboxController (o player). Mais sutil que o HitImpactEffect já que dispara com muito mais frequência — um hit-stop curto mais um pequeno tremor, e prefabs de VFX opcionais.

PlayerReceiveHitEffect player recebe dano, perspectiva do receptor

Adicione ao player junto com HealthComponent. Spawna um prefab de VFX em (ou perto de) o player quando ele recebe dano — diferente do HitConnectEffect, que é a perspectiva do atacante.

Referência de Scripts

Core

Movement

Player

Combat

Combat/FX

Animations

Estendendo: Interfaces

O sistema de combate é construído em torno de pequenas interfaces em Core/ para que você possa adicionar novos tipos de entidade (inimigos, destrutíveis, escudos) sem tocar nos scripts do pacote.

Tornar algo capaz de receber dano sem usar 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;
    }
}

Adicionar um componente de bloqueio/parry

Implemente IDefendable no mesmo GameObject que HealthComponent — ele será consultado automaticamente antes do dano ser aplicado:

using CloudedStudio.CharacterPack2D.Core;

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

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

Invulnerabilidade customizada

PlayerController já implementa IVariableVulnerability. Para uma entidade que não seja o player, implemente você mesmo:

using CloudedStudio.CharacterPack2D.Core;

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

Tabela de Eventos

Solução de Problemas

O player não pula, ou pula de forma inconsistente.

Verifique se Ground Layer no CharacterGroundChecker inclui suas layers de chão/plataforma, e se o Collider2D do player não está marcado como trigger. Se o player ficar preso em paredes durante um pulo, garanta que ambos os campos de PhysicsMaterial2D estão atribuídos e que Dynamic Friction está ativado.

Os métodos do CharacterInputController nunca são chamados.

Confirme que o Behavior do componente PlayerInput está definido como Send Messages, e que as ações do seu action map estão nomeadas literalmente como Move, Jump, Dash, Attack (o PlayerInput deriva o nome da mensagem — OnMove, etc. — a partir do nome da ação).

O pulo sempre atinge a mesma altura, mesmo se eu soltar o botão rapidamente.

Isso significa que OnJump só está recebendo o press, nunca o release. Confirme com um teste rápido: adicione temporariamente Debug.Log(value.isPressed) dentro de CharacterInputController.OnJump — se o Console só mostrar True e nunca False, a action Jump não tem nenhuma Interaction atribuída, o que usa por padrão uma Interaction implícita Press no modo Press Only (sem fase Canceled no release). Adicione uma Interaction Press à action Jump e defina seu Trigger Behavior como Press and Release — veja o aviso em Configuração de Input.

As hitboxes nunca causam dano.

Verifique, em ordem: o Target Layers da hitbox inclui a layer do alvo; o alvo tem um Rigidbody2D ou o collider da hitbox consegue resolver o GameObject raiz do alvo diretamente; o alvo tem um componente implementando IDamageable (ex.: HealthComponent); o Animation Event está realmente chamando Activate("SeuId") no frame correto (avance o clip na janela de Animation para verificar).

Parâmetros do Animator geram avisos de "parameter does not exist".

Adicione todo parâmetro listado em Configuração do Animator ao seu Animator Controller — PlayerAnimationStatesController os define a cada frame independentemente de sua state machine usá-los atualmente.

O dano não é reduzido mesmo tendo anexado um componente de defesa/invulnerabilidade.

HealthComponent busca IDefendable / IVariableVulnerability via GetComponent no próprio GameObject — garanta que seu componente customizado está no mesmo GameObject que HealthComponent, não em um filho ou pai.

Time.timeScale fica travado abaixo de 1.

Isso pode acontecer se um GameObject com HitImpactEffect ou HitConnectEffect for destruído no meio do efeito fora do fluxo normal (ex.: parar o Play Mode enquanto uma coroutine está em execução). Ambos os scripts resetam Time.timeScale em OnDestroy, mas se você notar isso travado depois de uma parada abrupta, basta entrar e sair do Play Mode uma vez.

Perguntas Frequentes

Preciso do pacote Input System?

Apenas se você usar o CharacterInputController. Todos os outros scripts reagem a chamadas de método simples (Jump(), TriggerDash(), SetMovementInput(...), SetAttack()) — conecte-as a partir do Input Manager legado ou da sua própria solução de input, se preferir.

Posso usar isto para um inimigo em vez do player?

Os scripts de movimento/pulo/dash/combate não são exclusivos do player, exceto PlayerController, PlayerJump, PlayerHitCounter, PlayerHitSequence e PlayerAnimationStatesController, que assumem um único personagem controlado. Para um inimigo, controle CharacterMovement/CharacterJump/CharacterHitboxController/MeleeDamageDealer diretamente a partir do seu script de IA, em vez de via PlayerController.

Como adiciono um 5º ataque de combo?

Aumente o Combo Length em PlayerController, adicione o novo filho CharacterHitbox + estado de Animator + Animation Events, e adicione um par de métodos Activate/Deactivate correspondente em PlayerAnimationStatesController seguindo o padrão existente.

Por que não há sistema de target-lock / avanço até um inimigo?

Isso está intencionalmente fora do escopo deste pacote — é um controlador de personagem 2D de uso geral, não vinculado a nenhum design de targeting específico. Construa seu próprio sistema de targeting sobre o pipeline do MeleeDamageDealer se o seu jogo precisar disso.

Changelog