Page 1 of 1

EffectsGroup scope = Source

Posted: Sat Jul 07, 2018 8:02 pm
by flaviojs
I'm trying to fully understand how EffectsGroup is used.

From what I understood, scope is required and selects the targets that the EffectsGroup will affect.

Looking at focs files I see scope = Source all over the place.
I don't understand what it means when selecting targets...
if it means all targets, then shouldn't scope be optional (keeping all targets when missing, the most common case) or use a truth value?

Re: EffectsGroup scope = Source

Posted: Sat Jul 07, 2018 8:43 pm
by Dilvish
The Source is always a single object. Which particular object depends on the kind of content the script is specifying. Have you reviewed our Scripting Tutorial and Scripting Details pages? The latter has a section specifically talking about what object serves as the Source for different types of content.

So hopefully that clears up the idea that

Code: Select all

scope=Source
might match all objects. Did you perhaps get mixed up with the fact that the starting set of objects that the scope condition gets applied to is all objects? The scope clause that would just stick with that would be

Code: Select all

scope = All
and while conceivably that could be set as a default scope, I think it was deemed that there are probably not any effects whose proper scope really would be so broad, and so it would be probably useless and even misleading to make that a default scope.

As far as why "scope = Source" wasn't chosen as a default scope, while it is a common choice, I think it was deemed important to have the clarity of always making the scope explicit.

Re: EffectsGroup scope = Source

Posted: Sat Jul 07, 2018 10:13 pm
by flaviojs
I did review both of those pages before creating this post, but they did not clarify what 'scope = Source' could match, at least for me (someone that is new to it)...
Maybe it's just a matter of getting used to the syntax, which apparently is non-intuitive to me.

You imply that it does not match all... then does it make the source of the EffectsGroup the only possible target match?

Re: EffectsGroup scope = Source

Posted: Sat Jul 07, 2018 10:55 pm
by Dilvish
flaviojs wrote:then does it make the source of the EffectsGroup the only possible target?
Right. The scope is specified by a Condition, and the Condition named "Source" only matches the Source object. I've tried to clarify things a bit more on the Scripting Details page by adding a forward reference to the Conditions section from the section talking about using Source, Target, etc as part of ValueRefs.

Re: EffectsGroup scope = Source

Posted: Sun Jul 08, 2018 2:40 pm
by flaviojs
Thank you.

This is probably only helpful to beginners, but I just realized it becomes easier to figure out if I try to read it with human language...
"activation" can be read as "is active/enabled when the source is ..."
"scope" can be read as "the targets are ..."

I paid more attention to the EffectsGroup Specification before creating this post, so maybe put a note there?

Re: EffectsGroup scope = Source

Posted: Sun Jul 08, 2018 4:44 pm
by Dilvish
flaviojs wrote: so maybe put a note there?
I've made a few adjustments there now.

Re: EffectsGroup scope = Source

Posted: Sun Jul 08, 2018 8:36 pm
by Ophiuchus
Dilvish wrote:
flaviojs wrote: so maybe put a note there?
I've made a few adjustments there now.
How about something like the following

Code: Select all

  description = "DESCRIPTION" [optional -- may be left out]
  scope = CONDITION [defines targets to apply effects for] 
  activation = CONDITION [optional condition on Source -- omission defaults to always trigger effects]
  stackinggroup = "STACKINGGROUP" [optional -- may be left out]
  accountinglabel = "ACCOUNTINGLABEL" [optional -- may be left out]
  priority = PRIORITY [optional -- omission defaults to 100]
  effects = {EFFECT|[
      EFFECT
      EFFECT
      EFFECT
  ]}

Re: EffectsGroup scope = Source

Posted: Sun Jul 08, 2018 11:25 pm
by Dilvish
How about something like the following
Since the syntax already has a functional use for square brackets, I'm not a fan of trying to use them to indicate comments, I'd much rather see comments simply set off by \\