Over the years I made lots of python functions to do several things. Some are simple and boring, some are more sophisticated. I release them here for anyone interested. I feel I'm 7 years late doing this... but oh well, better late than never.
Some basic familiarity with python code is required to use them.
An Excel file is included with a brief description of what the utilities do.
######### INSTALL INSTRUCTIONS
1) Download the attached files and copy them in your Mods/yourmod/Assets/Python folder.
2) In all your python files where you want to use the utilities, write the following at the top (some of these lines may already exist in your files, so in that case write just the rest):
import CvUtil
from CvPythonExtensions import *
gc = CyGlobalContext()
localText = CyTranslator()
import Popup as PyPopup
import PyHelpers
import math
import random
import QGame
from QGame import *
import QConstants
from QConstants import *
import QUtilities
QPlayer = QUtilities.QPlayer
QUnit = QUtilities.QUnit
QPlot = QUtilities.QPlot
QCity = QUtilities.QCity
QMap = QUtilities.QMap()
QID = QConstants.QID
3) If you want to use the modder-defined variables (see below) then follow these instructions. You DON'T want to do it if you're already pickling variables because the utilities will mess up your existing pickles.
In your existing CvEventManager.py file you have to:
3.1) Write the following lines at the top of the file:
import QGame
from QGame import *
import QUtilities
QCity = QUtilities.QCity
QPlayer = QUtilities.QPlayer
3.2) Write these lines at the top of the existing onGameStart function.
for t in MyGameVars:
obj=QGame.getEmptyObject(t)
QGame.storeMyVar(t,obj)
for loopPlayer in QGame.getPlayersList():
qPlayer=QPlayer(loopPlayer)
qPlayer.initPlayer()
3.3) Write these lines at the end of the existing onCityBuilt function:
for t in MyCityVars:
obj=QGame.getEmptyObject(t)
QCity(city).storeMyVar(t,obj)
######## USING THE UTILITIES PART 1: QMap and QGame
Invoke the utilities included in the QMap using this format:
QMap.utilityname(xxx)
Depending on the utility xxx is non-existent or one or more data you have to provide. See each utility for details.
For example, to use the getAdjacentPlots utility, write this line:
x = QMap.getAdjacentPlots(myplotlist)
######### USING THE UTILITIES PART 2: QPlot, QCity, QPlayer, QUnit
The utilities under the QPlot category are used writing the code in this format:
QPlot(pPlot).utilityname(xxx)
where pPlot is the plot object you want to do stuff with. Depending on the utility xxx is non-existent or one or more data you have to provide. See each utility for details.
For example, to use the getNearestCity utility you write:
x = QPlot(yourplot).getNearestCity(iPlayer,buildinglist)
A few data is also stored in QPlot, which can be accessed using it without the second parenthesis. For example the following line gives you the plot's unique ID number:
x = QPlot(yourplot).ID
Check the Excel file to see what basic data is available.
Same logic for plots goes for cities (QCity), units (QUnit) and players (QPlayer).
########### USING UTILITIES PART 3: QID
This function, QID, is used only to ease coding. When modders need to get the ID (index in the XML) for a building, tech, civic, route, civilization, unit type, etc, they write something like:
iTaoism = gc.getInfoTypeForString('RELIGION_TAOISM')
With QID you can simply write instead:
iTaoism = QID('Taoism')
Just shorter and easier!
It's not magic though. To work a dictionary must be filled manually once in the QConstants file with all the elements you want to work with in this manner. I have wrote many but not all, just because I'm lazy. You can add all the rest or your own techs, units, etc from your mod.
########### USING UTILITIES PART 4: MODDER-DEFINED VARIABLES
The utilities provide an easy-to-use way to define and use your own variables, storing them (persistently) in Player objects, Unit objects, Plot objects, City objects or the global level Game, thanks to the python's so-called pickle system. Your variable can be an integer, float (decimal), string, boolean, list or dictionary.
To use this feature you have to define your variables names in the QConstants file as a list file following the naming restrictions described there. In other words:
MyGameVars=[x1,x2...]
MyPlayerVars=[y1,y2...]
MyPlotVars=[z1,z2....]
MyUnitVars=[w1,w2...]
MyCityVars=[v1,v2...]
Then in your coding you'd use them like this:
For a Unit level integer variable for example named, say, iStuff, you write this to give it a value, say 5:
QUnit(affectedunit).storeMyVar('iStuff',5)
To read the variable's current value, you write:
x = QUnit(affectedunit).getMyVar('iStuff')
Your modder-define variable can be a list. If so, you can append a new element to the list as shown below, assuming you named it lSuperList and you want to append the value 77:
QUnit(affectedunit).appendMyVar('lSuperList', 77)
And you can remove the element 15 from the list like this:
QUnit(affectedunit).removeMyVar('lSuperList', 15)
Note variable names are always in simple quotation marks.
Some basic familiarity with python code is required to use them.
An Excel file is included with a brief description of what the utilities do.
######### INSTALL INSTRUCTIONS
1) Download the attached files and copy them in your Mods/yourmod/Assets/Python folder.
2) In all your python files where you want to use the utilities, write the following at the top (some of these lines may already exist in your files, so in that case write just the rest):
import CvUtil
from CvPythonExtensions import *
gc = CyGlobalContext()
localText = CyTranslator()
import Popup as PyPopup
import PyHelpers
import math
import random
import QGame
from QGame import *
import QConstants
from QConstants import *
import QUtilities
QPlayer = QUtilities.QPlayer
QUnit = QUtilities.QUnit
QPlot = QUtilities.QPlot
QCity = QUtilities.QCity
QMap = QUtilities.QMap()
QID = QConstants.QID
3) If you want to use the modder-defined variables (see below) then follow these instructions. You DON'T want to do it if you're already pickling variables because the utilities will mess up your existing pickles.
In your existing CvEventManager.py file you have to:
3.1) Write the following lines at the top of the file:
import QGame
from QGame import *
import QUtilities
QCity = QUtilities.QCity
QPlayer = QUtilities.QPlayer
3.2) Write these lines at the top of the existing onGameStart function.
for t in MyGameVars:
obj=QGame.getEmptyObject(t)
QGame.storeMyVar(t,obj)
for loopPlayer in QGame.getPlayersList():
qPlayer=QPlayer(loopPlayer)
qPlayer.initPlayer()
3.3) Write these lines at the end of the existing onCityBuilt function:
for t in MyCityVars:
obj=QGame.getEmptyObject(t)
QCity(city).storeMyVar(t,obj)
######## USING THE UTILITIES PART 1: QMap and QGame
Invoke the utilities included in the QMap using this format:
QMap.utilityname(xxx)
Depending on the utility xxx is non-existent or one or more data you have to provide. See each utility for details.
For example, to use the getAdjacentPlots utility, write this line:
x = QMap.getAdjacentPlots(myplotlist)
######### USING THE UTILITIES PART 2: QPlot, QCity, QPlayer, QUnit
The utilities under the QPlot category are used writing the code in this format:
QPlot(pPlot).utilityname(xxx)
where pPlot is the plot object you want to do stuff with. Depending on the utility xxx is non-existent or one or more data you have to provide. See each utility for details.
For example, to use the getNearestCity utility you write:
x = QPlot(yourplot).getNearestCity(iPlayer,buildinglist)
A few data is also stored in QPlot, which can be accessed using it without the second parenthesis. For example the following line gives you the plot's unique ID number:
x = QPlot(yourplot).ID
Check the Excel file to see what basic data is available.
Same logic for plots goes for cities (QCity), units (QUnit) and players (QPlayer).
########### USING UTILITIES PART 3: QID
This function, QID, is used only to ease coding. When modders need to get the ID (index in the XML) for a building, tech, civic, route, civilization, unit type, etc, they write something like:
iTaoism = gc.getInfoTypeForString('RELIGION_TAOISM')
With QID you can simply write instead:
iTaoism = QID('Taoism')
Just shorter and easier!
It's not magic though. To work a dictionary must be filled manually once in the QConstants file with all the elements you want to work with in this manner. I have wrote many but not all, just because I'm lazy. You can add all the rest or your own techs, units, etc from your mod.
########### USING UTILITIES PART 4: MODDER-DEFINED VARIABLES
The utilities provide an easy-to-use way to define and use your own variables, storing them (persistently) in Player objects, Unit objects, Plot objects, City objects or the global level Game, thanks to the python's so-called pickle system. Your variable can be an integer, float (decimal), string, boolean, list or dictionary.
To use this feature you have to define your variables names in the QConstants file as a list file following the naming restrictions described there. In other words:
MyGameVars=[x1,x2...]
MyPlayerVars=[y1,y2...]
MyPlotVars=[z1,z2....]
MyUnitVars=[w1,w2...]
MyCityVars=[v1,v2...]
Then in your coding you'd use them like this:
For a Unit level integer variable for example named, say, iStuff, you write this to give it a value, say 5:
QUnit(affectedunit).storeMyVar('iStuff',5)
To read the variable's current value, you write:
x = QUnit(affectedunit).getMyVar('iStuff')
Your modder-define variable can be a list. If so, you can append a new element to the list as shown below, assuming you named it lSuperList and you want to append the value 77:
QUnit(affectedunit).appendMyVar('lSuperList', 77)
And you can remove the element 15 from the list like this:
QUnit(affectedunit).removeMyVar('lSuperList', 15)
Note variable names are always in simple quotation marks.
