1. We have added the ability to collapse/expand forum categories and widgets on forum home.
    Dismiss Notice
  2. All Civ avatars are brought back and available for selection in the Avatar Gallery! There are 945 avatars total.
    Dismiss Notice
  3. To make the site more secure, we have installed SSL certificates and enabled HTTPS for both the main site and forums.
    Dismiss Notice
  4. Civ6 is released! Order now! (Amazon US | Amazon UK | Amazon CA | Amazon DE | Amazon FR)
    Dismiss Notice
  5. Dismiss Notice
  6. Forum account upgrades are available for ad-free browsing.
    Dismiss Notice

CivPlayer Python scripting utility 2016-10-05

CivPlayer Python scripting utility

  1. Baldyr
    CivPlayer is a Python module and a Python scripting utility application.

    Complete documentation available in the main thread:
    http://forums.civfanatics.com/showthread.php?t=438602

    What does it do?
    CivPlayer has two main features:
    1. Making handling various player and team values and instances easy to handle.
    2. Has built-in support for storing custom data - both player specific and global data.​

    How does it work?
    CivPlayer is self-contained in the CivPlayer.py file and there are three things you need to do in order to access the included features:
    1. Download and install the module in the \Assets\Python\ folder of your mod.
    2. Initiate the setup code by adding function calls from the mod's Python event managing structure.
    3. Import the module to any other module using it.​
    More details in the installation section.

    What are the player/team values, then?
    In CivIV each player is a CvPlayer instance and those objects are inherited by the Python scripting environment as CyPlayer instances. In order to do just about anything concerning the players with Python, you need to fetch the CyPlayer instance. So you end up doing this often. Very often. Other times you need the player ID - also known at the PlayerType - for various tasks indirectly affecting a player. So you need to get that value also on-the-fly.

    Now, this isn't all there is to handling players. Each player also has a Civilization attribute associated with it. And every player is part of a team - these are known as CvTeam instances or CyTeam instances in Python terms. The same goes here; sometimes you need to get hold of the player's CyTeam object, and other times you need to fetch the teamID/TeamType.

    CivPlayer wraps all of this up in a easy-to-use package using something called CivPlayer instances. A CivPlayer is basically a collection of all the values and objects associated with one of game's players or Civilizations. As a bonus, the CivPlayer instance also holds a PyPlayer instance for easy-access. PyPlayer is "helper class" found in the PyHelpers module that ships with the game, and it adds some very useful methods not otherwise available with CivIV Python.

    What is the advantage of a CivPlayer instance over a CyPlayer and a CyTeam instance?
    It's a matter of convenience as it saves time and results in shorter scripts with less repetition. Because even if you wrap up the main methods of fetching the associated instances and index values, you end up calling these functions over and over again.

    With a CivPlayer instance, you can just invoke the CivPlayer.get() method for fetching any value on-the-fly. And there are numerous different and convenient ways of getting hold of the CivPlayer instance itself.