Difference between revisions of "FOCS Scripting Tutorial"

From FreeOrionWiki
Jump to: navigation, search
(Step 1: What is your tech?)
(Formatting (no [code] tags in wiki), and link to examples page)
Line 25: Line 25:
 
You’ll need to fill out the “fields” in the form.  Since “Drek’s Effects Turorial” is a technology, I’ll be filling out the technology XML form:
 
You’ll need to fill out the “fields” in the form.  Since “Drek’s Effects Turorial” is a technology, I’ll be filling out the technology XML form:
  
[code]
+
 
<Tech>
+
  <Tech>
 
       <name>NAME</name>
 
       <name>NAME</name>
 
       <description>DESCRIPTION</description>
 
       <description>DESCRIPTION</description>
Line 47: Line 47:
 
       EFFECTS_GROUP [optional]
 
       EFFECTS_GROUP [optional]
 
   </Tech>
 
   </Tech>
[/code]
+
 
  
 
NAME:  this a placeholder for the name of your technology.  The actual name of your technology will go into a “string table”, so you should just type out, in all caps without using spaces, a pithy name.
 
NAME:  this a placeholder for the name of your technology.  The actual name of your technology will go into a “string table”, so you should just type out, in all caps without using spaces, a pithy name.
[code]
+
 
<Tech>
+
    <Tech>
  <name>LEARN_DREK_TUTORIAL</name>
+
        <name>LEARN_DREK_TUTORIAL</name>
[/code]
+
 
 
DESCRIPTION:  this is another placeholder, this time for the description of your technology.  Type out the same pithy name you did in the previous field, but this time append the word “DESC”.    You’ll be writing out the actual description later.
 
DESCRIPTION:  this is another placeholder, this time for the description of your technology.  Type out the same pithy name you did in the previous field, but this time append the word “DESC”.    You’ll be writing out the actual description later.
[code]
+
 
  <description>LEARN_DREK_TUTORIAL_DESC</description>
+
  <description>LEARN_DREK_TUTORIAL_DESC</description>
[/code]
+
 
 
TYPE: This is the type of technology.  In FreeOrion, there are three different types of techs:
 
TYPE: This is the type of technology.  In FreeOrion, there are three different types of techs:
 
* TT_THEORY  A theory.  A theory contains applications, and generally should have little or no effects.
 
* TT_THEORY  A theory.  A theory contains applications, and generally should have little or no effects.
Line 65: Line 65:
 
For the Type field, you’ll need to type in one of the above types.  Most techs (esp. techs that actually do things) should be Applications.   
 
For the Type field, you’ll need to type in one of the above types.  Most techs (esp. techs that actually do things) should be Applications.   
  
[code]
+
    <type>TT_APPLICATION</type>
  <type>TT_APPLICATION</type>
+
[/code]
+
  
 
CATEGORY: There are five categories that “hold” techs in FreeOrion.  You need to assign your technology to one of them.  Note, that an application or refinement should be in the same category as it’s parent theory.
 
CATEGORY: There are five categories that “hold” techs in FreeOrion.  You need to assign your technology to one of them.  Note, that an application or refinement should be in the same category as it’s parent theory.
Line 81: Line 79:
 
The technology I’m developing clearly falls into the Learning Category.
 
The technology I’m developing clearly falls into the Learning Category.
  
[code]
+
  <category>LEARNING_CATEGORY</category>
  <category>LEARNING_CATEGORY</category>
+
[/code]
+
  
 
RESEARCH_COST:  The number of research points a player needs to spend each turn to research a tech.
 
RESEARCH_COST:  The number of research points a player needs to spend each turn to research a tech.
Line 90: Line 86:
 
In FO, all techs cost X RP for Y Turns to research.  The numbers are still being decided as of this writing, for now assume a low level tech takes around 10 RP for 5 Turns to research.
 
In FO, all techs cost X RP for Y Turns to research.  The numbers are still being decided as of this writing, for now assume a low level tech takes around 10 RP for 5 Turns to research.
  
[code]
+
    <research_cost>10</research_cost>
  <research_cost>10</research_cost>
+
    <research_turns>5</research_turns>
  <research_turns>5</research_turns>
+
[/code]
+
  
 
PREREQUISITES: The techs required before research can start.  An application should always have its parent theory as a prerequisite.  You’ll need to read up on the forums to determine the current state of the tech tree in order to pick out some proper prerequisites for your tech.
 
PREREQUISITES: The techs required before research can start.  An application should always have its parent theory as a prerequisite.  You’ll need to read up on the forums to determine the current state of the tech tree in order to pick out some proper prerequisites for your tech.
Line 101: Line 95:
 
Let’s say the Theory of Drek is the parent theory for my technology:
 
Let’s say the Theory of Drek is the parent theory for my technology:
  
[/code]
+
    <prerequisites>
  <prerequisites>
+
        LEARN_THEORY_OF_DREK
    LEARN_THEORY_OF_DREK
+
    </prerequisites>
  </prerequisites>
+
[/code]
+
  
 
UNLOCKED_ITEMS: In the field, you’d type of the pithy names for all of the buildings your technology unlocks.  An unlocked building can be constructed by a player on a planet.
 
UNLOCKED_ITEMS: In the field, you’d type of the pithy names for all of the buildings your technology unlocks.  An unlocked building can be constructed by a player on a planet.
Line 113: Line 105:
 
My tech doesn’t unlock a building, so *poof* I pressed delete and got rid of that section.  But let’s say you did want to unlock a couple of buildings, the Tower of Babel and the Great Pyramids, for example:
 
My tech doesn’t unlock a building, so *poof* I pressed delete and got rid of that section.  But let’s say you did want to unlock a couple of buildings, the Tower of Babel and the Great Pyramids, for example:
  
[code]
+
 
 
   <unlocked_items>
 
   <unlocked_items>
 
     <Item>
 
     <Item>
Line 124: Line 116:
 
     </Item>
 
     </Item>
 
   </unlocked_items>
 
   </unlocked_items>
[/code]
 
  
 
Notice how each item to unlock has its own little item XML markups.  You’d then have to define these two buildings, in much the same way techs are defined.
 
Notice how each item to unlock has its own little item XML markups.  You’d then have to define these two buildings, in much the same way techs are defined.
Line 130: Line 121:
 
So far my tech looks like this:
 
So far my tech looks like this:
  
[code]
+
  <Tech>
<Tech>
+
 
       <name>LEARN_DREK_TUTORIAL</name>
 
       <name>LEARN_DREK_TUTORIAL</name>
 
       <description>LEARN_DREK_TUTORIAL_DESC</description>
 
       <description>LEARN_DREK_TUTORIAL_DESC</description>
Line 143: Line 133:
 
       EFFECTS_GROUP [optional]
 
       EFFECTS_GROUP [optional]
 
   </Tech>
 
   </Tech>
[/code]
+
 
  
 
=Step 3: The Defining the Effects Groups=
 
=Step 3: The Defining the Effects Groups=
Line 157: Line 147:
 
Just like techs, Effects Groups have an XML form that you need to fill out.  Here it is:
 
Just like techs, Effects Groups have an XML form that you need to fill out.  Here it is:
  
[code]
+
  <EffectsGroup>
<EffectsGroup>
+
 
       <scope>SCOPE</scope>
 
       <scope>SCOPE</scope>
 
       <activation>ACTIVATION</activation>
 
       <activation>ACTIVATION</activation>
Line 168: Line 157:
 
           EFFENTN
 
           EFFENTN
 
       </effects>
 
       </effects>
</EffectsGroup>
+
  </EffectsGroup>
[/code]
+
  
 
SCOPE  This field defines what objects in the game are influenced by your technology.  My tech operates on “all friendly worlds set to Primary/Secondary Science Focus”.  Most techs should constrain their effects to worlds set to a particular focus, or environment, or whatever.
 
SCOPE  This field defines what objects in the game are influenced by your technology.  My tech operates on “all friendly worlds set to Primary/Secondary Science Focus”.  Most techs should constrain their effects to worlds set to a particular focus, or environment, or whatever.
Line 175: Line 163:
 
First off, we need to pick out all friendly worlds.  We can do that with the EmpireAffiliation condition:
 
First off, we need to pick out all friendly worlds.  We can do that with the EmpireAffiliation condition:
  
[code]
 
 
   <Condition::EmpireAffiliation>
 
   <Condition::EmpireAffiliation>
 
       <empire_id>Source.Owner</empire_id>
 
       <empire_id>Source.Owner</empire_id>
Line 181: Line 168:
 
       <exclusive>1</exclusive>
 
       <exclusive>1</exclusive>
 
   </Condition::EmpireAffiliation>
 
   </Condition::EmpireAffiliation>
[/code]
 
  
 
Notice I filled out empire_id with source.owner.  This is a variables...there are many variables you can access, listed in the Effects document.
 
Notice I filled out empire_id with source.owner.  This is a variables...there are many variables you can access, listed in the Effects document.
Line 191: Line 177:
 
When FreeOrion executes this empire affiliation condition, it will pick out all of the objects in the game owned by your empire.  This includes space ships and buildings...but we are only concerned with the planets.  So, I need to add another condition to the mix—the Type condition.
 
When FreeOrion executes this empire affiliation condition, it will pick out all of the objects in the game owned by your empire.  This includes space ships and buildings...but we are only concerned with the planets.  So, I need to add another condition to the mix—the Type condition.
  
[code]
 
 
   <Condition::Type>OBJ_POP_CENTER</Condition::Type>
 
   <Condition::Type>OBJ_POP_CENTER</Condition::Type>
[/code]
 
  
 
This is yet another enumeration form here.  Now, all population centers will be selected, including any future space based colonies that are not on planets.
 
This is yet another enumeration form here.  Now, all population centers will be selected, including any future space based colonies that are not on planets.
Line 199: Line 183:
 
We need to glue these two conditions together.  For that, we use the And condition:
 
We need to glue these two conditions together.  For that, we use the And condition:
  
[code]
 
 
   <Condition::And>
 
   <Condition::And>
 
     <Condition::EmpireAffiliation>
 
     <Condition::EmpireAffiliation>
Line 208: Line 191:
 
     <Condition::Type>OBJ_POP_CENTER</Condition::Type>
 
     <Condition::Type>OBJ_POP_CENTER</Condition::Type>
 
   </Condition::And>
 
   </Condition::And>
[/code]
 
  
 
Pretty cool, huh?  By sticking our conditions into an And XML field, we are saying that we want FreeOrion to pick out everything that’s both owned by our empire and a population center.   
 
Pretty cool, huh?  By sticking our conditions into an And XML field, we are saying that we want FreeOrion to pick out everything that’s both owned by our empire and a population center.   
Line 216: Line 198:
 
First, let’s select all worlds that have the primary science focus, using the focustype condition:
 
First, let’s select all worlds that have the primary science focus, using the focustype condition:
  
[code]
+
  <Condition::Focus>
<Condition::Focus>
+
 
       <primary>1</primary>
 
       <primary>1</primary>
 
       <FocusType>FOCUS_RESEARCH</FocusType>
 
       <FocusType>FOCUS_RESEARCH</FocusType>
</Condition::FocusType>
+
  </Condition::FocusType>
[/code]
+
  
 
I filled out the primary field with a 1, meaning “true”.  This will select all worlds with a Primary focus in science.  Note that it really will select ALL worlds, including those of enemy empires.
 
I filled out the primary field with a 1, meaning “true”.  This will select all worlds with a Primary focus in science.  Note that it really will select ALL worlds, including those of enemy empires.
Line 231: Line 211:
 
Now the two statements need to be glued together.  Since the effect works on Secondary *or* Primary focus, use the condition Or:
 
Now the two statements need to be glued together.  Since the effect works on Secondary *or* Primary focus, use the condition Or:
  
[code]
+
  <Condition::Or>
<Condition::Or>
+
      <Condition::Focus>
  <Condition::Focus>
+
      <primary>1</primary>
+
      <FocusType>FOCUS_RESEARCH</FocusType>
+
  </Condition::FocusType>
+
  <Condition::Focus>
+
      <primary>1</primary>
+
      <FocusType>FOCUS_RESEARCH</FocusType>
+
  </Condition::FocusType>
+
</Condition::Or>
+
[/code]
+
 
+
Finally, to complete our scope field, we need to glue both pieces together.  Just insert the Or condition into the And condition:
+
 
+
[code]
+
<scope> 
+
  <Condition::And>
+
    <Condition::EmpireAffiliation>
+
        <empire_id>Source.Owner</empire_id>
+
        <affiliation>AFFIL_SELF</affiliation>
+
        <exclusive>1</exclusive>
+
    </Condition::EmpireAffiliation>
+
    <Condition::Type>OBJ_POP_CENTER</Condition::Type>
+
    <Condition::Or>
+
      <Condition::Focus>
+
 
         <primary>1</primary>
 
         <primary>1</primary>
 
         <FocusType>FOCUS_RESEARCH</FocusType>
 
         <FocusType>FOCUS_RESEARCH</FocusType>
      </Condition::FocusType>
+
      </Condition::FocusType>
      <Condition::Focus>
+
      <Condition::Focus>
 
         <primary>1</primary>
 
         <primary>1</primary>
 
         <FocusType>FOCUS_RESEARCH</FocusType>
 
         <FocusType>FOCUS_RESEARCH</FocusType>
      </Condition::FocusType>
+
      </Condition::FocusType>
    </Condition::Or>
+
  </Condition::Or>
   </Condition::And>
+
 
</scope>
+
Finally, to complete our scope field, we need to glue both pieces together.  Just insert the Or condition into the And condition:
[/code]
+
 
 +
   <scope> 
 +
    <Condition::And>
 +
      <Condition::EmpireAffiliation>
 +
        <empire_id>Source.Owner</empire_id>
 +
        <affiliation>AFFIL_SELF</affiliation>
 +
        <exclusive>1</exclusive>
 +
      </Condition::EmpireAffiliation>
 +
      <Condition::Type>OBJ_POP_CENTER</Condition::Type>
 +
      <Condition::Or>
 +
        <Condition::Focus>
 +
          <primary>1</primary>
 +
          <FocusType>FOCUS_RESEARCH</FocusType>
 +
        </Condition::FocusType>
 +
        <Condition::Focus>
 +
          <primary>1</primary>
 +
          <FocusType>FOCUS_RESEARCH</FocusType>
 +
        </Condition::FocusType>
 +
      </Condition::Or>
 +
    </Condition::And>
 +
  </scope>
  
 
Notice, you can nest And/Or conditions.  We are saying:
 
Notice, you can nest And/Or conditions.  We are saying:
Line 277: Line 253:
 
Notice that everything above is contained by the scope XML field of the Effects Group.  Now, we need to fill out the activation field.
 
Notice that everything above is contained by the scope XML field of the Effects Group.  Now, we need to fill out the activation field.
  
[code]
 
 
   <activation>
 
   <activation>
 
     <Condition::Self/>
 
     <Condition::Self/>
 
   <activeation>
 
   <activeation>
[/code]
 
  
 
The activation field is a universe that consists only of the object’s owner.  You use the same conditions as the scope field—if any object is selected by the condition, then the effect fires.  This is useful is you don’t want an effects group to fire under certain conditions.  For example, for a building we could test it’s planet’s environment.  We could set up a condition to test if the planet is Barren, or whatever.
 
The activation field is a universe that consists only of the object’s owner.  You use the same conditions as the scope field—if any object is selected by the condition, then the effect fires.  This is useful is you don’t want an effects group to fire under certain conditions.  For example, for a building we could test it’s planet’s environment.  We could set up a condition to test if the planet is Barren, or whatever.
Line 289: Line 263:
 
Next, the stacking group:
 
Next, the stacking group:
  
[code]
 
 
   <stacking_group>STACK_DREK_TUTORIAL</stacking_group>
 
   <stacking_group>STACK_DREK_TUTORIAL</stacking_group>
[/code]
 
  
 
Stacking groups are mostly for buildings.  If you have two buildings in the same solar system that both effect every planet in the solar system, you’d only want one building’s effects to fire.  That’s more or less what the stacking group is for.
 
Stacking groups are mostly for buildings.  If you have two buildings in the same solar system that both effect every planet in the solar system, you’d only want one building’s effects to fire.  That’s more or less what the stacking group is for.
Line 299: Line 271:
 
Now, the payload, the actual effects:
 
Now, the payload, the actual effects:
  
[code]
+
  <effects>
<effects>
+
    <Effect::SetMeter>
  <Effect::SetMeter>
+
 
       <meter>METER_RESEARCH</meter>
 
       <meter>METER_RESEARCH</meter>
 
       <value>Target.MaxResearch+2</value>
 
       <value>Target.MaxResearch+2</value>
 
       <max>1</max>
 
       <max>1</max>
  </Effect::SetMeter>
+
    </Effect::SetMeter>
</effects>   
+
  </effects>   
[/code]
+
  
 
My tech has only one effect...but you can include as many effects as you need.  
 
My tech has only one effect...but you can include as many effects as you need.  
Line 319: Line 289:
 
Our tech is mostly finished.  When we slide the Effects group into it’s proper slot, the whole thing looks like this:
 
Our tech is mostly finished.  When we slide the Effects group into it’s proper slot, the whole thing looks like this:
  
[code]
+
  <Tech>
<Tech>
+
 
       <name>LEARN_DREK_TUTORIAL</name>
 
       <name>LEARN_DREK_TUTORIAL</name>
 
       <description>LEARN_DREK_TUTORIAL_DESC</description>
 
       <description>LEARN_DREK_TUTORIAL_DESC</description>
Line 361: Line 330:
 
         </effects>
 
         </effects>
 
       </EffectsGroup>
 
       </EffectsGroup>
</Tech>
+
  </Tech>
[/code]
+
  
 
As you’ve probably noticed, the scope condition is the longest and toughest part to write.  
 
As you’ve probably noticed, the scope condition is the longest and toughest part to write.  
Line 380: Line 348:
 
It can be pretty simple:
 
It can be pretty simple:
  
[code]
+
LEARN_DREK_TUTORIAL
LEARN_DREK_TUTORIAL
+
Drek’s Effects Tutorial
Drek’s Effects Tutorial
+
LEARN_DREK_TUTORIAL_DESC
 
+
A marvelous, high tech tutorial that enlightens all who read it. /n Effect: +2 Max Science to all friendly worlds set to the Science Focus.
LEARN_DREK_TUTORIAL_DESC
+
A marvelous, high tech tutorial that enlightens all who read it. /n Effect: +2 Max Science to all friendly worlds set to the Science Focus.
+
[/code]
+
  
 
Notice the /n, for a “newline.”  There’s other pieces of formatting you can use, see the faq for details.
 
Notice the /n, for a “newline.”  There’s other pieces of formatting you can use, see the faq for details.
Line 394: Line 359:
 
==Appendix: Additional Examples==
 
==Appendix: Additional Examples==
  
(Forthcoming)
+
I made a page of [[XML_Description_Examples|XML Examples]] earlier. -Geoff

Revision as of 15:46, 16 December 2004

Texas Drek’s Downhome Effects Tutorial

So you want to write up a technology/building/special for FO? Yeehaw: you are about to embark on an exciting adventure, with chills and thrills to rival any Hollywood blockbuster.

Creating a building or a special is basically the same process as writing up a technology, so from here on out I’ll refer to all of the above as “techs”.

Step 1: What is your tech?

Give your tech a name and description, and figure out what you want it to do. Hint: In the next step you’re going to have to describe in exacting detail precisely what your tech does in a way that FreeOrion can understand. That means your tech needs to do something the actual FreeOrion program is capable of doing.

Hence you need to know how FreeOrion v.3 works. To discover how FO plays, read the requirements document and the effects document. (instead of the requirements, you might just peek at the cliff notes intead, but the effects document is a must.) Read tzlaine’s faq on the forum. If you don’t want to read the documentation because it’s long and boring then stop at this step: We don’t need your “help” designing techs. Feel free to post stuff in brainstorming, or contribute art, or whatever….but you really do need to read the docs if you want to build techs that we can use the actual game.

If you have any questions about requirements or effects doc, ask away on the forum. Someone will answer.

Here’s the tech I’ve come up with, for the purposes of this tutorial:

Drek’s Effects Tutorial
A marvelous, high tech tutorial that enlightens all who read it.
Effect: +2 Max Science to all friendly worlds set to the Science Focus

Step 2: Copy and paste the correct XML template from the effects document.

The templates are: tech, building, and special.

You’ll need to fill out the “fields” in the form. Since “Drek’s Effects Turorial” is a technology, I’ll be filling out the technology XML form:


  <Tech>
      <name>NAME</name>
      <description>DESCRIPTION</description>
      <type>TYPE</type>
      <category>CATEGORY</category>
      <research_cost>RESEARCH_COST</research_cost>
      <research_turns>RESEARCH_TURNS</research_turns>
      <prerequisites>
          NAME0
          NAME1
          ...
          NAMEN
      </prerequisites>
      <unlocked_items>
          ITEM0
          ITEM1
          ...
          ITEMN
      </unlocked_items>
      EFFECTS_GROUP [optional]
  </Tech>


NAME: this a placeholder for the name of your technology. The actual name of your technology will go into a “string table”, so you should just type out, in all caps without using spaces, a pithy name.

   <Tech>
       <name>LEARN_DREK_TUTORIAL</name>

DESCRIPTION: this is another placeholder, this time for the description of your technology. Type out the same pithy name you did in the previous field, but this time append the word “DESC”. You’ll be writing out the actual description later.

  <description>LEARN_DREK_TUTORIAL_DESC</description>

TYPE: This is the type of technology. In FreeOrion, there are three different types of techs:

  • TT_THEORY A theory. A theory contains applications, and generally should have little or no effects.
  • TT_APPLICATION An application. An application is contained by a theory, and has some sort of minor effect and/or unlocks a building.
  • TT_REFINEMENT A refinement. A refinement is contained by a theory, and often refines a building or shippart. As of this writing, refinements are not possible, so don’t worry about them.

For the Type field, you’ll need to type in one of the above types. Most techs (esp. techs that actually do things) should be Applications.

   <type>TT_APPLICATION</type>

CATEGORY: There are five categories that “hold” techs in FreeOrion. You need to assign your technology to one of them. Note, that an application or refinement should be in the same category as it’s parent theory.

The categories you can use:

  • LEARNING_CATEGORY deals with the science meter, and fundamental technologies
  • GROWTH_CATEGORY deals with the health of a population, the size of a population, and growing food.
  • PRODUCTION_CATEGORY deal with building stuff like ships and structures. The mining and industry meters are governed here.
  • CONSTRUCTION_CATEGORY deals with developing your colonies. The construction meter is handled here.
  • ECONOMICS_CATEGORY deals with the trade meter, money, etc.

The technology I’m developing clearly falls into the Learning Category.

  <category>LEARNING_CATEGORY</category>

RESEARCH_COST: The number of research points a player needs to spend each turn to research a tech. RESEARCH_TURNS: The number of turns required to research a tech.

In FO, all techs cost X RP for Y Turns to research. The numbers are still being decided as of this writing, for now assume a low level tech takes around 10 RP for 5 Turns to research.

   <research_cost>10</research_cost>
   <research_turns>5</research_turns>

PREREQUISITES: The techs required before research can start. An application should always have its parent theory as a prerequisite. You’ll need to read up on the forums to determine the current state of the tech tree in order to pick out some proper prerequisites for your tech.

The pithy name we gave the tech in the NAME field is its identification. All techs have such a name...it’s what you type into the prerequisites field.

Let’s say the Theory of Drek is the parent theory for my technology:

   <prerequisites>
       LEARN_THEORY_OF_DREK
   </prerequisites>

UNLOCKED_ITEMS: In the field, you’d type of the pithy names for all of the buildings your technology unlocks. An unlocked building can be constructed by a player on a planet.

If your tech doesn’t unlock any buildings, then just delete this field.

My tech doesn’t unlock a building, so *poof* I pressed delete and got rid of that section. But let’s say you did want to unlock a couple of buildings, the Tower of Babel and the Great Pyramids, for example:


  <unlocked_items>
    <Item>
      <type>UIT_BUILDING</type>
      <name>BUILDING_TOWER_BABEL</name>
    </Item>
    <Item>
      <type>UIT_BUILDING</type>
      <name>BUILDING_GREAT_PRYAMIDS</type>
    </Item>
  </unlocked_items>

Notice how each item to unlock has its own little item XML markups. You’d then have to define these two buildings, in much the same way techs are defined.

So far my tech looks like this:

  <Tech>
      <name>LEARN_DREK_TUTORIAL</name>
      <description>LEARN_DREK_TUTORIAL_DESC</description>
      <type>TT_APPLICATION </type>
      <category>LEARNING_CATEGORY</category>
      <research_cost>10</research_cost>
      <research_turns>5 </research_turns>
      <prerequisites>
          LEARN_THEORY_OF_DREK
      </prerequisites>
      EFFECTS_GROUP [optional]
  </Tech>


Step 3: The Defining the Effects Groups

This is the hard part. Defining an effects group is a little like writing a simple computer program. You’ll want to read the Effects document, print it out, read it again, and keep it around for reference. The Effects engine is versatile, it can a lot stuff. The trade off is complexity: it’s not as trivial as just filling out fields in a form.

You can have as many Effects Groups as you need to define what a tech does. My effect...

+2 Max Science to all friendly worlds set to Primary/Secondary Science Focus

...requires just one Effects Group.

Just like techs, Effects Groups have an XML form that you need to fill out. Here it is:

  <EffectsGroup>
      <scope>SCOPE</scope>
      <activation>ACTIVATION</activation>
      <stacking_group>STACKING_GROUP</stacking_group>
      <effects>
          EFFECT0
          EFFECT1
          ...
          EFFENTN
      </effects>
  </EffectsGroup>

SCOPE This field defines what objects in the game are influenced by your technology. My tech operates on “all friendly worlds set to Primary/Secondary Science Focus”. Most techs should constrain their effects to worlds set to a particular focus, or environment, or whatever.

First off, we need to pick out all friendly worlds. We can do that with the EmpireAffiliation condition:

  <Condition::EmpireAffiliation>
      <empire_id>Source.Owner</empire_id>
      <affiliation>AFFIL_SELF</affiliation>
      <exclusive>1</exclusive>
  </Condition::EmpireAffiliation>

Notice I filled out empire_id with source.owner. This is a variables...there are many variables you can access, listed in the Effects document.

I filled out the affiliation field with an “enumeration”. You can find the enumerations here. Certain fields require certain enumerations: it’s mostly self explanatory. For example, the condition PlanetType requires PlanetType enumerations.

Exclusive is a Boolean value, which just means true (the number 1) or false (the number 0). For this particular field, safe bet is just to enter “1” when dealing with planets.

When FreeOrion executes this empire affiliation condition, it will pick out all of the objects in the game owned by your empire. This includes space ships and buildings...but we are only concerned with the planets. So, I need to add another condition to the mix—the Type condition.

 <Condition::Type>OBJ_POP_CENTER</Condition::Type>

This is yet another enumeration form here. Now, all population centers will be selected, including any future space based colonies that are not on planets.

We need to glue these two conditions together. For that, we use the And condition:

 <Condition::And>
    <Condition::EmpireAffiliation>
       <empire_id>Source.Owner</empire_id>
       <affiliation>AFFIL_SELF</affiliation>
       <exclusive>1</exclusive>
    </Condition::EmpireAffiliation>
    <Condition::Type>OBJ_POP_CENTER</Condition::Type>
 </Condition::And>

Pretty cool, huh? By sticking our conditions into an And XML field, we are saying that we want FreeOrion to pick out everything that’s both owned by our empire and a population center.

We need a couple more conditions to make things work...remember that that we only want worlds that are set to the Primary or Secondary Science focus. Notice the word “or”.

First, let’s select all worlds that have the primary science focus, using the focustype condition:

  <Condition::Focus>
      <primary>1</primary>
      <FocusType>FOCUS_RESEARCH</FocusType>
  </Condition::FocusType>

I filled out the primary field with a 1, meaning “true”. This will select all worlds with a Primary focus in science. Note that it really will select ALL worlds, including those of enemy empires.

FocusType is yet another enumeration.

We need to do the same thing to select all worlds with Secondary focus in science, only this time the primary field would be 0.

Now the two statements need to be glued together. Since the effect works on Secondary *or* Primary focus, use the condition Or:

  <Condition::Or>
     <Condition::Focus>
        <primary>1</primary>
        <FocusType>FOCUS_RESEARCH</FocusType>
     </Condition::FocusType>
     <Condition::Focus>
        <primary>1</primary>
        <FocusType>FOCUS_RESEARCH</FocusType>
     </Condition::FocusType>
  </Condition::Or>

Finally, to complete our scope field, we need to glue both pieces together. Just insert the Or condition into the And condition:

 <scope>  
   <Condition::And>
      <Condition::EmpireAffiliation>
        <empire_id>Source.Owner</empire_id>
        <affiliation>AFFIL_SELF</affiliation>
        <exclusive>1</exclusive>
      </Condition::EmpireAffiliation>
      <Condition::Type>OBJ_POP_CENTER</Condition::Type>
      <Condition::Or>
        <Condition::Focus>
          <primary>1</primary>
          <FocusType>FOCUS_RESEARCH</FocusType>
        </Condition::FocusType>
        <Condition::Focus>
          <primary>1</primary>
          <FocusType>FOCUS_RESEARCH</FocusType>
        </Condition::FocusType>
      </Condition::Or>
   </Condition::And>
 </scope>

Notice, you can nest And/Or conditions. We are saying:

If the object is owned by our empire AND the object is a population center AND (the object is set to Primary Science Focus OR the object is set to Secondary Science Focus) THEN do something funky to the object.

  • whew* Seems like a lot of work spelled out like that, but it’s easier once you get the hang of it.

Notice that everything above is contained by the scope XML field of the Effects Group. Now, we need to fill out the activation field.

 <activation>
    <Condition::Self/>
 <activeation>

The activation field is a universe that consists only of the object’s owner. You use the same conditions as the scope field—if any object is selected by the condition, then the effect fires. This is useful is you don’t want an effects group to fire under certain conditions. For example, for a building we could test it’s planet’s environment. We could set up a condition to test if the planet is Barren, or whatever.

It’s safe just to enter the Self condition, which ensures the effect always fires.

Next, the stacking group:

 <stacking_group>STACK_DREK_TUTORIAL</stacking_group>

Stacking groups are mostly for buildings. If you have two buildings in the same solar system that both effect every planet in the solar system, you’d only want one building’s effects to fire. That’s more or less what the stacking group is for.

For technologies, it’s safe just to enter the name of the tech, perhaps prefixed with the word “STACK”.

Now, the payload, the actual effects:

 <effects>
   <Effect::SetMeter>
      <meter>METER_RESEARCH</meter>
      <value>Target.MaxResearch+2</value>
      <max>1</max>
    </Effect::SetMeter>
 </effects>  

My tech has only one effect...but you can include as many effects as you need.

The most common effect is SetMeter. The first field, meter, determines which meter is effected. These are enumerations.

The second field is an expression. An expression can be nearly any math statement (4*3 or Target.MaxResearch+10). Notice, I took the value of the Target’s Max Research, then added 2. If I had just typed “2” into the value field, it would set the meter to “2”. Instead of being a bonus, my tech would suck ass.

The third field is max, which determines whether it’s the current value of the meter or the max value of the meter effected. In FO, techs normally operate on the max value of a meter. Then, the current value slowly rises to match at a speed based on the construction meter. Putting “1” into the max field (for “true”) will operate on the max meter, which 9 times out of 10 is exactly what you want to do.

Our tech is mostly finished. When we slide the Effects group into it’s proper slot, the whole thing looks like this:

  <Tech>
      <name>LEARN_DREK_TUTORIAL</name>
      <description>LEARN_DREK_TUTORIAL_DESC</description>
      <type>TT_APPLICATION </type>
      <category>LEARNING_CATEGORY</category>
      <research_cost>10</research_cost>
      <research_turns>5 </research_turns>
      <prerequisites>
          LEARN_THEORY_OF_DREK
      </prerequisites>
      <EffectsGroup>
        <scope>
          <Condition::And>
            <Condition::EmpireAffiliation>
              <empire_id>Source.Owner</empire_id>
              <affiliation>AFFIL_SELF</affiliation>
              <exclusive>1</exclusive>
            </Condition::EmpireAffiliation>
            <Condition::Type>OBJ_POP_CENTER</Condition::Type>
            <Condition::Or>
              <Condition::Focus>
                <primary>1</primary>
                <FocusType>FOCUS_RESEARCH</FocusType>
              </Condition::FocusType>
              <Condition::Focus>
                <primary>1</primary>
                <FocusType>FOCUS_RESEARCH</FocusType>
              </Condition::FocusType>
            </Condition::Or>
          </Condition::And>
        </scope>
        <activation><Condition::Self\></activation>
        <stacking_group>STACK_DREK_TUTORIAL</stacking_group>
        <effects>
          <Effect::SetMeter>
            <meter>METER_RESEARCH</meter>
            <value>Target.MaxResearch+2</value>
            <max>1</max>
          </Effect::SetMeter>
        </effects>
     </EffectsGroup>
  </Tech>

As you’ve probably noticed, the scope condition is the longest and toughest part to write.

Step 4 Composing the string table

Not everyone speaks English.

I’ll give my fellow Americans time to recover from that statement.

...

...

As tiring as it is to accommodate the English impaired, we need to anyway. This means writing out any words that appear in the game in a string table.

It can be pretty simple:

LEARN_DREK_TUTORIAL
Drek’s Effects Tutorial
LEARN_DREK_TUTORIAL_DESC
A marvelous, high tech tutorial that enlightens all who read it. /n Effect: +2 Max Science to all friendly worlds set to the Science Focus.

Notice the /n, for a “newline.” There’s other pieces of formatting you can use, see the faq for details.

That’s pretty much it. Congrats if you’ve read this far. I probably would have got bored round step #2.

Appendix: Additional Examples

I made a page of XML Examples earlier. -Geoff