README

Description
===========

Have a massive Empire? Want to delegate power to a small number of
Kings? Annoyed by having to wait for everything to de-jure drift into
titles that don't represent the whole area?

Well, now you have a solution. High Kings!

What are High Kings?
--------------------

High Kings hold all of the territory in a de-jure Empire. Instead of
all the little Kingdoms there's one with the same name and flag as the
Empire title.

The High Kingdom remains de-jure part of the Empire they were created
from, but they can be de-jure drifted out into your primary Empire.

How do I make a High Kingdom?
-----------------------------

Either completely control all the de-jure lands of the Empire of your
Primary Title, or ensure a vassal of yours holds all the lands of
the Empire.

The decision will become visible after you (or your vassal) hold at
least two de-jure Kingdoms in the de-jure Empire of your (or your
vassal's) primary title.

There are no limits from rank, so you can make a High Kingdom for yourself
as a Count, Duke, King or Emperor, but you need to be an Emperor to make
a High Kingdom for a Vassal.

GitHub Installation Instructions
================================

If you're installing from the Steam Workshop, you don't need to do this.

Either download the latest snapshot zip
(https://github.com/fishface60/highkings/archive/master.zip), and
extract the contents of the highkings-master folder into a directory
called highkings, or clone the repository and call it highkings.

Then copy the `highkings.mod` file out of the repository and put it into
your mod directory.

Links
=====

The workshop page for this mod can be seen at:
http://steamcommunity.com/sharedfiles/filedetails/?id=342561690

The github for this mod can be seen at:
https://github.com/fishface60/highkings

FAQs
====

1.  Does this mod conflict with any base game functionality or other mods?

    It should not. I was careful to use the drop-in files way of adding
    functionality, rather than editing existing files, so it should not
    override changes to base-game changes, which other mods may need
    to change.

    So if Paradox updates the game my mod won't force it to use old files,
    which may be incompatible with other changes.

    Similarly if another mod has to alter existing files, then my mod
    won't conflict with that, so theoretically, my mod should be usable
    in a total conversion.

    There can still be logic conflicts which can break things, such as
    if a Kingdom title has special meaning, as the High Kings mod will
    destroy it and redistribute its lands regardless.

2.  The decision does not appear.

    You need to completely control the Empire. Holding all the Kingdoms
    alone isn't sufficient, you also need to hold all the counties
    and baronies.

    There's often a county at the edge of the Empire that has been missed.

    To check whether you have everything, you can either enter the De-Jure
    Empires map mode and scan the borders to see whether the borders
    don't match up, and inspect all the counties to see if there's any
    small flags; or you could locate the Empire in the title menu, check
    the de-jure mode box, and walk through the de-jure vassal titles to
    see if any are highlighted in red.

3.  Can I use your mod in my mod?

    You can easily do this by just copying all the files from my mod
    into yours, as I've been careful not to override any existing files.

4.  May I use your mod in my mod?

    The mod is permissively licensed, so I couldn't stop you from doing
    so even if I wanted to.

    Giving me credit for the contribution would be nice, but you aren't
    required to.

5.  Why shouldn't I use your mod in my mod?

    You don't need to merge my mod into yours to have the functionality
    provided by my mod.

    You could instead list it as a recommended mod to install alongside.

    It becomes extra work for you to update your mod if you want to
    include a new version of my mod in yours, whereas if people subscribe
    to my mod then it's all automatic.

    You may accidentally break someone else's mod if both you and they
    include my mod.

    On a more personal note, it means that I don't get feedback on
    whether people like, or are actively using my mod, so if Paradox
    add a new feature to the game engine that would make my mod better,
    I may not think it's worth the effort to improve this mod.

6.  Given the above, why might I still want to include your mod in my mod?

    If it's a total conversion then it's less likely that there'll be
    other mods installed that would conflict, so you don't need to worry
    about that.

    Any changes to my mod will be focussing on improving the core features,
    but it's possible that your mod may conflict with a future version
    of my mod. So including a specific version of my mod would prevent
    updates to my mod causing problems.

    If you heavily depend on functionality provided by my mod, then
    including my mod would prevent your users from having broken
    installations if they forgot to include my mod.

    I'd prefer this were handled by creating a steam workshop collection
    of the kind "Items that work together", so you get a subscribe to
    all button to handle ensuring everything needed is instaled, but if
    it's a regular occurrence that your users fail to install dependent
    mods, then it may be the best approach.

TODO
====

*   Consider how best to balance the decisions.

    Perhaps High Kingdom as King should have a prestige cost, and High
    Kingdoms as Emperor should require Imperial Administration.

*   Consider how to create Viceroyal High Kingdoms for Vassals.

    It's undocumented on ck2wiki.com, and there's no explicit announcement
    of how to do it in the ChangeLog, other than for history files.

    If there's no way to create the titles as Viceroyal, then I'll have to
    create the title in the scope of the Emperor and Viceroyally grant it.

*   Refactor the logic into character flags for potential High Kings,
    so the selection logic can be the same for yourself being eligible
    and your vassals being eligible.

    Triggered modifiers may be the most convenient way to do this, but
    there's no drop-in directory for them, see Feature request 4.

    This can be accomplished with `character_event`s and `character_modifier`s,
    but it requires more code and complexity than would be saved.

Bugs
====

*   The old Kingdoms can still be created as Titular Kingdoms.

    See feature request 1.

*   Titular Kingdoms don't contribute towards when the decision appears.

    This may either be a bug or a feature, but I don't have the choice.

    See feature request 1.

*   Making a High Kingdom for a Duke vassal grants the de-jure lands,
    but in the process the Counts become directly your Vassal.

Feature Requests
================

1.  Checking whether a title is active or changing the active status of
    a title requires it to be explicitly named.

    This is sufficient for base-game, as the events are tied to specific
    titles, but I need to be a lot more dynamic.

    To be able to handle this, I need to be able to pass a reference like
    `PREV` or `THIS` to `is_title_active` and `activate_title`.

2.  Allow the `empire` scope to be used on empire tier titles.

    I need two different decisions to handle making High Kingdom titles
    when I'm an Emperor or a King. If I could get an empire scope from
    an empire then the same logic would fall through.

3.  Allow drop-in directories for triggered_modifiers.txt

    I need a flag for eligibility for High Kingship, but it's annoying to
    have to trigger an event to add the flag and an event to remove it,
    and define the flag itself, so it would be convienient to be able
    to put all 3 in the same definition.