MM, I got your PMs and scanned them; you are right that something went amiss with the formatting. But, from what I could see, they were nice docs and generally more clear than the EMS docs. I guess, I am not exactly sure why you sent them to me. As far as I know, I haven't made any complaints about your ability to document things. Did you write EMS? Are you considering updating the doc sheet for it and including it with your revision of Aielund? If the latter, then I think that would be a welcome improvement.
BTW, before diving back into those spell change descriptions in the EMS docs, I would like to comment that, had the EMS author simply provided script source for his changes, we probably wouldn't be having this discussion. I probably still would have thought the docs were lacking, but it would have been less likely to have come up because I would have had the option to read the scripts where I had any remaining questions. To my mind, releasing something like EMS as a black box only increases the need for clear docs.
And, as I have said before, the version of EMS that I have - which I am pretty sure is the same as the version currently on the new vault - does not have the script source. If I (and the new vault) have gotten an incomplete version and the version with the source is supposed to be available, I would like to see it.
Before you listed 8 spells out of the first 20 which you considered to be unclear.
4 of those 8 were actually clear in the first place in terms of what they did.
Among the first 20 spells in the spell list in EMS_Changes.txt, I listed Charm Person, Color Spray, Scare, Ability Buffs, Combust, Continual Light, Darkness, and Flame Weapon as being written in a way that would be unclear or confusing to an NWN player. Since you go through four of them below, I assume you are saying that the others - Color Spray, Scare, Ability Buffs, and Combust - are those that are "clear in the first place" about what the EMS versions do. Obviously, clarity is a judgment call, but I would say that they aren't.
Once again, these are things that I think will be unclear to a player reading the EMS doc. The fact that you or I or others with sufficient experience can figure out what the spells are likely to really do doesn't mean that the docs are clear. If you disagree that they are unclear, I'd be happy to be proven wrong with something like "EMS says 'X, Y, and Z' about this spell and each of those is something that clearly explains to an NWN player how EMS changes the spell's functionality without adding confusion."
Color Spray makes no attempt to define what the "correct" way to combine effects would be. The EMS change of stacking the effects in a way not described in the spell description because the author prefers it that way is not made clear in the EMS doc. As far as I can see, the Bioware version of the spell does pretty much what Bioware says it will do. The NWN docs say it does one thing, the EMS doc says that something about the Bioware approach is wrong (EMS doesn't say if it's Bioware's implementation, or Bioware's idea of what the spell ought to do, or both) and fails to say what it is. An NWN player is not left with a clear understanding of what the spell does.
Scare is still unclear because of shaken. Regardless of its presence in the spell script comments, it is not a standard term that an NWN player will find in the game docs. Even if an NWN player searches the wiki and sees the term buried in one article about a standard feat, he only sees it in the notes, it is only defined indirectly, and it isn't treated as a standard term that the player should expect to be used for other NWN spells or feats. The latter isn't surprising, given that it is mentioned in the wiki for no other NWN spell or feat.
I would agree that the EMS docs about the Ability Buffs hopefully make it clear that the buff is a constant +4. That adds questions about what empower or maximize will do (or if they even apply anymore) and IMO the EMS doc would be clearer without the editorializing about potions. But, the +4 part for the plain jane casting is okay.
Combust I agree that, ignoring the 10x editorial remark about Bioware's version, it describes what the EMS version will do.
Charm Person was just...slightly weird but there's no reason to think anything of significance changed outside of the stuff that was clear.
Meh. If the player assumes that the very first change listed either doesn't mean anything or doesn't mean anything he should worry about (so why is it in the docs?), then the rest is clear. To me, if the reader has to assume "the part of the doc I can't make sense of must not be important", then the doc lacks clarity. I agree that the problem here may be minor or irrelevant (possibly that EMS fixes a problem that Bioware also fixed, though it's tough to tell since the Bioware script has been the same for a while).
Continual Flame is unclear, I agree. On the flip side, given how it's a really stupid spell in the first place due to being prone to massive abuse and causing problems with IRL (can Continual Flame an item and then be unable to use it) I think that's a pretty minor matter and easily forgivable.
I agree with you that it's a spell subject to abuse. (I expect some of that could be dealt with by making appropriate adjustments to the item property cost 2DAs.) But, the fact that the spell is an abusable one doesn't make the EMS doc about changes to it any more clear.
Darkness is pretty straightforward except for the question of whether Ultravision/True Seeing pierces it. Of course, the default assumption is to assume it works correctly unless stated otherwise. And, in fact, now that I have EMS_Changes handy, searching for "Darkness" reveals this line:
"fix: Ultravision and True Seeing remove the 20% miss chance of Darkness"
So that clears that up.
It would if I believed it; I am not sure I do. This is similar to Evard's in that it raises questions about how it is scripted and whether it really works right. After all, there is no effect in NWN scripting that gives concealment-except-against-those-opponents-who-have-a-certain-spell-effect-or-item-effect. So, if I have true sight but the other PCs in the party or the henchmen do not, then what happens when we attack creatures inside the Darkness AoE? These questions might be answered by testing, but the docs don't answer them.
BTW, consider the above an aside. I take your point that the additional comment in the fix list does clarify what EMS thinks this spell should do and I agree that it does. Whether the spell actually works as described isn't necessarily a problem with the docs.
Flame Weapon is unclear in its own section, but looking at the "HotU Spells and Weapon Enhancement" section reveals that it (and Darkfire and so on) have been changed to actual damage on the weapon (meaning they won't stack with each other or damage of that type on the weapon already, can trigger things like Cleave, will be multiplied on a crit, etc). Could it be more explicit about the exact damage values? Sure, but it's not something that will change how you play and is pretty minor overall.
Fair enough.
So, overall, 18 of the first 20 entries are clear. 1 is unclear but who seriously uses that spell anyway? 1 is mostly clear but lacking exact values.
Obviously, as detailed above and before, I think that more than two of those descriptions would be unclear to most players. And, of course, unclear documentation of a spell people rarely use is still unclear documentation.
It is a term taken from Bioware. Here's the info at the top of the script for Terrifying Rage:
"Upon entering the aura of the creature the player must make a will save or be struck with fear because of the creatures presence.
- Save DC is a Intimidate check result of the raging character
- If the creature has less HitDice than the barbarian they freeze in terror 1d3 rounds
- if the creature has less HD than the BarbarianHD*2, they are shaken (-2 to attack, -2 to saves)
- if the creature has more than double HD than the Barb, they are immune to the effect"
That's why the wiki uses the term Shaken. There's where EMS gets the term Shaken.
So people who have played D&D know the term, people who have looked into Terrifying Rage on the wiki know the term, and people who have looked at the Terrifying Rage script know the term at a minimum. Of the remaining players, most are not going to be concerned in the first place (I mean, seriously, who even uses Scare?) or can easily look up the term if they care. You're making a mountain out of a molehill with Shaken.
Regarding "shaken": I am not transforming molehills to mountains; I agree this is a molehill and have not said it's a mountain. It's no more than a technical point about the EMS documentation for a spell that I rarely ever use. To provide examples that you asked for, I went through the first twenty items in the EMS and checked each to see if it would be clear to a player reading it to see what the spell changes were. Where I saw an issue, I noted it in that earlier post. The entry for Scare used a term that is not a standard NWN term, so I mentioned it as something that would be unclear to players. You seemed to think that "shaken" was a term that was not unclear because it was a Bioware term and a D&D term. I pointed out that it wasn't a term in the NWN docs and now you have pointed out that it is mentioned in the source code for the Scare script. That's why we have spent as much time on shaken as we have. I am not saying it is the paradigm of poor documentation or anything; it was merely one example among several of unclear documentation.
And, as far as it goes, it still a term that deserves explanation if it's going to be used. The reference to shaken in x2_s2_terrage_a.nss hardly qualifies as user documentation and it is mentioned nowhere in the NWN documentation Bioware provides. We can't expect players to look through the source code to understand what a term means. And, per above, the offhand mention in the wiki notes for an unrelated feat never treats shaken as a standard NWN term and only defines it indirectly anyway.
Furthermore, I really don't understand your position now -- it seems to be the following:
"I am very familiar with NWN and it's mechanics to the point where I know obscure terms and maybe 1-3% of EMS isn't clear for me, if that. However, since other people less familiar with NWN may be confused by EMS, despite the fact most of them will just play it and not care, I will refuse to use EMS on general principle since I think the documentation for a small minority of spells (like 10-15%) should be better than it is...even though I still understand 80-90% of that 10-15% just fine anyway."
I don't get it.
Except that I never said much of that. Some of the confusion stems from there being two issues here. One is that I chose not to use EMS because the poor documentation put me off of it when I first played Aielund. The other is our disagreement about whether EMS is poorly documented.
For one thing, I don't refuse to use EMS on general principle. I said that the poor documentation was the reason I chose to turn it off the first time I played Aielund. (It's slightly more complicated than that, but it was a significant factor.) I was playing MP and had limited opportunity to stop and experiment to see what EMS was doing. And, by the end of the run, not encountering any show-stopping problems without EMS, I didn't use it the next time I played. Both times I had fun playing the module. I have said that I might use EMS for a play-through at some point in the future. But, I have only completed two playthroughs of Aielund, so, for those playthroughs, I didn't use EMS and I never looked back and regretted not using it.
Second, we ended up digging into the minutia on what I consider to be some poorly documented changes even though I think I can make pretty reasonable assumptions about what most of it means. Why have we spent so much time discussing this? Possibly because of different ideas of what a poorly documented change is. I complained that some of the potential improvements were poorly documented and you seemed to be arguing that 95% of them were perfectly clearly documented. In fact, I said, "I disagree with the '95% perfectly clear' number." Once such a strong claim was on the table, we were off to the races. :-)
Anyway, that may all have been a misunderstanding. To me, documentation for a spell system should be written to be clear for the typical player who wants to know what's going on when his wizard casts a spell. IMO, there are plenty of examples in the EMS doc where a typical player will not know how the spell is changed from the Bioware version or what the EMS version does. To me, those spell changes are poorly documented. You have noted that most players won't care, and I am not disagreeing. But, people not caring about X doesn't mean that X is clear. Honestly, we wouldn't have had this discussion (or much of it) if you had instead said, "If you're as interested in the mechanics of the spells as you seem to be, then you can probably figure out what most of those spell changes in the EMS doc mean, whether they are well documented or not." It was the notion that the spell change documentation was so clear that I was disagreeing with.
