Skip to main content

Troubleshooting

Trace the failed stage: database lookup, working build, validation, actor acquisition, equipment, visual assembly or active weapon selection.

Assets Cannot Be Found​

Check that the asset ID is non-empty, unique and present in the correct database Table. Verify that the database is assigned in Weapon SubSystem Project Settings and has finished loading.

Use DumpWeaponDBLookup and DumpWeaponLookupTables. A valid asset in the Content Browser is not enough if its ID is unregistered. Check stale soft references after moving/renaming assets.

Build Validation Fails​

Check WeaponID, all part IDs, ParentPartID, socket names and slot tags. Providers must supply the socket used by an attachment. Add parent parts before children that depend on their slots.

Check CompatibleSlot, the provider's tags against WeaponTagsFilter, duplicate parent/socket pairs, capability conflicts and RequiredParts. Required slot tags must match exactly in this implementation.

Read the Build validation failed reason in the Output Log. CreateValidateBuildOp.bSucceed is not the validation result.

No Actor Appears​

Equip does not spawn an actor. First queue CreateAcquireOp, then obtain a valid registered actor GUID. Check the controller's Net component, interface, controlled pawn and requested weapon type.

For internal acquisition in Standalone/authority play, the current code does not deliver the same owning-client acquisition callback. See Implementation Limits.

Actor Exists but Is Not Attached​

Check AC_WeaponCharComp on an ACharacter, I_WeaponPawn, the mesh returned by GetCharMesh and the target character socket. The attachment path does not use an arbitrary Pawn mesh automatically.

Check that the actor is registered and available in the character's reference cache. Late actor registration/replication may defer an attachment.

Actor Has No Visible Weapon Mesh​

Check the master/part MeshType, assigned mesh and available static/skeletal component counts. Restart the editor after changing default component counts.

Check master/part registration, loaded assets, socket maps and the build's runtime entries. A successful equip request is not a guarantee that all asynchronous visual assembly has finished.

Attack Does Nothing​

First select the assigned weapon using CreateUseOp. Attack helpers target the Character component's ActualUsedWeapon.

Use CreateWeaponAttackOp for firing; CreateUseOp only selects/moves the weapon. The current routed attack has Range handling but empty Melee and Throwable branches.

Unequip Does Nothing​

Check that the requesting controller has a registered Net component, the target Character has a registered Char component, and the weapon GUID resolves in that Character's reference cache. Implement I_WeaponController::WeaponUnequipCallback to destroy an internal actor or return an external actor to its pool.

The current handler clears runtime data and removes the assignment but does not destroy or detach the actor itself. It also clears ActualUsedWeapon unconditionally, including when removing another assigned weapon. A retained actor may need additional project cleanup. The helper's empty TargetSocket does not block the current routed Unequip path.

Saved Weapons Are Missing​

The subsystem registry is not persistent storage. Restore build data through Import, then Validate before Acquire and Equip. Save additional gameplay state separately; a build does not store current ammo or durability.

Multiplayer Differences​

Check replicated actors, controller ownership, registered Net/Char components and both required interfaces. Test Standalone, Listen Server and a remote client independently. The acquisition callback, working-build delegates and RepNotify paths differ between authority and clients.

Before Requesting Support​

Include the plugin version, reproducible steps, network mode, relevant Output Log messages and build/database dumps. Reproduce the issue in a minimal test level when possible.