502c3f6aa4
> [!IMPORTANT] > **Breaking change to API to fix NPC AI issues** ## Symptom `FamiliarAITests.HiddenCaster_FamiliarRefusesRetaliation` fails on main at `Assert.False(wolf.Warmode)`: the familiar's `Combatant` stays null as intended, but it is left in war stance. In-game the familiar of a hidden caster flips into warmode for a tick when struck, until `FamiliarAI.StandDown()` clears it on the next think. CI never saw it because the familiar tests are `SkippableFact` (they need client tiledata). ## Root cause #2644 and #2645 landed a day apart and are individually correct but conflict at one seam. Since #2645, a familiar (`Commandable == false`) is no longer "told to stand down", so `BaseCreature.AggressiveAction` continues past `AIObject.OnAggressiveAction(aggressor)` to its generic fallback: ```cs else if (Combatant == null && !BardPacified) { Warmode = true; Combatant = aggressor; } ``` `FamiliarAI.OnAggressiveAction` had already declined (caster hidden), but the hook was `void`, so the creature could not tell. The fallback raised `Warmode` before `BaseFamiliar.Combatant` vetoed the target. ## Fix This is the follow-up agreed in #2645: the retaliation policy moves into a virtual `BaseAI.OnAggressiveAction(aggressor) -> bool`. - **`BaseAI.OnAggressiveAction`** now holds the stand-down verdict, the closer-aggressor swap (`PreferCloserAggressor`), and the `IssueOrder(Attack)` vs `Combatant =` decision. Returns `false` when the creature stands down. - **`BaseCreature.AggressiveAction`** keeps only bookkeeping — `ControlMaster.Aggressors` entry, `StopFlee`, `ForceReacquire`, ethics `FinishShield` — keyed off the return, so an AI that declines is never second-guessed. - **`FamiliarAI`** overrides the whole policy: no orders to stand down on, never fights for a hidden caster or a hidden aggressor. Behaviour for every other AI is unchanged. Moving the fallback ahead of `StopFlee`/`ForceReacquire` is order-safe: both are pure field resets, `IssueAttack` does not `Think()`, and `OnCombatantChange` only derives `Warmode`. Two commits: the first is the minimal `bool` hook that alone fixes the test, the second the policy move. ## Not changed (noted for later) - `Warmode = true; Combatant = x;` (also in `FamiliarAI.Act`, `IssueAttack`) is redundant when the setter accepts — `BaseCreature.OnCombatantChange` derives `Warmode` — and is the dangling-warmode hazard whenever a `Combatant` setter vetoes. - Since #2614 a stood-down pet skips the ethics `FinishShield`; RunUO ran it unconditionally. Preserved as-is. ## Tests `HiddenCaster_FamiliarRefusesRetaliation` fails on main and passes here. Full `UOContent.Tests`: 1126 passed, 0 failed, 2 skipped (spawner fixture capture + benchmark).
47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
---
|
|
name: migrate-items-mobiles
|
|
description: >
|
|
Trigger: when converting RunUO Item, Mobile, or BaseCreature subclasses to ModernUO. Most common migration task.
|
|
Covers: complete item/creature conversion combining serialization, timers, properties, naming.
|
|
---
|
|
|
|
# RunUO -> ModernUO Item/Mobile/Creature Migration
|
|
|
|
## When This Activates
|
|
- Converting any `Item` subclass from RunUO
|
|
- Converting any `Mobile`/`BaseCreature` subclass
|
|
- This is the most common migration task -- combines all other systems
|
|
|
|
## Item Conversion Checklist
|
|
1. [ ] Foundation: file-scoped namespace, `using ModernUO.Serialization;`
|
|
2. [ ] Class: add `[SerializationGenerator(N, false)]` (N = old version + 1, `false` if old `Deserialize` used `ReadInt()`), add `partial`
|
|
3. [ ] Fields: `m_X` -> `[SerializableField(N)] _x` with `[SerializedCommandProperty]`
|
|
4. [ ] Add `[InvalidateProperties]` where RunUO setter called `InvalidateProperties()`
|
|
5. [ ] Delete: Serial constructor, Serialize, Deserialize
|
|
6. [ ] `[Constructable]` -> `[Constructible]`
|
|
7. [ ] `Name = "text"` -> `public override string DefaultName => "text";`
|
|
8. [ ] Timers: nested class -> `Timer.StartTimer()` + `TimerExecutionToken` + `[AfterDeserialization]` + `OnAfterDelete`
|
|
9. [ ] Properties: `GetProperties(ObjectPropertyList)` -> `GetProperties(IPropertyList)`, apply string hole rule
|
|
10. [ ] Context menus: `List<ContextMenuEntry>` -> `ref PooledRefList<ContextMenuEntry>`
|
|
|
|
## Creature-Specific Changes
|
|
- `[CorpseName("...")]` attribute -> `public override string CorpseName => "...";`
|
|
- `BaseCreature(AI, Fight, 10, 1, 0.2, 0.4)` -> `BaseCreature(AI, Fight)` (extra params default)
|
|
- `Name = "text"` -> `public override string DefaultName => "text";`
|
|
- Expression-bodied overrides: `public override int Meat { get { return 1; } }` -> `public override int Meat => 1;`
|
|
- AI movement calls lose the `run` flag: `MoveTo(m, true, range)` -> `MoveTo(m, range)` (also `WalkMobileRange`, `ApproachTarget`, `MoveToPoint`, `PathFollower.Follow`); the Running bit is derived from step pace -> `dev-docs/runuo-migration-docs/09-items-mobiles-creatures.md` § AI Movement
|
|
- `AcquireOnApproach` (bool) -> `AcquireOnApproachDelay` (TimeSpan; `Zero` = old instant behavior) -> same doc § Target Acquisition
|
|
- `BaseAI.OnAggressiveAction(aggressor)` is `bool`, not `void`: the AI owns the retaliation policy (`BaseCreature` no longer sets `Combatant` after it); an early `return;` that refused a fight -> `return false;`, otherwise `return true;`; swap-only overrides call `PreferCloserAggressor(aggressor)` instead of `base` -> same doc § Retaliation
|
|
- `DamageEntries` is an inline `ref readonly ValueLinkList<DamageEntry>`, not a `List`: indexer/`Add`/`Remove`/`Clear` -> `foreach` / `.ByDescending()` (needs `using Server.Collections;`) and `ClearDamageEntries()`; `GetLootingRights` takes it by `in` -> same doc § Damage Entries
|
|
|
|
## Anti-Patterns
|
|
- Using `_field--` instead of `Property--` (bypasses MarkDirty tracking)
|
|
- Forgetting `[AfterDeserialization]` for timer restoration
|
|
- Forgetting `OnAfterDelete()` for timer cancellation
|
|
|
|
## See Also
|
|
- `dev-docs/runuo-migration-docs/09-items-mobiles-creatures.md` -- detailed migration with before/after examples
|
|
- `dev-docs/content-patterns.md` -- ModernUO content templates
|
|
- `dev-docs/claude-skills/modernuo-content-patterns.md` -- ModernUO content skill
|
|
- `dev-docs/claude-skills/modernuo-serialization.md` -- serialization patterns
|
|
- `dev-docs/claude-skills/modernuo-timers.md` -- timer patterns
|