Difference between revisions of "FOCS Scripting Tutorial"

From FreeOrionWiki
Jump to: navigation, search
m (reduce intro footprint)
(Add basic editing)
Line 2: Line 2:
 
This tutorial covers how to modify FreeOrion Content Script (FOCS) files.  For details on all of the possible values, see [[Effects]].
 
This tutorial covers how to modify FreeOrion Content Script (FOCS) files.  For details on all of the possible values, see [[Effects]].
  
 +
=Getting Started=
 
All FOCS files are plain text files, though some contain extended characters, especially the language files.<br />
 
All FOCS files are plain text files, though some contain extended characters, especially the language files.<br />
 
{{FOCS_Notepad_Notice}}
 
{{FOCS_Notepad_Notice}}
Line 166: Line 167:
  
 
If you need further help, post a question in the [http://www.freeorion.org/forum/ forums].
 
If you need further help, post a question in the [http://www.freeorion.org/forum/ forums].
 +
 +
=Adding New Content=
 +
==Linking a Tech and a Building==
 +
Create a new file in ''default/scripting/techs/''<br />
 +
We will save this file as TUTORIAL_ONE.focs.txt
 +
<pre style="color: blue; display:block">
 +
Tech
 +
    name = "TECH_TUTORIAL_ONE"
 +
    description = "TECH_TUTORIAL_ONE_DESC"
 +
    short_description = "BUILDING_UNLOCK_SHORT_DESC"
 +
    category = "DEFENSE_CATEGORY"
 +
    researchcost = 4 * [[TECH_COST_MULTIPLIER]]
 +
    researchturns = 1
 +
    prerequisites = "DEF_ROOT_DEFENSE"
 +
    unlock = Item type = Building name = "BLD_TUTORIAL_TWO"
 +
    effectsgroups =
 +
        EffectsGroup
 +
            scope = And [
 +
                Planet
 +
                OwnedBy empire = Source.Owner
 +
                [[CANDIDATE_BATTLE_CHECK]]
 +
            ]
 +
            effects = SetTroops value = Value + 1
 +
    graphic = ""
 +
 +
#include "techs.macros"
 +
 +
#include "../common/shared.macros"
 +
 +
</pre>
 +
This tech:
 +
* Requires DEF_ROOT_DEFENSE to be researched first (which every player starts with)
 +
* Allows a player to build BLD_TUTORIAL_TWO (we have not created this yet)
 +
* Increases the speed of new troop recruitment on the planet by an additional 1 per turn, as long as combat is not occurring.
 +
The short description is for the hover text on the tech screen, as well as the brief description at the top of the 'pedia entry.<br />
 +
Techs all belong to one tech category, these are defined in [https://github.com/freeorion/freeorion/blob/master/default/scripting/techs/Categories.inf Categories.inf].  It is recommended to use one of the existing categories.
 +
 +
Notice ''researchcost'' uses the macro TECH_COST_MULTIPLIER, which is defined in default/scripting/common/shared.macros  So we also <nowiki>#include</nowiki> that file at the bottom.<br />
 +
The ../ means to go back one directory, in this case to default/scripting (because our file is in default/scripting/techs).<br />
 +
This definition also uses the CANDIDATE_BATTLE_CHECK macro, so the techs.macros file is needed for that.
 +
 +
Let's go ahead and add the new building in, create the file '''default/scripting/buildings/TUTORIAL_TWO.focs.txt'''
 +
<pre style="color: blue; display: block">BuildingType
 +
    name = "BLD_TUTORIAL_TWO"
 +
    description = "BLD_TUTORIAL_TWO_DESC"
 +
    buildcost = 20
 +
    buildtime = 3
 +
    location = And [
 +
        Planet
 +
        Not Contains Building name = "BLD_TUTORIAL_TWO"
 +
        OwnedBy empire = Source.Owner
 +
        TargetPopulation low = 1
 +
    ]
 +
    EnqueueLocation = [[ENQUEUE_BUILD_ONE_PER_PLANET]]
 +
    effectsgroups = [
 +
        EffectsGroup
 +
            scope = And [
 +
                Planet
 +
                Ownedby empire = Source.Owner
 +
                Contains Building name = "BLD_TUTORIAL_TWO"
 +
            ]
 +
            stackinggroup = "STACKING_TUTORIAL_TWO_TROOPS"
 +
            effects = SetMaxTroops value = Value + 3
 +
        EffectsGroup
 +
            scope = And [
 +
                Planet
 +
                Ownedby empire = Source.Owner
 +
                Contains Building name = "BLD_TUTORIAL_TWO"
 +
                Contains Building name = "BLD_TUTORIAL_ONE"
 +
            ]
 +
            stackinggroup = "STACKING_TUTORIAL_TWO_DEFENSE"
 +
            effects = SetMaxDefense value = Value + 5
 +
    ]
 +
    icon = ""
 +
 +
#include "../common/shared.macros"
 +
 +
</pre>
 +
This building can only be built on a planet with at least 1 population, and is limited to one per planet.<br />
 +
It also has a couple of effects, the first allows an additional 3 troops on the planet<br />
 +
The second allows an extra defense of 5, but only if there is also a BLD_TUTORIAL_ONE on the planet.
 +
 +
''location'' tells the game where this building can be constructed.
 +
* at any Planet
 +
* that is without a BLD_TUTORIAL_TWO
 +
* that is also owned by the player
 +
* that also has a population of at least 1
 +
 +
''EnqueueLocation'' restricts when a building can be placed into the production queue.
 +
 +
The ''effectsgroups'' contains any effects and the conditions of when and where to apply them.<br />
 +
Looking at the first ''EffectsGroup'', the ''scope'' defines what the effect applies to (the Target):
 +
* any Planet
 +
* with the same owner as the building owner
 +
* that has a completed BLD_TUTORIAL_TWO
 +
 +
''stackinggroup'' limits when an effect can take place.  You might create a new building or tech with the same stackinggroup, and only the first one would apply.
 +
 +
''effects'' define what effects apply.  The ''Target'' variable can be used here.
 +
 +
For a more in-depth look at all of the possible attributes and descriptions of each, see [[Effects]]
 +
 +
Remember to add in the stringtable entries for the new tech and building:
 +
<pre style="color: blue; display: block">TECH_TUTORIAL_ONE
 +
Tutorial tech 1
 +
 +
TECH_TUTORIAL_ONE_DESC
 +
The first tutorial tech.
 +
 +
BLD_TUTORIAL_TWO
 +
Tutorial building 2
 +
 +
BLD_TUTORIAL_TWO_DESC
 +
Second tutorial building, adds troops and defense.
 +
 +
</pre>
 +
 +
[[Category:Guides]]
 +
[[Category:Scripting]]

Revision as of 00:47, 13 March 2016

Template:WIP This tutorial covers how to modify FreeOrion Content Script (FOCS) files. For details on all of the possible values, see Effects.

Getting Started

All FOCS files are plain text files, though some contain extended characters, especially the language files.
Template:FOCS Notepad Notice

When a reference is made to the default/ directory, this refers to the Resources Files directory.
This directory varies on different systems and can be manually changed.
If you are unsure where this directory is:
Start FreeOrion → OptionsDirectories (next to last) → Resource Files.

Creating a new entry

Create a new file in the default/scripting/buildings/ directory, name it TUTORIAL_ONE.focs.txt
BuildingType
    name = "BLD_TUTORIAL_ONE"
    description = "BLD_TUTORIAL_ONE_DESC"
    buildcost = 15
    buildtime = 1
    icon = ""

It is good practice to make sure the file ends with a blank line.

This creates a very basic building type that could be built anywhere but has no effect.

No player would be able to build this building however, as their empire does not know how.
For now, we will just give the knowledge to everyone at the start of the game:

Edit default/scripting/starting_unlocks/items.inf
Add the following line at the top
Item type = Building name = "BLD_TUTORIAL_ONE"

If you start the game now and select the production screen at your home planet, you will see:

ERROR: BLD_TUTORIAL_ONE

Hover over that and the tooltip shows:

ERROR: BLD_TUTORIAL_ONE_DESC

This is because we have not told the game what our building should be labelled as, just to use the key reference of BLD_TUTORIAL_ONE.
Just like the filename, key references could be named anything, regardless of what label we want to use.
The name entry in the definition needs to be unique, but description can be shared among other entries if needed.

The key references are looked up based on the language selected, in one of the stringtables.
You can start with the file that suits you best, for this example we will use the english file.

Edit default/stringtables/en.txt
Search for BLD_COL_SUPER_TEST_DESC
On the next blank line enter the following

BLD_TUTORIAL_ONE
A new building type from the scripting tutorial.

BLD_TUTORIAL_ONE_DESC
This is a brand new building type we just created.

Make sure there are blank lines before and after these new entries.

If you were going to share this entry with others, create the same entries in each of the other stringtable files as well. Few people are fluent in all of these languages, so simply copy the same text into the same spot in each file. If you can provide a translated version, please do as it cuts down on work others would need to do.

You now have a very basic building in the game, though it has no purpose.

Entry Files

All of the FOCS entry files have a double extension of .focs.txt.
These files will be loaded regardless of the rest of their filename, or how deeply nested in the sub-directory they are.

Some special entry files have the extension .inf.
While most of these files can be freely edited, they can not be renamed or moved.

Any other file extension is not loaded into the game, unless an entry file specifically includes it.
The extension .macros is commonly used to denote scripting macros used in various entry files.
Entries that are not wanted in the game currently, but kept around for reference, are typically given the extension .disabled.

Entry files should never #include a file with another entry definition in it.

Directory Structure

Entry files are categorized by their type and should remain within the directory for that type(nested sub-directories are ok).
For example Tech entries can be anywhere in default/scripting/techs/, but should never be in default/scripting/fields/.
This only applies to the actual definition files, those with the extension .focs.txt.

The following directories within default/scripting are for .focs.txt entries:

alignments/ Alignment entries
buildings/ Building entries
empire_statistics/ Empire statistics entries
encyclopedia/ Encyclopedia topic entries
fields/ Field entries
monster_designs/ Ship loadout designs for space monsters
ship_designs/ Ship loadout design entries
ship_hulls/ Ship hull designs
ship_parts/ Ship part entries
specials/ Entries for specials
species/ Species entries
techs/ Tech entries

Required files

These are relative to default/scripting/:

keymaps.inf To Be Determined - Default keymap values
monster_fleets.inf Entries for monster fleets
starting_unlocks/buldings.inf Buildings pre-built on every starting homeworld.
starting_unlocks/fleets.inf Entries for fleets every player starts the game with.
starting_unlocks/items.inf Blueprints available at the start of the game to every player. For techs this means they are completed, for other types it allows the player to produce them.
techs/Categories.inf Categories that a tech must belong to. For now these should not be changed or added to, aside from possibly the graphic or colour definitions.

Additionally, definitions listed in any starting_unlocks/ file or monster_fleets.inf need to be avaiable.
The default AI may assume any or all of the default entries to exist.

Macros

A basic macro definition looks like this:

FIRST_ONE
'''2'''

The three apostrophies denote preformatted text, meaning any newlines are part of the macro.
Macro names should be in all uppercase, with underscores in place of spaces. They should also be uniquely named.

References to a macro are done by adding double brackets:

buildtime = [[FIRST_ONE]]

The game will end up seeing this as buildtime = 2

Macros may also use arguments:

NEW_MACRO
'''@1@ * @2@'''
Multiplies the first argument by the second.
[[NEW_MACRO(2,3)]]
Results in 6 (2 * 3)

You can pass other macros for the arguments:

[[NEW_MACRO(FIRST_ONE,4)]]
Results in 8 (2 * 4)

Macros are mainly used to keep consistant values for multiple definitions.
When this is the case, it is best to have the macro definition in a file by itself, so other files can include it.
Sometimes macros are used for a complicated formula to help the readablity of the file. There is no need for these macro definitions to be separated if they are never used in another definition.

Including other files

Files are usually included for macro definitions.
You can include another file with the #include directive:

#include "some_file.macros"
Includes the file named some_file.macros

The directive should by on a line by itself, without any spaces before #include. There is no restriction on what files are included, however you should not include files containing another FOCS entry in it. This would lead to a conflict when the entry is loaded twice.

Troubleshooting

If the entry is in the game, but does not show the name or the description correctly, check the stringtable entry for your selected language.

Typically if there is a problem with the game parsing an entry, it will show the error in the console window. The error will also be in the log file freeorion.log, which is located in your user directory (Options > Directories > Save files (parent directory))

If there are no errors shown, you can make sure the file is loading by setting the log level to TRACE.
Either edit the config.xml file in your user directory or launch the game with the --log-level TRACE argument.
The client log file (freeorion.log) will now show each file as it was loaded in, as well as any files that were skipped.

If you need further help, post a question in the forums.

Adding New Content

Linking a Tech and a Building

Create a new file in default/scripting/techs/
We will save this file as TUTORIAL_ONE.focs.txt

Tech
    name = "TECH_TUTORIAL_ONE"
    description = "TECH_TUTORIAL_ONE_DESC"
    short_description = "BUILDING_UNLOCK_SHORT_DESC"
    category = "DEFENSE_CATEGORY"
    researchcost = 4 * [[TECH_COST_MULTIPLIER]]
    researchturns = 1
    prerequisites = "DEF_ROOT_DEFENSE"
    unlock = Item type = Building name = "BLD_TUTORIAL_TWO"
    effectsgroups =
        EffectsGroup
            scope = And [
                Planet
                OwnedBy empire = Source.Owner
                [[CANDIDATE_BATTLE_CHECK]]
            ]
            effects = SetTroops value = Value + 1
    graphic = ""

#include "techs.macros"

#include "../common/shared.macros"

This tech:

  • Requires DEF_ROOT_DEFENSE to be researched first (which every player starts with)
  • Allows a player to build BLD_TUTORIAL_TWO (we have not created this yet)
  • Increases the speed of new troop recruitment on the planet by an additional 1 per turn, as long as combat is not occurring.

The short description is for the hover text on the tech screen, as well as the brief description at the top of the 'pedia entry.
Techs all belong to one tech category, these are defined in Categories.inf. It is recommended to use one of the existing categories.

Notice researchcost uses the macro TECH_COST_MULTIPLIER, which is defined in default/scripting/common/shared.macros So we also #include that file at the bottom.
The ../ means to go back one directory, in this case to default/scripting (because our file is in default/scripting/techs).
This definition also uses the CANDIDATE_BATTLE_CHECK macro, so the techs.macros file is needed for that.

Let's go ahead and add the new building in, create the file default/scripting/buildings/TUTORIAL_TWO.focs.txt

BuildingType
    name = "BLD_TUTORIAL_TWO"
    description = "BLD_TUTORIAL_TWO_DESC"
    buildcost = 20
    buildtime = 3
    location = And [
        Planet
        Not Contains Building name = "BLD_TUTORIAL_TWO"
        OwnedBy empire = Source.Owner
        TargetPopulation low = 1
    ]
    EnqueueLocation = [[ENQUEUE_BUILD_ONE_PER_PLANET]]
    effectsgroups = [
        EffectsGroup
            scope = And [
                Planet
                Ownedby empire = Source.Owner
                Contains Building name = "BLD_TUTORIAL_TWO"
            ]
            stackinggroup = "STACKING_TUTORIAL_TWO_TROOPS"
            effects = SetMaxTroops value = Value + 3
        EffectsGroup
            scope = And [
                Planet
                Ownedby empire = Source.Owner
                Contains Building name = "BLD_TUTORIAL_TWO"
                Contains Building name = "BLD_TUTORIAL_ONE"
            ]
            stackinggroup = "STACKING_TUTORIAL_TWO_DEFENSE"
            effects = SetMaxDefense value = Value + 5
    ]
    icon = ""

#include "../common/shared.macros"

This building can only be built on a planet with at least 1 population, and is limited to one per planet.
It also has a couple of effects, the first allows an additional 3 troops on the planet
The second allows an extra defense of 5, but only if there is also a BLD_TUTORIAL_ONE on the planet.

location tells the game where this building can be constructed.

  • at any Planet
  • that is without a BLD_TUTORIAL_TWO
  • that is also owned by the player
  • that also has a population of at least 1

EnqueueLocation restricts when a building can be placed into the production queue.

The effectsgroups contains any effects and the conditions of when and where to apply them.
Looking at the first EffectsGroup, the scope defines what the effect applies to (the Target):

  • any Planet
  • with the same owner as the building owner
  • that has a completed BLD_TUTORIAL_TWO

stackinggroup limits when an effect can take place. You might create a new building or tech with the same stackinggroup, and only the first one would apply.

effects define what effects apply. The Target variable can be used here.

For a more in-depth look at all of the possible attributes and descriptions of each, see Effects

Remember to add in the stringtable entries for the new tech and building:

TECH_TUTORIAL_ONE
Tutorial tech 1

TECH_TUTORIAL_ONE_DESC
The first tutorial tech.

BLD_TUTORIAL_TWO
Tutorial building 2

BLD_TUTORIAL_TWO_DESC
Second tutorial building, adds troops and defense.