Player Upgrade Overview

Upgrades are applied in the starting zone of each level, before any player movement begins. The player customizes their character through an interactive, grid-based UI, where modification parts can be placed, rearranged, and combined. Each part directly influences the character’s stats.

Interaction & Combination Rules

Interaction with elements is performed via drag & drop.

Elements that are eligible for combination are highlighted in green. If a combination is not available, the element is highlighted in red.

Element combination is available in two locations:

• The interactive upgrade board

• The player’s model

Combination on the Upgrade Board

On the board, elements can be combined only if:

• Their type matches

• Their level matches

Combination on the Player Model

On the player model, elements can be combined only if:

• Their type matches

• Their level matches

• The element type on the board is higher than the element type currently installed on the player

Prefabs involved in Player Upgrade Logic

The player upgrade system uses three main prefabs:

• PlayerGraphics Prefab path: Assets/StaticAssets/Prefabs/Units/PlayerGraphics.prefab Responsible for rendering and visual representation of the player character.

• Board For more details, [click here] Prefab path: Assets/StaticAssets/Prefabs/Board/Board.prefab The interactive grid-based field where parts are assembled and combined.

• Part For more details, [click here] The universal upgrade element prefab that is dragged, combined, and upgraded on the board and player.

PlayerGraphics Prefab

Prefab Structure

The PlayerGraphics prefab includes the following child elements, each responsible for visual representation of specific vehicle parts and their upgrade effects:

• Vehicle Visual representation of the vehicle body.

• Wheels Contains visuals for wheels at different upgrade levels.

  • ElectricalSparks — particle system played during part merging/upgrading.

  • Level Indicator — component showing the upgrade level of the wheels.

• Turrets Contains visuals for turrets at various upgrade levels.

  • ElectricalSparks — particle system for merging effects.

  • Trajectory — LineRenderer component displaying the laser sight/aim.

  • Level Indicator — displays the turret's upgrade level.

• Armors Contains visuals for armor parts at different levels.

  • ElectricalSparks — merging particle effects.

  • Level Indicator — shows armor upgrade level.

• Ammo Contains visual representation of ammo boxes.

  • ElectricalSparks — merge particle effects.

  • Level Indicator — displays ammo upgrade level.

• Rockets Contains visuals for rocket launcher parts.

  • ElectricalSparks — particle effects during upgrades.

  • Level Indicator — shows rocket upgrade level.

Components Overview

• ⚠️ BoxCollider — defines the physical boundaries of the player.

  • Monsters use this collider to apply damage.

  • The upgrade system uses it to detect hovering and interaction.

• PlayerGraphicsContext implements the IPlayerGraphicsContext interface and serves as the central access point to all visual and effect components of the player. It requires the following components on the same GameObject: ExplosionEffect, UpgradeLevelController.

• ExplosionEffect — handles explosion effects for player parts (Rigidbody + FragmentExplosionConfig). This component automatically finds child fragment handlers and applies the explosion when triggered.

• UpgradeLevelController — manages player part upgrade levels, synchronizes with player progress, and controls level indicators and upgrade effects.

• DamageFlashEffect — manages temporary white flash effects on player parts when taking damage. The effect is applied asynchronously, and the original materials are restored automatically after the flash.

Interaction Diagram (Summary)

PlayerGraphicsContext
│
├─ ExplosionEffect
│   └─ FragmentExplosionConfig, ExplosionEffectHandler[]
│
├─ UpgradeLevelController
│   └─ UpgradeLevelSwitcher[] → manages visual player parts
│
├─ DamageFlashEffect
│   └─ List<Renderer> → temporarily swaps materials to white
│
├─ Turret
├─ RocketLauncher
└─ PlayerGraphicsCollider

Component Parameters

• Turret — visual and logical turret elements.

• RocketLauncher — visual and logical rocket launcher elements.

• PlayerGraphicsCollider — collider for the entire player graphics object for interaction with the environment and physics.

---

• config — defines explosion parameters such as fragment count, spawn angles, radius, and rotation.

• origin — the reference point from which fragment trajectories are calculated.

---

• TargetRenderer — the list of Renderers whose material will flash.

• FlashDuration — the duration (in seconds) of a single flash phase.

• WhiteFlashMaterial — the material used for the flash effect.

Child Components

All player vehicle parts (Wheels, Turrets, Armors, Ammo, Rockets) include three core shared components: UpgradeLevelSwitcher, PartLevelController, and PartVisualsController.

The UpgradeLevelSwitcher acts as a bridge between a part’s logic (PartLevelController) and visuals (PartVisualsController).

• PartLevelController

  • Manages the part’s type and current level.

  • Determines upgrade eligibility.

  • Integrates with persistent player progress.

• PartVisualsController

  • Handles all visual aspects of the part.

  • Controls backlight previews.

  • Plays merge particle effects.

  • Updates level indicators.

• UpgradeLevelSwitcher

  • Coordinates the logic and visuals.

  • Initializes the part.

  • Updates level indicators.

  • Enables/disables backlights.

  • Plays upgrade effects.

Together, these components encapsulate a complete, modular upgrade element.

Class Relationship Scheme (Hierarchy & Interaction):

UpgradeLevelSwitcher
├── PartLevelController  // manages levels, upgrades, and progress
└── PartVisualsController // manages visual representation, backlights, particles, level indicators

PartLevelController
└── PartInfo (contains array of GameObjects per level)
└── IPersistentProgressService (checks player progress)

PartVisualsController
├── ParticleSystem mergeFX
├── LevelIndicator
├── Material greenMat / redMat
└── Handles activation/deactivation of parts, visual backlight logic, and animations

Interactions:

• UpgradeLevelSwitcher.Initialize(level) → sets the level in PartLevelController → finds the current part → passes it to PartVisualsController for visual setup.

• UpgradeLevelSwitcher.PlayUpgradeEffect() → triggers particle and scale animation in PartVisualsController.

• Backlight and level indicator display is dynamically managed by UpgradeLevelSwitcher based on upgrade eligibility determined by PartLevelController.

Vehicle

ExplosionInfo defines the list of vehicle parts that are detached and scattered when an explosion occurs.

• ExplosionInfo.ExplodeParts A list of Rigidbody components used for the physical simulation of the exploded parts.

• ExplosionInfo.ExplodeRenderer A list of MeshRenderer components used to display the visually burned or destroyed parts of the player’s vehicle.

---

All player vehicle parts (Wheels, Turrets, Armors, Rockets) share a common core component: ExplosionPart. The ExplosionPart class inherits from ExplosionEffectHandler and extends it by adding the following field:

[SerializeField] PartLevelController levelController;

• levelController Indicates which level controller the explosion system should use to process and handle this part during an explosion.

---

Turret

• Trajectory A LineRenderer used to visualize the projectile trajectory or aiming direction.

• TurretParts An array of TurretPart elements used to define turret rotation, firing point, firing components, ammo consumption, and firing mode.

Important: The order of elements in the array matters.

• HitMask A LayerMask that defines which layers are considered for hit detection (Raycast, SphereCast, etc.).

• TurretLevel Used to determine the level of the currently active turret.

---

Important: The positioning of the same turret may vary depending on the armor level.

• PrimaryPart The main part whose level determines the positioning logic.

• DependentPart The dependent part to which the transformation is applied.

• Orientations A container that stores transformation data.

Important: The order of elements in the array matters.

Ammo

• PartLevel Used to retrieve the current ammunition level.

• BulletAmount A reference to the visual element that displays the current ammo count.

---

• List A list of objects that will be moved by a specified offset over a defined duration before the level starts.

Rockets

• PartLevel Used to retrieve the current rocket level.

• RocketRenderer A list of MeshRenderer components used to update the visual appearance of the object based on its level.

• RocketColor A list of colors corresponding to each level. Important: The order of elements matters.

---

• Rockets Contains a list of rockets available for launch.