EffectsGroup scope = Source

Programmers discuss here anything related to FreeOrion programming. Primarily for the developers to discuss.

Moderator: Committer

Post Reply
Message
Author
flaviojs
Krill Swarm
Posts: 12
Joined: Sat Jul 07, 2018 7:24 pm

EffectsGroup scope = Source

#1 Post by flaviojs » Sat Jul 07, 2018 8:02 pm

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?

User avatar
Dilvish
AI Lead, Programmer
Posts: 4688
Joined: Sat Sep 22, 2012 6:25 pm

Re: EffectsGroup scope = Source

#2 Post by Dilvish » Sat Jul 07, 2018 8:43 pm

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.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

flaviojs
Krill Swarm
Posts: 12
Joined: Sat Jul 07, 2018 7:24 pm

Re: EffectsGroup scope = Source

#3 Post by flaviojs » Sat Jul 07, 2018 10:13 pm

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?

User avatar
Dilvish
AI Lead, Programmer
Posts: 4688
Joined: Sat Sep 22, 2012 6:25 pm

Re: EffectsGroup scope = Source

#4 Post by Dilvish » Sat Jul 07, 2018 10:55 pm

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.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

flaviojs
Krill Swarm
Posts: 12
Joined: Sat Jul 07, 2018 7:24 pm

Re: EffectsGroup scope = Source

#5 Post by flaviojs » Sun Jul 08, 2018 2:40 pm

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?

User avatar
Dilvish
AI Lead, Programmer
Posts: 4688
Joined: Sat Sep 22, 2012 6:25 pm

Re: EffectsGroup scope = Source

#6 Post by Dilvish » Sun Jul 08, 2018 4:44 pm

flaviojs wrote: so maybe put a note there?
I've made a few adjustments there now.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

Ophiuchus
Vacuum Dragon
Posts: 510
Joined: Tue Sep 30, 2014 10:01 am

Re: EffectsGroup scope = Source

#7 Post by Ophiuchus » Sun Jul 08, 2018 8:36 pm

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
  ]}
Any code or patches in anything posted here is released under the CC and GPL licences in use for the FO project.

User avatar
Dilvish
AI Lead, Programmer
Posts: 4688
Joined: Sat Sep 22, 2012 6:25 pm

Re: EffectsGroup scope = Source

#8 Post by Dilvish » Sun Jul 08, 2018 11:25 pm

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 \\
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

Post Reply