Contracts should use *actual* part names, not "descriptions"

[Snark]

In contracts that require building something (e.g. a station) that has a particular part on it, use the actual part name in the contract criteria, not a chatty paraphrased description that players can misinterpret.

Some examples:

• Bad:  "an ISRU conversion unit"  (Note that none of the terms "ISRU", "conversion", or "unit" appear in the part's actual name or description.)
• Good:  "a Convert-O-Tron 250"
• Bad:  "a research lab"
• Good:  "a Mobile Processing Lab MPL-LG-2"
• Bad:  "materials bay"  (Note that neither "materials" nor "bay" appears in the part's actual name or description. The word "laboratory," however, does, which makes this confusable with "a research lab.")
• Good:  "SC-9001 Science Jr."

Why this is important:  The chatty description can mislead players.  I just wasted over an hour of my time because I assumed "an ISRU conversion unit" meant any ISRU, whereas apparently the contract wanted a Convert-O-Tron 250 and not a Convert-O-Tron 125.  In another thread a month or two ago, I saw a player get really confused because they saw "a research lab" and thought it meant a SC-9001 Science Jr. because the part's description says "...a cutting edge, self contained laboratory."

Chatty descriptions are terrible.  They're very easy to misinterpret.  They can also be extremely opaque.  For example, "an ISRU conversion unit" made sense to me because I've been playing KSP a long time and I'm very familiar with the term ISRU.  (And even then, I got it wrong, 'coz I thought the little one would be okay.  But at least I knew what kind of part it was.)  But suppose a new KSP player comes along, how the dickens are they supposed to interpret that?  The contract wants a Convert-O-Tron 250, but says "an ISRU conversion unit."  Guess what?  None of the words "ISRU", "conversion", or "unit" appear anywhere on that part!  Not in the name, not in the description.  There is no way for a player to know that "ISRU conversion unit" means "Convert-O-Tron 250" without having prior knowledge.  Ditto "materials bay" for the Science Jr.

Furthermore, it seems to me that re-working it this way would be good not just for the players, but for Squad as well.  Any time you have a chatty description, somebody has to sit down and explicitly type that out.  I don't know if KSP is localized into other languages (and if so, how many), but you've also just added an additional term that your translators are going to have to translate, too.  And it's a maintenance hassle, because parts sometimes get renamed or their descriptions tinkered with, and new parts get added all the time, so a chatty description that makes sense now could become ambiguous or flat-out wrong in the future.  So if you re-do the contract logic so that the contract internally just specifies the unique ID of the part (i.e. the one that's immutable, will never change, is never displayed to a user), and the game just programmatically inserts the actual name of the part, then you have less work for the developers, less work for the translators, and it will automatically stay completely up-to-date in the future.

The only case where a chatty description could be acceptable is when you're describing an entire category of parts (i.e. "an antenna", "a docking port") and it's completely clear and obvious what that means.  For all cases where a specific part is needed, however, use the actual part name.

I've restrained myself, with difficulty, from delving into my particular tale of woe here that led me to make this post, since it's less relevant to anyone but me.  But I just have to get this off my chest, so here it is in a spoiler section for anyone who's interested.

Spoiler

So I just got a contract that involves building a station, and one of the requirements reads thus:

"Have an ISRU resource conversion unit on the station"

Hmm, think I.  Does this mean the big one or the little one, or does it not matter?  I'd better check the actual part names, right?

• The big one:  "Convert-O-Tron 250"
• The little one:  "Convert-O-Tron 125"

Okay!  Clearly it doesn't matter.  Neither of these has "ISRU" in the name, both of them are in fact ISRU conversion units.  Squad even went to the trouble of giving them identical names except for the 250-vs-125 thing, to emphasize that these are both essentially the same kind of gizmo.  And the contract just says "an ISRU resource conversion unit," which these both are, so either one should work, right?

So I go to a lot of trouble, and expense, and flying things around, and landing, and mining to fulfill some other requirements, and put in over an hour of my time, all told, and finally launch it into a solar orbit to complete the contract.

So.... anyone care to guess whether the contract completed?  Anyone?  Go on, you'll never guess.

<pause for dramatic effect>

.

.

.

...Yes, that's right.  No dice.  The "Have an ISRU resource conversion unit" criterion isn't checked.  Clearly, it wants the big guy, not the little one.  I just completely wasted over an hour of my time.

Yes, I bear a certain amount of responsibility here.  For example, I could have seen, right after launch, that it wasn't satisfying that criterion, and saved myself a lot of hassle.  But it was something that came completely out of left field and I wasn't expecting; it simply didn't occur to me to check it.  If the game didn't use misleading language in the contract, it wouldn't have wasted my time because I would have gotten the correct part in the first place.  I shouldn't have to be a contract lawyer in order to interpret contracts in this game.  It's supposed to be KSP, not KLP. 

 

Edited January 12, 2016 by Snark

[GarrisonChisholm]

My *like* and " ***** " ratings don't go nearly far enough towards representing my agreement with this post.

[Guest]

Yep. I also totally agree with this.

And another thing that needs to be clarified about contracts are the "do X and land on Y", because contracts like that don't accept splashdowns, even though they're somewhat a landing?

[John FX]

1 hour ago, Aperture Science said:

Yep. I also totally agree with this.

And another thing that needs to be clarified about contracts are the "do X and land on Y", because contracts like that don't accept splashdowns, even though they're somewhat a landing?

In fairness there are contracts which do specify a splashdown and should you land on solid ground that would not complete those contracts. IMO they should say `must land on solid ground` or `must land in water`.

I support this call for plain english in the contracts. IIRC there is a mod that does that.

[r_rolo1]

Definitely agreed.The vague descriptions do not help in anything ...

1 hour ago, Aperture Science said:

And another thing that needs to be clarified about contracts are the "do X and land on Y", because contracts like that don't accept splashdowns, even though they're somewhat a landing?

Technically in game terms you can only "land" on land ( in theory, atleast ) ... and splashing is a completely diferent thing. But yeah, the diference should be stated clearly to avoid confusion.

Other issue with the contracts wordings is the meaning of the word "flying" in contracts, that is not the meaning of "flying" in terms of science collection ( TBH I got somewhat baffled by the first "get gravioli reading in flight above X altitude" because you can't get gravioli readings while in a "flying" situation  ) and that the "in flight" expression means two diferent things inside the contract system ( I have filed a bug report more than a year ago on this, if you want more details  ). Indeed another pass on the wording used on the contract system would surely  be helpful ...

Edited January 12, 2016 by r_rolo1

[Sovek]

Uhhh, you do know there are mods out there that have material bays and are not named 9001 science jr...

[r_rolo1]

7 minutes ago, Sovek said:

Uhhh, you do know there are mods out there that have material bays and are not named 9001 science jr...

May I point out you to the OP?

7 hours ago, Snark said:

The only case where a chatty description could be acceptable is when you're describing an entire category of parts (i.e. "an antenna", "a docking port") and it's completely clear and obvious what that means.  For all cases where a specific part is needed, however, use the actual part name.

He's not asking for not using the "materials bay" designation, he's asking that when the game means "9001 Science Jr" and not "general materials bay", the game actually says "9001 Science Jr."

[Kerbart]

My favorite is “transmit science from xxx orbit.” Because alt-clicking an MLP in orbit and choosing transmit science does not count as transmit science.

[Snark]

37 minutes ago, Kerbart said:

My favorite is “transmit science from xxx orbit.” Because alt-clicking an MLP in orbit and choosing transmit science does not count as transmit science.

Yeah, but that one's not really the contract system's fault... the problem is that the science lab does a thing called "transmit science" that is completely different from the other thing called "transmit science" that you can do with a science result.  It's just one more source of confusion that can trip up folks unfamiliar with the lab's operation... really wish it had a different term, though honestly I don't know what else would be better.

[John FX]

6 hours ago, Snark said:

Yeah, but that one's not really the contract system's fault... the problem is that the science lab does a thing called "transmit science" that is completely different from the other thing called "transmit science" that you can do with a science result.  It's just one more source of confusion that can trip up folks unfamiliar with the lab's operation... really wish it had a different term, though honestly I don't know what else would be better.

Here`s hoping that all has been looked at during the U5 conversion.

[Matt77]

Could be worth mentioning if things such as kerbals awaiting rescue are going prograde or retro too. Or polar, not sure if those exist though.

 

[Superfluous J]

The problem is, the contract internally DOESN'T want a "SC-9001 Science Jr." It wants a part with the module that does materials bay science, which just so happens to be the science Jr only in the stock game.

I'd much prefer the game to state that the probe be able to, say, "Perform materials bay science" and have that be hoverable or clickable, and when you hover or click it shows all the parts that do that thing, highlighted red if you don't own them yet, or with an X or something. And if you hover or click on THOSE then it tells you their stats and actually says if you own them, or what it'd cost in science to unlock them.

And regarding "ISRU Units" there actually ARE two now, aren't there? I'll admit, I've not played 1.0.5 very much but I distinctly recall pics of mini drills and a mini converter.

The main thing is the parts list interface, contracts interface, and part descriptions are incomplete and of pre-release quality. That we have this in a post-1.0 game is because - apparently - version numbers don't actually mean anything anymore now that we're in a post-neo-software-cycle world.

[Waxing_Kibbous]

I swear I've seen the contracts menu in the VAB (or SPH?) check things off as I build them- if not, that would be a good way to show players they are all set to go before launching.

[Snark]

56 minutes ago, 5thHorseman said:

The problem is, the contract internally DOESN'T want a "SC-9001 Science Jr." It wants a part with the module that does materials bay science, which just so happens to be the science Jr only in the stock game.

You're sure about that?  (Not that I doubt you, just wondering how you know.)  But even if that's the case:  simply saying "a materials bay" is opaque to players, because there's no way for them to know what the heck does that mean.  It's not at all useful; the term "materials bay" doesn't appear in the part's name or description.  If they have a contract that wants any one of a category of parts, then that category needs to be blatantly clear (like "docking port").

1 hour ago, 5thHorseman said:

...have that be hoverable or clickable, and when you hover or click it shows all the parts that do that thing,

Yes.  Strongly agree with this, and with the rest of the suggestions in that paragraph. 

1 hour ago, 5thHorseman said:

And regarding "ISRU Units" there actually ARE two now, aren't there? I'll admit, I've not played 1.0.5 very much but I distinctly recall pics of mini drills and a mini converter.

Yes, and that's the problem.  The contract that bit me just said "an ISRU conversion unit," when what it meant was "specifically a Convert-O-Tron 250 and not a Convert-O-Tron 125."  I assumed that any ISRU conversion unit would be OK, since that's what the contract said.  But it wasn't.  It was highly misleading.  And, as I note above, "ISRU conversion unit" is a terrible description because the terms "ISRU", "conversion", and "unit" don't actually appear anywhere in the names or descriptions of those parts.  I'm lucky because I've been playing KSP a while so I know what ISRU means, but a new player would be left high and dry.

Basically, what it boils down to is:

• If a contract wants a particular part, it should say the actual name of that part.
• If a contract wants any part that fits in a given category, it should provide some way of listing the parts in that category.

[Superfluous J]

1 hour ago, Snark said:

You're sure about that?

I was far more sure about it before you said:

1 hour ago, Snark said:

The contract that bit me just said "an ISRU conversion unit," when what it meant was "specifically a Convert-O-Tron 250 and not a Convert-O-Tron 125."

I will go to my fallback position: The game is not even remotely complete and expecting it to be so is folly.

Two things:

1.

3 hours ago, Waxing_Kibbous said:

I swear I've seen the contracts menu in the VAB (or SPH?) check things off as I build them- if not, that would be a good way to show players they are all set to go before launching.

This is kinda true. It doesn't always work in the VAB/SPH (again a sign the game isn't complete) but it does always work on the launchpad. Put your ship there and make sure all the boxes are checked.

 

2. Cheat. Go into the cheat menu and complete the contract. You'll get the money and rep and shouldn't feel bad about it at all. It's there to mitigate these kinds of problems with the game.

[DMagic]

1 hour ago, Snark said:

You're sure about that?  (Not that I doubt you, just wondering how you know.)  But even if that's the case:  simply saying "a materials bay" is opaque to players, because there's no way for them to know what the heck does that mean.  It's not at all useful; the term "materials bay" doesn't appear in the part's name or description.  If they have a contract that wants any one of a category of parts, then that category needs to be blatantly clear (like "docking port").

Yes.  Strongly agree with this, and with the rest of the suggestions in that paragraph. 

Yes, and that's the problem.  The contract that bit me just said "an ISRU conversion unit," when what it meant was "specifically a Convert-O-Tron 250 and not a Convert-O-Tron 125."  I assumed that any ISRU conversion unit would be OK, since that's what the contract said.  But it wasn't.  It was highly misleading.  And, as I note above, "ISRU conversion unit" is a terrible description because the terms "ISRU", "conversion", and "unit" don't actually appear anywhere in the names or descriptions of those parts.  I'm lucky because I've been playing KSP a while so I know what ISRU means, but a new player would be left high and dry.

Basically, what it boils down to is:

• If a contract wants a particular part, it should say the actual name of that part.
• If a contract wants any part that fits in a given category, it should provide some way of listing the parts in that category.

 

Stock contracts do both. There are specific module parameters (those are the Include an Antenna, or a Docking Port requests), and there are specific part parameters, two actually.

The Part Test parameters really do ask for a specific part, and those should use the title (do they?) and have a button like 5thHorseman says (Contracts Window + used to have something like this, but that got dropped when they remade the editor).

The other specific part parameter, the one causing the problem, asks for a specific part, but not necessarily just one. In the Contracts.cfg file you can add whatever parts you want to the parameter (I use this to add my parts for satisfying those Include a Science Jr., or Goo Pod requests). One solution, the one that I've started using, is to take the first part in that list of acceptable parts and give its in-game title. I think that's better than a generic description (especially when parts covered by that description aren't accepted), but it's still problematic. It could lead people to think that is the only acceptable part. I guess you could list all of the acceptable parts in the contract notes. 

[DMagic]

21 minutes ago, 5thHorseman said:

I will go to my fallback position: The game is not even remotely complete and expecting it to be so is folly.

That's true, but also nonsense in this case.

If they add a part that should logically fill the same purpose as an existing part asked for by a contract, they should include the new part too. The contract in question is specifically designed to handle such cases.

Also, how do you split quotes in replies? And how do you copy a quote to an existing post rather than making a new one?

Edited January 14, 2016 by DMagic

[Superfluous J]

15 minutes ago, DMagic said:

Also, how do you split quotes in replies? And how do you copy a quote to an existing post rather than making a new one?

You don't You highlight the text in the post you want to quote, and a little "quote this" box comes up. You click that, and it inserts the quote. Then you repeat for other sections.

[Alshain]

 

 

I believe they are actually based on part Names rather than part Titles (and I agree they shouldn't be).  If you look at the part configs, the large ISRU name is "ISRU", the small ISRU part name is "miniISRU"

 

EDIT: Though I just checked the SC-9001 and it's name is "science_module" so now I'm not sure that is true either.

EDIT2: Ok, so looking a bit closer there are two ways they are defines, part requests and module definitions.  The ISRU/Materials Bay is a Part Request and it does appear to be easily renameable.  Just change the line that reads PartDescription in contracts.cfg.  Of course this should be done in stock IMO, if done in stock they should just remove the part description and always use the part Title from it's own config, rather than being redundant.

 

		PART_REQUEST // A potential materials bay request for satellites
		{
			Article = a // Article (A/An) to be used prior to part description
			PartDescription = materials bay // Plain speech description of part for request
			VesselDescription = satellite // Plain speech description of vessel for request
			Keyword = Scientific // Contract briefing keyword
			Part = science_module // A part ID that triggers this request
			MinimumScience = 7 // A minimum value this request places on science rewards
			Trivial // Easy Contracts
			{
				Weight = 5 // How common this request is in easy contracts
				FundsMultiplier = 1.05 // The multiplier this request places on funds in easy contracts
				ScienceMultiplier = 1.25 // The multiplier this request places on science in easy contracts
				ReputationMultiplier = 1.05 // The multiplier this request places on reputation in easy contracts
			}
			Significant // Medium Contracts
			{
				Weight = 15 // How common this request is in medium contracts
				FundsMultiplier = 1.05 // The multiplier this request places on funds in medium contracts
				ScienceMultiplier = 1.25 // The multiplier this request places on science in medium contracts
				ReputationMultiplier = 1.05 // The multiplier this request places on reputation in medium contracts
			}
			Exceptional // Hard Contracts
			{
				Weight = 25 // How common this request is in hard contracts
				FundsMultiplier = 1.05 // The multiplier this request places on funds in hard contracts
				ScienceMultiplier = 1.25 // The multiplier this request places on science in hard contracts
				ReputationMultiplier = 1.05 // The multiplier this request places on reputation in hard contracts
			}
		}

The mentioned "module definitions" define requirements for power generator, antenna, docking port, and wheel.

Edited January 14, 2016 by Alshain

[egoego]

10 hours ago, 5thHorseman said:

I'd much prefer the game to state that the probe be able to, say, "Perform materials bay science" and have that be hoverable or clickable, and when you hover or click it shows all the parts that do that thing, highlighted red if you don't own them yet, or with an X or something. And if you hover or click on THOSE then it tells you their stats and actually says if you own them, or what it'd cost in science to unlock them.

Something like this would be very helpfull. +1

[KerbonautInTraining]

At the very least the contract should include a picture of the part. Some parts don't have very intuitive names (i.e. ones that are just model numbers). Or you could copy the interface from the VAB. (mouse over the part, it starts spinning and shows a description etc.)

[DMagic]

19 hours ago, Alshain said:

I believe they are actually based on part Names rather than part Titles (and I agree they shouldn't be).  If you look at the part configs, the large ISRU name is "ISRU", the small ISRU part name is "miniISRU"

There are good reasons why the internal part name is used by the contract, not the title. The internal name is unique, there is no confusion there; the title can be anything.

Also, if you look at the part = ... line in the PART_REQUEST node, you can just add more part  = whatever lines and the contract will then accept any of those parts.

Edited January 15, 2016 by DMagic

[Alshain]

1 hour ago, DMagic said:

There are good reasons why the internal part name is used by the contract, not the title. The internal name is unique, there is no confusion there; the title can be anything.

Well if you read all the edits to that post instead of deleting them, you'd see I figured out that wasn't the case.  Besides, readable text doesn't need to be necessarily unique (though in this case it should be anyway).  We aren't talking about the contract definition, we are talking about what appears on your screen.

[Blaarkies]

10 hours ago, KerbonautInTraining said:

At the very least the contract should include a picture of the part. Some parts don't have very intuitive names (i.e. ones that are just model numbers). Or you could copy the interface from the VAB. (mouse over the part, it starts spinning and shows a description etc.)

^This is what we need 
But I see a small problem with this solution when looking at the contracts window "in-flight".

...at least after you choose the contract in the Mission Control building, you will know exactly what is expected of you.

[KerbonautInTraining]

7 hours ago, Blaarkies said:

^This is what we need 
But I see a small problem with this solution when looking at the contracts window "in-flight".

...at least after you choose the contract in the Mission Control building, you will know exactly what is expected of you.

Well, you just need to know which part it is so your can put it on a vessel, once in flight you already have the part and just need to test/use it.