UnitWeapon.lua

---@meta

-- Engine internal states for Tactical/Nuke fire tasks:
-- State 0: Check range
-- Move the unit within min/max range.
-- Then go to State 1 if we need ammo or State 2 if we don't.
-- State 1: Building ammo
-- Checks every 10 ticks if ammo is loaded, afterwards transitioning to State 2.
-- State 2: Waiting to fire
-- If unit not busy, give a fire command and increment State. Always waits 3 ticks afterwards.
-- State 3: Firing
-- Check if unit busy, in which case increment State. Always waits 3 ticks afterwards.
-- State 4: Finished firing
-- If unit not busy, end the task, otherwise wait 3 ticks.

-- Only weapons with `ManualFire = true` and `OverChargeWeapon = false` in their blueprint can be used for tactical/nuke fire orders.

---@class moho.weapon_methods
local UnitWeapon = {}

---
---@return boolean
function UnitWeapon:BeenDestroyed()
end

--- `UnitWeapon:CanFire` calls this engine `CanFire` function that is used in the firing cycle, alongside
--- the self-explanatory `HasTarget`, `HasSiloAmmo`, and `TargetSolutionStatusGun() == TRS_Available` calls.
---
--- Here is the list of conditions for the engine `CanFire`, written in pseudo-lua with underscores ("_") for engine fields.
--- It can return early in the list, as indicated by the return statements. If no return is reached, it returns false.
--- !unit:IsStunned()
--- !unit:IsUnitState("Busy")
--- !unit.Blueprint.Air.CanFly or unit.Layer == "Air"
--- !unit.Blueprint.AI.NeedUnpack or unit:IsUnitState("Immobile")
--- Check if the weapon's below/above water firing restrictions.
--- if !unit.Blueprint.Air.Winged then return weapon._AimOnTarget end -- aim on target in terms of firing tolerance
--- !weapon.Blueprint.AutoInitiateAttackCommand or unit:_GetSpeed() >= 0.25 * unit.Blueprint.MaxAirSpeed * unit._SpeedMult
--- if !weapon.Blueprint.NeedToComputeBombDrop or !weapon:_HasTarget() then return weapon._AimOnTarget end
--- unit.IsUnitState("MakingAttackRun")
--- if weapon:_UnitIsInBombDropZone() then reutrn weapon._AimOnTarget end --Involves weapon BombDropThreshold and unit PredictAheadForBombDrop

--- Returns true if the weapon has a target and it can fire at it, identical to the engine's firing conditions.
---
--- This includes having a target, ammo, a firing solution for the target, aiming within firing tolerance, unit
--- not being busy or stunned, and a list of other conditions based on blueprint values.
---@return boolean
function UnitWeapon:CanFire()
end

---
---@param damage number
function UnitWeapon:ChangeDamage(damage)
end

---
---@param radius number
function UnitWeapon:ChangeDamageRadius(radius)
end

---
---@param typeName DamageType
function UnitWeapon:ChangeDamageType(typeName)
end

---
---@param tolerance number
function UnitWeapon:ChangeFiringTolerance(tolerance)
end

---
---@param max number
function UnitWeapon:ChangeMaxHeightDiff(max)
end

---
---@param maxRadius number
function UnitWeapon:ChangeMaxRadius(maxRadius)
end

---
---@param minRadius number
function UnitWeapon:ChangeMinRadius(minRadius)
end

--- Changes the projectile blueprint of a weapon
---@param projBp BlueprintId
function UnitWeapon:ChangeProjectileBlueprint(projBp)
end

---
---@param value number
function UnitWeapon:ChangeRateOfFire(value)
end

---
---@param muzzlebone Bone
---@return Projectile
function UnitWeapon:CreateProjectile(muzzlebone)
end

---
---@param bone Bone
---@param r number
---@param g number
---@param b number
---@param glow number
---@param width number
---@param texture string
---@param lifetime number
function UnitWeapon:DoInstaHit(bone, r, g, b, glow, width, texture, lifetime)
end

---
---@return boolean
function UnitWeapon:FireWeapon()
end

---
---@return WeaponBlueprint
function UnitWeapon:GetBlueprint()
end

---
---@return Blip | Unit | nil
function UnitWeapon:GetCurrentTarget()
end

---
---@return Vector
function UnitWeapon:GetCurrentTargetPos()
end

--- Returns the progress of the engine's firing clock determined by RateOfFire, usually from the blueprint
---@see ChangeRateOfFire
---@return number # within [0.0, 1.0]
function UnitWeapon:GetFireClockPct()
end

--- Gets the firing randomness
---@return number
function UnitWeapon:GetFiringRandomness()
end

---
---@return ProjectileBlueprint
function UnitWeapon:GetProjectileBlueprint()
end

--- Returns true if the given AimManipulator is the weapon's fire control
---@see SetFireControl
---@param label string label that was used to create the AimManipulator
---@return boolean
function UnitWeapon:IsFireControl(label)
end

---
---@param params SoundHandle
function UnitWeapon:PlaySound(params)
end

--- Force the weapon to recheck its targets. Also resets the counter for AttackGroundTries
function UnitWeapon:ResetTarget()
end

---
---@param enabled boolean
function UnitWeapon:SetEnabled(enabled)
end

--- Set the AimManipulator for which `OnFire` will be called when its
--- *defined* yaw/pitch bones are on target (within the firing tolerance).  
--- Defaults to the first aim controller that was created for the weapon.
---@param label string # label that was used to create the AimManipulator
function UnitWeapon:SetFireControl(label)
end

---
---@param mask string
function UnitWeapon:SetFireTargetLayerCaps(mask)
end

---
---@param randomness number
function UnitWeapon:SetFiringRandomness(randomness)
end

---
---@param entity Entity | Unit
function UnitWeapon:SetTargetEntity(entity)
end

---
---@param location Vector
function UnitWeapon:SetTargetGround(location)
end

--- Sets the targeting priorities for the unit
---@param priorities EntityCategory[]
function UnitWeapon:SetTargetingPriorities(priorities)
end

--- Transfers target from this weapon to another.  
--- The other weapon may still change targets automatically afterwards.
---@param otherWeapon Weapon
function UnitWeapon:TransferTarget(otherWeapon)
end

--- Returns true if the weapon currently has a target.
--- This only updates at the end of a tick, so it shouldn't be used in behavior relating to OnLostTarget or OnGotTarget callbacks
---@return boolean
function UnitWeapon:WeaponHasTarget()
end

return UnitWeapon