[Documentation] Up-/Downgrading Facilities

[ohartenstein23]

New feature documentation time!  With a recent code addition to OXCE+, you can now 'upgrade' existing facilities by building over them, and you can also make it such that removing a facility can 'downgrade' it to another facility.

The rules for this feature are as follows:

When a facility is removed, the ruleset is checked for a list of facility names leaveBehindOnSell

• If the first facility on the list is equal to the size of original, then that facility is placed over the previous one
• If the list contains all size 1 facilities, then the list is iterated over, placing facilities until the size of the previous is reach
• If the sizes don't match one of the above conditions, an exception is thrown letting the player/modder know the sizes don't match up

The facilities left behind are given a build time according to the previous facility's removalTime:

• If removalTime: 0, then the facility is instantly built (default behavior)
• If removalTime: -1, then the build time is set to the new facility's normal build time
• If removalTime is a number greater than 0, then the build time for the new facility is set to that number

Any facility placed by this left behind method is flagged for having a facility there previously; this flag makes the facility count as already built for base connectivity, makes it so the facility cannot be removed until it is fully built (this is to represent deconstruction time), and makes the new facility have it's map placed during base defense missions.

When a facility is built, the buildings under where it's being placed are checked for the tag canBeBuiltOver; if the tag is true, then new facility can be built over the previous one.  The refund for removal of each of the facilities being replaced is applied, and the build time for the new facility is reduced by the build time of each of those previous facilities, normalized by the size of the new facility.  This build time can never be reduced below 1 day.  The new facility is flagged similarly to ones left behind after being removed, unless all the facilities being replaced are under construction.
You can further specify which facilities one building is allowed to replace by the buildOverFacilities list - if this list is empty, no filter is applied.  Otherwise, the facilities which are being replaced have to be on this list, otherwise the facility building is blocked.  Upgrading an existing facility is also blocked if all of the other ones connecting to it are under construction, even if build queue is turned on.

I'm attaching a mod to test this code - many of the beginning facilities will leave corridors behind when they're deconstructed, corridors can be upgraded to living quarters and any other facility, general stores can be upgraded to anything but living quarters, and small radar can't be built over anything.  You can also build over hangars, but only with other hangars; this is just to test the code with 2x2 buildings.  The sectoid research mission at the beginning of the game is replaced with a retaliation mission to make sure the base maps are generated correctly.

This code also adds the following messages to let you know exactly why a facility can't be built:

Code: [Select]

#BasescapeState.cpp
  STR_CANNOT_DISMANTLE_FACILITY_UPGRADING: "CANNOT DISMANTLE FACILITY!{SMALLLINE}Facility cannot be removed during upgrading."
#BaseView.cpp
  STR_CANNOT_UPGRADE_FACILITY_ALREADY_UPGRADING: "CANNOT BUILD HERE!{SMALLLINE}Existing facility is already being built over."
  STR_CANNOT_UPGRADE_FACILITY_WRONG_SIZE: "CANNOT BUILD HERE!{SMALLLINE}Selected facility must completely cover existing facility."
  STR_CANNOT_UPGRADE_FACILITY_WRONG_TYPE: "CANNOT BUILD HERE!{SMALLLINE}Existing facility cannot be upgraded over by selected facility."
  STR_CANNOT_UPGRADE_FACILITY_DISALLOWED: "CANNOT BUILD HERE!{SMALLLINE}Existing facility cannot be built over."
  STR_CANNOT_BUILD_QUEUE_OFF: "CANNOT BUILD HERE!{SMALLLINE}Connecting facilities must finish construction first."


[The Reaver of Darkness]

This is great! I wanted a thing like this going way back! Thanks! Now to figure out how it works...

[The Reaver of Darkness]

When building a 2x2 building on top of one or more 1x1 buildings, it is not enough to set that the large building can be built on the small building; the small building must be able to accept anything built over it.

Example: I want to build large living quarters on top of multiple small living quarters.

Code: [Select]

  - type: STR_LIVING_QUARTERS
    buildOverFacilities:
      - STR_LIVING_QUARTERS_LARGEThis is not enough to get the job done. It must be done like this:

Code: [Select]

  - type: STR_LIVING_QUARTERS
    canBeBuiltOver: true
This has the unintended consequence of allowing me to build a large laboratory, or a hangar, on top of my living quarters.

[ohartenstein23]

You have that tag on the wrong facility; right now you're telling the game the living quarters can be built on top of the large living quarters instead of the other way around. Try this:

Code: [Select]

facilities:
  - type: STR_LIVING_QUARTERS
    canBeBuiltOver: true
  - type: STR_LIVING_QUARTERS_LARGE
    buildOverFacilities:
      - STR_LIVING_QUARTERS


[The Reaver of Darkness]

That's not how it works with small facilities only, and I tried it both ways. When I put the tag for general stores on a living quarters, it allowed me to build a general stores on the living quarters, but did not let me build a living quarters on the general stores.

However I tried it both ways for small to large and neither one worked.

[ohartenstein23]

I have it working with upgrading a Living Quarters to a Hangar in vanilla - are you sure the living quarters is not in use, i.e. you have enough space without that living quarters, before you tried upgrading it?  Once you start building over a facility you lose any functionality that it had previously, so while the large quarters is being built you have however much less living space from the original living quarters.  Here's what I have that allows building the 2x2 Hangar over a Living Quarters:

Code: [Select]

facilities:
  - type: STR_LIVING_QUARTERS
    canBeBuiltOver: true

  - type: STR_HANGAR
    buildOverFacilities:
      - STR_LIVING_QUARTERS

Similarly, this is what works for building a living quarters on top of a general stores, but again you have to make sure that you can remove the general stores normally before you can build over it, i.e. you don't get the "CANNOT DISMANTLE FACILITY! Facility in Use" message:

Code: [Select]

  - type: STR_GENERAL_STORES
    canBeBuiltOver: true

  -  type: STR_LIVING_QUARTERS
     buildOverFacilities:
      - STR_GENERAL_STORES


[The Reaver of Darkness]

As I said in my first post yesterday, it works because you have the line "canBeBuiltOver: true", which supercedes the non-functional code bit "buildOverFacilities: - STR_LIVING_QUARTERS".

I was also incorrect in my previous position that the bug exists only when putting a large on top of a small. It seems the bug exists also when putting a small on top of a small. I must have had "canBeBuiltOver: true" set on one of my buildings. When the line isn't present, nothing can build over anything else. When it is present, anything can be built on it.

[ohartenstein23]

I can tell you for a fact that "canBeBuiltOver: true" does not supercede the "buildOverFacilities" list; what's happening in the code is that the pre-existing facility must have the first tag in order for anything to be placed over top it and the new facility is looking for the "buildOverFacilities" list.  If that list is empty, then the new facility can be built over anything pre-existing facility with "canBeBuildOver: true".  Why don't you attach a copy of your mod so I can actually diagnose your issue?

[The Reaver of Darkness]

Code: [Select]

  - type: STR_LIVING_QUARTERS
    canBeBuiltOver: true
    buildOverFacilities:
      - STR_LIVING_QUARTERS_LARGEWith this code, I can build a large living quarters on the small one, but I can also build a large laboratory on the small living quarters. The buildOverFacilities list isn't accomplishing anything because it only switches lines to yes which are already yes.

[ohartenstein23]

Your buildOverFacilities in this example does nothing; you're telling the living quarters you can place it on top of the large one.  If you want Large Living Quarters to go over Living Quarters, but not Large Laboratory to go over Living Quarters, then you need this:

Code: [Select]

  - type: STR_LIVING_QUARTERS
    canBeBuiltOver: true

  - type: STR_LARGE_LIVING_QUARTERS
    buildOverFacilities:
      - STR_LIVING_QUARTERS

  - type: STR_LARGE_LABORATORY
    buildOverFacilities:
      - STR_LABORATORY # or STR_NONE

As I said in my previous post, if the buildOverFacilities list is empty (default), you can place that facility on top of *any* facility with "canBeBuiltOver: true".

[The Reaver of Darkness]

Oh okay I get it now. That is really confusing to me. I feel like the way it should work is that if a facility is listed to be able to build on top of something else, that something else shouldn't need the canBeBuiltOver tag. It's redundant and confusing, and it means if I want to have even one building that can have a specific something built on it, I have to include a build list for every facility.

[ohartenstein23]

It's written on a different logic; if you see the test mod I put in the original post, I have a Corridor facility that allows for almost all facilities to be put over it since it has "canBeBuiltOver: true" and most other facilities don't have the buildOverFacilities list.  If you want a facility to be more picky on what goes under it, then you give it a buildOverFacilities list.  My intent was that "canBeBuiltOver: true" should be as inclusive as possible for things like placing cheap corridors/excavating tunnels to later make it easy to build facilities all over the base, and then you use the buildOverFacilities list to do more complex stuff.

[The Reaver of Darkness]

That all makes sense until you start trying to upgrade facilities. If the buildOverFacilities list superceded the canBeBuiltOver check, it would fix this and enable easy building upgrades. After all, if I didn't want anything to be built on top of the small living quarters, why would I put on the large living quarters that it can be built on top of the small living quarters?


I found another bug. If you remove a large facility and it is replaced by a small facility type, it correctly places four of them but it builds them instantly and displays them with the default structural element instead of the one built into the facility. You can test it easily with my mod by setting any large facility to leave corridors when removed. It places them instantly and leaves the white cross hub which is supposed to not be present.

[ohartenstein23]

The original post says instant building of left behind facilities is the default; you need to set removalTime if you want different behavior.  This code also does not effect sprites, only whether or not the facility is construction, so any display issue is with your definition of the sprites.

Edit:  I'm not going to change these tags so that one supercedes the other - by design and source code readability canBeBuiltOver is a pre-existing facility property and buildOverFacilities is a filter for new facility construction.

[The Reaver of Darkness]

The original post says instant building of left behind facilities is the default; you need to set removalTime if you want different behavior.  This code also does not effect sprites, only whether or not the facility is construction, so any display issue is with your definition of the sprites.

Did you try it with my mod? I had set one of the facilities to leave behind corridors with a 4 day removal time. It build corridors immediately, and they looked different from the corridors which were not built immediately.

I believe the display issue is with OXC and not yours or my mod; the incorrect sprite is shown during construction but then removed upon finishing. This has been the case since before I upgraded to OXCE+.