5.9 Specifying New Agent Resources

In an Apex human model, the general Action Selection Architecture does not interact with the world model directly. Instead, perceptual, cognitive, and motor resources comprising a resource architecture mediate interactions with the world and also constrain the agent to perform with human limits and other characteristics. Resources are implemented as software modules and may be replaced or modified with moderate effort¹³. This section describes how to create a new resource, e.g. a prehensile tail. Users interested in creating or modifying resources should look at examples in apex/app/building-blocks/human.

Step 1: Define the new resource type.

Every resource is implemented as Lisp class with slots representing resource state attributes. The following defines a class of resources called tail with a single state attribute called grasp. The value of this slot is a representation of an object that the tail is currently grasping - or nil if no such object exists.

(defclass tail (human-resource physob)
((grasp :accessor grasp :initarg :grasp :initform nil)))

tail inherits from the classes human-resource and physob (which itself inherits from visob - see Appendix B), which carry along a number of state attributes. Users are encouraged to study the definitions of these objects. New resource classes associated with a particular model can be stored in a simworld definitions file.

Step 2: Redefine the class standard-human to include the new resource.

Human models in Apex are instances of the class standard-human. As there is currently no support for human models based on other classes, standard-human and associated functions must be modified to make use of new resource types. This class is defined in <apex>/apexlib/human/human.lisp. The first required modification is to the class definition itself, adding a slot named for the new resource.

(tail :accessor tail :initarg :tail)

Next modify the assemble method defined in the same file to include a call to the function add-apex-resource.

(add-apex-resource (make-instance 'tail) human-1)

In some cases, it is useful to create active resources - i.e. resources that engage in some periodic behavior rather than passively accepting commands from the Action Selection Architecture. Such behaviors can be initialized in the assemble method. For example, the following line will initiate a wiggle action every 1000 simulation time units (1 unit = 1ms by default). This assumes that the method wiggle has been defined and, when called, produces an appropriate effect.

(start-activity human-1 'wiggle :resource (tail human-1) :update-interval 1000)

Step 3: If appropriate, define activities the new resource can be commanded to carry out.

Resources representing motor faculties (e.g. hands or tails) can be commanded to action by the PDL primitive action type start-activity. Each new kind of action (i.e. activity) is represented by a class (used to represent the state of the action at a given moment) and one or more methods defining the effect(s) of the activity. There are two kinds of methods: complete-activity and update-activity. The former is used to describe what happens when the activity comes to completion. The latter describes what happens at intervals prior to completion. The following definitions support the activity tail-grasp.¹⁴

(defclass tail-grasp (resource-activity)
((target :accessor target :initarg :target :initform nil)))

(defmethod
complete-activity ((act tail-grasp) (tail-1 tail)&key cause)
(signal-event
(grasped (target act) (setting act) :cause cause))

(defmethod grasped ((obj physob) (tail-1 tail) &key cause)
(setx (grasp tail-1) obj :cause cause))

A step from such as the following can be used to invoke this behavior from PDL:

(step s1 (start-activity tail tail-grasp :target banana
:duration 2500))

Step 4: If appropriate, define event-generating processes invoked by the resource.

Some resources, particularly those modeling perception, generate input to the Action Selection Architecture called cogevents. This is accomplished using the function cogevent

(cogevent <eventform> <agent> [:trigger-asa <Boolean>])

where <eventform> is an arbitrary list representing what has occurred and <agent> is a pointer to the (human) agent that has detected the event. The optional trigger parameter determines whether the event should be processed by the Action Selection Architecture immediately or whether it should be stored in a buffer and processed the next time a processing cycle for the architecture occurs.¹⁵

13. It not always necessary to define new resources to get some of the functionality. If the only need for a resource is to affect the agent’s resource allocation, it is enough to simply name the resource in a profile clause (making it a virtual resource). The action selection architecture will do resource conflict detection and resolution without regard for whether that resource is associated with a class definition.
    
    
14. Signal-event and setx are special forms used to track causal dependencies in a simulation. The former should be wrapped around a function or method call implementing a change of state to one or more simulated objects. setx should be used to effect the state change as it were setf.
    
    
15. There is no automatic architecture cycle; it must be triggered by a resource. In the default model, the vision resource triggers processing periodically.