####################################
### WAY OF KINGS ARTIFACT MODULE ###
###          README              ###
###        by  Tobbzn            ###
####################################
# This is a near-complete rewrite of Godherja's standalone Artifact Module. They deserve credit for providing the original version which we reverse engineered into this.
# The module retains all the functionality of the Godherja Artifact Module but aims to make it easier to work with and maintain by refactoring and automating the back-end systems. The result is that functions like
transfer_all_artifacts = {A = char1 B = char2}
# are trivial to implement and are now easily accessible if you wish to tie that in to your custom inheritance rules or events, for example. The above is implemented by
for_all_artifacts_nofix = {APPLY = transfer_artifact A = $A$ B = $B$}
# Here the "_nofix" entails that the $ARTIFACT$ argument which will be sent to the transfer_artifact function will not have any prefixes or suffixes appended to it. You should think of it as equivalent to
for_all_artifacts = {APPLY = transfer_artifact PREFIX = "" SUFFIX = "" A = $A$ B = $B$}
# but empty string arguments are not handled very well, and should be avoided by using nofix.

# This module is also much easier to update with new artifacts, artifact slots or artifact types.
# Instead of manually repeating commands hundreds of times throughout the code, there is now only one master list of artifacts in the script:
# scripted_effects/artifacts_custom contains the list that is invoked to apply custom functions that are added by modders, like 
transfer_artifact = {ARTIFACT = artifact_11 A = character:1 B = character:2}
# which will transfer artifact_11 from A to B.

# From these lists, we generate a set of global variable lists of flags, and those lists are named with the format 
#    global_artifact_list_TYPE
# where TYPE can be all, handheld, armor, headgear, jewelry, mount, shard or fabrial. 
# The GUI functionality depends only on the flags in these lists.

## NOTE FOR ADVANCED MODDERS (and enthusiastic beginners):
# To use complicated strings as arguments, you MUST call the lowest-level artifact list *directly*, because strings will get resolved after being passed from one function to the next, and functions such as for_all_artifacts_nofix actually just call the lowest-level lists with empty prefix and suffix strings.
# This is what allows for code injection in the first place, so it's not so bad - it's the closest we'll get to having global lists of strings accessible for scripts in this engine.
# I have not been able to find a reliable workaround, but there might exist one if one implements arguments of the form TYPE = "$TYPE$".
# This restriction includes empty "" strings! Those are perhaps the most complicated of all!

##### How to include the module in your own mod
# Add the line 
#       initialize_artifacts = yes
# in the effects of your on_game_start, in the file common/on_actions/game_start.txt.

##### How to add artifacts to characters on game start:
# If you want your characters to have artifacts, you can either add them via an on_action or via character history. In the character history, this is done by adding the
867.1.1 = { # <- Date, useful if you have bookmarks at different times
    effect = {
        add_artifact = {ARTIFACT = artifact_5}   # <- Replace artifact_5 with whichever artifact you want.
    }
}
# inside the scope of your character. For an example of how to do it via on_actions, look in common/on_actions/artifacts_on_actions.txt

##### How to add a brand new artifact: 
# 1. Choose a name for your artifact, henceforth referred to as "(ID)".
# ID can be an integer like 534 or a string like Supersword_420_xoxo.
# The benefit of choosing an integer between 32 and 999 is that you won't have to manually add lines to the texticons to get an icon loaded, because we already added those.
# The mod will automatically detect .dds image files with path gfx/artifacts/artifact_(ID).dds 
# 2. Add the line 
#     $APPLY$ = {ARTIFACT = $PREFIX$artifact_(ID)$SUFFIX$ A = $A$ B = $B$ }
# to one of the for_TYPE_artifacts functions in common/scripted_effects/artifacts_custom.txt
# 3. Add the effects of equipping the artifact in common/modifier/artifact_modifiers.txt
# 4. Add the localization to localization/english/artifacts_loc_l_english.yml or the equivalent if you're localizing for a different language. Inspect the examples in the existing file.
# 5. Add an icon to the gfx/artifacts folder as artifact_ID.dds
# 6. If your ID is not an integer between 32 and 999, you need to copy one of the entries of gui/artifact_icons.gui with your (ID). You can then choose whatever icon path you want.

##### How to add a new artifact slot or type(such as handheld artifacts or armor):
# Add your type or slot to the appropriate lists at the start of artifacts_custom.txt
for_all_slots
for_all_non_slots
for_all_rarities
# Useful functions to add to your type:
#for_TYPE_artifacts_prefix
#for_TYPE_artifacts_suffix 
#for_TYPE_artifacts_nofix <- Particularly useful as the global list system is dependent on it. Functionality may break if you don't add this (towards the end of the files)
#for_TYPE_artifacts_no_arguments <- Useful for tinkering
# These can be copied from an existing slot or type; just change the TYPE in their name to match your type.
# Then add your type to listify_all_typed_artifacts_as_flags, also in artifacts_custom.txt
# Finally add your type or slot to artifact_triggers.txt in the scripted_triggers folder and add customizable_localization in the customizable_localization folder.

### File reference list:
## These are of interest to casual modders who just want to make artifacts and such:
# common/scripted_effects/artifacts_custom.txt: Defines a list of artifacts for custom functions or functions with multiple variables to apply to, such as set_variable = {name = $ARTIFACT$ value = flag:$ARTIFACT$}
# common/scripted_effects/artifacts_scripted_effects.txt: Provides a toolbox of useful functions that can be run on the custom artifact lists, such as transfer_artifact, transfer_all_artifacts, add_artifact (now with an effect tooltip!) and listify_typed_artifacts_as_flags. Also provides some AI functionality, since the AI can't use the GUI.
# localization/english/artifacts_loc_l_english: Defines all the text stuff like the actual name that'll show in-game when you reference your ID.
# common/modifier/artifact_modifiers.txt: Provides the character bonuses to having an equipped artifact.
# gfx/artifacts/ : The folder to put your icons in if you want your icons to be automatically detected.
# gui/artifact_icons.gui: Add an entry for your custom artifact if your artifacts are too cool to be named artifact_434 or whatever.

## These are of interest to advanced modders. Most of their functionalities are completely dynamic and can handle new artifacts automatically.
# common/scripted_triggers/artifact_triggers.txt: Provides a lot of checks for whether a character has an artifact of a given type.
# common/scripted_gui/artifact_scripted_gui.txt: Hooks into what happens when buttons are clicked in the gui, such as making sure a sentient artifact talks to you when you equip it.
# common/on_actions/artifact_on_actions.txt: Periodically asks the AI to use artifacts, determines what artifacts exist on game start, and defines default inheritance behavior.
# common/custom_localization/artifacts_custom_loc: Parses localization for the GUI in a dynamic way, such as identifying what your types and rarities are called.
# common/scripted_lists/00_artifact_lists.txt: Provides a scripted list to use in on_actions for performance reasons.

## These files are just happy to be here; the rest of the mod works with or without them.
# common/decisions/gh_artifact_decisions: The source of the Make Artifact decision.
# events/artifacts_system_events.txt: Some events that may happen at war.
# events/gh_artifact_creation_events.txt: The event that fires when the Make Artifact decision is made.
# common/character_interactions/00_artifact_interactions : Lets you gift artifacts.
# common/opinion_modifiers/00_artifact_opinion : Add some opinion when you gift someone artifacts. 

## These files are for debugging:
# common/character_interactions/01_artifact_debug_interactions : Lets you steal all artifacts from the target.
# common/decisions/artifact_debug_decision : Gives you all artifacts.

## Most of the gui files are too complex to explain here. They make the sidebar GUI and the Gift Artifacts GUIs work.

## These are deprecated:
# common/effect_localization/artifact_effects : I can't figure out how to pass the artifact flag names through this effect localization.
# common/scripted_effects/artifacts_core.txt : These could be used for simple functions like has_variable = $ARTIFACT$ but they're really not necessary so long as you can create a custom function that does the same thing. Not really any point to maintaining these functions.