Sandbox (Procedure)

Behavior

Description:
The Sandbox Procedure makes the actor look "active" by interacting with various things in his environment. It takes various parameters defining what activities it is allowed to perform while "sandboxing."

1. Procedures: The actor moves around within a specified location and interacts with furniture, idle markers, and other NPCs, looking purposeful and intelligent (or, at least, active and engaged with its environment).
2. Activities: If allowed to eat, it eats breakfast, lunch and dinner at times selected randomly from within an appropriate range of hours (specified by gamesettings). Likewise for sleeping, if allowed to sleep.

The procedure completes:
Never completes.

Parameters

• Location (Location): Specifies the area that the actor will Sandbox within
• AllowEating (Bool): Specifies whether the actor is allowed to eat while Sandboxing
• AllowSleeping (Bool): Specifies whether the actor is allowed to sleep (in beds) while Sandboxing. (Occurs most often "at night")
• AllowConversation (Bool): Specifies if the actor should decide to talk to other actors while Sandboxing (see: Random Conversations)
• AllowIdleMarkers (Bool): Specifies whether the actor is allowed to use Idle Markers while Sandboxing.
• AllowFurniture (Bool): Specifies whether the actor is allowed to use furniture while Sandboxing.
• AllowSitting (Bool): Specifies whether the actor is allowed to use chairs (and other furniture whose markers are of type "Sit" or "Lean", but not "Sleep", and not furniture with the "Special" keyword) while Sandboxing.
• AllowWandering (Bool): Specifies whether the actor is allowed to aimlessly wander while Sandboxing. (Usually False)
• WanderPreferrefPath (Bool): If true, the actor will stay exclusively on preferred-path navmesh triangles when wandering.
• Energy (Float): Used in the formulas for how much time to spend on each type of sub-procedure. See "Procedure Duration Formulas" below.
• AllowSpecialFurniture (Bool): Specifies whether the actor is allowed to use furniture with the "Special" keyword (for instance: grindstones, forges, alchemy tables, arcane enchanters etc.) while Sandboxing.
• MinWanderDistance (Float): The minimum distance away from his current position the actor will decide to wander to when picking a point on the navmesh within the sandbox distance when AllowWandering is true.

               

Notes

• If you are creating a new package, and you want it to include a Sandbox procedure that will end after a specified amount of time, put the Sandbox in a Simultaneous node along with a Wait procedure. (A Simultaneous node completes when any of its children complete, so it will end when the Wait runs out of time.)
• They don't eat real food: When the Sandbox runs an Eat procedure, it never consumes real food items from the actor's inventory.
• Other NPCs can still talk to them: Setting AllowConversations to false will not stop other NPCs from starting conversations with the sandboxing NPC. It only prevents the sandboxing NPC from choosing to start conversations with others.
• They stay in their sandbox location: If a sandboxing actor chooses to talk with an NPC who then moves outside the Location, it will give up pursuit once the target leaves the Location.
• They check ownership: A sandboxing actor will only use idle markers and furniture if they are not owned, or if they are owned by the NPC or its faction.
• They reserve their targets, and respect reservations: Sandboxing actors place a reservation on the target ref with which they want to interact. No other sandboxing actor will attempt to use those refs.
• You can chain sandbox markers via LinkedRefs but this is kludgy: If the Location is a ref with Patrol data and a linked ref, the actor will remain in that location for the duration specified by the Patrol data, and then move along to the LinkedRef, to continue sandboxing there. So, sandboxes can be chained, like they could in Fallout. However: it is now very easy to build (or to ask an expert to build) a specialized package that is a sequence of sandbox procedures, so this is only questionably relevant anymore.

Action Selection

When a sandbox package starts up, it builds a list of nearby objects with which it could interact. To select an action, it computes a score for each object, based on the specifics of that object. That score will be set to zero if that object becomes an invalid target, or if it was the same object that the sandbox just selected previously. Each object's score is then weighted by a relative "probability" value based on the type of the interaction (i.e. sleep, eat, use furniture, use idle markers, or dialogue). The sandbox maintains these probability values over time, adjusting them each time it choses a target object. It drops the probability to zero for the type that was just chosen, and increases the probability for the other types. This ensures that the actor will not select the same kind of action repeatedly (unless it has no other options). For example, after eating, the probability of eating again immediately will be zero, but will increase over time as the actor performs actions other than eating.

Idle Markers

Much of the behavior of an NPC using the sandbox package results directly from data attached to objects in the world (idle markers, with collections of potential animation), or simply from the presence of objects in the word (furniture, food, other NPCs), with no extra data required.

See Idle Markers for more information about what can be specified on a marker.

Sleeping

Sleep time and duration is calculated when the sandbox package starts, and then recalculated once per day as necessary.

Sleeping is based on the following gamesettings:

iSandboxSleepStartMin

Min time to start sleeping. (Default = 19)

iSandboxSleepStartMax

Max time to start sleeping. (Default = 1)

iSandboxSleepDurationMin

Minimum duration for sleeping. (Default = 6)

iSandboxSleepDurationMax

Maximum duration for sleeping. (Default = 10)

Start Time

Rolls randomly for sleep start time between iSandboxSleepStartMin and iSandboxSleepStartMax.

So sandboxing actors can start sleeping between 19:00 and 1:00, using these gamesettings.

Duration

Rolls randomly for sleep duration using iSandboxSleepDurationMin and iSandboxSleepDurationMax.

Eating Meals

Sandboxing actors calculate their mealtimes when the sandbox package starts, and then recalculate them once per day as necessary.

The meal times are based on the following gamesettings:

iSandboxBreakfastMin

Min time to start eating breakfast. (Default = 6)

iSandboxBreakfastMax

Max time to start eating breakfast. (Default = 9)

iSandboxLunchMin

Min time to start eating lunch. (Default = 11)

iSandboxLunchMax

Max time to start eating lunch. (Default = 14)

iSandboxDinnerMin

Min time to start eating dinner. (Default = 17)

iSandboxDinnerMax

Max time to start eating dinner. (Default = 20)

iSandboxMealDurationMin

Min duration for eating a meal. (Default = 0)

iSandboxMealDurationMax

Max duration for eating a meal. (Default = 2)

Other Behaviors

When not sleeping or eating a meal, the actor can engage in other activities -- if allowed by the package and available within the package radius.

Sandbox Debug Page

A tool for investigating the inner workings of the Sandbox procedure, to help diagnose bugs. It provides both textual and graphical representations of the sandbox's internal state.

To access the Sandbox debug page from the console, first open the AI debug pages:

tdt
sdt npcai

Then close the console and PageDown twice (to Page 3). This is the sandbox debug page.

Procedure Debug Info

Located in the top-left corner of the debug page.

• Sandbox Package State:
  • "Getting Up": the NPC thinks it is leaving a furniture object, in order to move to its target.
  • "Moving": the NPC thinks it is en route to its target
  • "Performing": the NPC thinks it is at its target and performing the selected procedure.
• Sandbox Procedure: Sit, Sleep, Eat, Idle Marker, Dialogue, or Wander
• Sit/Sleep State: Generally "Normal" unless the actor is "Sitting." (When a sandboxing actor is stuck, check this; if it's out of sync with the actor's animation, look for relevant warnings in the warnings file.)
• Procedure time remaining: When this reaches zero, the actor should pick a new procedure (and until then they shouldn't). Dialogue is an exception; it should last as long as the scene lasts.
• List of Potential Targets: This is color-coded, and contains the name and form ID for each potential target. There is also a circle drawn at the object's location in the world.
  • Green text & circle: The current target.
  • Purple text &circle: The previous target. Actors will not reselect this, unless it's the only option.
  • Red text & circle: A target that could not have been selected, because it is currently reserved for use by another actor.
  • Grey text/cyan circle: A target that wasn't picked for use this time, but could have been. The brighter the circle, the likelier this option is.

Activity Debug Info

Located in the top-right corner of the debug page.

• Next activity: the type of activity (meal or sleep) that is running or is scheduled to start next. Note the "not active yet" message if this isn't
• Activity start: At what hour of the day will we start the relevant procedure for this activity.
• Activity duration: How long the activity will last.

Procedure Weights

Located on the right side of the debug page. One for each procedure type. This weight is multiplied with the weight for each specific target. When the actor performs a procedure, the weight for that procedure type is set to zero, and all the others are increased by one.

Procedure Duration Formulas

Let's work through the duration formulas, using Furniture as an example. Variable names in italics are the names of gamesettings.

• We start by computing a baseline duration value for using furniture:

BaseDuration = fSandboxDurationBase * fSandboxDurationMultFurniture

• We then use the procedure's Energy parameter to modify that baseline:

EnergyDuration = BaseDuration * ( 1.0 + Energy * fSandboxEnergyMult * fSandboxEnergyMultFurniture )

• Finally, we pick a random duration in a range around the baseline.

MinimumDuration = EnergyDuration * (1.0f - fSandboxDurationRangeMult);
MaximumDuration = EnergyDuration * (1.0f + fSandboxDurationRangeMult);
Duration = random value between MinimumDuration and MaximumDuration

Semi-Scheduled Activities: Meals and Sleeping

(All units are in hours.)

• Sleeping: Sandbox actors who are allowed to sleep will sleep automatically, based on gamesettings.

Bedtime:		fSandboxSleepStartMin,  	fSandboxSleepStartMax
Sleeping duration:	fSandboxSleepDurationMin,	fSandboxSleepDurationMax

• Eating: Sandbox actors who are allowed to eat will have regular mealtimes three times per day All units are in hours.

Breakfast:	fSandboxBreakfastMin,	fSandboxBreakfastMax
Lunch:		fSandboxLunchMin,	fSandboxLunchMax
Dinner:		fSandboxDinnerMin,	fSandboxDinnerMax
Meal durations: fSandboxMealDurationMin, fSandboxMealDurationMax

Relevant Gamesettings

• fMinSandboxRescanSeconds: Min time (in seconds) before the sandbox re-scans the world for new stuff to interact with.
• fMaxSandboxRescanSeconds: Max time (in seconds) before the sandbox re-scans the world for new stuff to interact with.
• fSandboxCylinderTop: Truncate a spherical sandbox location to a cylinder at this height above the center point. Should be a positive number.
• fSandboxCylinderBottom: Truncate a spherical sandbox location to a cylinder at this height below the center point. Should be a negative number.
• fAIWanderDefaultMinDist: The default minimum wander distance; used if the procedure doesn't specify one.
• fSandBoxRadiusHysteresis: Extra padding so we don't need to repath back into the sandbox when on the edge of it.
• fSandBoxDelayEvalSeconds: Don't re-evaluate our package/procedure for atat // least this long after starting a new sandbox action.
• fSandBoxInterMarkerMinDist: Don't go from one idle marker to another that's closer than this.

See Also

• ??? None.