Author Topic: Spell Begin/End Scripts  (Read 1080 times)

Offline Paul R. Stevens

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2236
Spell Begin/End Scripts
« on: November 13, 2016, 08:16:12 PM »
It would appear that Spell Begin/End Scripts are not
being executed in all cases.  In particular:

An 'Entangle' spell in combat causes a lingering effect
on the battlefield; a green, wavering effect that covers
about 10 squares.  A friendly PC ran into the effect a few
moves later and then the combat ended.  Neither the
'Spell Begin Script' nor the 'Spell End Script' was
executed.

But this brings a question to mind.  There are several events
that can take place for such a spell with battlefield lingering
effects: (not necessarily in this order)

a) The caster casts the spell and the lingering effect is established.
b) A combatant is affected by the lingering effect and a spell
effect is applied to the combatant.
c) A combatant with an active spell effect is again affected by the
lingering effect.
d) The spell effect on a combatant wears off.
e) The battlefield lingering effect expires.
f) Combat ends

Which of these events should trigger the Begin and End scripts?
One requirement is absolute:  Each 'Begin' must be matched one-to-
one with an 'End'.

I anticipate that there will be questions about what this all means.
It could be complicated.

The simplest rule I can think of would
be that the 'Begin' script is executed when the spell is cast and
the 'End' script is run when the battlefield lingering effect expires.
The Begin/End would be run only once for each time the
spell is cast.

A more complicated rule might be that the Begin Script
is executed when a spell effect is applied to a combatant
and the End Script is executed when that Spell Effect expires.
For spells with no long-term effects, the End script would be
run immediately after the Begin Script.  A Begin/End script
would be run once for each combatant that suffers the effect
of the lingering Spell.

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #1 on: November 14, 2016, 01:24:31 PM »
I probably will have some questions along the way, but I understand what you are asking and positing.

I am not sure that I knew that if a spell had a Begin script that it must also have an End script. If I did know this, I did not write it down anywhere in my notes, nor comb through the databases to make sure that I had done this.

Too further complicate matters, we have multiple kinds of lingering effets, namely lingering that only effects once and lingering that effects again at the start of each round. I think that DC likely handles the resolution the same way, but I am nost sure.
Additioinally, there are lingers that are scripted events, so not actual "Lingering" effects, but in my mind I have failed to differentiate between them as to how I might use Begin?End scripts.
Also, we have Aura effects. These are only handled through scripting, so not the same as the "Lingering" effects one can mark in the spell editor.

Honestly, I am fine with the simple method or the more complicated method. I say we use the simple method unless someone can show why we can't :) I really need to go through the database and pick a method and convert all like things to that method. In an ideal world, I would actually just start from scratch and write it all in one version of DC. :D


Offline Milos Gulan

  • Hero Member
  • *****
  • Posts: 3173
Re: Spell Begin/End Scripts
« Reply #2 on: November 14, 2016, 01:32:29 PM »
(Edit: I started typing this before Mankius answered)

Ok I don't know much about scripting yet so I can't help that much, but I have looked at PHB and 1e spell is different from 2e version. Effect lasts 1 minute per level and victim needs to save vs dexterity to be free.

So about the script I think it should be first option, it starts when spell starts and ends when duration is off. If someone gets caught it lasts until he breaks free it means he throws dex check first without penalty then every round at -5 either on Str on Dex.

I would like to see 2e version of the spell too :) but it seems there will be a lot of work to get things in order :D

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #3 on: November 14, 2016, 01:44:21 PM »
(Edit: I started typing this before Mankius answered)

Ok I don't know much about scripting yet so I can't help that much, but I have looked at PHB and 1e spell is different from 2e version. Effect lasts 1 minute per level and victim needs to save vs dexterity to be free.

So about the script I think it should be first option, it starts when spell starts and ends when duration is off. If someone gets caught it lasts until he breaks free it means he throws dex check first without penalty then every round at -5 either on Str on Dex.

I would like to see 2e version of the spell too :) but it seems there will be a lot of work to get things in order :D

This is not at all what we are talking about. Paul is asking about the way DC handles certain scripts, and actually has nothing to do with Dungeons & Dragons or any version there of. ;)

Offline Paul R. Stevens

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2236
Re: Spell Begin/End Scripts
« Reply #4 on: November 14, 2016, 02:41:30 PM »
Quote
I am not sure that I knew that if a spell had a Begin script that it must also have an End script.

Oooops....I may have stated this badly.

What I meant to say was that the engine must ATTEMPT to execute
the scripts in pairs.  Not that the scripts must actually exist in pairs.
The designer is free to create a begin script without an end script or
vise versa.

So in my question, we must demand that the engine runs the scripts
in pairs if such pairs are provided by the designer.

Have I said that in a way that is clear?

Offline Milos Gulan

  • Hero Member
  • *****
  • Posts: 3173
Re: Spell Begin/End Scripts
« Reply #5 on: November 14, 2016, 03:11:05 PM »
I think so :) and yes sorry for me not knowing things again :)

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #6 on: November 14, 2016, 03:19:17 PM »
Paul, that makes sense. If the designer has given us both scripts, then DC should (maybe even must) treat them as a pair.

Offline Paul R. Stevens

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2236
Re: Spell Begin/End Scripts
« Reply #7 on: November 14, 2016, 03:38:00 PM »
Quote
If the designer has given us both scripts, then DC .... must....treat them as a pair.

Quite right.  And this means that an End Script must be
run before a spell ends if combat ends.  It is a very minor point
and not likely to confuse anyone.  But it could conceivably
cause a problem if not understood. 

In fact, this is exactly what occurred in the bug report by
Milos Gulan and in which the engine itself got confused.

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #8 on: November 14, 2016, 03:43:48 PM »
When exact outcome of this issue is decided, I will ;put an explanatory note in the spells database.

Offline Nol Drek

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2186
    • Nol Drek's Web Site
Re: Spell Begin/End Scripts
« Reply #9 on: November 14, 2016, 08:41:58 PM »
But this brings a question to mind.  There are several events
that can take place for such a spell with battlefield lingering
effects: (not necessarily in this order)

a) The caster casts the spell and the lingering effect is established.
b) A combatant is affected by the lingering effect and a spell
effect is applied to the combatant.
c) A combatant with an active spell effect is again affected by the
lingering effect.
d) The spell effect on a combatant wears off.
e) The battlefield lingering effect expires.
f) Combat ends

I think you have this quite right. I can think of four pairs of situations for which Begin/End Scripts might need to be run.

OnStartCombat: <begin>
OnEndCombat: <end>

OnLingeringSpellCast: <begin>
OnLingeringSpellWearsOff: <end>

OnSpellEffectAppliedToCombatant: <begin>
OnSpellEffectWearsOffOfCombatant: <end>

OnStartCombatantTurnWithASpellInEffect: <begin>
OnEndCombatantTurnWithASpellInEffect: <end>
"Into the Drachensgrab Mountains!"

http://www.noldrek.com

Offline Paul R. Stevens

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2236
Re: Spell Begin/End Scripts
« Reply #10 on: November 14, 2016, 09:06:26 PM »
Nol, I rather agree with your assessment.  Except that
OnStartCombat and OnEndCombat are outside the current
discussion.

The other three situations make perfect sense.

The unfortunate facts are that we currently have
'BeginSpellScript' and 'EndSpellScript' implemented.
We cannot go back and remove these; they must remain
and do what they already do.  What is it that they do?
Good question.  I think they are  equivalent to your
SpellEffect[AppliedTo|WearsOffOf]Combatant.
We could certainly rename them.

If you read the Help.txt file in the UAF Editor Resources
folder, you can see what we say about these scripts.

I would be willing to add the OnLingeringSpell[Cast|WearsOff]
if someone (you, perhaps?) would promise to do the
testing.  This would require a change to the game data
file format and is therefore more tricky to make backward
compatible.

We could decide not to do any scripts at the time a lingering
spell is cast.  The Begin and End scripts would only run when the
effects of the lingering spell are applied or removed from a
combatant.  I rather like this idea.

I could add the On[Start|End]CombatantTurnWithASpellEffect
without changing the game data format and without worrying about
backward compatibility.  It is not totally clear to me what a 'Turn'
might be, however.  There are free attacks when an opponent
moves into or out of a combatant's vicinity and sometimes these
consume a turn and sometimes not.  I know these rules confuse
me. 

Well, Let us continue the discussion until we can get a good handle
on all of this.

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #11 on: November 15, 2016, 01:47:03 PM »
I am not opposed to the adding of any Hooks, but it seems that much of what these new pairs would do is already at least partly handled in the AURA Hooks.
I would prefer that if we need pairs of Hooks, that we try to utilize existing Hooks as part of the pairs..

Offline Nol Drek

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2186
    • Nol Drek's Web Site
Re: Spell Begin/End Scripts
« Reply #12 on: November 15, 2016, 09:13:27 PM »
Do the AURA hooks create/remove a lingering effect such as "Stinking Cloud"? If so, then that eliminates the pair which makes backwards compatibility difficult.

Reading the "Help.txt" file in the EditorResources folder helps but raises some questions:
When a spell is cast, the 4th thing that happens is the "Spell Begin Script" executes. Does this script execute exactly once? Does it execute even if the spell is cast on an area of the field of battle where there are no combatants? Does it execute once for each combatant who is within the area of effect of the spell?

As I'm using the word in the current context, a Turn is a unit of time. Each combatant should get one Turn in each Round of combat. If there are N combatants on the field of battle, then One Round of combat = N Turns. Some combatants won't be able to do anything during their Turn (due to being immobilized or paralyzed by a spell for example), but they should still get a Turn (which ends immediately after it begins). I'm thinking of something like Shambling Mound Engulf (the combatant takes damage at the start of their Turn because they are currently being enveloped in a giant pile of garbage and can't breathe).
"Into the Drachensgrab Mountains!"

http://www.noldrek.com

Offline Paul R. Stevens

  • Dungeon Craft Tester
  • Hero Member
  • ***
  • Posts: 2236
Re: Spell Begin/End Scripts
« Reply #13 on: November 16, 2016, 09:52:51 AM »
Nol:

Things are rather complicated.  What with [Non-]Cumulative,
Saving throws, etc.  Generally, the [Begin|End] scripts
run when a particular target is affected by a spell.

I would like to document these things rather completely and
precisely.  Could we do the following:

Someone create a mini-mod for a particular spell of interest.
Start with a simple(?) case with instantaneous effect like "ReduceHP10".
I will actually step through the code and document the entire
process.  You will read what I write and see that questions
arise.  You will make another mini-mod to answer those questions.
We will repeat until all interested parties think they have the
information they need.  As we proceed, we will also be able to modify
the engine if it is doing things incorrectly or is not doing what is
most helpful.

It would be nice if this documentation could be included in the
"Help.txt" file and would therefore be available in the editor
at the time a spell is being created.

Offline manikus

  • Skriptor
  • Administrator
  • Hero Member
  • *****
  • Posts: 9863
Re: Spell Begin/End Scripts
« Reply #14 on: November 16, 2016, 03:46:40 PM »
I don't have a Help.txt file in my Editor Resources. :( I will fix that.

AURA Hooks can be used to apply and remove lingering efforts. Among other things. I think that if one were so inspired, they could redo all spells and monster effects with AURA, but this is not terribly user-friendly for non-scripters.

Let me download and read the Help.txt file, and then I can be completely up on the conversation.

edited to add:

Is this the file?
http://www.dianneandpaul.net/UAF/Help.txt
« Last Edit: November 16, 2016, 03:57:27 PM by manikus »

 

anything