Weapons Test Plan - UQcsse3200/2026-studio-4 GitHub Wiki

Overview

This test plan covers the Weapons feature team's work across the sprint:

  • The shared weapon pipeline — stats, cooldown, damage scaling, and hitbox spawning (Weapons).
  • The three weapons: Knife, Sword, and Bow.
  • Weapon sprite rendering (Weapon Rendering).
  • Weapon Upgrades — the shared upgrade system, each weapon's heavy attack on K, and its upgraded sprite.
  • The fix for the game crashing when a weapon hitbox killed an enemy (#56).

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.

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, weapon sword, weapon 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
  • In normal play weapons are equipped from the weapons hotbar; the weapon command is the QA shortcut for the same state

Run all automated tests with:

cd source
./gradlew :core:test

Coverage is written to source/core/build/reports/jacoco/test/html/index.html by:

cd source
./gradlew :core:jacocoTestReport

Coverage

Last verified run: 17 Sept 2026 on task/126-bow-sprite-change — 1178 tests, 0 failures project-wide, of which 184 tests across 17 classes cover weapons.

Quality Gate Coverage

Reference: SonarCloud project overview · coverage by component

The badges above are project-wide. The figures below are the weapons code only.

Per-file coverage

Figures are from a local JaCoCo run of this branch, which is the same measurement SonarCloud consumes. SonarCloud's own published figures lag by one analysis until this branch is merged. Each file links to its SonarCloud measures page.

File Lines Line coverage Branch coverage
weapons/WeaponComponent.java 45 95.6% 94.1%
weapons/WeaponStatsComponent.java 40 100.0% 100.0%
weapons/WeaponUpgradeComponent.java 24 100.0% 100.0%
weapons/WeaponUpgradeStats.java 4 100.0% 100.0%
weapons/SwordWeaponComponent.java 42 100.0% 60.0%
weapons/KnifeWeaponComponent.java 87 100.0% 100.0%
weapons/BowWeaponComponent.java 34 100.0% 100.0%
weapons/SweepComponent.java 25 100.0% 100.0%
weapons/FollowComponent.java 16 100.0% 100.0%
weapons/ProjectileComponent.java 36 88.9% 75.0%
weapons/LifetimeComponent.java 29 69.0% 50.0%
weapons/WeaponSelectionComponent.java 22 100.0% 100.0%
weapons/WeaponAssetsComponent.java 10 100.0% 50.0%
factories/HitboxFactory.java 41 100.0% 100.0%
factories/HitboxSpec.java 49 100.0% 88.9%
rendering/RotatingTextureRenderComponent.java 26 100.0% 100.0%
commands/UpgradeCommand.java 17 100.0% 100.0%
commands/WeaponCommand.java 11 100.0% 75.0%

Aggregate across all 18 classes (JaCoCo, source/core/build/reports/jacoco/test/html/index.html):

Counter Covered Missed Coverage
Instructions 2389 46 98.1%
Branches 211 21 90.9%
Lines 543 15 97.3%
Methods 149 2 98.7%
Classes 18 0 100.0%

Every weapon class, the upgrade system, the hitbox factory and both terminal commands are at 100% line coverage. The gaps are listed under Known coverage gaps.

Tests per class

Test class Tests
WeaponStatsComponentTest 21
WeaponComponentTest 20
KnifeWeaponComponentTest 20
SwordWeaponComponentTest 19
HitboxFactoryTest 17
WeaponUpgradeComponentTest 12
SweepComponentTest 11
BowWeaponComponentTest 10
ProjectileComponentTest 9
RotatingTextureRenderComponentTest 8
FollowComponentTest 8
UpgradeCommandTest 7
LifetimeComponentTest 7
HitboxSpecTest 5
WeaponSelectionComponentTest 4
CollisionDisposalTest 3
CollisionSpawnTest 3
Total 184

Automated Unit Test Plan

Shared Pipeline

Every weapon shares the same stats, cooldown gate, and hitbox factory, so these tests protect all three weapons at once. Damage resolves from the wielder's effective base attack, so both item buffs (Strength Charm) and ability buffs (Last Stand) scale weapon hits.

WeaponStatsComponentTest

Test Purpose Expected Result
shouldScaleBaseAttackByMultiplier / shouldRoundResolvedDamageToNearest Resolve damage from the wielder's base attack. Damage is round(baseAttack × multiplier), so Strength Charm buffs scale weapon hits.
shouldApplyExtraDamageScaleOnTopOfMultiplier Resolve damage with an extra upgrade scale. Damage is round(baseAttack × multiplier × scale), and the shared multiplier is left untouched — an upgrade can never leak onto another weapon.
shouldResolveZeroDamageForZeroMultiplier Resolve damage with a 0 multiplier. Damage resolves to 0.
shouldShortenCooldownForFasterAttackSpeed / shouldLengthenCooldownForSlowerAttackSpeed Resolve cooldown against the wielder's attack speed. Effective cooldown is cooldown / attackSpeed in both directions.
shouldIgnoreNonPositiveAttackSpeedWhenResolvingCooldown Resolve cooldown with attack speed ≤ 0. Falls back to the base cooldown instead of dividing by zero.
shouldGateAttackByResolvedCooldownDuration / shouldAllowAttackAfterCooldownElapses / shouldRemainGatedOnPartialTick Trigger the cooldown and tick time forward. Attacks are blocked until the full cooldown has elapsed, then allowed again.
shouldAlwaysAllowAttackWhenCooldownIsZero Use a zero-cooldown weapon. Attacks are never blocked.
shouldClampRemainingWhenUpdateOvershoots / shouldTreatNegativeDeltaAsZero / shouldTreatNegativeTriggeredCooldownAsZero Feed oversized or negative frame times and durations. The countdown clamps at zero and never runs backwards.
shouldRejectNegativeConstructorValues / shouldRejectNegativeSetters Construct stats with invalid values. IllegalArgumentException is thrown.

WeaponComponentTest

Test Purpose Expected Result
shouldCallCreateAttackWhenReady / shouldNotCreateAttackWhileCoolingDown / shouldCreateAttackAgainAfterCooldown Attack repeatedly through a cooldown cycle. createAttack fires only when the shared cooldown allows it.
shouldFailCreateWithoutStats Attach a weapon to an entity with no WeaponStatsComponent. Creation fails fast rather than crashing mid-game.
shouldRejectNullOriginOrDirection / shouldRejectNullOriginOrDirectionForHeavyAttack Attack with null arguments. IllegalArgumentException is thrown for both light and heavy attacks.
shouldScaleHitboxDamageByWielderBaseAttack / shouldFollowBaseAttackBuffs Buff the wielder's base attack, then attack. The spawned hitbox carries the newly scaled damage.
shouldScaleCooldownByWielderAttackSpeed / shouldUseBaseCooldownWithoutCombatStats Attack with and without combat stats. Cooldown scales with attack speed, and falls back cleanly when the wielder has no stats.
shouldUseLiveLastStandDamageAndCooldownWithoutChangingWeaponOrRawStats Attack while a Last Stand buff is active, then after it expires. Damage and cooldown follow the live ability buff without permanently editing weapon or player stats.

Weapon Upgrades

An upgrade grants a weapon more light-attack damage, a heavy attack on K, a longer shared cooldown when that heavy attack is used, and a fancier sprite. Upgrade state lives on the player in WeaponUpgradeComponent, never in the weapon, so upgrading one weapon cannot buff another.

Each upgraded sprite is an unedited crop of the same CC0 steel-weapons.png sheet, drawn at the same angle as the base sprite, with grid cells recorded in core/assets/licenses/OPENGAMEART-ATTRIBUTION.md.

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 one weapon, then read the others. 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 (heavy attack pipeline)

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.

UpgradeCommandTest

Test Purpose Expected Result
shouldUpgradeSword / shouldUpgradeAndRevertKnife / shouldUpgradeAndRevertBow Run upgrade <weapon> [off]. QA can apply and revert any upgrade without a pickup or shop.
shouldStayUpgradedWhenRunTwice / shouldRevertSwordUpgradeWithOff Run the command repeatedly, then revert. Applying is idempotent and reverting restores 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 player abilities feature.
shouldTriggerHeavyWeaponAttackInFacingDirectionOnHeavyAttack Walk, stop, then heavy attack. The heavy attack uses the player's current facing.

Knife

The knife's heavy attack is a three-hit flurry: two 70° slashes in opposite directions, then a finishing stab. Only the finisher knocks back, so enemies stay in reach of every hit.

KnifeWeaponComponentTest

Test Purpose Expected Result
shouldSpawnFollowingHitboxWithoutASweep Attack with the knife. One short-lived hitbox spawns, follows the wielder, and has no sweep behaviour.
shouldSizeAndPlaceHitboxForAHorizontalAttack / shouldTransposeHitboxForAVerticalAttack Attack left/right, then up/down. The blade-shaped hitbox is transposed to match the attack axis and placed just outside the wielder.
shouldSnapOffsetToACardinalDirection Attack on a diagonal facing. The stab snaps to the nearest cardinal direction (matches WASD facing).
shouldAttachSpriteFacingTheAttackDirection Attack in each direction. The knife sprite is attached and rotated to point along the stab.
shouldScaleDamageByWielderBaseAttack Buff the wielder, then stab. Hitbox damage reflects the buffed base attack.
shouldExpireBeforeTheWielderCanAttackAgain Compare stab lifetime against the cooldown. The old stab is always gone before a new one can spawn, so an enemy can never take double hits from stacked hitboxes.
shouldRenderSpawnedKnifeWithLivePlayerAbilitiesAndExpiry Attack, then activate and expire player abilities. The stab sprite follows the player's live appearance, e.g. fading while invisible.
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 / shouldNeverCoolDownBeforeTheFlurryEndsWithAttackSpeedBuffs Use the flurry, with and without an attack-speed buff. The cooldown is tripled, and never ends before the combo does, so two flurries cannot overlap.
shouldUseTheBaseSpriteWhenNotUpgraded / shouldUseTheUpgradedSpriteForEveryStrikeOnceUpgraded Check the sprite in each state. The upgraded knife sprite is drawn for the stab and every flurry strike, and the base sprite returns when reverted.

Sword

The sword's heavy attack is a full 360° spin using the same blade, slower than the light sweep so the turn reads clearly.

SwordWeaponComponentTest

Test Purpose Expected Result
shouldSpawnASweepingHitboxThatFollowsTheWielder Attack with the sword. The hitbox has both a FollowComponent and a SweepComponent, so it arcs while tracking the wielder.
shouldSizeAndTransposeHitboxWithTheAttackAxis Attack horizontally and vertically. The blade hitbox is transposed to match the attack axis.
shouldStartTheArcHalfATurnBeforeTheAimDirection Inspect the spawn offset. The swing starts half the arc before the aim direction, so the aim sits in the middle of the sweep.
shouldAimTheSpriteAlongTheStartOfTheArc / shouldTurnTheBladeAsTheSweepProgresses Step the sweep forward. The sword sprite starts aligned with the arc's start and rotates through the swing.
shouldScaleDamageByWielderBaseAttack Buff the wielder, then swing. Hitbox damage reflects the buffed base attack.
shouldRenderSpawnedSwordWithLivePlayerAbilitiesAndExpiry Swing, then activate and expire player abilities. The blade sprite follows the player's live appearance.
shouldKeepSprintOneLightAttackWhenNotUpgraded / shouldNotHeavyAttackWhenNotUpgraded Attack before upgrading. The sword keeps its original blade, arc and damage, and K spawns nothing.
shouldBoostLightDamageButKeepItsSweepWhenUpgraded Light attack while upgraded. Same 90° arc and blade, more damage.
shouldHeavyAttackWithTheSameBladeWhenUpgraded / shouldSpinTheHeavyAttackAFullTurnAroundTheWielder Heavy attack, then step it to the end. The spin uses the same blade, 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 / shouldKeepHeavyCooldownAtLeastAsLongAsTheSpinWithAttackSpeedBuffs Spin, then attack again, with and without an attack-speed buff. The cooldown is doubled and shared, and never drops below the spin's own length, so two spins can never overlap.
shouldUseTheBaseSpriteWhenNotUpgraded / shouldUseTheUpgradedSpriteForBothAttacksOnceUpgraded Check the sprite in each state. The upgraded blade is drawn for both attacks while upgraded, and the base sprite returns when reverted.
shouldRevertToSprintOneSwordWhenUpgradeRemoved Revert the upgrade, then attack. Sprint 1 damage, blade and sprite all return, and K goes inert.

SweepComponentTest

Test Purpose Expected Result
updateSetsOffsetAtStartAngleOnFirstFrame / updateInterpolatesAngleAtHalfDuration / updateClampsAtEndAngleOncePastDuration Step a sweep from start to past its end. The offset moves along the arc from start angle to end angle and clamps there.
updateAccumulatesElapsedTimeAcrossCalls Step in many small frames. Progress accumulates correctly regardless of frame size.
updateMovesHitboxToTheNewOffsetInTheSameFrame Step a sweep one frame. The blade's position updates in the same frame as its rotation, so fast sweeps never look tilted.
updateIsNoOpWithoutFollowComponent Attach a sweep to a non-following entity. Nothing happens rather than crashing.
constructorRejects… (zero/negative duration, negative radius) / negativeDeltaTimeTreatedAsZero Feed invalid values. Rejected or clamped safely.

Bow

The bow's heavy attack fires three arrows at once: one along the aim direction and one 15° to each side.

BowWeaponComponentTest

Test Purpose Expected Result
shouldSpawnTravellingHitboxOnAttack Fire the bow. A world-space hitbox (no owner) spawns carrying round(baseAttack × multiplier) damage and a ProjectileComponent.
shouldNotFireThroughAdjacentWall Fire while standing against a wall. No arrow spawns — the bow refuses to fire through an obstacle the player is touching.
shouldRenderSpawnedArrowWithLivePlayerAbilitiesAndExpiry Fire, then activate and expire player abilities. The arrow sprite follows the player's live appearance.
shouldNotHeavyAttackWhenNotUpgraded Press the heavy attack before upgrading. No arrows spawn and no cooldown starts.
shouldBoostLightDamageWhenUpgraded Fire a single arrow while upgraded. The arrow carries the upgraded damage.
shouldFireThreeArrowsOnHeavyAttackWhenUpgraded Heavy attack while upgraded. Three arrows spawn: one straight ahead and one 15° to each side.
shouldFireOnlySideArrowsWhenCentreSpawnBlockedOnHeavyAttack Heavy attack with the centre line blocked. Each arrow is checked independently, so one blocked arrow does not cancel the other two.
shouldRevertToSprintOneBowWhenUpgradeRemoved Revert the upgrade, then fire. Sprint 1 damage returns and K goes inert.
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.

ProjectileComponentTest

Test Purpose Expected Result
shouldTravelInGivenDirection Step the arrow over several frames. It moves in a straight line at its configured speed.
shouldDespawnOnEnemyHit Fly the arrow into an enemy. It damages the first enemy it touches, then despawns — it does not pierce.
shouldDespawnWhenWallBlocksNextStep / arrowStopsAtWallAcrossRangesAndFrameRates / arrowStopsAtWallAfterFrameHitch Fly the arrow at walls across many distances, frame rates, and a simulated frame hitch. The arrow always stops at the wall — it never tunnels through, even on a slow frame.
arrowKeepsFlyingWhenNothingBlocksIt Fly through open space. The arrow keeps going until its lifetime expires (~1.5 s, which caps its range).
constructorRejects… (null/zero direction, non-positive speed) Construct with invalid values. IllegalArgumentException is thrown.

Hitbox Spawning

HitboxFactoryTest and HitboxSpecTest

Test Purpose Expected Result
shouldSpawnSensorOnWeaponLayer Build a hitbox from a spec. The entity is a kinematic sensor on PhysicsLayer.WEAPON.
shouldDamageTargetOnCollision Collide the sensor with an NPC-layer target. The target takes the spec's damage through the existing combat components.
shouldFollowWhenOwnerProvided / shouldNotFollowWhenOwnerOmitted Build with and without an owner. Melee hitboxes get a FollowComponent; world-space hitboxes (arrows) do not.
shouldStartOnTheOwnerOffsetRatherThanTheSpawnOrigin Build a hitbox that follows its wielder. It starts on its offset before any update runs, so a delayed strike (e.g. a queued flurry slash) never renders on top of the player for a frame.
shouldInheritLiveAppearanceWithoutFollowingOrRescalingDamage / shouldAllowVisualSourceWithoutTextureAndWithoutFollowOwner Build with an appearance source. A hitbox can inherit the player's live appearance without inheriting movement or damage scaling.
shouldPreserveHostileHitboxAsDamageSourceAndRespectInvisibilityOnCollision Collide a hostile hitbox with an invisible player. Invisibility is respected at the point of damage.
shouldReject… (null spec, missing position/size, non-positive size, negative lifetime/damage/knockback) Build from invalid specs. Each throws IllegalArgumentException.
shouldDefaultLayerAndOffset / shouldCopyVectorsOnSetAndGet Inspect spec defaults and vector handling. Sensible defaults; vectors are defensively copied so callers cannot mutate the spec.

FollowComponentTest

Test Purpose Expected Result
shouldTrackOwnerPlusOffset / shouldHoldOffsetWhenOwnerDoesNotMove Move the owner around. The hitbox stays at owner position + offset every frame.
shouldAllowOffsetMutationForSweeps Change the offset mid-lifetime. The hitbox moves to the new offset — this is what drives the sword's arc.
shouldCopyOffsetSoCallerMutationDoesNotMoveFollower / shouldExposeOwnerAndOffsetCopies Mutate vectors after passing them in. The follower is unaffected; state is defensively copied.
shouldRejectNullOwner / shouldRejectNullOffset / shouldRejectNullSetLocalOffset Construct or update with nulls. IllegalArgumentException is thrown.

LifetimeComponentTest

Test Purpose Expected Result
shouldNotDisposeBeforeLifetimeElapses / shouldDisposeOnceWhenLifetimeElapses Tick a hitbox through its lifetime. It survives until expiry, then is disposed exactly once.
shouldDisposeImmediatelyWhenLifetimeIsZero Use a zero lifetime. Disposed on the first update.
shouldNotDisposePhysicsAgainWhenOwningRoomIsDisposed Expire a projectile, then dispose its room. The physics body is disposed only once — no double-free crash.
shouldRejectNegativeLifetime / shouldTreatNegativeDeltaAsZero Feed invalid values. Rejected or clamped safely.

Weapon Selection

WeaponSelectionComponentTest

Test Purpose Expected Result
startsWithSwordAndSwitchesExclusivelyThroughEvents Equip each weapon through the shared selection events. The sword starts equipped, and exactly one weapon is enabled at a time.
repeatedAndInvalidSelectionsPreserveStateAndDoNotEmitEvents Re-select the current weapon, and select an invalid one. State is unchanged and no spurious events fire.
missingWeaponDoesNotDisableCurrentWeapon Select a weapon the player does not carry. The current weapon stays equipped.
terminalUsesSharedSelectionAndPreservesCooldown Equip through the weapon terminal command. The terminal and the hotbar share one source of truth, and switching does not reset the shared cooldown.

Rendering

RotatingTextureRenderComponentTest

Test Purpose Expected Result
shouldDrawCentredOnEntityCentreUsingEntityScale Draw with no visual overrides. The sprite is centred on the entity's centre so it pivots about its middle, not a corner.
shouldPreferVisualScaleOverEntityScale / shouldFallBackToEntityScaleWhenVisualScaleCleared Set and clear a visual scale. The sprite can be sized independently of the hitbox, and reverts cleanly.
shouldAddRotationOffsetToRotation / shouldReportRotationWithoutOffset Rotate with a fixed art-correction offset. The offset is applied at draw time only; logical rotation stays clean.
shouldShiftSpriteAlongFacingWithoutMovingTheEntity / shouldRotateOffsetByFacingOnlyNotBySpriteOffset Apply a facing-relative visual offset. The sprite shifts (e.g. handle pulled to the wielder) without moving the hitbox.
shouldCopyVisualScaleOnSetAndGet Mutate vectors after passing them in. State is defensively copied.

Regression: Crash When a Weapon Kills an Enemy

Box2D forbids creating or destroying physics bodies during a collision callback. These tests step a real Box2D world and confirm the fix from #56 holds: they reproduce the original crash when the fix is reverted.

CollisionDisposalTest

Test Purpose Expected Result
shouldNotDisposeEnemyDuringPhysicsStepThatKillsIt A weapon sensor deals lethal damage mid-step. The enemy is not disposed during the physics step (which would crash in DestroyFixture).
shouldDisposeEnemyAfterPhysicsStepThatKillsIt Update the entity service after the step. The enemy is disposed on the next update.
shouldKeepSteppingAfterDisposingEnemyKilledByCollision Keep stepping the world afterwards. No crash.

CollisionSpawnTest

Test Purpose Expected Result
shouldNotSpawnChildrenDuringPhysicsStepThatSplitsEnemy A weapon hit makes a split enemy split mid-step. Children are not spawned during the physics step (which would crash in CreateBody).
shouldSpawnChildrenAfterPhysicsStepThatSplitsEnemy Update the entity service after the step. Both children appear on the next update.
shouldKeepSteppingAfterSplittingEnemy Keep stepping the world afterwards. No crash.

Manual Gameplay Test Plan

Setup for every test below: run the game, open the debug terminal (F1), enter weapon knife / weapon sword / weapon bow to equip, enter debug on to see hitbox outlines, then close the terminal (F1). Upgrade tests additionally use upgrade <weapon> and upgrade <weapon> off.

Knife

Test Steps Expected Result
Directional stab Face each direction with WASD and press J. A small hitbox and knife sprite appear just in front of the player, pointing the way they face.
Follows the wielder Attack while walking. The hitbox and sprite move with the player for the stab's duration.
Damage Stab an enemy. The enemy takes damage and dies at zero health.
No stacked hits Hold or spam J next to an enemy. Only one stab exists at a time; the enemy is never double-hit by overlapping hitboxes.
Heavy locked Press K before upgrading. The attack sound plays, but no hitbox appears.
Flurry Run upgrade knife, then 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 faced when K was pressed.
No sprite flash Watch the player through the flurry. No knife sprite appears on top of the player between strikes.
Switching mid-combo Press K, then change weapons on the hotbar straight away. The remaining strikes never appear, including after switching back.
Upgraded sprite on every strike Watch a flurry while upgraded. Both slashes and the finisher use the upgraded knife sprite, not just the stab.
Upgraded sprite and revert Compare the blade before and after upgrade knife, then run upgrade knife off. The upgraded knife sprite is drawn while upgraded, and the base knife and inert K return afterwards.

Sword

Test Steps Expected Result
Sweeping arc Attack and watch the debug outline. The hitbox sweeps a 90° arc around the player, centred on the facing direction.
Blade turns with the swing Attack and watch the sprite. The sword sprite rotates through the arc, handle staying near the player.
Follows the wielder Attack while walking. The whole arc moves with the player.
Damage Sweep through an enemy. The enemy takes damage anywhere along the arc.
Heavy locked Press K before upgrading. The attack sound plays, but no hitbox appears.
Heavy spin Run upgrade sword, then press K while surrounded. 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.
Shared cooldown Press K, then immediately J. The light attack is blocked until the longer cooldown ends.
Upgraded sprite and revert Compare the blade before and after upgrading, then run upgrade sword off. The fancier winged sword is drawn while upgraded; the Sprint 1 sword and inert K return afterwards.

Bow

Test Steps Expected Result
Arrow flight Face each direction and press J. An arrow spawns at the player's edge and flies straight, sprite pointing along its flight.
Non-piercing Fire into a group of enemies. The arrow damages the first enemy it touches, then disappears.
Blocked by obstacles Fire at walls, rocks, and barrels. The arrow stops instead of passing through.
No firing through walls Stand against a wall and fire into it. No arrow spawns beyond the wall.
Range cap Fire into open space. The arrow expires after roughly 1.5 seconds of flight.
Heavy locked Press K before upgrading. The attack sound plays, but no arrow appears.
Three-arrow volley Run upgrade bow, then press K. Three arrows fly out: one straight ahead and one angled to each side.
Partly blocked volley Heavy attack with a wall directly ahead. The blocked arrow is skipped while the others still fly.
Upgraded sprite on every arrow Fire J and K while upgraded. The single shot and all three volley arrows use the upgraded arrow sprite, including the angled ones.
Revert Run upgrade bow off. Single arrows with the base sprite return, and K goes back to sound only.

Rendering

Test Steps Expected Result
Sprite vs hitbox Attack with debug on. The sprite and the hitbox outline are independent: the outline is sized for collision, the sprite keeps its own square aspect ratio.
Crisp pixel art Attack in every direction and mid-sweep. Sprites stay sharp at every angle (rotation happens at draw time, not by resampling the image).
One sprite at a time Spam attacks. Old sprites disappear with their hitboxes; sprites never pile up.
Upgraded sprites line up Upgrade each weapon, then attack in every direction. Upgraded sprites sit and rotate exactly like the base ones, since each is cut from the same sheet at the same angle.
Abilities Activate Invisibility, then attack with each weapon. Weapon sprites, including every flurry strike and volley arrow, fade with the player.

Weapon Selection

Test Steps Expected Result
Hotbar and terminal agree Switch with the hotbar, then with weapon <name>. Both change the same equipped weapon; only that weapon attacks.
Upgrades are per weapon Upgrade one weapon, then switch to another. Each weapon keeps its own upgrade state and sprite; switching never grants or removes an upgrade.
Cooldown is shared Attack, then switch weapons immediately and attack again. The shared cooldown still applies, so switching cannot be used to attack faster.

Stability

Test Steps Expected Result
Kill on contact Kill many enemies with each weapon, light and heavy, with and without debug on. No Box2D crash when the killing blow lands.
Split enemies Hit a splitting enemy with a weapon. It splits into two children without crashing, and the children die normally.

Known Coverage Gaps

Fifteen lines are uncovered, all of them defensive fallbacks or one untested attack axis:

Location Uncovered Why
LifetimeComponent.removeNow() The whole method, plus the expired early return The fallback used when no EntityService is registered. Every test and the game itself register one, so only the normal runAfterUpdate path is exercised. This is the largest gap in the feature.
ProjectileComponent.update() / onCollisionStart() Null-clock and paused-frame guards, and the "not my fixture" / "not a stopping layer" early returns Guards against a missing clock, a paused game and collisions reported for other fixtures. The flight and wall-stop behaviour they protect is covered directly.
SwordWeaponComponent.spawnSweep() The vertical branch of the axis flip shouldSizeAndTransposeHitboxWithTheAttackAxis only asserts a horizontal swing, so the transposed blade and reach for an up or down swing are never measured. Worth closing — the knife covers the same branch in both axes.
WeaponComponent.onWeaponAttack() The !enabled early return for the light attack The heavy attack's equivalent guard is covered; the light one is only exercised through weapon selection rather than by a direct test.
HitboxSpec.visualScale() / visualOffset() The null branches of both setters Clearing a visual override back to null never happens in production; the non-null paths are covered.
WeaponAssetsComponent.dispose() The null ResourceService branch Guards disposal after the service is torn down.
WeaponCommand.action() Two branches of the equip guard The missing-player and missing-selection paths; WeaponSelectionComponentTest covers equipping itself.

Areas Not Covered by Automated Tests

  • Rendering tests verify the arguments passed to the sprite batch, not actual pixels. Visual correctness (anchoring, crispness, whether the sword swing "reads" as a swing, whether an upgraded weapon looks like an upgrade) is tested manually.
  • Game feel and tuning values (lifetimes, arc widths, spin and flurry timings, arrow speed and spread, damage multipliers, cooldown lengths) are judged manually, not asserted.
  • 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.
  • Heavy attacks have no dedicated player animation yet; 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 upgrade terminal command uses.
  • The debug terminal weapon and upgrade commands are exercised manually every session; UpgradeCommandTest covers the command logic, but the terminal parsing around it is manual.

AI Declaration

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

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