Author: Causeless
Original thread: R2TR Toolkit: Historical Events Documentation

Historical Events

Historical Events Modding


(Note - this modding guide requires the R2TR scripting toolkit!)

This is the modding documentation to implement historical events using the R2TR scripting toolkit. Using this, you can add event messages which pop up on certain dates - for example like the historical messages in the original Rome or Medieval 2, where messages would pop up to inform you about inventions, discoveries, or other immersive notes.

Firstly, open up _r2tr_tools.pack using the pack file modder of your choice.

Before you get started, you need to look at lua_scripts/world.lua. This file governs, well, the "world" - things like turns per year, the start year, and functions to convert between them. So look at the variables "startYear" and "turnsPerYear" near the top - you need to change these to match the starting date and the turns per year your mod uses. If there is any way to grab the turns per year or starting date directly from the game itself, I'd appreciate the knowledge

As long as both those functions are set correctly for whatever turns per year or starting date you choose, the actual historical events themselves will automatically change the turn number they happen on to the correct date. This means you can easily interchange the same set of historical events between different mods as long as you appropriately set the two variables above.

Please remember that depending on the mod you can always keep any changed files in another .pack file to overwrite the scripting toolkit in certain places. This could be beneficial if you want to easily update the toolkit in the future.

So let's get started - now you must go into scripts/_lib/lib_historical_events.lua. Here, there is a lua table with 2 dummy events that I used for testing and to show how it works:

Code:
events = {    
    {-272, "custom_event_1000"},
    {-271, "custom_event_1001"}
}
These 2 events are at the starting year of vanilla, and the year after (or 1 turn after). If you start the game up with this toolkit enabled, you'll see both these events pop up on the first and second turns.

Here, every time you want to add a new event you add to the table with the year and a new custom event id... so lets say I wanted an event that happened at 0 AD, the table would become this:

Code:
events = { 
    {-272, "custom_event_1000"},
    {-271, "custom_event_1001"},
    {0,    "custom_event_1002"}
}
Take care about the presence or lack thereof of the minus signs before the year number (-218 is 218 BC, while 218 is 218 AD), the quotations marks around the event ids, and the commas after all but the last 2 } table ends. You need to ensure these are all right otherwise it won't work. For the sake of cleanliness, you might want to ensure that all the year numbers and IDs are in order, but there's nothing actually enforcing this in the scripts - you are free to do whatever.

Ok, so afterwards you need to go into db/message_event_strings_tables/r2tr_message_event_strings. Here, you'll see a list of all the events. Ignore event_0, that's a test one! You can see a bunch of parameters - culture, which allows you to have different text for each culture, text, which is a name used to determine what text is used in the info box, image, which is the image at the top of the info box, icon, which is the icon in the messages list in-game, and the sound_event which is the type of sound that plays when you open it.

The image can be any image found inside data_rome2.pack/ui/eventpics, and the icon can be any image found in data_rome2.pack/ui/campaign ui/message_icons.

A bit more explanation about the text parameter - it's like a key to the text, but it's NOT the actual text itself. I'll get to that later. Anyways, it may make sense to name the text "event_concrete" for the discovery of concrete, for example. It's just something that describes and links to the text.

Ok, so now you need to go into db/message_events_tables/r2tr_message_events. Again, you see the test events I already have there, and a few parameters - instant_open, which determines whether the text box forcefully opens itself at the start of a turn or not (for some reason it doesn't work on the first turn, probably because the first mission overrides it), and "layout", which can be "standard", "diplomacy_notification", "incident", "custom_list", "appoint_new_general", "ally_attacked", "building_constructed", "capital_lost", "fame", "recruitment", "technology_advances" or "trait_ancillary_gained".

So now you go into text/db/r2tr_message_event_strings. You'll yet again see a list of the current test events I have. The localised string there is the title of the info box. You can see the custom_event_* and cultures there, too, so make sure they are correct.

Now, finally, text/db/r2tr_message_event_text. Here's where the actual text goes - remember the text key I mentioned earlier? You put that after message_event_text_text_, and then the localised string is the actual text inside the event info box. Here's where you'd write the interesting stuff.

For the first 2 events, you can just replace custom_event_1000 and custom_event_1001, or delete them if you want.

I hope this documentation helps. Further information on other parts of the tools will be created later.

Please follow us at our forums to find news and information about the scripting toolkit and other mods in the R2TR family, including our total overhaul.