[WIP][1.7.x] Kerbal Status Effects - say no to touristification! [ v0.1.0 @ 2019-04-13 ]

[cakepie]

Kerbal Status Effects
v0.1.0 @ 2019-04-13

Kerbal Status Effects is an addon that provides a framework for applying status effects that temporarily modify the skills (ExperienceEffects) of affected Kerbals.

This mod is currently WIP and is not feature complete. See roadmap below for development plans.
The current release is a dev build, intended to enable other modders to review, test, and serve as a starting point for using/integrating it in their own mods.
Nothing for end-user consumption yet. (That means you, players. Come back later!)

~ ~ ~ ~ ~

Rationale

A number of mods currently exist that change a kerbal's class to Tourist in order to render them "useless" or "unable to work".
This is the most convenient way to achieve that goal, since the KSP API just doesn't provide any straightforward means of doing so.
However, this is less than optimal, for several reasons:

• Mod incompatibilities

  If more than one mod is installed that utilizes "touristification", they may step on each others' toes and leave things in an incorrect or invalid state.
  This generally means that such mods are mutually incompatible with one another, so players cannot use them together.

  This was less of a problem when the only mods that performed "touristification" were life-support mods: such mods are typically intended to be mutually exclusive, and (despite being a less punishing alternative to outright death) "touristification" is an undesirable outcome that players are supposed to avoid, so it shouldn't occur very frequently.

  However, there are also mods such as Duty Roster and Kerbal Health that do not fit into this category of "life-support mods", so it is desirable to move toward an approach that will allow different mods to play well with one another, e.g. see this user request.

• Brittle, potentially save-breaking

  The process of "touristification" involves saving a copy of the kerbal's original specialization, then changing it to "tourist". This is error-prone (e.g. saving the wrong data) and can lead to saves being left in an invalid state if the mod is uninstalled (e.g. concerns voiced here by the maintainer of Snacks!)

• Loss of information / contradictory information from player POV

  Players may be interested in what the original specialization of a "touristified" Kerbal was, but only the mod responsible for the "touristification" knows this information. Furthermore, it might not even provide that information to the player via UI anywhere.

  For all intents and purposes, the Kerbal will be shown as a tourist by stock KSP UI (e.g. astronaut complex, tracking station, map view) and other mods (e.g. Portrait Stats) and treated as such for logic purposes. If the "touristification" mod shows the original specialization in its UI, this will conflict with all other information available elsewhere.

  One might argue that the fact that a crewmember became a tourist is intended to provide feedback to the player (e.g. that life support requirements were not met, etc). However this is not obvious and isn't sufficiently informative, as evidenced by players asking via forums or other social media why their kerbal became a tourist. There is also no way to distinguish between a "touristified" crewmember vs an actual tourist. We all know that Jeb is obviously a pilot and not supposed to be a tourist, but other randomly-generated kerbals are not likely to be as memorable.

• Unintended effects and consequences

  Turning crewmembers into tourists is a sledgehammer-style approach, in that it does not just remove their specialization-related skills. It will also:

  • Downgrade GeeForceTolerance to 0.75
    This may make some sense in some situations, e.g. weakened by lack of food or other life support. But it is not always applicable.
  • Remove EVAChuteSkill
    May preclude life-saving use of parachute in dire circumstances.
  • Prevent EVA
    Could be a massive unintentional inconvenience, e.g. kerbals who ran out of life support in a vessel without docking ports will not be able to EVA to board a rescue ship.

Kerbal Status Effects remedies all of the above, providing assurances of:

• Mod interoperability

  Kerbal Status Effects serves as a common clearinghouse for all changes to kerbal skills, and will maintain consistency even when multiple mods apply status effects that touch the same skill.

• Robust, will not break saves

  Kerbal Status Effects does not touch any of the stock KSP crew roster data, and will not lead to broken saves under any circumstances.

  If a downstream mod is uninstalled, Kerbal Status Effects will notice that it is gone, and remove its associated status effects from all affected kerbals.
  If Kerbal Status Effects itself is uninstalled, no status effects will be applied and all kerbals effectively revert to their stock behavior.

• Clear and informative

  Information about kerbals and the status effects they are affected by will be clearly provided in UI. (Not implemented yet.)

• Precise impacts

  Kerbal Status Effects permits precise changes to the skills of individual kerbals, with no unintended consequences.

~ ~ ~ ~ ~

For Players

There is nothing here for you yet. Come back later!
This mod is currently not feature complete, please don't bother me with questions or feature requests.

~ ~ ~ ~ ~

For Modders

The mod is not fully feature complete yet, but it is in a functional enough state to be released for review and testing.

You should be able to start work on integration into your mod, but please treat as a feature branch for now. You may release test builds, but please include clear warnings re: backing up saves, etc.

Kerbal Status Effects can currently parse definitions of status effects from config files, and the API for other mods to request for a status effect to be applied to/removed from kerbals is in place. Only skill deletions are possible at the moment, but this should suffice for any mod that currently turns crewmembers into tourists for the purpose of rendering them "useless" or "unable to do any work". Skill additions and modifications will come later; they're trickier to get right because of the need to enforce some kind of consistency when multiple mods apply status effects that touch the same skill.

Integration: only available as a hard dependency for now. This shouldn't be a massive deal-breaker, most use cases should not treat the dependency as optional.
Nonetheless, wrapper code will be made available later™.

A fully-fledged inspection and debugging tool is available by typing /kse in the Ctrl-Alt-F12 console.
Caveat: this command may be limited to debug builds only in the future. It might be a bit too dangerous in the hands of end-users.

See roadmap below for development plans.

~ ~ ~ ~ ~

Roadmap

Things that are in the pipeline:

• Adding skills; modifying existing skills
  These are trickier to get right because of the need to enforce some kind of consistency when multiple mods apply status effects that touch the same skill.
  But I do have some ideas for how it can be done.
• UI
  Provide better information to the player.
  Note: Not a substitute for downstream mods having their own UI.
  • Status pane (per kerbal) to display all status effects they are affected by
  • Listing of kerbals affected by status effects, with sort/filter by:
    • Kerbal name
    • Kerbal specialization / class (Trait)
    • Show current vessel or EVA only
    • RosterStatus (Assigned, Available)
    • Status effect (also by source mod if it has multiple effects)
    • Net impact on kerbal ( buff / debuff / incapacitated )
  • Notification when kerbal gains a status effect
    • Allow suppression for routine (e.g. shift change) or pseudo-permanent (e.g. trained skill) statuses
  • Toolbar integration (stock + blizzy)
• Wrapper code
  To avoid requiring a hard dependency.
• Better / consolidated documentation for modders
  The source code is already heavily commented but it'd probably be more convenient to consolidate all guidance into once place.

~ ~ ~ ~ ~

License

The Kerbal Status Effects plugin is released under the MIT License.

~ ~ ~ ~ ~

Download

Kerbal Status Effects v0.1.0 for KSP 1.7.x
WARNING: dev build for testing and integration purposes. Not intended for end-users.
This has not been tested for backward compatibility with older versions of KSP.

CKAN: Not supported. Do not ask, and do not add.
This is not in a state that is suitable for general release to the CKAN masses.

Installation:
Delete older version, if any.
Place contents of GameData into your installation's GameData folder.

Source: GitHub

Changelog:

v0.1.0 ~ 2019-04-13 ~ KSP 1.7.0
Initial Dev Build
- skeletal functionality, no UI
- supports only deletion of skills, no addition/modification
- has not been tested for backward compatibility with older versions of KSP

 

Edited April 16, 2019 by cakepie
fix typos

[Angelo Kerman]

I wondered if such a thing was possible, nice to see that it is and that you've taken up the torch to make it happen! A mod like this would be a great companion for Snacks and offer additional challenges to players. Kudos to @cakepie for making this possible!

[theonegalen]

Fantastic!

/10thDoctor

[garwel]

Interesting. I'd like to try and implement this approach in Kerbal Health. Is there any manual for integrating it in mods?

[cakepie]

@garwel Besides stuff already mentioned in the OP above there is also some additional guidance that I offered to wile1411 for Duty Roster over at this PR.
It should be sufficient to bootstrap any implementation of a touristification alternative.

Other than that I haven't gotten around to any documentation beyond comments in my source code. Look in KSE's dev branch.
If you care about what you can put in your status effect definition and how it will get parsed, check StatusEffect.cs.
Public-Facing API is in a clearly marked region in KSEAddon.cs, though it's most likely more convenient to use extension methods provided in KSExtensions.cs.

Again, I strongly recommend doing any implementation in a feature branch -- not even dev branch -- so as not to contaminate your existing workflow for an existing released mod.
It may take a while for Kerbal Status Effects to get properly fleshed out, in its current state I'd consider it more like a tech demo, not even a beta build.

[cyberKerb]

Awesome!. This should be interesting to implement. I finally have some time to code and will do some testing  with Duty Roster tonight.

Also adding obligatory @SQUAD ping to see if this is something they could support in the future stock API somehow to increase available modding support.

Edited April 15, 2019 by wile1411

[Beetlecat]

Fantastic idea and presentation. Looking forward to watching this develop/deploy