NPC emotion runtime

Emotional simulation belongs to UniqueNpcEntity and is implemented by internal.ai.emotion.UniqueNpcEmotionManager. The shared NpcEmotionManager is an internal interface, not a public facade; other NPCs use a no-op implementation. See NPC moods and personalities for player meanings and dialogue fields.

What it does

Events add impulse and memory, context sensing changes situational targets, and the manager resolves primary and secondary moods. Only the primary mood ordinal travels through entity tracked data. Reservoirs remain server-side, while dialogue obtains a separate snapshot. NpcEmoteManager handles body animations independently of emotional intensity and emoji stickers.

Runtime model

Reservoirs and time

Each mood stores Impulse, Memory and Context, each clamped to 0–100. Displayed intensity is min(100, Impulse + Memory + Context). Stimulation sanitises raw intensity to finite 0–100, then multiplies by temperament reactivity × responseScale(mood). Retention, clamped to 0–1, splits that amount into memory and impulse; each reservoir caps separately. Soothing does not apply temperament multipliers: it removes impulse, then context, then memory, using at most 100 sanitised intensity.

State updates every 20 ticks and mood resolution runs on a separate 20-tick schedule. Recovery uses elapsed world ticks divided by 20, capped at 7 days; time moving backwards resets the baseline first. Context movement uses at most 2 seconds per update. Impulse/memory lose seconds × 100 / lifetime × recoveryScale; sensitive moods additionally multiply recovery by resilience. Residuals below 0.01 become zero.

Construction advances composed context to 9. NBT reading first clears every reservoir; an absent or mismatched schema does not reinsert that initial 9, so later sensing approaches the target gradually. The idle counter advances once per sample, without converting offline seconds into samples.

Mood tuning

Lifetimes are seconds for a full 100-intensity reservoir to empty at recovery multiplier 1, not a fixed duration for every stimulus. Context rates are intensity per second. A true resilience column applies the extra resilience recovery multiplier.

Primary selection starts with composed, then follows enum order, accepting a mood at its threshold only when strictly stronger than the current candidate. Equal intensity retains the earlier candidate. A different candidate replaces the current mood if any condition holds: lead of at least 3.5, current mood below its threshold, or 60 ticks since the last switch. Completed dwell does not also require a 3.5 lead. Secondary selection takes the strongest active non-composed mood other than the primary, also keeping the earlier candidate on a tie.

Event wrappers, stimulate(MoodImpulse) and soothe request resolution no later than the next server tick rather than immediately synchronising a switch. The internal three-argument stimulate(Mood,float,float) does not request fast resolution itself; the reaction model uses it to combine changes.

Context targets

Each sample clears targets, takes the maximum of overlapping sources, multiplies by that mood’s responseScale and clamps to 0–100. Reactivity does not apply.

Here danger = (0.50 - healthRatio) / 0.50. Idling requires no sleep, active POI, combat, dialogue or tracked item use, idle navigation and total velocity squared below 0.0025. Any failed condition resets the counter. inverse(t) = clamp(2 - t, 0.45, 1.55). Leaving a situation approaches zero at the fall rate; clearing the target does not immediately clear the context reservoir.

Temperament tuning

The manager captures its personality profile from NPC configuration at construction. Traits must be finite and positive. Mood-scale arrays must match the mood count and are copied on construction; a missing personality profile fails registry initialisation. Unspecified response/recovery scales are 1.00.

Built-in reaction formulas

The table gives stimuli before the common temperament response multiplier. s = clamp(amount / max(1, maxHealth), 0, 1); d = clamp((0.45 - healthRatio) / 0.45, 0, 1); m = clamp(abs(favorGain) / 30, 0, 1). R(x,a,b) = a + (b-a) × x² × (3-2x); inverse is defined above. The ordinary damage path notifies emotions only after successfully applied damage, separately from combat’s attempted-hit hostility counter.

Additional soothing: consumption removes bored 4 and exhausted 3 × resilience; a zero gift removes bored 2; a positive gift removes bored 6, hurt 2 + 4m and angry 1 + 3m; an attack removes bored 4. The negative gift-signal branch does not soothe. Gift acceptance belongs to the interaction layer; the emotion method receives only an integer signal and does not validate an item.

Contracts

Interface and saved fields

BaseNpcEntity.getEmotionManager() returns the shared internal interface. The disabled implementation reports composed, intensity 0, a snapshot without secondary mood and the default temperament; events and persistence are no-ops. Unique NPCs invoke the active manager from role ticks, successful damage, item use and role-NBT hooks.

MoodImpulse clamps intensity to 0–100 and retention to 0–1, treating nonfinite values as 0. Fleeting uses retention 0; lingering uses the supplied retention. Snapshot normalisation divides each intensity by 100 and clamps to 0–1.

Only Schema 1 is accepted. Missing mood compounds remain cleared; loading enumerates current keys, so unknown fields are not retained for later recovery and old emotion roots are not migrated. Persistence uses keys while client tracking uses enum ordinals; enum order changes require matching clients and servers. Load synchronisation does not invoke the mood-change hook; normal dominant switches invoke onMoodChanged. Direct setMood changes the tracker, not server reservoirs, and the manager can overwrite it later.

Body emotes

NPC registerDefaultEmotes and registerEmotes populate definitions lazily, then the manager caches them. The base default-registration hook is empty. Array indices synchronise to clients, so order must match. Duplicate IDs do not throw: ID lookup takes the last registration while the idle pool retains every flagged entry.

tryEmote respects cooldowns and the current emote’s interruption/priority rules. forceEmote bypasses those checks, but still obeys physical state and ordinary dialogue locking. queueEmote holds a single pending ID: later requests replace it and an unknown ID clears it. When idle, the manager consumes that slot and attempts one forced start; failure does not retain the request.

Playback requires the server side, a living nonremoved NPC, no sleep, swimming, flight/hover, riding, climbing, tracked item use, busy POI, combat phase or attackable target, and horizontal velocity squared at most 0.0001. Losing eligibility stops playback. Navigation locking also forgets WALK_TARGET/PATH and disables sprinting. Movement locking clears forward/sideways input, not velocity.

Per-emote and global cooldowns start immediately at the maximum of current and defined values, and continue ticking through dialogue pauses. Looping clips still end at durationTicks. Ordinary dialogue clears the queue and stops non-session emotes. playDialogueEmote requires the player’s active dialogue to target this NPC, binds its session UUID, and stops when the session changes or becomes invalid.

Base idle scheduling uses at least 80 idle ticks, a random 120–320-tick check interval and chance 0.45. The first eligible check can happen immediately; there is no guarantee of waiting a full interval first. It samples the idle pool once, without retrying another entry if that emote is cooling. Leaving dialogue resets the random check interval. This manager does not persist emote state, queue or cooldowns.

Extending it

Call emotion methods on the server tick/event path; the active manager does not automatically route every mutation to the server. Subclass the unique NPC layer and choose a profile through NpcConfig.Builder.personality. A new mood requires aligned Mood, MoodCatalog, reaction/context logic, personality arrays and both language entries. A new personality needs a complete TemperamentProfiles registration. These are code definitions, not data-pack reload surfaces.

Register body-emote definitions and react through onEmoteStarted/onEmoteStopped. There is no automatic one-to-one mapping from emotions to emotes. Verify Gecko resources when changing animation keys: a valid constructor does not establish that a clip exists. Keep this internal interface distinct from a stable public API.

Verifying

1. Send equivalent events to a unique NPC and ordinary citizen. Only the former should change reservoirs; the latter stays composed/0.
2. Apply low- and high-retention stimuli to the same mood; inspect splitting, linear recovery and soothing order.
3. Test gifts, applied damage, avoided damage, eating, attacking, work and dialogue. Dialogue must not accumulate boredom.
4. Test the 3.5 lead, 60-tick dwell and below-threshold switch paths, observing the primary mood from another client.
5. Save, unload and advance world time; check recovery cap, context step and idle count. Also test backwards time, unknown moods, missing fields, wrong schema and nonfinite values.
6. Test duplicate emote IDs, forced/ordinary replacement, single-slot queue, loop duration, cooldowns and session replacement. Movement or combat must stop playback.
7. After code tuning changes, run language assembly and Java compilation, then check tracked state with matching client/server registration order.

Related

• NPC moods and personalities
• NPC foundations
• NPC combat
• Emoji API