Limit number of fleets & spawn specified number when entering system

[UnorderedSigh]

Feature: This implements a feature requested by @Zitchas: limit the number of fleets that spawn in a system. It does a bit more than that, too.

This is identical to PR endless-sky#8082 to endless-sky master

Previously, @RisingLeaf attempted this in #7167

As noted in the comments, there's a PR #8074, still in progress, which I may be able to use to expand this functionality. That PR isn't working yet, as of this writing, so I can't be certain, but at this point it looks like they could go into master in either order. If 8074 goes in first, I'll add functionality to this PR. If this PR goes in first, I can do another PR later to add functionality. That PR has been closed and orphaned.

Feature Details

You can:

1. Limit the number of a specific fleet that can be spawned at a time.
2. Limit the number of non-disabled fleets of a specific type that can be spawned at a time.
3. Require that a minimum number exist upon entering a system.
4. Give fleets a "category" so that multiple fleets count as one for the purposes of items 1 & 2.
5. Have a fleet ignore the enemy strength when deciding to spawn.
6. Tell a fleet not to spawn at system entry during the loop that spawns five seconds of ships. (This is needed for integration testing.)

Syntax:

system
    fleet "Fleet name" <period>
         period <period>             # alternative to <period> at top line
         limit <limit>               # No more than this many can spawn with the same category
         non-disabled limit <limit>  # No more than this many can spawn with the same category,
                                     # ignoring fleets of all disabled ships
         initial count <count>       # Ensure this many have spawned when system is entered (overrides limit)
         category "fleet category"   # The category of the fleet; multiple fleets can have the same category

         # Normally, the game will not spawn random event fleets if the side is too
         # much stronger than its enemies. This flag tells the Engine to ignore that:
         ignore enemy strength

         # There is a loop during system entry where the engine will spawn
         # 5 seconds of ships, which causes problems for integration tests.
         # This option turns it off for one fleet
         skip system entry

All arguments are optional, except the fleet name. The default category is "fleet name@system" so the limits and initial counts only apply to that fleet in that system if you give it no category.

The Engine will keep track of fleets as they despawn. However, disabled ships have not despawned, so if there's a limit of 10 fleets and 10 fleets are sitting in the system disabled, no more will come. To avoid this, use non-disabled limit which skips fleets whose ships are all disabled.

Usage Examples

1. A guard ship. There's an example of this in the test cases. An Archon is assigned to Korath Exile space because somebody is pillaging the Korath Exiles to extinction. Six systems have a limit of one Archon each, but the limits have the same category. That gives the illusion of an Archon being wherever it is needed.
2. Ensure at least a certain number of fleets are present without going over. The Drak vs. Pug fight shows this. A non-stop flow of Pug Arfectas come into the system and die. They're limited to 12 fleets of 6 though, so the number never gets out of hand. Likewise with the Remnant vs. Korath examples.
3. Tell a ship to ignore the strength (cost) of enemy governments when spawning. This would be useful for Korath raiding fleets in human space, where the Korath ships cost so much more than human ships that they only spawn when they're overwhelmed with firepower. If this option were turned on, the Korath would keep raiding even if they could vastly overpower the humans.

If the period, limit, and initial count, are connected to conditions, then we can do this:

1. Presence or absence of an Archon is dependent on a single condition.
2. A non-stop battle may or may not be raging in a particular system, and its intensity depends on the limit, period, and initial count set in conditions.
3. The player rudely boards a disabled ship. The faction activates a rescue fleet by increasing the limit above 0.

Testing Done

Put this somewhere in the data directory:

limittest.txt

Load this save:

Friction Diction~3024-05-02 test limit.txt

Your flagship has afterburners and a cloak. Don't forget that! You'll need them.

---

Example 1: Solo ship vs a replenishing fleet of consistent size.

It's the fight we've all been waiting for: Drak vs. Pug.

1. Load the provided save file.
2. Depart and land to activate the events.
3. Fly to Cardax.

Notice the non-stop flow of Pug Arfectas. Despite the arrival period of 100, the number never gets out of hand. That's because there's a limit of 12 fleets of 6 Arfectas. Also, there's always exactly one Archon.

event "pug vs drak at cardax"
        system Cardaxi
                fleet "Pug Arfecta"
                        period 100
                        initial count 10
                        limit 12
                        ignore enemy strength
                fleet "Archon (Cloaked)"
                        period 500
                        initial count 1
                        limit 1

---

Example 2: multi-system guard ship

Somebody has been farming the Korath to extinction, so the Drak have placed an Archon in the Korath Exile systems.

1. Load the provided save file.
2. Depart and land to activate the events.
3. Fly to any Korath Exile system.
4. Leave, and fly to another one.
5. Keep doing that.

The first time you enter one of these systems, an Archon will be there to greet you. If you leave the system, it'll take at least 1000 frames for the Archon to arrive. That's because it takes 1000 frames to despawn after you leave the system, and then has a 500 frame arrival period.

If, by some miracle, you managed to destroy the Archon, another one would show up soon after.

event "korath archons"
        system "Kor Ak'Mari"
                fleet "Archon" 500
                        initial count 1
                        limit 1
			category "korath guard"
        system "Kor En'lakfar"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"
	system "Kor Fel'tar"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"
	system "Kor Men"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"
	system "Kor Nor'peli"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"
	system "Kor Tar'bei"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"
	system "Kor Zena'i"
		fleet "Archon" 500
			initial count 1
			limit 1
			category "korath guard"

---

Example 3: Fleet counts include disabled fleets

1. Load the provided save file.
2. Depart and land to activate the events.
3. Fly to Moktar.
4. Remember your afterburners and cloak.

Here, the Remnant and Korath are battling. Eventually, the Korath will stop sending new fleets because they've hit their maximum due to all of their fleets being disabled. If you destroy some of the disabled Korath ships, new Korath fleets will arrive. The fighters are part of the fleet, so you'll have to destroy those too.

event "remnant vs korath at moktar"
	system Moktar
		fleet "Korath Raid"
			period 500
			initial count 3
			limit 7
			category korath
			ignore enemy strength
		fleet "Korath Large Raid"
			period 500
			initial count 3
			limit 3
			category korath
			ignore enemy strength
		fleet "Heron"
			period 1200
                        limit 1
	                skip system entry
                        category remnant
		        ignore enemy strength
		fleet "Small Remnant"
			period 500
			initial count 1
			limit 3
			category remnant
			ignore enemy strength
		fleet "Large Remnant"
			period 500
			initial count 5
			limit 2
			category remnant
			ignore enemy strength

Notice both remnant fleets have the same category. That means their fleet counts are combined into one. Each has its own limit, though, and that limit is compared against the combined count when deciding whether to spawn ships.

Also, notice the remnant fleet initial counts are higher than the limits. When initially spawning fleets, the initial count ignores the limit.

The Heron fleet will only spawn if the Remnant run out of ships. This is it has no initial count and doesn't spawn during the 5 second system entry loop, so the system will already be filled with ships in the "remnant" category.

---

Example 4: Fleet counts that do NOT include disabled ships

1. Load the provided save file.
2. Depart and land to activate the events.
3. Fly to Durax.
4. Remember your afterburners and cloak.

As with the third example, the Remnant and Korath are battling, but this time both sides will keep sending ships no matter how many are disabled. This is because they use non-disabled limit instead of limit.

event "remnant vs korath at durax"
        "test events" ++
        system Durax
                fleet "Korath Raid"
                        period 500
                        initial count 3
                        non-disabled limit 7
                        category "korath ignore disabled"
                        ignore enemy strength
                fleet "Korath Large Raid"
                        period 500
                        initial count 3
                        non-disabled limit 3
                        category "korath ignore disabled"
                        ignore enemy strength
		fleet "Heron"
			period 1200
                        limit 1
	                skip system entry
                        category "remnant ignore disabled"
		        ignore enemy strength
                fleet "Small Remnant"
                        period 500
                        initial count 1
                        non-disabled limit 3
                        category "remnant ignore disabled"
                        ignore enemy strength
                fleet "Large Remnant"
                        period 500
                        initial count 11
                        non-disabled limit 2
                        category "remnant ignore disabled"
                        ignore enemy strength

---

Automated Tests Added

There is an integration test for the new txt file functionality.

I did not add any for LimitedEvents since it's just a few pieces of data with set/get functions. If people want unit tests for that, let me know and I'll add some.

Performance Impact

Negligible.

[Zitchas]

And, like with endless-sky#8082, would you be able to update this please?

[UnorderedSigh]

Last tested and known to work Tue, 27 Aug 2024 00:12:06 UTC.

[Zitchas]

Thank you. It will be at least wo weeks before I will be able to test and merge this, but I am looking forward to doing so.

[Zitchas]

Ok, it looks like I'm on a roll and able to review and test out things. Can I update this with the update button, or would you prefer to do so?

I see there is a test file and pilot. I look forward to testing this out. This is a big and very useful change for setting up encounters and situations.

[UnorderedSigh]

This is a fun one to test. I suggest you test it yourself.

[UnorderedSigh]

The tests produce preposterous situations which make the AI act like the stereotypical Endless Sky psycho, but in a calm and controlled manner. I, at least, find it hilarious to watch. Somebody else should see it before the PR is merged.

[Zitchas]

Hmmm... The exe artifact is giving me an error regarding the dlls. Odd. I'll try a different way.

[Zitchas]

OK, got it running. Just missing the dlls. Of course. In any case, updating so that it has the new directory for preferences and saves would be appreciated. (or just confirming that I can hit the "update" button without causing problems works too)

[Zitchas]

Hmmm... Flying the provided Friction Diction pilot, landed and took off a couple of times then went to Cardax, nothing happened.

[Zitchas]

OK, I had to do a bit of debugging, but I got it to work. Specifically, deleting the last "Test Event" call in the mission. That event hasn't been defined, so the fact it is undefined is stopping the mission from triggering. I deleted it, and then everything worked exactly as described in your walkthrough.

It is rather fun to watch the variety of spawning behaviors in action.

edit: Left the game run for a while Example 4. Disabled ships everywhere... Raiders jumping in, not seeing an active target nearby, jumping out, then immediatelyi jumping back in...

[Zitchas]

I'm not sure what the holdup is upstream with endless-sky#8082, but this is an awesome thing for enabling more finely tuned battles and situations. It also means that static things like Archons and lone alien ships that are always present don't need missions clogging up pilot files in order to have them always be present.

[TheGiraffe3]

Although about the Archons then we need separate fleet/name definitions for each of them...

[Zitchas]

True, we would. But that's easy enough to do. And I would be much, much happier having the minute amount of extra data in the data files for those fleets, then having to have a separate mission perpetually loaded in every single pilot file forever.

I mean, really. If a mission is permenently loaded, never visible to the player, and never actually acts like a mission... Why keep it front and center of the player's pilot file for them to just get confused about every time they try to figure out what's going on with their pilot?