Function; Useful Functions - HWRM/KarosGraveyard GitHub Wiki

--
-- USEFUL FUNCTIONS
--

SetTOSettings( TO_NoATIAtAll ) -- in m01_tanis.lua

-------------------------------------------------------------------------------
------------------------------------- MAP -------------------------------------
-------------------------------------------------------------------------------
addAsteroid(<sName>, <tLocation>, <f%RU>, <fxRot>, <fyRot>, <fzRot>, <null>)
-------------------------------------------------------------------------------
------------------------------------- GET -------------------------------------
-------------------------------------------------------------------------------
GetActualPlayerFleetExtraRU()
GetActualPlayerFleetSizeInRU()
getCurrentLevelName()
GetGameSettingAsNumber()
GetGameSettingAsString()
getglobal()
GetMultiplierForExtraRU()
GetMultiplierForExtraShips()
getn()
GetReactiveFleetExtraRU()
GetReactiveFleetSizeInRU()
GetResearchId()
GetRulesFormat()
GetRulesHasTag()
GetRulesName()
getRulesNum()
GetShipId()
getShipNum()
GetSubSystemId()
gettagmethod()
-------------------------------------------------------------------------------
------------------------------------- CPU -------------------------------------
-------------------------------------------------------------------------------
CPU_RemoveSobGroup( 1, "InitialAttack_Bombers1" )
-------------------------------------------------------------------------------
---------------------------------- SELECTION ----------------------------------
-------------------------------------------------------------------------------
Selection_GetMissiles("AllMissiles") -- gets all missiles!
Selection_GetResources(<sSelection>, <sResourceType>) -- Tested with "Salvage" and "Asteroids"
Selection_FilterExclude(<sSelectionToPopulate>, <sSelectionToFilter>, <sFilterType>, <?Filter>, <?FilterValue>) -- <sFilterType> = "ScriptFlagsSetAll" or "NearPoint" or "PlayerOwner"
Selection_SetVelocity(<sSelection>, <tVelocity>)
Selection_Create(<sSelection>) -- Creates an empty selection
Selection_FilterInclude(<sSelectionToPopulate>, <sSelectionToFilter>, <sFilterType>, <?Filter>, <?FilterValue>) -- <sFilterType> = "ScriptFlagsSetAll" or "NearPoint" or "PlayerOwner"
-------------------------------------------------------------------------------
------------------------------------ PLAYER -----------------------------------
-------------------------------------------------------------------------------
Player_AddLocalChatMessage()
Player_AllowDockFromUIOverride()
Player_BuildOptionIsRestricted()
Player_CancelResearch()
Player_CanResearch()
Player_FillProximitySobGroup()
Player_FillShipsByType()
Player_FillSobGroupInVolume()
Player_GatheredRUs()
Player_GetLevelOfDifficulty()
Player_GetLocalPlayerID()
Player_GetName()
Player_GetNumberOfSquadronsOfTypeAwakeOrSleeping()
Player_GetRace()
Player_GetResearchCost()
Player_GetRU()
Player_GetShipsByFilterExclude()
Player_GetShipsByFilterInclude()
Player_GetShipsByType()
Player_GrantAllResearch()
Player_GrantResearchOption()
Player_HasQueuedBuild()
Player_HasQueuedResearch()
Player_HasResearch()
Player_HasResearchPrequisitesToBuild()
Player_HasShipWithBuildQueue()
Player_HasSubsystem()
Player_InstantDockAndParade()
Player_InstantlyGatherAllResources()
Player_InstantlyGatherAllResourcesAllTypes()
Player_IsAlive()
Player_IsResearching()
Player_IsShipInVolume()
Player_Kill()
Player_NumberOfAwakeShips()
Player_PauseBuildQueues()
Player_Research()
Player_ResearchOptionIsComplete()
Player_ResearchOptionIsRestricted()
Player_RestrictAllResearch()
Player_RestrictBuildOption()
Player_RestrictResearchOption()
Player_SetBadgeTexture()
Player_SetBounty()
Player_SetGlobalROE()
Player_SetGlobalStance()
Player_SetPlayerName()
Player_SetResearchCost()
Player_SetRU()
Player_SetTeamColours()
Player_SetTeamColourTheme()
Player_ShareVision()
Player_UnpauseBuildQueues()
Player_UnrestrictBuildOption()
Player_UnrestrictResearchOption()
playerOwner()
PlayerRace_DoesHaveTag()
PlayerRace_GetNumber()
PlayerRace_GetString()
-------------------------------------------------------------------------------
----------------------------------- SOBGROUP ----------------------------------
-------------------------------------------------------------------------------
Sob_DoesHaveTag()
Sob_GetStaticNumber()
Sob_GetStaticString()
SobGroup_AbilityActivate(<sSobGroup>,<sAbility>,<bActivate>) -- activates (or not) an ability
SobGroup_AddFilterExclude()
SobGroup_AddFilterInclude() -- e.g. (sobGroupNameToFill, sobGroupName, "displayFamily", "Capital")
SobGroup_AllowPassiveActionsAlways()
SobGroup_AreAllInHyperspace()
SobGroup_AreAllInRealSpace()
SobGroup_AreAnyFromTheseAttackFamilies()
SobGroup_AreAnyOfTheseTypes(<sSobGroupToCheck>, <sShiptype1>, <sShipType2>, ...) -- returns 1 or 0
SobGroup_AreAnySquadronsInsideDustCloud()
SobGroup_AreAnySquadronsInsideNebula()
SobGroup_AreAnySquadronsOutsideDustCloud()
SobGroup_AreAnySquadronsOutsideNebula()
SobGroup_AssignedToGroup()
SobGroup_Attack()
SobGroup_AttackPlayer(<sSobGroupName>, <iPlayerIndex>)
SobGroup_AttackSelection()
SobGroup_AttackSobGroupHardPoint()
SobGroup_AutoEngineGlow()
SobGroup_AvoidanceIgnore(<sSobGroup>, <sSobGroupToIgnore>) -- ignore another group's collision mesh
SobGroup_CanDoAbility(<sSobGroup>, <sAbility>) -- returns 1 if yes
SobGroup_CaptureSobGroup()
SobGroup_ChangePower()
SobGroup_Clear(<sSobGroupName>) -- empties the sob  group (not by killing ships..)
SobGroup_ClearScriptFlag()
SobGroup_ClearTumble()
SobGroup_CloakToggle()
SobGroup_Copy(<sSobGroupNew>, <sSobGroupSource>)
SobGroup_Count(<sSobGroup>) -- Returns the quantity of ships in the group
SobGroup_CountByFilterExclude()
SobGroup_CountByFilterInclude()
SobGroup_CountByPlayer()
SobGroup_CountByScriptFlag()
SobGroup_Create(<sSobGroupName>) -- creates an empty sob group
SobGroup_CreateIfNotExist(<sSobGroupName>)
SobGroup_CreateShip(<sSobGroupCreating>, <sShipTypeToCreate>) -- returns a SobGroup with the created ship in it
SobGroup_CreateSubSystem(<sSobGroupCreating>, <sSubsystemToCreate>)
SobGroup_CreateSubSystemCheck()
SobGroup_CurrentHealthTotal()
SobGroup_CustomCommand()
SobGroup_CustomCommandTargets()
SobGroup_DeployMines()
SobGroup_DeployMinesInCuboid()
SobGroup_DeployMinesInSphere()
SobGroup_DeSelectAll()
SobGroup_Despawn()
SobGroup_Disable(<sSobGroup>,<fTime>) -- makes a sobgroup "crazy" for a time...
SobGroup_DockSobGroup(<sSobGroup>,<sSobGroupToDockWith>) -- docks a group with another group
SobGroup_DockSobGroup_NoLatch()
SobGroup_DockSobGroupAndStayDocked()
SobGroup_DockSobGroupInstant(<sSobGroupDockingName>, <sSobGroupDockWithName>)
SobGroup_DockSobGroupWithAny()
SobGroup_DoDamageProximitySobGroup()
SobGroup_Empty()
SobGroup_EnterHyperSpaceOffMap(<sSobGroup>)
SobGroup_Exists()
SobGroup_ExitHyperSpace()
SobGroup_ExitHyperSpaceSobGroup()
SobGroup_FillBattleScar()
SobGroup_FillBattleScar_Debug()
SobGroup_FillCompare(<sSobGroupOutName>, <sSobGroupName1>, <sSobGroupName2>) -- ships shared by 1 and 2
SobGroup_FillIntersect()
SobGroup_FillProximityPoint()
SobGroup_FillProximitySobGroup()
SobGroup_FillShipsByFamily()
SobGroup_FillShipsByIndexRange()
SobGroup_FillShipsByType()
SobGroup_FillSobGroupByHealthBelow()
SobGroup_FillSobGroupInVolume()
SobGroup_FillSubstract()
SobGroup_FillSubtract()
SobGroup_FillUnion(<sSobGroupOutput>, <sSobGroup1>, <sSobGroup2>) -- new group containing 1 and 2
SobGroup_FilterExclude()
SobGroup_FilterInclude()
SobGroup_FollowPath(<sSobGroup>, <sPath>)
SobGroup_ForceStayDockedIfDocking()
SobGroup_FormHyperspaceGate()
SobGroup_FormSquadron()
SobGroup_FormStrikeGroup()
SobGroup_GetActualSpeed(<sSobGroup>)
SobGroup_GetAttackers(<sSobGroup>)
SobGroup_GetCentrePosition(<sSobGroup>) -- gets centre position of group
SobGroup_GetCommandTargets(<sOutputSobGroup>, <sSobGroupDoingTargetting>, <sCommand>) -- <sCommand> = COMMAND_Attack or COMMAND_Guard
SobGroup_GetCoordSys(<sSobGroup>) -- outputs
SobGroup_GetCurrentOrder(<sSobGroup>) -- 1=move, 2=attack, 3=?, 4=dock
SobGroup_GetDistanceToSobGroup(<sSobGroup1>, <sSobGroup2>) -- returns distance between two groups
SobGroup_GetHardPointHealth()
SobGroup_GetNextPathPoint()
SobGroup_GetPlayerOwner()
SobGroup_GetPosition(<sSobGroup>)
SobGroup_GetROE()
SobGroup_GetShipType(<sSobGroup>)
SobGroup_GetSobGroupBeingCapturedGroup()
SobGroup_GetSobGroupCapturingGroup()
SobGroup_GetSobGroupDockedWithGroup()
SobGroup_GetSobGroupRepairingGroup()
SobGroup_GetSobGroupSalvagingGroup()
SobGroup_GetSpeed(<sSobGroupName>)
SobGroup_GetSquadronsInsideDustCloud()
SobGroup_GetSquadronsInsideNebula()
SobGroup_GetStance()
SobGroup_GetStaticF(<shiptype>, "buildcost") -- or "buildtime"
SobGroup_GetTechHarvestedAmount()
SobGroup_GroupInGroup()
SobGroup_GuardSobGroup(<sSobGroupName>, <sSobGroupToGuardName>) -- issues guard command
SobGroup_HasBeenRendered()
SobGroup_HasFiredAtSobGroup(<sSobGroupFiringName>, <sSobGroupBeingShotName>, <sWeaponBeingFiredName>) -- checks attack command, not firing...
SobGroup_HasSubsystem()
SobGroup_HasUpgrade()
SobGroup_HealthPercentage()
SobGroup_HyperspaceTo()
SobGroup_HyperspaceToVector(<sSobGroup>, <tPosition>)
SobGroup_InactiveWhenCaptured()
SobGroup_InStrikeGroup()
SobGroup_InWorldBound()
SobGroup_IsBuilding()
SobGroup_IsCloaked()
SobGroup_IsDocked(<sSobGroupName>)
SobGroup_IsDockedCompletely(<sSobGroupName>)
SobGroup_IsDockedSobGroup(<sSobGroupName>, <sSobGroupNameDockedWith>)
SobGroup_IsDoingAbility(<sSobGroupName>, <iAbility>)
SobGroup_IsGateDeployed(<gate1>, <gate2>) -- checks if gate1 is linked to gate2
SobGroup_IsGuardingSobGroup()
SobGroup_IsInControlGroup()
SobGroup_IsInVolume(<sSobGroup>, <sVolume>)
SobGroup_IsReturningHarvest()
SobGroup_IsReturningSalvage()
SobGroup_IsSelectable()
SobGroup_IsShipNearPoint()
SobGroup_Kamikaze()
SobGroup_Launch()
SobGroup_LaunchSelf()
SobGroup_LeaveStrikeGroup()
SobGroup_LoadPersistantData()
SobGroup_MakeDead(<sSobGroupName>)
SobGroup_MakeSelectable()
SobGroup_MakeUntargeted()
SobGroup_ManualEngineGlow()
SobGroup_MaxHealthTotal()
SobGroup_MinimumHealth()
SobGroup_Move(<iPlayerIndex>, <sSobGroup>, <sVolumeOrPoint>)
SobGroup_MoveToPoint(<iPlayerIndex>, <sSobGroup>, <sVolumeOrPoint>)
SobGroup_MoveToSobGroup()
SobGroup_OnScreen()
SobGroup_OwnedBy()
SobGroup_ParadeSobGroup(<sSobGroupName>, <sSobGroupParadeRoundName>, <iParadeMode>) -- i = 0(normal)/1(with hyperspce)/2(instant). NB: errors with this function are sometimes referred to as "SobGroup_DockSobGroup" in the log
SobGroup_PlayerIsInSensorRange()
SobGroup_ReleaseSalCapSobGroup()
SobGroup_RemoveFromAll()
SobGroup_RemoveType()
SobGroup_RepairSobGroup()
SobGroup_ResearchModuleExistOrSelected()
SobGroup_ResetAvoidanceIgnore()
SobGroup_ResetRenderedFlags()
SobGroup_Resource(<iPlayer>, <sSobGroup>) -- issues the "harvest" command
SobGroup_RestrictBuildOption()
SobGroup_SalvagedByPlayer()
SobGroup_SalvageSobGroup()
SobGroup_Selected(<sSobGroupName>) -- is group selected?
SobGroup_SelectSobGroup(<sSobGroupName>)
SobGroup_SetAsDeployed()
SobGroup_SetAutoLaunch()
SobGroup_SetBuildSpeedMultiplier()
SobGroup_SetCaptureAlwaysDisables()
SobGroup_SetCaptureState()
SobGroup_SetDamageMultiplier()
SobGroup_SetDisplayedRestrictedHardpoint()
SobGroup_SetEventID()
SobGroup_SetFiredAtSobGroup()
SobGroup_SetFixed(<sSobGroup>, <bOnOff>) -- seems to be something to do with formations?
SobGroup_SetGhost(<sSobGroup>, <iGhost>) -- used in HW1 M10, no idea what ghost is...
SobGroup_SetHardPointHealth()
SobGroup_SetHealth(<sSobGroup>, <fHealth>)
SobGroup_SetHidden()
SobGroup_SetIgnoreWorldBounds(<sSobGroup>, <bIgnore>) -- 1 = ignore
SobGroup_SetInherentVisibility("MineLayingTeam1", 0, VisFull) -- used in HW1RM m10
SobGroup_SetInRadiation()
SobGroup_SetInvulnerability()
SobGroup_SetInvulnerabilityOfHardPoint()
SobGroup_SetMadState(<sSobGroup>, <sMadState>) -- e.g. "Docked" or "CodeGreen"
SobGroup_SetMaxSpeed(<sSobGroup>, <fMaxSpeed>)
SobGroup_SetMaxSpeedMultiplier()
SobGroup_SetPosition(<sSobGroup>, <tPosition>) -- moves a group instantly to a position
SobGroup_SetRetaliation()
SobGroup_SetROE()
SobGroup_SetScriptFlag()
SobGroup_SetShaderValues()
SobGroup_SetSpeed(<sSobGroup>, <fSpeed>) -- sets the speed
SobGroup_SetStance()
SobGroup_SetSwitchOwnerFlag()
SobGroup_SetTeamColours()
SobGroup_SetTeamColourTheme()
SobGroup_SetTransform(<sSobgroup>,<tCoords>) -- set the SobGroup rotation to a 9-value rotation table
SobGroup_SobGroupAdd(<sSobGroupTarget>, <sSobGroupToBeAdded>)
SobGroup_Spawn(<sSobGroupName>, <sVolumeName>)
SobGroup_SpawnNewShipInSobGroup(<iPlayerIndex>, <sShipType>, <sSquadronName>, <sSobGroupToAddToName>, <sVolumeName>)
SobGroup_SpawnToVector(<sSobGroup>, <tPosition>) -- Spawns a group in a specific position
SobGroup_SplitGroupFromGroup()
SobGroup_Stop(<iPlayer>, <sSobGroupToStop>) -- issues the stop command
SobGroup_SubSystemSelected()
SobGroup_SwitchOwner(<sSobGroupName>, <iPlayerIndex>)
SobGroup_TakeDamage()
SobGroup_TakeDamageAbsolute()
SobGroup_Tumble()
SobGroup_UnderAttack()
SobGroup_UnRestrictBuildOption()
SobGroup_UpdateClass()
SobGroup_UseHyperspaceGate()



-- Commmands (from SobGroup_GetCurrentOrder(<sSobGroup>))
COMMAND_Attack = 2
COMMAND_AttackMove = 20
COMMAND_Build = 3
COMMAND_Capture = 10
COMMAND_Despawn = 17
COMMAND_Dock = 4
COMMAND_FormHyperspaceGate = 13
COMMAND_Guard = 9
COMMAND_Hyperspace = 11
COMMAND_HyperspaceViaGate = 14
COMMAND_Idle = 0
COMMAND_Launch = 6
COMMAND_LayMines = 18
COMMAND_Move = 1
COMMAND_MoveToSob = 12
COMMAND_NumCommands = 25
COMMAND_Parade = 8
COMMAND_RallyParade = 21
COMMAND_Repair = 15
COMMAND_Resource = 5
COMMAND_Retire = 16
COMMAND_Salvage = 19
COMMAND_WaypointMove = 7


-- abilities
AB_None
AB_Move
AB_Attack
AB_Guard
AB_Repair
AB_Cloak
AB_Harvest
AB_Mine
AB_Capture
AB_Dock
AB_AcceptDocking
AB_Builder
AB_Stop
AB_Hyperspace
AB_Parade
AB_FormHyperspaceGate
AB_HyperspaceViaGate
AB_SensorPing
AB_SpecialAttack 
AB_Retire 
AB_DefenseField 
AB_DefenseFieldShield 
AB_HyperspaceInhibitor 
AB_Salvage 
AB_Steering 
AB_Targeting 
AB_Sensors 
AB_Lights 
AB_Scuttle 
AB_UseSpecialWeaponsInNormalAttack





function SobGroup_SplitGroup(SobGroupOut, SobGroupToSplit, ReferenceGroup)
    local sobgroups_produced = {}

    local remaining_ships = "remaining_ships"
    SobGroup_Create(remaining_ships)
    SobGroup_Clear(remaining_ships)
    SobGroup_SobGroupAdd(remaining_ships, SobGroupToSplit) -- just copy into new group

    local ships_within_interval = "ships_within_interval"
    SobGroup_Create(ships_within_interval)
    SobGroup_Clear(ships_within_interval)

    local reference_point = {}
    if (SobGroup_Count(ReferenceGroup) == 0) then
        reference_point = SobGroup_GetCentrePosition(SobGroupToSplit)
    else
        reference_point = SobGroup_GetCentrePosition(ReferenceGroup)
    end

    local interval = 50
    local step = 1
    while (SobGroup_Count(remaining_ships) > 0) do
        local current_distance = interval * step
        SobGroup_FillProximityPoint(ships_within_interval, remaining_ships, reference_point, current_distance)
        if (SobGroup_Count(ships_within_interval) == 0) then -- failed to grab anything, expand search
            step = step + 1 -- grow the sphere
        else if (SobGroup_Count(ships_within_interval) > 1) then -- grabbed too much, make the interval twice as sensitive
            local coord_to_offset = ceil(random(0, 3))
            reference_point[coord_to_offset] = reference_point[coord_to_offset] + 1 -- offset our ref point a little
            interval = interval / 2
            step = (step - 1) * 2 -- step back but keep our current progress considering new interval size
        else -- we got 1 ship, perfect
            local new_group = SobGroupOut .. (getn(sobgroups_produced) + 1) -- index from 1
            SobGroup_Create(new_group)
            SobGroup_Clear(new_group)
            SobGroup_SobGroupAdd(new_group, ships_within_interval) -- create the sg
            sobgroups_produced[getn(sobgroups_produced)] = new_group  -- make a record of this
            SobGroup_FillSubstract(remaining_ships, remaining_ships, new_group) -- remove this ship from the pool
            reference_point = new_group -- start searching again from here
            step = step + 1 -- grow the sphere
        end
    end
end

-------------------------------------------------------------------------------
--Regarding filters
-------------------------------------------------------------------------------
An exploration of all the FilterInclude and FilterExclude functions, examples of their calling, and what they can be fed.

Player_ functions fill a passed sob-group. There are some LCWatcher_ functions that deal with filters, but I can only find one example of any LCWatcher_ functions being called anywhere and it's something to do with voice lines. There's also a BKG_EditFilter but again no example of it is forthcoming in the stock files. Selections and Sobgroups do not appear to be interchangable but this has not been tested.

#Functions pulled from a global dump of the gamerule context.
  Player_GetShipsByFilterExclude()--Player_GetShipsByFilterExclude(0, selectToDock, "Ability", "HyperSpaceCommand") 
  Player_GetShipsByFilterInclude()--Player_GetShipsByFilterInclude(0, "KAS_AttackHarrass_Targets", "NoFilter", "")
  Selection_FilterExclude()--Selection_FilterExclude("IncomingMissiles", "AllMissiles", "PlayerOwner", ""..playerID, "")
  Selection_FilterInclude() -- Selection_FilterInclude("IncomingMissiles", "IncomingMissiles", "NearPoint", defensePointString, ""..4500)
  SobGroup_AddFilterExclude()--SobGroup_AddFilterExclude(sobGroupNameToFill, sobGroupName, "displayFamily", "Capital")
  SobGroup_AddFilterInclude()--SobGroup_AddFilterInclude("PlayerStrikeCraftNearOffice", "PlayerShipsNearOffice", "displayFamily", "Corvette")
  SobGroup_CountByFilterExclude() --Appears to never be used
  SobGroup_CountByFilterInclude() --SobGroup_CountByFilterInclude("temp", "DockFamily", "drone") 
  SobGroup_FilterExclude()--if (SobGroup_FilterExclude("GrowSelection_Move", TeamName, "CurrentCommand", "COMMAND_Idle") == 0) then
  SobGroup_FilterInclude()--SobGroup_FilterInclude("PlayerStrikeCraftNearOffice", "PlayerShipsNearOffice", "displayFamily", "Fighter")

#Observed categories fed to filters, and parenthteical sub-categories for those where it's not obvious.
Ability(SalcapCommand,RepairCommand,CustomCommand,MoveCommand,CloakAbility,HyperSpaceCommand)
AttackFamily
CurrentCommand(COMMAND_Idle,COMMAND_Attack,COMMAND_Hyperspace,COMMAND_Dock,COMMAND_Launch)
CurrentCommandState(SALCAPSTATE_ReturningToBaseWithTech,LAUNCHSTATE_Queue,DOCKSTATE_Docked)
displayFamily
Docked
DockFamily
NearPoint("x,y,z","r")
NoFilter
PlayerOwner
ScriptFlagsSetAll
ShipType