👀Perception

Reminder of what is a perception

A perception is the way of the NPC to query external data about the world and store it. For example NACT comes with a few perceptions by default.

Analyzing the Surroundings perception

We will take a look at the Surroundings perception. It's goal is to query informations about how much ennemies and allies are surroundings the NPC.

Before jumping into how a Perception is created, this is how it is called inside a Planner:

    self.npc:AddPerception(Perception_Surroundings, {
        identifier = "melee",
        radius = 100,
        refresh_rate = 50
    })

We will start by the serverside.

Constructor and refresh rate

A perception is a class. First we create our class definition following ClassLib

Perception_Surroundings = BaseClass.Inherit("Perception_Surroundings")

We then create our constructor. The constructor has two parameters:

• The NACT Entity (in short a NPC, but it can also be a Squad or a Territory)

• Any additionnal configuration that can be passed to define our Perception

And we store everything we might need

function Perception_Surroundings:Constructor(oNactEntity, tAdditionalConfig)
    self.entity = oNactEntity
    self.radius = tAdditionalConfig.radius
    self.identifier = tAdditionalConfig.identifier
    self.refresh_rate = tAdditionalConfig.refresh_rate
    self.debug = tAdditionalConfig.debug or false
end

Finally, as with almost any NACT classes, we need to define a refresh rate:

function Perception_Surroundings:GetRefreshRate()
    return self.refresh_rate
end

Refresh rate is defined by a function, while this is unused, the idea is that you could specify different refresh rate depending on the context.

Tick

Like with most classes of NACT, we need to define a Tick.

function Perception_Surroundings:Tick()
    -- Console.Log("Perception tick"..NanosTable.Dump(self.npc))
    local pAuthority = self.entity:GetNetworkAuthority()
    
    -- Console.Log("Perception authority : "..NanosTable.Dump(pAuthority))
    if (pAuthority) then
        Events.CallRemote(
            "NACT:PERCEPTION:SURROUNDINGS_QUERY",
            pAuthority,
            self:GetID(),
            self.entity:GetLocation(),
            self.entity:GetTeam(),
            self.radius,
            self.debug
        )
    else
        self:ProcessResult(nil)
    end
end

As you can see, the surroundings perception does not do much in the Serverside, what it does is querying the Client, more specifically the current Network Authority of the NPC, where the rest of the code happends.

Clientside part

The surroundings perception will launch a Spherical Trace in the clientside, the code is a bit big so I will not explain it completly there, but if we look at the code that handles the event:

Events.SubscribeRemote("NACT:PERCEPTION:SURROUNDINGS_QUERY", function(iRequestorID, vSourceLocation, iSourceTeam, iProximityRadius, iDrawDebug)
    tPendingSurroundingQueries[#tPendingSurroundingQueries+1] = {iRequestorID, vSourceLocation, iSourceTeam, iProximityRadius}
    local tCharacterLocation = vSourceLocation
    local iCharacterTeam = iSourceTeam

    local iDrawMode = TraceMode.ReturnEntity
    if (iDrawDebug) then
        iDrawDebug = TraceMode.ReturnEntity | TraceMode.DrawDebug
    end

    local tSurroundingResults = {}
    local tTraceResult = Trace.SphereMulti(
        tCharacterLocation,
        tCharacterLocation,
        iProximityRadius,
        CollisionChannel.Pawn,
        iDrawMode
        -- TraceMode.ReturnEntity | TraceMode.DrawDebug,
        -- TraceMode.ReturnEntity
    )
    
    local tCleanedResults = processTraceResults(tTraceResult)
    tSurroundingResults = splitEnemiesAndAllies(iCharacterTeam, tCleanedResults)

    Events.CallRemote("NACT:PERCEPTION:SURROUNDINGS_RESULT", iRequestorID, tSurroundingResults)
    -- Console.Log("Surrounding results : "..NanosTable.Dump(tSurroundingResults))
end)

Basically, what this does is creating a Spherical Trace, split the enemies and the allies then return back the results to the perception code Serverside.

Storing the result in the blackboard

Finally, if we go back to the server, we will look at what happends when we receive our results

function Perception_Surroundings:ProcessResult(tResults)
    self.entity.blackboard:SetValue("surroundings_"..self.identifier, tResults)
end

Events.SubscribeRemote("NACT:PERCEPTION:SURROUNDINGS_RESULT", function(_, iRequestorID, tResults)
    local oTargetClass = Perception_Surroundings.GetByID(iRequestorID)
    -- Console.Log("Target class : "..NanosTable.Dump(oTargetClass))
    if (oTargetClass) then
        oTargetClass:ProcessResult(tResults)
    else
        Console.Warn("Received result for a perception but target class was not found")
    end
end)

What happends is that we store the results of what was sent into the Blackboard of the entity, with the identifier. So, for example, if there is an enemy surrounding us in the "melee" surroundings perception, we will store the information inside this blackboard. Wich will then be used by the Planner to take action because of that.

Reacting to Damage with the DamageTaken perception

Reacting to a nanos event is also a perception you might need, for example when an NPC takes damage.

On the presets NPC this is done via the Perception_DamageTaken perception:

Perception_DamageTaken = BaseClass.Inherit("Perception_DamageTaken")

function Perception_DamageTaken:Constructor(oNactNpc)
    self.npc = oNactNpc
    
    local _self = self
    self.npc.character:Subscribe("TakeDamage", function(self, iDamage, sBone, xType, vFrom, pInstigator, eCauser)
        _self:ProcessResult(iDamage, vFrom, eCauser)
    end)
end

As you can see, aside from the classic boilerplate of perceptions what we do is listen to the nanos TakeDamage event and call our ProcessResult event

function Perception_DamageTaken:ProcessResult(iDamage, vFrom, eCauser)
    self.npc.blackboard:SetValue("damage_taken", {
        from = eCauser:GetLocation(),
        causer = eCauser,
        amount = iDamage
    })
end

Finally we store the damage that just has been taken so that the NPC planner can take decisions based on what we stored :)