Dom 3 Scripting Framework (SP)

[Illuminated One]

So one of the big limits of modding was that you could only change stats of units or spells, not create dynamic events let alone scenarios.
No more, this Frameworks allows you to create mods that are completely scripted.


Features

Interface for running D3SF games with dynamically scripted mods
Compatible with hotseat games
API for changing the mod - with the following functions: ActivateCommand(Line), VariableinLine(Line, Variable)
Access to global game information like turn count or a nation's income, through API
Access (if not really easily implemented atm) to more specific information like which spells were cast through debug logs


(Possible) Future Updates

Pretier Interface + some bugs
API for sending messages and items to player
Some security
Installer


Some security notes - Read before installing

This Framework will run python scripts and allow them to do all things necessary for a dynamic mod - like reading or writing files. This however is insecure (as it could read your personal or overwrite system files). So if you are using a mod, make sure you can trust it (basically the script should not open, read or write anything other than game files in the mod and savedgames folder. It shouldn't execute anything either).
In any case I don't take any liability for any harm that comes to you or your computer when using it.
If there are some mods made for this I will make a more secure version, disallowing anything but API calls - some additional function for using the debug log and maybe savegame files will be added. So use the API wherever possible.



Requirements

Python 3.0 (probably lower versions work haven't checked)



Ok, so how do I play a D3SF mod?

First you need to start the game. You do this exactly like starting a normal game. Select the mods you want to use, select map, nations and name and start.

Ok, say I create the game MySPGame.

But instead of playing the first turn you exit dominions to the desktop and start the script Main.py (for windows users there's also a Main.bat) in the Frame Folder in your Mod Folder.
You will be promted to select the game you want to play through typing in a number. Should look like this

------------------------------------------------------------------------------

Welcome to the Dom3 Scripting Framework

------------------------------------------------------------------------------

Select a game
0) Quit

1) cataclysm
2) pyrothere
3) earlydays
4) MySPGame
5) newlords

So I type in 4 and hit enter.

Ok, that's all you have to do. After that the game plays just like a normal SP game, only that you get the in between turn popups like in MP games.

Just hit exit if you have played the turn, or open up the turn if it is new one.
Whenever you want to quit use the "Save and Quit" or" Quit without Saving" options. You can go back anytime by starting the Main.py again and selecting the game.
The script will automatically create another game, which is called SF_... (whatever you called your game). That's only a working directory and not meant to be played. If you have any troubles creating a new game with the same name, it could be that you need to delete the SF_... game first.
If you find any Bugs, let me know


How do I install it?

Ok, this requires a little work, but as long as you can get Python installed, you're save.
First Unzip the Zip into your Mods Folder.
Since the game contents are not saved consistently between different computers you have to find them out and enter them into the DomScript.ini.
It should be pretty straightforward.
Dompath - is the path were your main dominions directory is.
Exepath - needs and must not be changed atm
Modpath - your mod folder. You just unzip into it.
Savepath - your saved games are there

Viola!



How do I install new mods for this?

Copy the *.py file and if included the *.dm file into the Frame/mods/ folder. Run the Main.py on any game you like or make another copy of the *.dm file into your normal folder.
There are two mods already included, TheGrowingSwamp which is only a demo (play as Sauro), and a Researcher mod for Marverni.


How to make a mod with this?

All a mod needs is a python script that goes into the Frame/mods/ folder.
You will have three arguments
1) Dominions mod folder (Debug logs reside at ./Frame/log/, the mods itself in ./Frame/mods/)
2) Game Name
3) Working directory of the game (here you can find the scoredump.html)

Look at the included mods to get started (TheGrowingSwamp = just a small demo, of what you can do. Play with Sauro, keep an eye on your sites and Witch Kings and expand.

You are free to script in any way you like, however I would ask that you adhere to the following standards:
1) Every mod should contain a mod template that has all the lines that can be active but outcommented. The script should only activate the commands or change variables when conditions are met
2) Provide the mod in zipped form in the same structure as the downloaddable demo. Makes it easier to install
3) Whenever you add new useful functions please send me the code so I can make API functions out of it. Or if you feel like making an API or fixing something about the interface yourself I'd be even more grateful
4) Keep your mod bug-free. Some bugs might crash the whole Framework.


Downloads (Linux and windows version)