feat(enhancement): Add "on encounter" trigger for NPCs

[danaris]

---

Feature: This PR implements a new action trigger for NPCs, on encounter. It performs the specified mission actions the first time the player is in the same system as the target NPC ship and neither are cloaked. The idea was brought up on Discord and it seemed easy enough to implement.

Feature Details

Adds a check in Engine::Step() that loops through ships belonging to NPCs of the player's active missions, and queues a ShipEvent of a new ENCOUNTER type.

UI Screenshots

N/A

Usage Examples

mission "Encounter Test"
	name "An Unexpected Encounter"
	job
	source
		government "Wanderer"
	to offer
		has "main plot completed"
	npc "scan outfits"
		on encounter
			dialog `You have found the test ship!`
		government "Wanderer"
		ship "Hurricane" "Winds of Change"
		personality target uninterested marked waiting
		system
			government "Wanderer"
		dialog
			`The ship recognizes you when you scan it. Good job!`

Testing Done

I added the above mission to a plugin, fired up a save file where I happened to be in Wanderer space post-FW, launched and landed, and grabbed the mission from the Job Board. I launched again, observed that there was no appreciable change in performance compared to before I added the new check, and jumped until I ended up in the same system as the target ship. The dialog appeared, I dismissed it and scanned the ship, which brought up the second dialog, and I landed back on the source planet, which caused the mission to complete and disappear.

Edit to add: At the advice of Saugia, I changed the test ship's personality to be one that would jump around, and tested both decloaking in the system with the test ship, and waiting for it to jump into my system. Both correctly triggered the on encounter action.

Performance Impact

There is a concern about performance impact due to adding a nested loop to the Engine::Step() method. However, even with a half-dozen active missions, no appreciable change in performance was observed. It might be wise to test this on a lower-end computer (mine is an M1 Max) to ensure that it does not cause degraded performance there. If it does, this could potentially be reimplemented by checking both when the player enters a system and when any NPC ship enters a system.

[lumbar527]

Sounds like this could be cool, maybe for a hunt for another ship?

[MiscelaneousItem]

Perhaps creating a list of encouterable ships on takeoff would be better performance wise ?

[danaris]

That wouldn't catch situations where the NPC jumps into your system midflight, or where you or the NPC decloak when already in the same system.

As I noted, there appears to be no performance impact of this change in practice.

[Zitchas]

Oh, this could be very useful. Very useful indeed. I can think of all sorts of situations where I would make use of this in future Remnant missions.

Thanks for working on this!

[MiscelaneousItem]

That wouldn't catch situations where the NPC jumps into your system midflight, or where you or the NPC decloak when already in the same system.

As I noted, there appears to be no performance impact of this change in practice.

You seem to have misunderstood my suggestion.
Instead of looping through every ship of every mission NPC each frame, one would only loop through the precalculated list of ships that have an encounter associated.
In any case, having given the matter more thought, I believe the approach proposed by RisingLeaf to be more appropriate, if there is actually a demonstration that this poses a problem performance wise.

[warp-core]

Related: #1647

[danaris]

Ah, I see—yes; if it does turn out that we need to worry about its performance, on-X checks for each of the possible times it can trigger would be better.

[danaris]

Related: #1647

From the same discussion that spawned this idea, we also thought it would be worthwhile to add flagship cloaked to PlayerInfo::RegisterDerivedConditions(), but I haven't yet written that.

[quyykk]

I believe it should be possible to use the JUMP event for this, because this event is triggered when the player jumps to a new system. That would avoid using the triple loops.

Edit: And for cloaking you can inject the new ship event when the player uncloaks

edit2: Maybe emit both JUMP and ENCOUNTER events when the player enters a new system instead of hijacking JUMP?

[danaris]

That's still missing the conditions where the target ship arrives or decloaks in the system while you're already there—unless I'm misunderstanding, and the JUMP event fires on any ship jumping...?

[quyykk]

You'd do them in the same way as for the player, but slightly differently. So like:

• If the player jumps to a new system: Send the ENCOUNTER event if the player is uncloaked
• If the player decloaks in a system: Send the ENCOUNTER event
• If a NPC ship jumps to a new system: Send the ENCOUNTER event if the player is in that system too and uncloaked
• If a NPC ship decloaks: Send the ENCOUNTER event if the player is in that system too and uncloaked

[danaris]

Ah, I see—so you are, indeed, just saying you think this should shift, overall, from a check-all-the-time model to a check-on-events model.

I'll see what I can do with that!

[danaris]

I've added the individual triggers and removed the main-loop check.

[Amazinite]

It took a bit for me to wrap my head around each of these ENCOUNTER cases and make sure there was no overlap, so I figure adding comments explaining every case would help.

[Amazinite]

This doesn't seem to work if you take off from a planet and the NPC is already in the same system as you.

Thoughts on changing from simply checking cloaking to checking targetability of the ship? Ship::IsTargetable accounts for cloaking, but it also accounts for taking off from a planet (waiting until you've fully taken off) and completely exiting hyperspace.

[danaris]

Really? Hm. I thought that the section in Engine.cpp, lines 1398-1403, would handle that—doesn't EnterSystem() get called upon launch?

IsTargetable() does sound like a good idea. I will see about refactoring all the cloaking sections to use that, instead.

[Amazinite]

I deleted the two sections I figured were dead code and tested the following cases:

• Enter the system with the NPC while my flagship is cloaked and then uncloak.
• Enter the system with the NPC while my flagship is uncloaked.
• Take off in the same system as the NPC.
• Have the NPC enter my flagship's system.

So it seems like switching to targetable does cover all the cases in a single location. That simplified things a lot more than I was expecting. 😄

[danaris]

Cool, that's an unexpected bonus.