OpenXcom Forum

Modding => OpenXcom Extended => OXCE Suggestions DONE => Topic started by: ohartenstein23 on June 01, 2018, 03:45:36 pm

Title: [Documentation] Soldier Transformations
Post by: ohartenstein23 on June 01, 2018, 03:45:36 pm
Edit:  This is now officially a part of OXCE+; while the following description of the UI only applied to the preview version and is therefore obsolete, the ruleset description in the next post is up-to-date with the feature as it is in the official version.

I'm excited to announce a new feature for upcoming versions of OXCE+: Soldier Transformations!  These transformations allow for mods to define projects that allow for direct editing of soldier stats and types in ways previously only possible by save editing, including the possibility of raising your favorite soldier from the dead or creating clones of them!  As this is such a large new piece of code, I'm releasing a preview build of it here for testing and feedback along with a mod that showcases some of the capabilities of transformation projects.  The zip archive I'm attaching to this post is a standalone OpenXcom build with a windows executable and a mod for testing the new code - installation is just unpacking the archive and copying the original game files to the UFO folder, a process familiar to those of you who play Piratez or the X-Com Files.

In order to access the transformation projects, when a project is unlocked via research (similar to a manufacturing project), the button from the Soldiers screen that takes you to the Memorial screen will turn into a drop-down menu for accessing the Soldier Transformations screen, the Memorial, and psi training or physical training if those are available at a base.  It can also be accessed from the Memorial screen in a similar manner if you have any projects available for resurrecting or cloning your fallen soldiers, or from a right-click action on a facility in the basescape view if it is modded to do so.

(https://openxcom.org/forum/index.php?action=dlattach;topic=6331.0;attach=37616;image)

Once you reach the transformation screen you'll be shown a list of soldiers that are eligible for your unlocked transformation projects at a particular base; any fallen soldiers eligible will show up at the bottom of the list in a different color.  From there, you can select a project from the drop-down in the lower-left corner of the screen that will filter the list of soldiers by those eligible for only that particular project.  In the mod attached here, I've created three different projects to try out - one to send a soldier off to training for a week to bring their firing accuracy up to the maximum possible starting accuracy, one to create a clone of a soldier using their starting stats, and one that will allow you to bring a soldier back from the dead, but at a loss of 25% of the stats they've gained.

(https://openxcom.org/forum/index.php?action=dlattach;topic=6331.0;attach=37618;image)

Clicking on a soldier in the list with the project selected will bring up an allocation screen where you can preview what's necessary to start the project and, if the option is turned on from the Options menu, how the soldier's stats will change when the project is started.  Clicking the start button performs the selected project on the selected soldier, placing them in a transfer to that base (if defined in ruleset) and giving them recovery time (also if defined in the ruleset).

(https://openxcom.org/forum/index.php?action=dlattach;topic=6331.0;attach=37620;image)

There are a huge number of possibilities for what you can do with these transformations - XCOM 2012-style MEC soldiers and gene modding?  Yep!  Transferring soldiers' consciousness into cybernetic killing machines?  Check!  Creating an army of undead from all the rookies you sacrificed down the ramp of the Skyranger?  You betcha!  So please test this new code out and let me know what you think, particularly with respect to the interface and what information you get from these screens - I want this to be as clear and fun a process as possible.
Title: Re: [EXE] Soldier Transformations
Post by: ohartenstein23 on June 01, 2018, 03:51:24 pm
Here's the ruleset documentation for the modders out there, it's also contained as a text file in the mod attached to the post above:

Code: [Select]
soldierTransformation:
  - name: STR_PROJECT_NAME # (REQUIRED) The name of this project listed in the Soldier Transformations screen
    listOrder: 100 # The list order of this project, defaults to increasing by 100 for each project in the mod when not defined
    requires: # A list of research projects required before this project appears in the list of available transformations, the default empty list means this project is available from the beginning of the game
      #- STR_SOME_RESEARCH
    requiresBaseFunc: # A list of base functions required at a base in order to do this project, the default empty list means no special facilities are required
      #- SOME_BASE_FUNC
    producedSoldierType: STR_SOLDIER # The type of soldier produced by this project - any soldier undergoing this transformation will be switched to this type. If left empty, the soldier type does not change.
    producedSoldierArmor: STR_NONE_UC # The armor the soldier produced will have when the project finishes, only used when keepSoldierArmor is false. Leaving it empty will give the soldier the armor defined by the type in the soldiers: ruleset.
    keepSoldierArmor: false # Default false, this parameter determines whether or not the soldier will keep the armor they're wearing through this transformation
    createsClone: false # Default false, this parameter determines whether the selected soldier has the transformation done to them or a new soldier is created that is a copy of the original and the transformation is done to the new soldier.
    needsCorpseRecovered: true # Default true, if your project allows dead soldiers, this determines whether or not you needed to have a corpse item available at the end of the battle in which the soldier died. This does not mean you need the corpse item in your stores, just that it would have been recovered if recover: true was set on the item
    allowsDeadSoldiers: false # Default false - can dead soldiers undergo this transformation?  If so, they are brought back to life at the base you started this project in
    allowsLiveSoldiers: false # Default false - can live, non-wounded soldiers undergo this transformation?
    allowsWoundedSoldiers: false # Default false - can wounded soldiers undergo this transformation?
    allowedSoldierTypes: # (REQUIRED) This list determines which soldier types can undergo this transformation, the default empty list means nobody can have this project done to them.
      #- STR_SOLDIER
    requiredPreviousTransformations: # A list of transformation projects that must be done to a soldier before they're eligible for this project, the default empty list means no previous projects are required.
      #- STR_SOME_TRANSFORMATION
    forbiddenPreviousTransformations: # A list of transformation projects that a soldier cannot have undergone in order to be eligible for this project, the default empty list means no previous projects are forbidden
      #- STR_SOME_OTHER_TRANSFORMATION
    requiredMinStats: # The minimum stats a soldier must have in order to be eligible for this project, defaults to all 0 so any soldier is eligible
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    requiredItems: # A list of items that must be consumed from the base's stores in which you start this project, the default empty list means no items are used
      #STR_SOME_ITEM: 1
    cost: 50000 # The cost of the project in dollars
    transferTime: 0 # Soldiers can be put in a transfer back to the base where they started if this parameter is greater than the default of 0 hours. New clones or resurrected soldiers are automatically given a transfer to the base with a default of 24 hours.
    recoveryTime: 0 # The amount of wound recovery time a soldier is given after this project completes and the transfer, if any, is completed. The default value is 0 days.
    flatOverallStatChange: # A direct change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain 5 max time units, while tu: -5 means the soldier will lose 5 max time units. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    percentOverallStatChange: # A percent change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain an extra 5% of their max time units, while tu: -5 means the soldier will lose 5% of their max time units. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    percentGainedStatChange: # A percent change to the soldier's stats, but instead of taking a portion of the overall stats, this only applies to the stats they've trained up from their initial values, can be positive or negative - firing: -100 means the soldier will lose all of the firing accuracy they trained since joining, while firing: 10 means they gain 10% of the amount they trained over their initial values. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    useRandomStats: false # Default false, when true, this parameter overrides the stat changes above and has the produced soldier roll random stats according to their new soldier type from this transformation project.
    lowerBoundAtMinStats: true # Default true, this parameter determines whether or not any changes in stats from this project should go below the minStats defined on the new soldier type.
    upperBoundAtMaxStats: false # Default false, this parameter determines whether or not any changes in stats from this project should go above the maxStats defined on the new soldier type.
    upperBoundAtStatCaps: false # Default false, this parameter determines whether or not any changes in stats from this project should go above the statCaps defined on the new soldier type.

The associated strings are:
Code: [Select]
extraStrings:
  - type: en-US
    strings:
#SoldierTransformationAssignState.cpp
      STR_TRANSFER_TIME: "Transfer Time>{ALT}{0}"
      STR_RECOVERY_TIME: "Recovery Time>{ALT}{0}"
      STR_CURRENT_STATS: "Current stats"
      STR_CHANGES: "Changes"
Title: Re: [EXE] Soldier Transformations
Post by: Starving Poet on June 01, 2018, 04:34:44 pm
Awesome work!  I can totally see myself using this in the future.
Title: Re: [EXE] Soldier Transformations
Post by: Ethereal on June 02, 2018, 10:07:20 am
Despite the fact that I have long learned how to play without losses among soldiers, thanks to tanks and smoke, I support this idea. Improving the characteristics of soldiers is generally fine! However, due to poor knowledge of English, i it is not possible to master the functional in order to conduct adequate testing. I'll wait for the release version.
Title: Re: [EXE] Soldier Transformations
Post by: bulletdesigner on June 04, 2018, 12:06:41 am
ho man i go to do this for the dreadnoughts , can i use it now or wait for the next extender release?
Title: Re: [EXE] Soldier Transformations
Post by: Meridian on June 04, 2018, 01:23:52 am
ho man i go to do this for the dreadnoughts , can i use it now or wait for the next extender release?

You can test and use it now already... it will be available in the next oxce+ version with the same ruleset (and maybe slightly updated gui)
Title: Re: [EXE] Soldier Transformations
Post by: ohartenstein23 on June 04, 2018, 04:56:32 am
ho man i go to do this for the dreadnoughts , can i use it now or wait for the next extender release?

That reminds me, I've been playing your mod with my test version and using this for dreadnoughts in my personal 40k edits mod, I'm attaching the mod that has the ruleset for dreads.  Also, I should let you know I designed this feature knowing that it would be used exactly for this.

As before, I don't recommend you take everything from my personal mod, just the stuff that looks helpful, like the marine-to-dread transformations ruleset.
Title: Re: [EXE] Soldier Transformations
Post by: ohartenstein23 on June 08, 2018, 02:39:26 pm
<snip>

Sure, all of that will be possible using this new code, the hardest part will be getting all the graphical assets together.
Title: Re: [EXE] Soldier Transformations
Post by: Meridian on June 15, 2018, 06:34:55 pm
Merged into OXCE+.
Newest build: https://lxnt.wtf/oxem/builds//ExtendedPlus/Extended+-3.10a-8263d93-2018-06-19-win32.7z

Also, I made a small mod for my LP to re-hire clones of dead soldiers.
Attaching here if someone wants to use it.

Code: [Select]
soldierTransformation:
  - name: STR_HIRE_CLONE
    listOrder: 1
    producedSoldierType: STR_SOLDIER
    producedSoldierArmor: STR_NONE_UC
    keepSoldierArmor: false
    createsClone: true
    needsCorpseRecovered: false
    allowsDeadSoldiers: true
    allowsLiveSoldiers: false
    allowsWoundedSoldiers: true  # adding these guys too, if we want to sack them
    allowedSoldierTypes:
      - STR_SOLDIER
    forbiddenPreviousTransformations:
      - STR_HIRE_CLONE
    cost: 40000
    transferTime: 72
    recoveryTime: 0
    useRandomStats: true
    lowerBoundAtMinStats: true
    upperBoundAtMaxStats: false
    upperBoundAtStatCaps: true
extraStrings:
  - type: en-US
    strings:
      STR_HIRE_CLONE: "Hire Clone"

Edit: see also soldier bonuses: https://openxcom.org/forum/index.php/topic,7405.0.html

Edit: more goodies: https://openxcom.org/forum/index.php/topic,7196.msg117767.html#msg117767
Title: Re: [EXE] Soldier Transformations
Post by: ohartenstein23 on June 15, 2018, 09:40:24 pm
Still not released yet, Meridian was just saying it'll be in the next release, which should be soon.

Also, all of what you want to mod is possible with the proposed ruleset above, using the already-available parameters on soldier types and armors.
Title: Re: [EXE] Soldier Transformations
Post by: Meridian on June 19, 2018, 11:18:59 pm
released
Title: Re: [Documentation] Soldier Transformations
Post by: DaEMon on July 29, 2018, 07:05:17 am
Hi,  I´m interested in the cloning dead soldiers feature. How do I enable it ingame?   
Title: Re: [Documentation] Soldier Transformations
Post by: ohartenstein23 on July 29, 2018, 04:59:19 pm
This needs to be enabled by a mod; you can see an example ruleset that does this in Meridian's post above, and if you ask nicely enough, he'll probably package it into a mod for you.
Title: Re: [Documentation] Soldier Transformations
Post by: Ethereal on July 30, 2018, 01:45:35 am
Hi,  I´m interested in the cloning dead soldiers feature. How do I enable it ingame?

Code: [Select]
soldierTransformation:
  - name: STR_CLONE_SOLDIER
    requires:
      - STR_SOLDIER_CLONE
    cost: 1500000
    producedSoldierType: STR_SOLDIER
    producedSoldierArmor: STR_NONE_UC
    allowsDeadSoldiers: true
    allowsLiveSoldiers: false
    needsCorpseRecovered: false
    createsClone: true
    allowedSoldierTypes:
      - STR_SOLDIER
    lowerBoundAtMinStats: false
    upperBoundAtMaxStats: false
    upperBoundAtStatCaps: true
    flatOverallStatChange:
      bravery: 10
      reactions: 10
      firing: 10
      throwing: 10
      melee: 10

Allegedly so...
Title: Re: [Documentation] Soldier Transformations
Post by: Carfax on January 25, 2020, 08:13:37 pm
Hi. I have a problem with the cloning code. I added it to the W40k mod (thx ohartenstein) and everything is working , but it won´t take the random stat option for the cloned Soldier.
All other optinons like % stat gain/loss, reset training etc. work but the random just won´t. the clone is generated with the stats at the time of death. Can somebody have a look at my .rul
and help me out pls. Playing with Extended 6.2
Code: [Select]
  - name: STR_CLONE_GUARDSMAN
    producedSoldierType: STR_GUARDSM
    needsCorpseRecovered: false
    createsClone: true
    allowsDeadSoldiers: true
    allowedSoldierTypes:
      - STR_GUARDSM
    forbiddenPreviousTransformations:
      - STR_CLONE_GUARDSMAN
    cost: 15000
    transferTime: 72
    useRandomStats: true
    lowerBoundAtMinStats: true
    upperBoundAtMaxStats: false
    upperBoundAtStatCaps: true
Title: Re: [Documentation] Soldier Transformations
Post by: Meridian on January 31, 2020, 07:54:02 pm
useRandomStats attribute doesn't exist: https://openxcom.org/forum/index.php/topic,7196.msg117767.html#msg117767
Title: Re: [Documentation] Soldier Transformations
Post by: Meridian on May 14, 2020, 08:43:07 pm
Added new atribute 'upperBoundType'.

Determines how strictly to apply 'upperBoundAtMaxStats' and 'upperBoundAtStatCaps'.
Possible values:

    0 = dynamic (i.e. soft when not changing the soldier type; hard when changing the soldier type)
    1 = soft (if the soldier is already above the maximum before the transformation, don't reduce his overflown stats)
    2 = hard (always reduce if above the maximum)

Default 0.
Title: Re: [Documentation] Soldier Transformations
Post by: psavola on November 30, 2022, 05:53:56 pm
I noticed (in TWoTS: implant a mind control protection or convert to a cyborg) that if you can apply this to a gravely wounded soldier, the excess wounds get healed up when doing a transformation.

Example: current wound recovery 20 days, transformation requires 15 days of recovery - after transformation the recovery is 15 days.

I would have expected the greater of the two, i.e., 20 - I'm assuming a soldier can both recover from battle wounds and surgery at the same time.

This would likely be a very simple code change, but I wonder if in some other contexts of transformations this might be undesirable. So I'm not sure if it would be worth it.
Title: Re: [Documentation] Soldier Transformations
Post by: Meridian on November 30, 2022, 06:31:18 pm
The primary inspiration for this feature was xcom2012's MECs.

If I remember correctly, the conversion heals them.
Title: Re: [Documentation] Soldier Transformations
Post by: Aldorn on February 25, 2023, 01:06:30 pm
Hi,

I'm really interested by this amazing feature  :o  (once more  ::)), but I fail to download zip file attached in first post

May it be this zip archive is corrupted?

EDIT: not sure if zip contains interesting resources or if it has only to do with programming, anyway I succeeded to mod it, very good feature
Title: Re: [EXE] Soldier Transformations
Post by: Aldorn on February 25, 2023, 01:10:15 pm
Here's the ruleset documentation for the modders out there, it's also contained as a text file in the mod attached to the post above:

Code: [Select]
soldierTransformation:
  - name: STR_PROJECT_NAME # (REQUIRED) The name of this project listed in the Soldier Transformations screen
    listOrder: 100 # The list order of this project, defaults to increasing by 100 for each project in the mod when not defined
    requires: # A list of research projects required before this project appears in the list of available transformations, the default empty list means this project is available from the beginning of the game
      #- STR_SOME_RESEARCH
    requiresBaseFunc: # A list of base functions required at a base in order to do this project, the default empty list means no special facilities are required
      #- SOME_BASE_FUNC
    producedSoldierType: STR_SOLDIER # The type of soldier produced by this project - any soldier undergoing this transformation will be switched to this type. If left empty, the soldier type does not change.
    producedSoldierArmor: STR_NONE_UC # The armor the soldier produced will have when the project finishes, only used when keepSoldierArmor is false. Leaving it empty will give the soldier the armor defined by the type in the soldiers: ruleset.
    keepSoldierArmor: false # Default false, this parameter determines whether or not the soldier will keep the armor they're wearing through this transformation
    createsClone: false # Default false, this parameter determines whether the selected soldier has the transformation done to them or a new soldier is created that is a copy of the original and the transformation is done to the new soldier.
    needsCorpseRecovered: true # Default true, if your project allows dead soldiers, this determines whether or not you needed to have a corpse item available at the end of the battle in which the soldier died. This does not mean you need the corpse item in your stores, just that it would have been recovered if recover: true was set on the item
    allowsDeadSoldiers: false # Default false - can dead soldiers undergo this transformation?  If so, they are brought back to life at the base you started this project in
    allowsLiveSoldiers: false # Default false - can live, non-wounded soldiers undergo this transformation?
    allowsWoundedSoldiers: false # Default false - can wounded soldiers undergo this transformation?
    allowedSoldierTypes: # (REQUIRED) This list determines which soldier types can undergo this transformation, the default empty list means nobody can have this project done to them.
      #- STR_SOLDIER
    requiredPreviousTransformations: # A list of transformation projects that must be done to a soldier before they're eligible for this project, the default empty list means no previous projects are required.
      #- STR_SOME_TRANSFORMATION
    forbiddenPreviousTransformations: # A list of transformation projects that a soldier cannot have undergone in order to be eligible for this project, the default empty list means no previous projects are forbidden
      #- STR_SOME_OTHER_TRANSFORMATION
    requiredMinStats: # The minimum stats a soldier must have in order to be eligible for this project, defaults to all 0 so any soldier is eligible
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    requiredItems: # A list of items that must be consumed from the base's stores in which you start this project, the default empty list means no items are used
      #STR_SOME_ITEM: 1
    cost: 50000 # The cost of the project in dollars
    transferTime: 0 # Soldiers can be put in a transfer back to the base where they started if this parameter is greater than the default of 0 hours. New clones or resurrected soldiers are automatically given a transfer to the base with a default of 24 hours.
    recoveryTime: 0 # The amount of wound recovery time a soldier is given after this project completes and the transfer, if any, is completed. The default value is 0 days.
    flatOverallStatChange: # A direct change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain 5 max time units, while tu: -5 means the soldier will lose 5 max time units. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    percentOverallStatChange: # A percent change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain an extra 5% of their max time units, while tu: -5 means the soldier will lose 5% of their max time units. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    percentGainedStatChange: # A percent change to the soldier's stats, but instead of taking a portion of the overall stats, this only applies to the stats they've trained up from their initial values, can be positive or negative - firing: -100 means the soldier will lose all of the firing accuracy they trained since joining, while firing: 10 means they gain 10% of the amount they trained over their initial values. The default of 0 means no change.
      tu: 0
      stamina: 0
      health: 0
      bravery: 0
      reactions: 0
      firing: 0
      throwing: 0
      strength: 0
      psiStrength: 0
      psiSkill: 0
      melee: 0
    useRandomStats: false # Default false, when true, this parameter overrides the stat changes above and has the produced soldier roll random stats according to their new soldier type from this transformation project.
    lowerBoundAtMinStats: true # Default true, this parameter determines whether or not any changes in stats from this project should go below the minStats defined on the new soldier type.
    upperBoundAtMaxStats: false # Default false, this parameter determines whether or not any changes in stats from this project should go above the maxStats defined on the new soldier type.
    upperBoundAtStatCaps: false # Default false, this parameter determines whether or not any changes in stats from this project should go above the statCaps defined on the new soldier type.

The associated strings are:
Code: [Select]
extraStrings:
  - type: en-US
    strings:
#SoldierTransformationAssignState.cpp
      STR_TRANSFER_TIME: "Transfer Time>{ALT}{0}"
      STR_RECOVERY_TIME: "Recovery Time>{ALT}{0}"
      STR_CURRENT_STATS: "Current stats"
      STR_CHANGES: "Changes"

Explanation are really great !!

Providing new features is wonderful, explaining how to implement, with so much details, is paradise  :)
Title: Re: [Documentation] Soldier Transformations
Post by: ohartenstein23 on February 25, 2023, 09:03:51 pm
Hi,

I'm really interested by this amazing feature  :o  (once more  ::)), but I fail to download zip file attached in first post

May it be this zip archive is corrupted?

EDIT: not sure if zip contains interesting resources or if it has only to do with programming, anyway I succeeded to mod it, very good feature

The ZIP archive was a copy of the executable for testing purposes, not necessary anymore since this is part of OXCE's codebase. Glad you enjoy the feature!
Title: Re: [Documentation] Soldier Transformations
Post by: Aldorn on February 26, 2023, 03:19:16 pm
Perfect, thanks for your answer !
Title: Re: [Documentation] Soldier Transformations
Post by: 0xEBJC on November 22, 2023, 01:56:50 am
is there a way to make the cost as a function vs a fixed value?

I was looking at the untouchables mod that does regeneration and resurrection.

I'm just tinkering with some ideas at the moment, but was thinking it would be useful to have the cost based off the soldiers specific stats.

my particular thought is for regeneration a function of days wounded
cost: 20000 * currentRecovery

but this feature could enable a lot of other useful mod options like making cost specific to other stats like the higher you go in strength a strength transformation cost more
transform + 20 strength
cost: 2000 * currentStrength

also would be helpful to have the requiredItems allow for a function as well
reqiredItems:
  STR_ENERGENIC_BLOOD_PLASMA: currentStrength / 10
Title: Re: [Documentation] Soldier Transformations
Post by: Meridian on November 22, 2023, 09:58:09 am
is there a way to make the cost as a function vs a fixed value?

no