Python Development

From FreeOrionWiki
Revision as of 16:33, 12 March 2020 by Geoff the Medio (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page will be devoted to matters relating to python development in general for the FreeOrion project, including the general boost::python interface. A separate page is devoted to details specifically regarding the AI Python API. Other topics relating more specifically to the AI will be covered at AI_Development, and topics relating more specifically to universe creation will be covered at Universe_Creation. A good understanding of the Free_Orion_Content_Script_(FOCS) will also likely be very helpful since the use of python in FreeOrion closely relates to scripted content.

Python version

Supported python version is 3.5

Code style

C++ API use camelCase style

Python code should be written using general python style according to PEP8 also usefull to read google recommendations

Extend C+ API in python

In some cases it is more easy and effective to extend interface of c++ objects from python. For example string representation of object.

This code located in file default\AI\freeorion_debug\

PS. Add __repr__ and __str__ methods to objects as soon as you need it.

AI state in save file, and preserving backwards compatibility

The AIState is stored as an encoded string in save game files (currently via the pickle module). The attributes of the AIState must therefore be compatible with the encoding method, which currently generally means that they must be native python data types, not objects such as UniverseObject instances or C++ enum values brought over from the C++ side via boost. If desiring to store a reference to a UniverseObject store its object id instead; for enum values store their int conversion value.

Adding or removing AIState attributes can break save compatibility. If you're not entirely sure how to handle it one option is to not fully remove them, leave them with comment to remove, to make breaks less frequent. When adding attributes or changing their names, compatibility can be broken because some of the new code will try to use attributes that the saved object won't have. To deal with this, a custom __setstate__ method can be specified, which will be called during the unpickling process and which can add default values for the newly added attributes. For example, if a new attribute is added to the AIstate class, restoring the AIstate from a previous save file would fail unless additional steps are taken to deal with the conflict. The following __setstate__ method can be added to (or adjusted in) the AIstate class to provide default values for the new attribute(s); it is automatically called during the unpickling process. In this example the new attributes are all dictionaries. Keep in mind, this method is just used for unpickling saved games; default values still need to be provided in __init__ to handle new games:

   def __setstate__(self, state_dict):
       self.__dict__.update(state_dict) # update attributes
       for dict_attrib in ['qualifyingColonyBaseTargets',
           if dict_attrib not in state_dict:
               self.__dict__[dict_attrib] = {}


Internal Debug Mode

To be accessible this must be enabled by an AI config option:


For convenience, there is a premade config file that can be used invoking freeorion from the command line with the following option:

 --ai-config .\default\python\AI\ai_debug_config.ini

Then, to access chat commands you need to choose send all (default behavior) or select first AI

Send help to chat window.

You will got instruction how to work with it. start <id> will start debug mode with selected id stop will finish debug mode

To run start you need that this AI was selected (don't select any AI and all will work fine)

Most used variables already imported to scope with short name (e:empire, u: universe, ai: aiState)

Chat window does not support multiline input. Use semicolon as line separator

Use short user name. In examples I use ($) as short name for user.

This chat works like python shell. You can assign variables, print result and do almost all you want.

   $ x = 1
   $ x
   $ print x + 3
   $ e.playerName

See more possibilities: Tips and tricks


For windows remove Python27.* from installed game folder to use system python(don't forget to install it)


Pydev manual

To open console: If you want to use the interactive console in the context of a breakpoint, a different approach would be selecting a stack frame (in the debug view) > right-clicking it > pydev > Debug Console (or you can also in the debug view create a new console view connected to the debug session for the same effect).



Tips and tricks

Reload module

- enter debug mode

   $ start 2

- import module to current scope

   $ import ProductionAI

- change module - reload module

   $ reload(ProductionAI)

- end turn and enjoy result

Note: Reload module that store some state will ruin the game (FreeOrionAI)

Execute file

   $ execfile('file_path')

path can be absolute or relative to current working dir

   $ import os
   $ print os.getcwd()

Python editor

 It is your choice how to edit python code. Here are some suggestions:

- PyCharm community edition

- Eclipse based.

A good IDE will help you to make fewer mistakes, and keyboard shortcuts and other IDE features can greatly speedup your development. If you are unfamiliar with using an IDE then two key features to be sure to learn are how to quickly navigate to an item's declaration (preferably with a shortcut key), and how to use its code completion feature.

Deploying code

Best way to deploy your code to game is to specify resource-dir and stringtable-filename in persistent_config file.

- navigate to game folder with Config.xml
- create persistent_config.xml
- add next text and replace repository_path to your path
  <?xml version="1.0"?>


- Q: This page can be better / has typo / ...
- A: Welcome to forum, lets do it better.
- Q: Which python version used?
- A: Windows: python shipped with game(2.7.3) Other system use system python.
- Q: Where does print output go?
- A: stdout and stderr redirected to logs in the game settings folder.
- Q: How do I test new code?
- A: start/load a game (changing code during gameplay will not affect a current game; the code is already in memory).