Upgraded Weapons - UQcsse3200/2026-studio-4 GitHub Wiki

Overview

This page covers the Weapon Upgrades feature: how a weapon becomes upgraded, what each upgrade grants, and how the work is tested.

  • The shared upgrade system — per-weapon upgrade stats and the heavy attack pipeline (Weapons, Weapon Upgrades).
  • The upgraded Sword: a 360° heavy spin on K, stronger light sweep, and a fancier blade sprite.
  • The upgraded Knife: a three-hit heavy flurry on K, and a fancier knife sprite.
  • The upgraded Bow: a three-arrow heavy volley on K, and a fancier arrow sprite.
  • The QA terminal command upgrade sword|knife|bow [off].

An upgrade never edits the player's shared weapon stats, so upgrading one weapon can never buff another. Every weapon also swaps to a fancier sprite while upgraded, so an upgrade is recognisable at a glance.

Testing is divided into automated unit tests (what the code must do) and manual gameplay tests (what the player must see and feel). Every behaviour listed in the automated plan is enforced by a test in the repository — the test class is named above each table.

Design Summary

An upgrade gives a weapon four things: more light-attack damage, a heavy attack on K, a longer shared cooldown when that heavy attack is used, and an upgraded sprite. Values live in WeaponUpgradeComponent on the player, keyed by weapon.

Weapon Light damage Heavy damage Heavy cooldown
Sword ×1.2 ×1.35 ×2 (1.0 s)
Knife ×1.2 ×0.6 per slash, ×1.2 for the finisher ×3 (1.5 s)
Bow ×1.2 — (3 arrows at ×1 each) ×2 (heavy attack duration is instant)

Every upgraded sprite is an unedited crop of the same CC0 steel-weapons.png sheet, drawn at the same angle as the base sprite, so swapping one needs no rendering changes. Grid cells are recorded in core/assets/licenses/OPENGAMEART-ATTRIBUTION.md.

Weapon Base sprite Upgraded sprite
Sword sword.png sword_upgraded.png — winged golden guard
Knife knife.png knife_upgraded.png
Bow throwing_knife.png throwing_knife_upgraded.png — winged blade with a blue gem

Upgraded Sword

Property Light (J) Heavy (K)
Arc 90°, centred on facing 360° around the player
Duration 0.25 s 0.8 s
Blade hitbox 1.0 × 0.4 1.0 × 0.4 (unchanged)
Damage at base attack 10 12 14
Sprite Upgraded winged sword while upgraded Same

Upgraded Knife

The heavy attack is a three-hit flurry, aimed where the player faced when K was pressed.

Strike Spawns at Duration Damage at base attack 10 Knockback
Slash 1 (right → left, 70°) 0.00 s 0.12 s 6 none
Slash 2 (left → right, 70°) 0.15 s 0.12 s 6 none
Finishing stab 0.30 s 0.15 s 12 1.5× the weapon's knockback

Only the finisher knocks back, so enemies stay in reach of all three hits. Switching weapons mid-flurry cancels the strikes still queued. While upgraded, the stab and every flurry strike are drawn with the upgraded knife sprite.

Upgraded Bow

The heavy attack fires three arrows at once instead of a stronger single one — the upgrade's power comes from arrow count, not per-arrow damage.

Property Light (J) Heavy (K)
Arrow count 1 3 (centre + ±15°)
Damage at base attack 10 12 10 per arrow
Each arrow's path Checked independently; a blocked shot despawns silently Same — a wall blocking the centre arrow does not stop the two side arrows
Sprite Upgraded arrow while upgraded Same, on all three arrows

Unlike the sword and knife, the bow's heavy attack has no separate hitbox shape or lifetime from the light shot — it is the same arrow, fired three times in a spread, each with its own wall check.

Test Environment

  • Unit testing: JUnit 5 and Mockito, run headlessly with the engine's GameExtension
  • Game testing: Desktop application
  • Light attack: J — Heavy attack: K — Movement: WASD
  • Debug terminal (F1) commands: weapon knife|sword|bow to equip; upgrade sword|knife|bow to apply an upgrade and upgrade sword|knife|bow off to revert; debug on to show hitbox outlines

Run all automated tests with:

cd source
./gradlew :core:test

Last verified run: 17 Sept 2026 on task/126-bow-sprite-change — 1178 tests, 0 failures.

Automated Unit Test Plan

Shared Upgrade System

WeaponUpgradeComponentTest

Test Purpose Expected Result
shouldNotBeUpgradedInitially Inspect a fresh component. Nothing is upgraded, and every multiplier reads 1, so unupgraded weapons behave exactly as before.
shouldApplySwordUpgradeStats / shouldApplyKnifeUpgradeStats / shouldApplyBowUpgradeStats Upgrade each weapon. The documented multipliers apply (sword 1.2 / 1.35 / 2, knife 1.2 / 0.6 / 3, bow 1.2 / 1 / 2).
shouldStayUpgradedWhenAppliedTwice Apply the same upgrade twice. Applying is idempotent — no stacking.
shouldRevertUpgrade / shouldRevertBowUpgrade Turn an upgrade off. The weapon returns to its unupgraded multipliers.
shouldNotAffectOtherWeapons Upgrade the sword, then read the knife and bow. Other weapons are untouched — the shared weapon stats are never modified.
shouldRejectWeaponWithoutUpgradeStats Upgrade a weapon with no upgrade defined (an explicit stats map with only the sword). Rejected rather than silently doing nothing.
shouldTriggerEventOnlyWhenUpgradeStateChanges Apply, re-apply, then revert. weaponUpgraded fires only on real changes — a hook for upgrade VFX.
shouldRejectNullStatsMap / shouldRejectNegativeUpgradeStats Construct with invalid values. IllegalArgumentException is thrown.

WeaponComponentTest

Test Purpose Expected Result
shouldHeavyAttackOnEventWhenUpgraded Fire the weaponHeavyAttack event on an upgraded weapon. The heavy attack runs, and the light attack does not.
shouldIgnoreHeavyAttackEventWhenNotUpgraded / shouldNotHeavyAttackWithoutUpgradeComponent / shouldNotHeavyAttackWithoutAHeavyAttack Fire the event in each unsupported case. Nothing spawns and no cooldown starts, so K is inert until a weapon is upgraded.
shouldIgnoreHeavyAttackEventWhenDisabled Fire the event on an unequipped weapon. Only the equipped weapon responds.
shouldTriggerScaledCooldownAndRespectItForHeavyAttacks Heavy attack twice in a row. The cooldown is multiplied by the upgrade value and blocks the second attempt.
shouldScaleLightAndHeavyDamageByUpgradeOnlyWhenUpgraded / shouldApplyExtraScaleOnTopOfHeavyUpgradeDamage Resolve damage before and after upgrading. Light and heavy damage each use their own multiplier, and combo finishers can scale further on top.
shouldRejectNullOriginOrDirectionForHeavyAttack Heavy attack with null arguments. IllegalArgumentException is thrown.

WeaponStatsComponentTest

Test Purpose Expected Result
shouldApplyExtraDamageScaleOnTopOfMultiplier Resolve damage with an upgrade scale. Damage is round(baseAttack × multiplier × scale), and the shared multiplier is left untouched.

UpgradeCommandTest

Test Purpose Expected Result
shouldUpgradeSword / shouldUpgradeAndRevertKnife / shouldUpgradeAndRevertBow Run upgrade <weapon> [off]. QA can apply and revert any weapon's upgrade without a pickup or shop.
shouldStayUpgradedWhenRunTwice Run the command twice. Idempotent.
shouldRevertSwordUpgradeWithOff Run upgrade sword off. The weapon returns to its Sprint 1 behaviour.
shouldRejectInvalidArguments / shouldFailWhenPlayerHasNoUpgradeComponent Run with bad arguments, or on a player with no upgrade component. The command reports failure instead of changing state.

KeyboardPlayerInputComponentTest and PlayerActionsTest

Test Purpose Expected Result
shouldTriggerHeavyAttackNotSpecialAttackOnK Press K. A dedicated heavyAttack event fires; specialAttack stays free for the abilities feature.
shouldTriggerHeavyWeaponAttackInFacingDirectionOnHeavyAttack Walk, stop, then heavy attack. The heavy attack uses the player's current facing.

Upgraded Sword

SwordWeaponComponentTest

Test Purpose Expected Result
shouldKeepSprintOneLightAttackWhenNotUpgraded / shouldRevertToSprintOneSwordWhenUpgradeRemoved Attack before upgrading, and after reverting. The unupgraded sword is unchanged in size, arc and damage.
shouldNotHeavyAttackWhenNotUpgraded Press the heavy attack before upgrading. Nothing spawns and no cooldown starts.
shouldBoostLightDamageButKeepItsSweepWhenUpgraded Light attack while upgraded. Same 90° arc and blade, more damage.
shouldHeavyAttackWithTheSameBladeWhenUpgraded Heavy attack while upgraded. The spin uses the same blade hitbox, swept by a SweepComponent.
shouldSpinTheHeavyAttackAFullTurnAroundTheWielder Step the spin from start to finish. It opens behind the player, passes through the facing direction halfway, and completes a full 360°.
shouldSpinTheHeavyAttackSlowerThanTheLightSweep Compare both attacks over the same time. The light sweep finishes while the spin is still going, so the full turn is readable.
shouldDealHeavyUpgradeDamage Heavy attack while upgraded. Damage uses the heavy multiplier, not the light one.
shouldLengthenTheSharedCooldownAfterAHeavyAttack Heavy attack, then light attack. The cooldown is doubled and shared, so the spin cannot be spammed.
shouldKeepHeavyCooldownAtLeastAsLongAsTheSpinWithAttackSpeedBuffs Heavy attack with a 4× attack-speed buff. The cooldown never drops below the spin's own length, so two spins can never overlap.
shouldUseTheBaseSpriteWhenNotUpgraded / shouldUseTheUpgradedSpriteForBothAttacksOnceUpgraded Check the sprite in each state. The fancier blade is drawn for both attacks while upgraded, and the base sprite returns when reverted.

SweepComponentTest

Test Purpose Expected Result
updateMovesHitboxToTheNewOffsetInTheSameFrame Step a sweep one frame. The blade's position updates in the same frame as its rotation, so fast sweeps never look tilted.

Upgraded Knife

KnifeWeaponComponentTest

Test Purpose Expected Result
shouldNotFlurryWhenNotUpgraded Press the heavy attack before upgrading. Nothing spawns and no cooldown starts.
shouldBoostTheLightStabWhenUpgraded Stab while upgraded. Same stab hitbox, more damage, normal knockback.
shouldOpenTheFlurryWithAKnockbackFreeSlashRightToLeft Start a flurry. One slash spawns immediately, sweeping 70° across the front of the player with no knockback.
shouldFollowWithAReverseSlashThenAFinishingStab Step through the whole flurry. A reverse slash follows, then a stab with double damage and the only knockback — and nothing spawns afterwards.
shouldKeepEveryStrikeAimedWhereTheFlurryStarted Start a flurry facing up. All three strikes stay aimed where the flurry began.
shouldSpawnQueuedStrikesInFrontOfTheWielderNotOnThem Inspect queued strikes as they spawn. Each appears in front of the player, never flashing on top of them for a frame.
shouldFadeEveryFlurryStrikeWithThePlayerWhileInvisible Activate Invisibility mid-flurry. Every strike fades with the player, matching the light attack's behaviour.
shouldCancelTheRestOfTheFlurryWhenTheKnifeIsUnequipped Switch weapons mid-flurry. Queued strikes are dropped, not fired later when the knife is re-equipped.
shouldTripleTheCooldownAfterAFlurry Use the flurry. The shared cooldown is tripled.
shouldNeverCoolDownBeforeTheFlurryEndsWithAttackSpeedBuffs Use the flurry with a 4× attack-speed buff. The cooldown never ends before the combo does, so two flurries cannot overlap.
shouldUseTheBaseSpriteWhenNotUpgraded / shouldUseTheUpgradedSpriteForEveryStrikeOnceUpgraded Check the sprite in each state. The upgraded knife is drawn for the stab and every flurry strike, and the base sprite returns when reverted.

Upgraded Bow

BowWeaponComponentTest

Test Purpose Expected Result
shouldBoostLightDamageWhenUpgraded Attack (J) while upgraded. Still one arrow, now dealing 20% more damage.
shouldNotHeavyAttackWhenNotUpgraded Press the heavy attack before upgrading. Nothing spawns and no cooldown starts.
shouldFireThreeArrowsOnHeavyAttackWhenUpgraded Heavy attack (K) while upgraded. Three arrows spawn — centre plus ±15° — each dealing the same damage as an unupgraded shot.
shouldFireOnlySideArrowsWhenCentreSpawnBlockedOnHeavyAttack Heavy attack next to a wall blocking only the centre path. The two side arrows still fire independently.
shouldRevertToSprintOneBowWhenUpgradeRemoved Revert the upgrade, then attack and heavy attack. Light attack returns to base damage; heavy attack is inert again.
shouldUseTheBaseSpriteWhenNotUpgraded / shouldUseTheUpgradedSpriteForEveryArrowOnceUpgraded Check the sprite in each state. The upgraded arrow is drawn for the single shot and for all three volley arrows, and the base sprite returns when reverted.

Shared Hitbox Pipeline

HitboxFactoryTest

Test Purpose Expected Result
shouldStartOnTheOwnerOffsetRatherThanTheSpawnOrigin Create a hitbox that follows its wielder. It starts on its offset before any update runs, so delayed strikes never render in the wrong place.

Manual Gameplay Test Plan

Setup for every test below: run the game, open the debug terminal (F1), enter weapon sword, weapon knife or weapon bow to equip, enter debug on to see hitbox outlines, then close the terminal (F1).

Unupgraded Behaviour

Test Steps Expected Result
Sprint 1 sword Start a run and attack with J without upgrading. The original 90° sweep, blade and damage.
Sprint 1 knife Equip the knife and attack with J. The original stab.
Sprint 1 bow Equip the bow and attack with J. A single arrow with the original arrow sprite.
Heavy attack locked Press K with each weapon. The attack sound plays, but nothing spawns.

Upgraded Sword

Test Steps Expected Result
Apply the upgrade Run upgrade sword. The blade changes to the fancier winged sword on the next attack.
Stronger light attack Attack an enemy with J before and after upgrading. The same 90° sweep kills in fewer hits.
Heavy spin Press K surrounded by enemies. The blade sweeps a full circle around the player and hits enemies on every side.
Readable spin Watch the spin at normal speed. The full turn is easy to follow, and the blade stays pointed along its arc rather than looking tilted.
Shared cooldown Press K, then immediately J. The light attack is blocked until the longer cooldown ends.
Revert Run upgrade sword off and attack. The Sprint 1 sword and sprite return, and K is inert again.

Upgraded Knife

Test Steps Expected Result
Apply the upgrade Run weapon knife, then upgrade knife. J still stabs, now for more damage, drawn with the upgraded knife sprite.
Flurry Press K next to an enemy. Two slashes sweep across the front of the player in opposite directions, then a forward stab.
Enemies stay in reach Flurry a single enemy. The first two slashes do not push it away; only the final stab knocks it back.
Aim is locked Press K, then turn immediately. All three strikes keep the direction you faced when you pressed K.
No sprite flash Watch the player while the flurry plays. No knife sprite appears on top of the player between strikes.
Upgraded sprite on every strike Watch the flurry closely. Both slashes and the finisher use the upgraded knife sprite, not just the stab.
Switching mid-combo Press K, then change weapons on the hotbar straight away. The remaining strikes never appear, including after switching back.
Revert Run upgrade knife off. The base knife sprite returns and K goes back to sound only.

Upgraded Bow

Setup: equip with weapon bow, apply with upgrade bow.

Test Steps Expected Result
Apply the upgrade Run upgrade bow. J still fires a single arrow, now for more damage and drawn with the upgraded arrow sprite.
Heavy shot Press K facing an enemy. Three arrows fan out and can hit multiple enemies at once.
Upgraded sprite on every arrow Watch a volley. All three arrows use the upgraded sprite, including the two angled ones.
Blocked centre still fires sides Stand next to a wall directly ahead, press K. The straight shot is blocked; the two angled arrows still fire.
Revert Run upgrade bow off. J returns to a single, unboosted arrow with the base sprite; K is inert again.

Interaction With Other Features

Test Steps Expected Result
Hotbar Switch weapons with the hotbar, upgraded and not. Each weapon keeps its own upgrade state; only the equipped weapon attacks.
Player abilities Activate Invisibility, then attack with each weapon. Weapon sprites, including every flurry strike and volley arrow, fade with the player.
Stat buffs Pick up a Strength Charm, then attack. Upgraded damage scales on top of the buffed base attack.

Areas Not Covered by Automated Tests

  • Game feel and balance (spin and flurry timings, arrow spread, damage multipliers, cooldown lengths) is judged manually, not asserted. The values are constants and are expected to change with playtesting.
  • Sprite appearance is tested by the values passed to the sprite batch, not by pixels. Whether an upgraded weapon looks like an upgrade is a manual judgement.
  • Hitboxes stay axis-aligned while their sprites rotate, a pre-existing engine limitation. During the sword's spin, reach at the player's sides is slightly shorter than straight ahead. This is accepted, not tested.
  • The heavy attack has no dedicated player animation; that belongs to the upgrade animations ticket.
  • How upgrades are granted in normal play (pickup or shop) is not built yet. Anything granting one calls WeaponUpgradeComponent.setUpgraded(...), the same entry point the terminal command uses.

AI Declaration

This page was written with LLM assistance (Claude Code on Opus 5), generated from the weapon upgrade test suite and the team's pull requests, and reviewed before publishing.

⚠️ **GitHub.com Fallback** ⚠️