DESTINY 2

Actors and AI

The client carries the full AI stack. The client that holds authority over a bubble can run the actors in it: their commands, path finding and behavior. The Activity Host sends encounter state. Whether retail also runs a separate physics or AI host is unknown.

Action and object type names are the game’s own. Function and field names are descriptive labels. The 98 actor command selectors have no engine names and are known only by number.

For slot types, Auth and Sense, see The Activity Host protocol.

How an actor walks

A locally created actor stands still until something gives it a movement goal. The path finding stack is complete and local, but it is never asked for a path without that goal.

The chain, all inside the client:

stepwhat it does
Actor_DispatchCommandreads a command’s selector and routes it to one consumer
Actor_ResolveCommandConsumermaps a consumer index to a sub-object and a handler
AiAction_MoveHandlerthe path client’s handler
ActorPathClient_SetMovementGoalwrites the movement goal
ActorPathClient_Tickper-frame path client update
ActorPathClient_EvaluateGoalAndSubmitPathchecks the gates and submits a query
PathQuery_Submitmarks the query pending
PathFinding_SystemTickruns pending queries
PathQuery_FetchResultcopies 896 bytes of waypoints out

Command records

Commands are authored in packages. An actor group loads a blob of command records and turns each one into a 128-byte runtime command.

struct ActorCommand {          /* 128 bytes */
    uint8_t body[96];          /* +0x00  holds the payload; exact layout unknown */
    int8_t  selector;          /* +0x60  0 to 97 */
    uint8_t pad[25];
    uint8_t route;             /* +0x7A  how to resolve the payload's references */
    uint8_t rest[5];
};

The builder copies source record byte +10 to the selector and byte +11 to the route. It then copies the payload from source +16. The payload length comes from the selector’s metadata row. The selector is never a literal in code. It always comes from data.

The route byte picks one of three payload resolvers: 2 uses a context lookup, 3 a global or reference lookup, and any other value the consumer’s default decoder.

An actor group holds its live command list:

struct ActorGroupOrders {
    /* fields before +0x060 not shown */
    uint8_t      params[176];     /* +0x060  parameter block */
    uint32_t     count;           /* +0x110  six-bit count */
    uint8_t      pad[12];
    ActorCommand commands[32];    /* +0x120 */
};

The list is part of the group’s replicated component state. Only the entity’s owner can update it. A peer that does not own the actor cannot rewrite its orders.

Selector 30, the move command, is the only one re-issued when its parameter block changes while the command itself stays the same.

The command router

A command goes to one of eleven consumers. Consumers 0 to 9 are sub-objects of the actor’s AI record. Consumer 10 is a per-actor row outside it.

indexrole
0actor rows and structured targets
1a three-field state record
2actor-linked ids and actions
3the path client
4flags, ids and target state
5a selected row and a direction
6target lanes and actor-linked vectors
7the actor input record (faction, input state)
8three state blocks
9actor-owned records, spawn entries
10a per-actor row outside the AI record

The roles summarize what each handler writes. The dispatcher maps the 98 selectors onto 18 consumer indexes. Indexes 11 to 17 have no consumer, so 38 selectors do nothing on this path. Selector 0 returns at once. Selector 88 skips the resolver and calls consumer 0 directly.

There are three dispatch paths:

pathwhen
maina command is added to or changed in the persistent list
removala command leaves the persistent list
event ringone-shot commands queued on the actor and drained each actor frame

The main and event-ring paths carry the same 98-case switch but different handlers. A selector with a main effect can have no event-ring effect.

void Actor_Frame(Actor *a)
{
    ActorGroup_DiffPersistentList(a, on_added_or_changed, on_removed);
    for (ActorCommand *c : a->event_ring)
        Actor_DispatchEventRingCommand(a, c);
    a->event_ring.clear();
}

The command kinds that reach the path client

Only three selectors reach consumer 3:

selectoreffect
30builds the movement goal
31writes a 64-bit id on the path client
74writes a position input and sets a flag

So an actor that never gets selector 30 never has a movement goal.

Path request gates

The path client checks five gates in order. Any one stops the actor without a query.

void ActorPathClient_EvaluateGoalAndSubmitPath(PathClient *pc, ActorInput *in)
{
    if (in->flags & 0x200)                    /* 1: input record says blocked */
        return on_blocked();
    int kind = MovementGoal_GetKind(&pc->goal);
    if (kind == 0)                            /* 2: no goal */
        return on_no_goal();
    if (kind == 6 && !resolve(pc->goal.target_id))
        return on_no_goal();                  /* 3: goal target gone */

    switch (MovementGoal_ResolveToDestination(&pc->goal)) {   /* 4: destination */
    case 0: move_direct(pc); return;          /* no path needed */
    case 1: break;                            /* needs a path */
    case 2: turn_in_place(pc); return;
    default: clear_goal(pc); return;
    }
    if (!MovementProfile_Accepts(pc))         /* 5: movement profile */
        return clear_goal(pc);

    PathQuery_Submit(pc);
}

Gate 2 holds a new actor. The goal starts empty, and the move handler is its only known writer.

Gate 1’s bit is clear when the input record is created. A refresh sets it when a check fails. One term of that check is a parenting test. No authority or ownership test is on this path. The name “movement profile” for gate 5’s table is assumed.

The AI time budget

The actor executor updates one actor per tick. Each actor gets a time slice for the frame. When the slice is zero, the path client, mover, policy and sensors all skip that frame. Running totals are checked against three caps. Crossing one sets a throttle bit.

This is an update-rate throttle, not a data gate. It can make one actor move on some frames and not others.

Path finding is local

The path finding system is in-process. It holds a pool of 9,648-byte queries. Each tick it takes up to six pending queries and runs three jobs for each:

ai: single path finding job0
ai: single path finding job1
ai: single path finding job2

It waits for them in the same call. A query’s status is -1 when idle and 10 when done. No network call is on this path.

A sibling pipeline picks firing points (ai: fp select job, ai: fp path finding job). Whether a firing point becomes a movement goal is unverified.

Nav data is package content, loaded per region. A nav component registers each nav region’s polygons and reference frame when it loads, and unregisters them when it unloads. Unregistering also resets the region’s dynamic firing points, jump hints, avoidance volumes and nav links.

There is no per-bubble or per-actor lookup. A polygon query walks every registered region. When the reference-frame pool is full, a new region gets no handle and nothing reports it.

The waypoint HUD uses a different system with its own node graph.

The nav mesh format

The nav mesh is Bungie’s own format, not Havok AI. A map places it the way it places an entity:

tagclasscontent
nav holder0x80808CB648 bytes: the nav mesh tag at +8, a firing point tag at +12, then bounds min and max
nav mesh0x80808CB8a 16-byte header, then three layers of 208 bytes
firing points0x80808CBAthree 192-byte layers of static firing points

The install holds 426 nav meshes and 501 holders. The three layers look like one bake for three agent sizes: layer 0 has the most polygons. Which layer an actor uses is unverified.

struct NavLayer {               /* 208 bytes, class 0x80808C88 */
    uint8_t  pad0[16];
    uint32_t index;             /* +0x10  0, 1, 2 */
    uint8_t  pad1[20];
    ArrayRef polygons;          /* +0x28  60 bytes each, class 0x80808CA2 */
    ArrayRef vertices;          /* +0x38  6 bytes each: three u16 cells */
    ArrayRef linkLists;         /* +0x48  16 bytes each: the links that touch one polygon */
    ArrayRef links;             /* +0x58  76 bytes each */
    uint8_t  pad2[8];
    uint32_t treeBuildType;     /* +0x70  1 when the layer has polygons */
    float    treeScale;         /* +0x74 */
    uint8_t  pad3[8];
    float    treeOffset[4];     /* +0x80 */
    ArrayRef tree;              /* +0x90  Havok MOPP byte code, one leaf per polygon */
    float    boundsMin[4];      /* +0xA0 */
    float    boundsMax[4];      /* +0xB0 */
    float    cellSize[2];       /* +0xC0  0.5 and 0.5 in every layer */
    uint8_t  pad4[8];
};

ArrayRef is the 16-byte package array reference: a count, then a relative offset.

A vertex is boundsMin + cell * 0.5 on each axis. A polygon holds six vertex indices (0xFFFFFFFF for unused), six edge neighbours, a vertex count of 3 to 6, a link list index (-1 for none) and two island numbers. A neighbour word is 0x80000000 | layer << 28 | polygon, or 0 for an open edge. The first island joins polygons through neighbours. The second also merges islands that links join. Two polygons are connected when their island words match.

The box tree is Havok MOPP code. The client asks it which polygons a box may touch, then tests each of those polygons exactly. The client does not check for an empty tree, so a layer with polygons needs one. The firing point tag has its own box tree in the same form.

The 98 actor command selectors

The client has a 98-row table of command metadata, one 32-byte row per selector.

struct ActorCommandMeta {       /* 32 bytes */
    uint8_t  in_policy_table;   /* +0x00  gives the selector an ordinal */
    uint8_t  bank;              /* +0x01  one of two result/state banks */
    uint8_t  exclusion_group;   /* +0x02  0 = no conflicts */
    uint8_t  chain_previous;    /* +0x03  keep and chain the previous record */
    int32_t  ordinal;           /* +0x04  -1 when +0x00 is clear */
    uint64_t opaque;            /* +0x08  no known reader */
    uint64_t payload_bytes;     /* +0x10  exact copy length */
    uint64_t payload_class;     /* +0x18  reflected payload class */
};

71 selectors get an ordinal and 27 do not. The main selectors:

selectorpayload bytesconsumermain effectevent-ring effect
016–nonenone
3400nonesubmits a target
4167input stateyes
8249builds an actor recordyes
20404nonecleanup
3013sets the movement goalnone
3113writes a 64-bit idnone
3911writes a state recordnone
4547sets the actor factionnone
69320submits structured targetsnone
74123writes a position inputnone
7519builds an actor recordyes
83 to 85368update state blocksnone
8880 (direct)submits structured targetsnone
9184–nonenone
97166updates actor-linked vectorsnone

Only 30, 31, 45 and 74 have a meaning confirmed by their use. 48 selectors have no main effect. 24 have an event-ring effect.

Selector 45 shows why the two paths matter. It sets the faction on the main path. The event ring drops it, because that consumer only handles selectors 4, 14 and 15. So a faction command sent as a one-shot event does nothing.

Object behaviors

Placed objects carry behavior programs that run on the client. How they start, their node types and their object filters are on Behaviors.

Action kinds

An action request is 80 bytes. Its byte 0 is the action kind. The behavior node player_custom_interaction sends kind 70. The engine has 120 action kinds, 0 to 119, covering the whole player and AI action surface. A few:

kindaction
0loki_play_animation
1death
23grenade
51ai_sequence
57state_machine
70player_custom_interaction
95weapon_fire
97jump
106player_locomotion
108physics_driven_ai_locomotion

Only kind 70 is verified in the PC code. Several kinds share one implementation. These action kinds are not the actor command selectors. No mapping between the two is known.

Action rules

An actor’s action component decides what happens when a new action arrives while another runs. Its config selects a rule asset. The asset maps each kind to a group, and holds one rule per pair of groups, rule[group(incoming)][group(running)]. A kind with no group row is rejected before any rule.

resulteffect
0no rule
1ignore
2simultaneous: both run
3interrupt: the running action is released

The component has two request queues, picked by bit 0 of the request’s flags:

flag bit 0result 0 or 1result 2result 3
clearthe incoming request is droppedboth runthe running action is released
setthe running action is releasedboth runthe running action is released

So whether a request plays depends on what the actor runs now, not only on the request. For example, under one Cabal guard’s rule asset, a running state_machine action is released by an ai_sequence request, and kinds with no rule against it are dropped.

Temperaments

An actor’s behavior variant comes from a set of up to six temperament ids. The client merges it from the actor, its squad, gameplay switches, the package definition, the active behavior context and the combatant_sensor Auth body. Each id is looked up in a table owned by the actor’s behavior definition. The matching row picks native behavior states, and a change rebuilds the active state.

Two writers change the set at run time: a client atom in the combatant_sensor program, and a packaged action that adds or removes one id. All 121 installed packaged actions remove; none adds. The installed ids are 0 to 12 and 14. No id has a known name, so none can be called neutral or hostile. No damage, hit, health or faction code writes the set.

Sequences and responses

An actor plays named animations and voice lines through two kinds of tables. Both are package data, and both are found through the actor’s own components.

Sequence tables

A sequence key is looked up in the actor’s global sequence table first, then in its local one. Both hold sorted 24-byte rows, element class 0x808081AE:

struct SequenceRow {             /* 24 bytes */
    uint32_t key;                /* +0x00  FNV-1 of the sequence name; the sort key */
    uint8_t  kind;               /* +0x04  native action kind byte */
    uint8_t  pad[3];
    int64_t  path_rel;           /* +0x08  self-relative pointer to the resource path */
    uint32_t resource;           /* +0x10  sequence resource tag */
    uint32_t pad2;
};

Global tables have class 0x8080816C, local tables class 0x8080815F. An actor group config (class 0x80809C36) selects the local table, a compact behavior program and the global table. The install holds 9 global and 354 local tables, with 2,174 rows. The path is metadata; the lookup uses only the key.

A local table also holds ability groups: 32-byte rows, each a group key and a list of u32 names. The groups are lanes keyed by the FNV-1 of their name. 354 tables are installed, with thirteen group keys. Eight are named:

grouphashtables
state_machine0xAFB11A12329
melee0xBF39E12B209
jump0xE480E089159
teleport0x1F992208150
grenade0xC20DD42575
boost0x8E6FFB4641
dropship0x07EBF3545
spider_tank0x500BB3613

The state_machine group lists the machines the type-42 slot can start. Its names are authored per actor and ship only as hashes. Which row the AI picks at run time is unverified.

A sequence resource names a config that pairs an animation action with a voice action. The two keys are independent. For example, new_target plays animation new_target and voice target_sighted.

The kind byte matters only to command 87, which turns kind 1 or 2 into action kind 54 and kind 3 or more into kind 55. The combatant_sensor sequence atom always creates action kind 51, ai_sequence, whatever the row says. See The Activity Host protocol.

Named responses

A response is a voice line chosen by name. Command 6 plays a named response through one interface on the actor. A sequence’s voice action uses the same call when its bank is -1. The actor update also sends some responses by kind: kind 35 once per new perceived target within 30 m, and kind 37. The response tables hold names such as target_sighted, taunt, death and investigate.

Actor behavior programs

An actor group runs a compact behavior program, class 0x80806562. Authored scenes run their own program of the same class in place of it while they control an actor. The header holds typed arrays:

element classsizeholds
0x8080825C24a node: name hash, precondition expression, exit list, active and entry action lists
0x808082584an expression: first reference, count, op (one, not, and, or, action list)
0x808082944a leaf or expression index, and a nested flag
0x808082624a leaf: first parameter and a selector
0x808000074parameter values; 0x8080824D holds one type byte per value
0x808000704the name pool
0x808082608tree links: node, first child, next sibling
0x8080825E12chains; +6 is the root node
0x808081B432sorted keys, with an optional resource tag at +24

A leaf’s selector is a predicate inside a precondition or exit expression, and an actor command inside an action list. Parameter type 2 is a float. Type 4 is a comparison, 0 for less through 5 for not equal.

Parameter types 7 and 14 index the name pool and are used as written. Types 18 and 19 also index it, but a scene config rebinds them. Its binding table is a sorted array of 8-byte rows, class 0x808082BB: a name hash, a u16 count and a u16 index into the config’s own name pool. A count of zero means the program name is an internal port, not a name. So one program can serve several scenes, and each scene’s config names the machine and events it drives.

Animation graphs

An actor’s animation component selects an animation definition, and that selects a graph. A graph holds groups. Each group is a list of states with transitions.

recordsizefields
group56name hash at +0, state array at +8
state80name at +0, flags at +8, animation index at +16, blend at +20, transitions at +24
transition32target state at +12, offset to its condition at +24

A condition is an event or the end of playback. The event names are FNV-1 hashes, such as exit_guarding and interrupted_combat.

An animation definition (class 0x808036F6) also holds named rows of 32 bytes. Each row maps a name hash at +0x10 to a clip index at +0x18. A clip lists its events. An event can name an audio event tag.

How an actor picks a clip

A clip is picked by a query key, not by the clip’s own name. The actor’s sequence selector component (resource class 0x8080344B) names the animation definition at +144 and a query table at +156.

  1. A query key is the FNV-1 hash of an action name, such as flinch or fire_1.
  2. A kind-1 query holds one weighted set of name rows.
  3. A kind-2 query holds a tag tree and several sets. The tree picks one set from the actor’s tags: weapon (rifle, shock_pistol), movement (sprint), surface (floor, ceiling) and actor (dreg, captain).
  4. A set row names a definition name row by index. The name row names the clip.

Queries reach name rows by index, so a name row’s own hash is not a lookup key. This chain is read from the packages. The code that issues each key is unverified.

The authored squad spawner

Enemy squads are placed by a native spawner component, class 0x80809A3B. It is the type-1 activity slot, squad_sensor. The Activity Host drives it through that slot’s Auth body. The client that holds bubble authority does the rest: it picks members, finds spawn points and creates the actors.

The word “squad” is also used for a replicated simulation entity kind. No link between the two is known.

What the package supplies

  • The spawner definition: member slots and candidate actors, six candidate lanes per member.
  • A reference at definition +0x98 and +0xA0 to a spawn rule.
  • The spawn rule: a point set whose points match placed objects by identity.

The reference format:

struct ObjectSlotRef {      /* 8 bytes */
    uint32_t object_key;
    uint8_t  slot_type;     /* 0xFF = unset */
    uint8_t  pad;
    uint16_t slot_index;    /* 0xFFFF = unset */
};

The static chain from the squad slot to a position:

type-1 squad slot
  -> spawner definition +0x98 / +0xA0
     -> type-66 slot holding the spawn rule
        -> point identity
           -> placed object identity and transform

Some spawners carry their own point set instead of a rule reference. 3,815 installed type-1 spawners take this form, the Tower vendors among them. Every one read so far holds one point, and that point is the spawner’s own placement.

The Auth body

The type-1 Auth body is 196 bytes. The known fields:

struct SquadAuth {              /* 196 bytes; widths inferred from the offsets */
    uint64_t objective_ref;     /* +0x00 */
    uint64_t collection_ref;    /* +0x08  used when +0x00 is unset */
    uint8_t  pad0[0x24];
    uint32_t slot_count;        /* +0x2C  must match the definition */
    uint32_t count_per_slot[8]; /* +0x30  requested members */
    uint32_t explicit_count;    /* +0x50 */
    int32_t  explicit_index[8]; /* +0x54  per-member candidate index */
    int32_t  lane;              /* +0x74  candidate lane */
    uint8_t  pad1[4];
    int32_t  generation;        /* +0x7C  spawn generation */
    uint8_t  pad2[0x10];
    ObjectSlotRef dest_squad;   /* +0x90 */
    ObjectSlotRef rule_ref[2];  /* +0x98  overrides the package rule */
    int32_t  objective_rev;     /* +0xA8 */
    int32_t  awareness_rev;     /* +0xAC */
    int32_t  unknown_b0;        /* +0xB0  purpose unverified */
    int32_t  objective_group;   /* +0xB4  -1 = no objective */
    int32_t  dest_rev;          /* +0xB8 */
    uint8_t  active;            /* +0xBC */
    uint8_t  mode;              /* +0xBD  0 and 2 can spawn at once */
    uint8_t  pad3[2];
    uint32_t name_hash;         /* +0xC0 */
};

Rules the client applies:

  • The rule reference at +0x98 wins. The package reference is used only when it holds the unset sentinel. A bad reference that is not the sentinel silently disables the package rule.
  • A changed generation tears the squad down first. The compare is !=, not >.
  • With active zero, that teardown destroys the members. With active set, it releases them.
  • Member counts are not gated by the generation. Resending the same generation with new counts changes the population without a teardown.

Placing members

void Squad_Reconcile(Squad *s, SquadAuth *a)
{
    for (int i = 0; i < a->slot_count; i++) {
        int deficit = a->count_per_slot[i] - s->existing[i]
                    - s->reserved[i] - s->in_flight[i];
        if (deficit > 0 && (a->mode == 0 || a->mode == 2))
            AuthoredSpawner_BuildRequests(s, i, deficit);
    }
}

The requests go to one global table, capped at 80 requests. When it is full, new requests are dropped with no error. A per-frame drain resolves each point and asks the point object to place the actor.

The spawn rule picks points by a policy byte:

valuechoice
0walk from index 0
1shuffle with an LCG
2start after the last used point, wrapping
3, othertwo further methods; not read

Rule names fit the values: patrol rules use 2, reinforcement rules use 1.

What the squad reports

The squad’s Sense body goes back to the host. The alive count is recomputed on each report by checking each member’s handle. There is no death event in this build. The host sees a death only as a fall in the alive count, with no member identity and no cause. The Sense fields, and the combatant and object Sense that report damage and per-object death, are on The Activity Host protocol.

Class definitions

Every placed object, actor and player is built from a class definition, a package tag of class 0x80809C0F. The install holds 46,235. A class definition lists its component configs and carries a hash map of the component definition hashes it holds. Looking up a component on an object asks each node of the object’s class chain whether its map holds the hash. The first match wins.

classDef + 8 is the FNV-1 hash of the class’s internal name, such as fallen_vandal. Most class definitions have none and read 0x811C9DC5.

Object types

The byte at classDef + 150 is an object type. The 29 type names are the engine’s own:

typenametypename
0inherited15vehicle
1static_mesh16turret
2prop_simple_DEPRECATED17emitter
3prop_expensive_DEPRECATED18projectile
4prop_cosmetic_static19item
5prop_cosmetic_movable20item_ammo
6prop_cosmetic_movable_garbage21item_loot
7prop_networked_static22gear
8prop_networked_movable23hop_on
9prop_cinematic24hop_on_gear_biped
10speedtree25hop_on_gear_weapon
11interactive26hop_on_gear_ship
12biped27hop_on_gear_sparrow
13creature28system
14weapon

The player classes

Only three player class definitions exist: player_guardian, player_hunter and player_warlock. There is no player_titan. The character’s class byte reaches a class definition through two investment_globals tables:

class byteclassclass definition
0titanplayer_guardian
1hunterplayer_hunter
2warlockplayer_warlock

So player_guardian is the Titan’s class, not a shared base. All three carry the ability container and 61 or 62 components, far more than any other class. The class byte is server data, in the character record.

Combatant display names

An enemy’s display name, such as “Vandal” or “Taken Knight”, is not in the investment tables. It comes from the class definition: the combatant component’s config references a record of class 0x8080815F, whose +0x08 is a localized string hash. 354 such records exist and 128 distinct names resolve, covering the ordinary roster and bosses such as “Nightmare of Crota, Son of Oryx”. The record holds no string bank. Every installed enemy name sits in one bank, activity_global_strings, which the global activity resources list. That the name plate searches this bank is assumed. The record has no known race or faction field.

This record class is the same local sequence table described under “Sequence tables” above.

Open questions

  • Names for the 98 command selectors.
  • Most of the actor group’s class-message slots. 20 of 24 are unknown.
  • The native binding behind a spawn point and its lifetime.
  • How the retail host sets a guard’s “neutral until attacked” state, and what each temperament id means.
  • Which nav layer an actor uses, and what a nav link’s four points and flags mean.