worldbox-observer-mod/docs/event-reason.md

1.9 KiB
Raw Blame History

Event reasons (camera + orange dossier)

Contract

Registered events own the idle camera. EventStrength / TotalScore ranks who wins. Character fill runs only when the pending EventLed queue is empty, and uses an empty Label (task chip only).

Orange dossier reason = the owning events Label while the scene is active (InterestDirector.TryGetOwnedReasonCandidate). Quiet grace / inactive dwell clears the reason even if focus has not switched yet.

EventReason

IdleSpectator/EventReason.cs is the sole Label factory for camera candidates. Feeds call typed helpers (Fight, BuildingEat, SeekingLover, …) or Apply(template, a, b, id).

Rules:

  • Sentence form with names: {a} is fighting {b}, {a} is eating a beehive, {a} is seeking a lover.
  • Set RelatedUnit when the sentence names a second party.
  • Never invent stranger subjects for unit-led events.
  • Never use engine jargon that misstates the action (Consumes a building → eating/foraging via BehConsumeTargetBuilding).

Removed crumbs

Do not author these as orange reasons:

  • In action
  • bare Duel / Fight (N) without a named sentence
  • identity titles (King of X, Leader of X, Lone beetle)
  • Consumes a building / Damages a building: {a} crumb form

Strength dial (no ownership enum)

InterestOwnership / OwnsCamera were removed. Every registration is EventLed and may own the camera. CreatesInterest gates whether an id registers; EventStrength ranks. Instant cut-in when next.TotalScore >= current + cutInMargin (see scoring-model.json).

Dossier display

UnitDossier.EventLabelBeat keeps the authored sentence. It only rejects identity/weak crumbs and scrubs living stranger names (ReasonNamesStranger / LeadsWithForeignName).

See also