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)

[Gandalf Parker]

Access (if not really easily implemented atm) to more specific information like which spells were cast through debug logs

This is kindof old and Im sure I have notes lying around to update it.
http://forum.shrapnelgames.com/showthread.php?p=527869
but it does provide a list of some of the things Ive seen that the scores or debug log offer which might be used to create an interesting game variant. One I need to add is inter-player messages (which has been used to offer some control to RAND no-diplomacy games). I will try to dig up the notes and present a better list to spark some ideas of what people can do with your program.

Thanks again for making it.
Gandalf Parker
--
Some people NEED menus.
All options open with no menu list appears to them to be no options at all.

[Stavis_L]

Wow, that's amazing. Just want to ask a few clarification questions, since I don't have a score file available at the moment.

1) Are messages to the player limited to editing descriptions of units/items? I can't think of anything else that can be modded to "talk" to the player...might want to give the player an immortal "messageboard" unit or something, rather than updating the description of units that will see actual play. Would need to be reasonably killable to allow the player to lose though...maybe an item would be better.
2) What conditions are available in the score file to predicate events upon? Your example has #castles and turn #. What else is there?

Thanks!

[Illuminated One]

@Gandalf

Yeah, a list a long these lines is great. If you have something around that shows how they look in the debug log that would be perfect.

Well, as for ideas I have so many myself, otherwise I would't have made it.
But I certainly don't object to some brainstorming

Make some units like angels or devils more expensive or cheaper as you dominion grows (scores)

Give a weak nation a gem discount site that looses the discount when it's taken by another nation (debug log)

Changing mages based on your conquest (you have taken Mictlan cap and all your nationals have learned a bit about blood) (debug log)

Gem gens - make them spells that can be cast at provinces containing specially prepared sites and increase the gem income from the site. Make them more expensive with every turn/casting (debug log)


@Stavis_L

Atm I don't provide any way to access messaging options. Well, to be honest, atm I don't really provide access to anything, except through copying the examples.
Theoretically such a thing could be coded from scratch by anyone, and maybe it will be added in a long time, but I'm not sure if it's worth it, since it would require changing 2h files.
A immortal messageboard (who needs a starting scout anyway) is imo the best thing as you can use it to deliver both messages and gems (in an ugly way also items, if you give them access to exactly the paths needed for forging that for 1 turn, just look at the researchers mod) without messing with the turn files themselves.


The conditions in the scorefile are
Forts
Provinces (change

[Gandalf Parker]

This is still available from an old test game called Massive.
http://www.dom3minions.com/games/Massive/

There are score files and stat files and a zipped up log file. The log file is only one turn but......

Archive:  massive.zip

  Length     Date   Time    Name

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

 13514713  05-15-06 10:53   home/dom3/dominions3/savedgames/massive/massive.log

You can see why I only zipped up 1 turn at a time. Even in the small 4-man games on my server a log file is huge. There are a number of examples in the Dom3Minions games directory that are viewable online if you want some logs to dig thru.

In my Monster Scenario thread I did lay out some options for mid-game mod changes that could act like events. Such as placing a big runed monolith in each home province and having the mod change the "description" so that looking at it would tell you new things. Maybe have two images, one that is dull and one lit up to tell the player that the message of the runes has been changed.

Another was to place an immobile inactive completely hidden unit in various provinces which could erupt into something at some point later in the game (change it into something like an attacking army or horror) but Im not a real modder. I couldnt figure out how to make it automatically hidden so that it didnt affect the outcome of battles.

Also for some of the ideas about game overseeing, game management, reward/punishment of players I did create the "Watcher" nation mod. It could occupy a location not on the map, watch everything going on in every province, use messages from the GM (game master) to send rewards or use free spells to send punishments.

[Gandalf Parker]

a game with a better planned Early Age Ermor as an AI. Well designed god, well chosen scales, tweaked to play well as an AI. And then an outside program can watch the logs. When Ermors castle comes under siege then "Ermor casts a massive revenge spell" and suddely goes total undead with tweaks to be a big problem trying to take them out.

Or a "sacred forest" stretching across numerous provinces and when they are attacked then Pangaea erupts everywhere.

Game Progression: at 50 turns into the game the opponent AI will progress (as much as possible) from Early Age to Middle Age, and at 100 turns to Late Age.

SURPRISE: Someone has taught all Shamans a spell called "steroids". The applicable units with them are all highly buffed from this point on. (including any you recruit)

OOPS: an error in magic research has given all Amazons an STD. They are all diseased.

Sun Tzu has franchised: All "Arena" sites in all provinces (enter for training) have increased to include xxxxxxxxxx (this is an untested concept)

Snake Revolt: due to some very strange magic by a Sauromatian Mage, all magically captured snakes have been released. All Snake Rings, Serpent Kryss, and (stupid cobra amulet I cant remember) are now powerless.

AN ICE AGE IS COMING: in 30 turns astrologers predict that the world will grow cold, we will not be able to enter or leave water provinces, and all magic items not based on water-magic which grant water breathing will be worthless. (requires Watcher mod)

Pole Reversal: the magnetic poles have flip flopped. It was too fast for most people to notice but it did have the effect of cancelling ALL global spells which were in effect. (requires Watcher mod)

disclaimer yes I know some of these are laughably dumb but surely if they are then before saying so the poster can come up with something else to (A) react to in the game and (B) alter items, units, or magic sites

[Illuminated One]

I actually did an API and updated the Growing Swamp Example.

Hopefully this makes it easy enough to mod without knowing python.