Sci-Fi XP Hero Clone (Drop Zone) - Developer & Agent Overview

This project is a 3D mobile action RPG clone of XP Hero built in Unity. It features a futuristic sci-fi theme using Synty Studio Polygon low-poly assets and leverages a modular C# architecture.

---

🚀 Getting Started & Scene Assembly

The project includes an automated Editor Tool to compile and generate all materials, prefabs, upgrades, and scene hierarchies instantly.

To set up or reset the prototype scene:

1. Open the Unity Editor.
2. In the top menu, select: Tools -> XP Hero -> Setup Prototype Scene.
3. This editor script (SetupPrototypeScene.cs) will automatically:
   • Generate URP-compatible materials.
   • Instantiate prefabs (Cyborg_Enemy, Laser_Projectile, Support_Drone, and pickup drops).
   • Rebuild the complete scene hierarchy (Player_Hero with character meshes, Isometric_Camera, WaveSpawner, and CardUpgradeManager).
   • Find the character right hand bone, parent the weapon (SM_Wep_Rifle_01 prefab) to it, and automatically create a FirePoint child at the tip of the barrel.
   • Generate standard Roguelike Upgrade Cards.

---

🛠️ System Architecture

The game uses a modular, component-based C# design. All gameplay components are compiled into Game.asmdef.

1. Player & Controls

• PlayerController.cs:
  • Movement: Physics-based movement using a Rigidbody (manual velocity updates).
  • Rotation: Rotates towards movement direction when running freely, or locks rotation to target enemies when attacking.
  • Inputs: Multi-input support prioritizing Touch Virtual Joystick (Joystick Pack), falling back to Keyboard (WASD) and Gamepad.
  • Animation Driver: Feeds calculated parameters to the child Animator (details below).
• PlayerStats.cs:
  • Tracks run-time progression (HP, Max HP, XP, Level, Move Speed, Attack Speed, Damage).
  • Persistent progression is saved/loaded using PlayerPrefs.

2. Combat & Weapons

• PlayerCombat.cs:
  • Scans for the closest enemy within range of the active weapon.
  • Controls combat rotation (locking onto the target) and triggers the weapon auto-attack.
• Weapon.cs (Abstract Base):
  • Derives dynamic fire rate and damage modifiers from player stats.
  • RangedWeapon.cs: Spawns projectiles from a barrel-tip FirePoint and simulates procedural recoil kickback (pushing the model back and tilting it up).
  • MeleeWeapon.cs: Performs front-sweep overlap checks to damage targets in an arc.
• Projectile.cs:
  • Projectile physics and hit detection. Recycles itself back to the pool.
• SimplePool.cs:
  • Generic pooling system for recycling projectiles, enemies, and pick-ups.

3. Companions & Spawners

• DroneController.cs:
  • Companion drones orbit the player and auto-attack nearby targets independently.
• EnemySpawner.cs:
  • Configurable wave spawning system that handles scaling enemy difficulty and wave completion events.

4. Progression & UI

• CardUpgradeManager.cs:
  • Pauses the game on level up, selects 3 random unique cards (e.g. static upgrades or drone spawns), and applies them to the player.
• GameHUD.cs:
  • Links stats and game events directly to UI Sliders and Texts.

5. Floating Damage Numbers (DamageNumbersPro)

• DamageNumbersPro Integration:
  • Automatically displays world-space floating text when characters take damage.
  • Enemies: Spawns the Clear.prefab (loaded from Assets/DamageNumbersPro/Demo/Prefabs/3D/Clear.prefab) representing damage taken from the player or drones. Triggered inside EnemyController.TakeDamage.
  • Player: Spawns the Red Glow.prefab (loaded from Assets/DamageNumbersPro/Demo/Prefabs/3D/Red Glow.prefab) representing damage taken from enemies. Triggered inside PlayerStats.TakeDamage.
  • Auto-Assembly: Prefab references are loaded and serialized automatically by SetupPrototypeScene.cs.
  • Assembly Reference: Game.asmdef includes "DamageNumbersPro" in its references list.

---

🏃 Animation & Rigging Conventions

The player character uses a Synty Studio humanoid model (SM_Chr_SpaceSoldier_Helmet_Male_01) driven by the Julhiecio TPS Controller animation controller (AnimatorTPS Controller.controller).

Important Developer & Agent Gotchas:

1. Root Motion Interference:
   • The Animator uses applyRootMotion = true by default in the asset files.
   • Crucial: Because PlayerController.cs manually updates Rigidbody velocity, root motion must be disabled at runtime (animator.applyRootMotion = false) to prevent physics/animator fighting that freezes movement.
2. Override Layers weights:
   • The animator uses override layers for combat aiming stances: Legs Motion Layer (1) and Arms Motion Layer (4).
   • When the player is armed (combat mode), these weights must be set to 1.0f. Otherwise, the character will run with arms swinging by their sides while holding the weapon.
3. Dynamic Strafing Calculations:
   • In combat, the player locks orientation to face the nearest enemy while moving. This results in strafing (moving left, right, or backwards relative to facing direction).
   • In PlayerController.Update(), movement parameters must be converted into local player space using transform.InverseTransformDirection before feeding them to the animator:

     Vector3 relativeMove = transform.InverseTransformDirection(moveInput);
     animator.SetFloat("Horizontal", relativeMove.x);
     animator.SetFloat("Vertical", relativeMove.z);
     

   • This ensures the animator correctly blends strafe clips (Walk Left, Walk Forward Left, etc.) and avoids sliding/moonwalking.
4. Animator Parameter Mapping:
   • Ensure the following variables are pushed to the animator:
     • Grounded (Bool)
     • Moving (Bool)
     • Running (Bool)
     • Speed (Float)
     • Horizontal (Float) & Vertical (Float) - Calculated dynamically relative to player direction
     • ItemEquiped (Bool) - Set true for combat, false for unarmed
     • ItemsWieldingIdentifier (Int) - Set to 1 for rifle/blaster
     • ItemWieldingRightHandPoseID (Float) & ItemWieldingLeftHandPoseID (Float) - Set to 2f for rifle
     • FireMode (Bool) - Set true when aiming/shooting