Entries, phases, and AI spots

A community entry answers three different questions:

Who can spawn?        characterRecordId
In which authored mode? phaseName + appearance + time period
Where can they act?   spotNodeRefs -> worldAISpotNode -> workspot resource

Keeping those questions separate makes failures diagnosable. Changing the character record does not move the spot. Moving the spot does not change the appearance. Activating an entry with the wrong phase name does not fall back to a similarly named workspot.

Vanilla references

These focused base-game resources are useful comparisons. Extract them from your own installation; they are references, not files to copy into the project.

base\open_world\minor_activities\westbrook\japantown\
  ma_wbr_jpn_13\community\ma_wbr_jpn_013_claws_com.community

Registry-side entry shape

In the retained registry item, template data has this focused shape:

communityCommunityTemplateData
  entries[]
    communitySpawnEntry
      characterRecordId: TweakDBID
      entryName: CName
      phases[]
        communitySpawnPhase
          phaseName: CName
          appearances[]: CName
          timePeriods[]
            communityPhaseTimePeriod
              hour: CName-like period selector
              isSequence: Bool
              quantity: Int32
              spotNodeRefs[]: NodeRef

The important properties are:

entryActiveOnStart, stored under the registry item’s initial state rather than the spawn entry itself, decides whether quest logic begins with that entry active. For a controlled quest contact, false plus an explicit activation edge gives the graph a reviewable owner.

Area-side mirror

The compiled area does not repeat the character record. It repeats the topology needed to bind the entry/phase/time period to placed spot identities:

The values describe the same intended route through different serialized types. A valid character entry with a stale area mirror can activate but never obtain its intended spot.

When reviewing serialized sectors, do not pair rows merely because they are adjacent. Follow the entry name, phase name, full spot NodeRef, world-global spot ID, and sector NodeIndex. Later source snapshots can reorder nodes or change a workspot without changing a nearby debug string.

worldAISpotNode owns the placed activity

The AI spot is a concrete world node. Its decisive focused structure is:

worldAISpotNode
  isWorkspotInfinite
  isWorkspotStatic
  lookAtTarget
  spot -> AIActionSpot
    resource -> ResourcePath to .workspot
    snapToGround
    useClippingSpace

The sector’s nodeData owns its transform and binds the concrete node to the registered NodeRef. The worldAISpotNode owns the activity configuration. A workspot resource supplies animation/behavior data; it does not supply the world position.

Do not introduce a patrol merely by adding two points. Sequenced workspots, AI roles, navigation, interruption, combat, and cleanup are separate runtime surfaces. A single stationary contact spot is the smaller Lab 5 search surface.

Character record, entity, and appearance are separate

The community stores a TweakDBID, for example:

Character.jpn_tyger_claws_biker2_ranged2_copperhead_wa

That record is not an .ent depot path. It can refer onward to a character entity template and other gameplay records. The spawn phase’s appearance CName must be valid for the selected template chain. An appearance name that worked for a different record is not inherited because both entries say default.

For a first contact fixture, prefer a generic population/combat record whose bounded spawn behavior is retained over a story-unique character record. This reduces conflict with vanilla quest ownership, but it does not make every appearance, faction, voice, or AI behavior appropriate. Inspect the selected record and verify the actor in game.

Choosing a workspot

Choose a workspot from evidence tied to the exact record and candidate, then validate it at the new placement. Check:

1. the resource exists at the exact depot path;
2. the spot transform leaves enough clearance for the actor;
3. the surface is reachable and supports the intended ground contact;
4. the actor does not clip into walls, props, or the player approach lane;
5. the broad setup route streams the area before the scene needs the actor;
6. each named pre-scene seed load in Cases 3, 4, and 7 reacquires the same passive contact without duplication;
7. normal exit, post-contact_done reload, completed reload, and delayed deactivation do not leave the actor stuck in the workspot.

Check the workspot at its actual transform. A pose that works at one location can intersect geometry or lack a usable approach at another.

Common failures

Next: Activation, readiness, and acquisition.