Skip to content

Archived on 2026-10-24. The Godot rewrite is cancelled. Migration decisions and work checklists below are withdrawn. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

Player System

Purpose

The player system controls character setup, movement, input, target tracking, weapons, damage/shields/death, stats, item collection, companions, and HUD-facing state.

Current Unity Implementation

Main scripts:

Path Script Role
Assets/Script/Game/Entities/Player/Core/Player.cs Player Player core: character application, movement, target list, damage, death, regen, effects.
Assets/Script/Game/Entities/Player/Stats/PlayerModifier.cs PlayerModifier Base/shop/upgrade/temp stat calculation.
Assets/Script/Game/Entities/Player/Weapons/PlayerWeapon.cs PlayerWeapon Aim, reload, firing, damage calculation, ability attack modifiers.
Assets/Script/Game/Entities/Player/Combat/PlayerAttack.cs PlayerAttack Projectile/hitbox behavior.
Assets/Script/Game/Entities/Player/Collectibles/PlayerCollectItem.cs PlayerCollectItem Magnet/collection list and item reward handling.
Assets/Script/Game/Entities/Player/Presentation/StatusPanel.cs StatusPanel Player HUD stats, HP/stamina, reload/cooldown display.
Assets/Script/Game/Entities/Player/Core/AbilityHolder.cs AbilityHolder Player ability state and behavior.
Assets/Script/Shared/ScriptableObjects/Character.cs Character Character base data.
Assets/Script/Game/GameSystem/Player/PlayerManager.cs PlayerManager Run XP/level and player array.

Key Data

Character fields used by player setup:

  • id, charName, weapon, animator, icon, ability.
  • Base stats: health, stamina, stamina regen, dash stamina/speed/duration, crit damage/chance, movement speed, skill amp, damage taken, attack range, vampiric power/chance.
  • Audio/UI/progression: footstep, portrait, tags, difficulty, unlock data, price.

Player key fields:

  • playerNumber.
  • Components: modifier, abilityHolder, collectItem, weapons, abilityPanel.
  • Current resources: CurrentHealth inherited from Entity, currentStamina, potionAmount.
  • Targeting: nearestEnemies, IsFindEnemy, LastHorizontalInput.
  • State: IsInvulnerable, Speed, potion/stamina max flags.

PlayerModifier key stat groups:

  • Base stats copied from character/weapon.
  • Final stats recalculated from base + shop + upgrades + temporary ability modifiers.
  • Bonus stats from upgrades.
  • Shop stats from GameSession.Instance.modifiers.
  • Ability-specific modifiers: tacticalFireMultiplier, runandGunMultiplier, bloodThirstPower, meditateValue, stellarShieldSAMP, etc.

Runtime Flow

Character Setup

  1. GameInitialization.PreparePlayer() activates selected player objects.
  2. Player.ApplyCharacter() instantiates selected Character.weapon under the weapon parent.
  3. Weapon calls SetWeaponInStartAfterSpawned.
  4. Footstep sound and animator are assigned from the character asset.
  5. PlayerModifier.SetupPlayer() copies base stats from character and weapon and reads shop modifiers from GameSession.
  6. AbilityHolder.PlayerSettingsAbilityFirstTime() adds the character ability and initializes ability-specific starting objects.

Movement and Targeting

  1. Every Player.Update() calls Movement, resource regen, feedback/effects, invulnerability timer, CC timer, and target update.
  2. InputManagement() reads joystick first, then keyboard axes.
  3. Movement is normalized and applied to Rigidbody2D.linearVelocity unless dashing.
  4. Dash direction is prepared in abilityHolder.dashForce.
  5. Enemy target list is event-driven:
  6. GameEvents.AddTarget adds hitpoints for spawned enemies.
  7. GameEvents.RemoveTarget removes dead/despawned enemies.
  8. UpdateEnemyLocations() updates effective distance for every tracked hitpoint and sorts by distance.
  9. GetTargetByPriority() returns a hitpoint by priority or a cursor fallback outside the camera.

Weapon and Attack

  1. PlayerWeapon.Update() updates UI, aims weapon at selected target, ticks reload/attack timers, and checks readiness.
  2. Ready checks require:
  3. not dashing,
  4. not paused,
  5. target exists,
  6. target in range,
  7. not blocked by character exclusive weapon rules,
  8. ammo and reload are valid,
  9. attack speed timer expired.
  10. FireWeapon() triggers animation/audio, runs ability hooks, spawns attack, and applies multishot.
  11. AttackModify() writes damage, crit result, player reference, spell amp, and many ability flags onto PlayerAttack.
  12. PlayerAttack.OnTriggerEnter2D() applies damage and secondary effects.

Damage and Death

Player.TakeDamage() is very large. It handles:

  • ProtoBarrier reflection and shield threshold.
  • Emergency Barrier block/explosion.
  • Stellar Shield block/explosion.
  • Tidal Veil stack break.
  • Reload Shield absorption.
  • Damage reduction floor.
  • Unique Constitution stamina conversion.
  • Emergency shield prevention of lethal damage.
  • Actual HP loss unless Last Stand is active.
  • Thorn/ET armor reflection.
  • Survival Fitness stamina.
  • Adrenaline Rush, Rebuke, BloodThirst, FinalForm, FirstAid, FleeBoots, PanicFrenzy, ETArmor, Judgement, Jet Propulsion, Enrage, EmergencyShield triggers.
  • Last Stand replacement death state.
  • Invulnerability duration based on damage size.
  • Death disables player and asks GameManager.CheckGame().

Item Collection

  1. Items fire CollectibleSpawned/CollectibleDisabled.
  2. PlayerCollectItem maintains a list of collectibles.
  3. Every frame, it checks distance to each collectible and calls IsCollecting when within magnet radius.
  4. Items.Update() moves toward its target and triggers collection when close.
  5. PlayerCollectItem.ItemTrigger() handles reward by item type:
  6. chest/boss chest enqueue reward,
  7. coin grants XP/soul and counters,
  8. potions restore HP/stamina or apply temporary ability flags/effects,
  9. gem grants random stat.

Dependencies

  • Player depends on GameManager, GameSession, GameEvents, InputManager, AbilityFunction, PoolManager, AudioResources, Game.Audio.
  • PlayerModifier depends on GameManager, GameSession, AbilityFunction, player weapon data, shop modifiers.
  • PlayerWeapon depends on Player, PlayerModifier, AbilityHolder, PoolManager, AbilityFunction, GameManager.
  • PlayerCollectItem depends on Items, GameManager, AbilityFunction, GameEvents, Difficulty.

Problems / Risks

  • Player is too broad: movement, targeting, damage, shields, resources, and feedback.
  • Player.TakeDamage() contains many ability effects that should belong to damage/ability components.
  • Target sorting every frame can become expensive if there are many enemies and hitpoints.
  • ResetEnemyLocation() uses GameObject.FindGameObjectsWithTag.
  • PlayerCollectItem.Update() checks every collectible every frame for each player.
  • PlayerModifier.Update() recalculates final stats every frame.
  • PlayerWeapon.AttackModify() is another large ability switch implemented as many CheckAbility branches.
  • PlayerAttack carries many boolean effect flags, which makes combinations fragile.

Migration Notes for Godot

Preserve:

  • One/two player support.
  • Character base stats and weapon setup.
  • Target-priority behavior.
  • Dash/stamina/invulnerability rules.
  • Stat formulas where player-facing balance depends on them.
  • Item magnet and reward behavior.
  • Shield/damage order, especially because it affects survivability.

Redesign:

Player
- owns high-level state and child components

PlayerMovement
- input and movement velocity

PlayerStats
- base stats, modifiers, final stat calculation

HealthComponent
- damage pipeline and death

TargetSensor
- event-driven enemy/hitpoint registry and priority lookup

WeaponController
- fire/reload/aim

AbilityRunner
- listens to player/weapon/damage events

CollectibleCollector
- magnet and pickup behavior

Do not copy:

  • Damage ability effects embedded directly in Player.TakeDamage.
  • Per-frame stat recalculation without dirty flags.
  • Per-frame target sorting if a spatial query or throttled sorting can preserve behavior.

Open Questions

  • Exact stat formula compatibility requirements for the rebuild.
  • Whether target priority should consider enemy hitpoint size exactly as Unity does.
  • Which player abilities are character-default versus upgrades.
  • Unknown / needs manual confirmation.