Add README as Ledmitz asked, along informations

2 files changed, 66 insertions, 1 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0588705
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# The Mana World Classic Official Mods
+
+In this repository, you can find all our upstream mods.
+
+## Making a new mod
+
+1. Make a subfolder with the name of your mod. It should be ASCII and short.
+For example, if your mod is "Brilliant City", try calling it "brilliant_city"
+2. The folder root level is the equivalent to client-data root. So if you want to
+replace graphics/sprites/npcs/lamppost.png, you will add your new version to:
+`brilliant_city/graphics/sprites/npcs/lamppost.png`
+3. The exception is for monsters: It is safer to add them to
+`brilliant_city/mods/monsters.xml` or editing monsters.xml in mods folder directly.
+This file support includes.
+4. Make a PR to the official clientdata repository, changing mods.xml to add the
+following content:
+`<mod name="Brilliant City" description="Replace lamppost" help="COPYING" localdir="mods/brilliant_city/" />`
+
+A developer will further instruct you on how to e.g. optimize monster database for
+redistribution. In theory, your mod should be able to run regardless of upstream
+changes, but keep an eye out and maintain it just in case. Outdated mods may be
+removed.
+
+## Upgrading a local override to a mod
+
+Follow the same procedures above, moving all the contents of local/ to your
+subfolder. Make the PR to the official client repository from #4 and you're
+good to go.
+
+## Upgrading a local override for non-conflicts only
+
+If you want to retain your changes as a local override, but want to take the
+advantage of the mod system so they don't enter in conflict with upstream changes,
+it is also easy! This is specially important depending on what your mod does.
+Keep in mind that there's no way to support map changes easily, in either way.
+
+First of all, create `mods` folder inside the local overrides folder.
+
+If you plan in having multiple local overrides, create subfolders for them.
+
+Transfer all your changes to monsters.xml to mods/monsters.xml
+Transfer all your changes to items.xml to mods/items.xml
+
+* You can also uncomment the `<include>` statement in mods/monsters.xml if you
+never changed monsters.xml but has changes in a monsters/ folder in client-data.
+If you don't know what this is about, then you're not using an outdated local folder
+and can skip this bullet point.
+
+You can now follow the above procedures, but changing mods.xml in local/ folder,
+and this will spare you from merge conflicts. If you're using monsters/ folder,
+though, which is now deprecated, you can skip this part - just uncommenting the line
+should have done the magic for you.
+
+However, if you move `monsters/` folder to `mods/your_name`, and update
+mods/monsters.xml to point to your folder instead, you can submit it as a MR to the
+mods repository (along the changes from #4) and TMWT may, in the future, distribute
+your mod for anyone interested!
+
+## Disabling a mod temporarily
+
+In settings, the last tab should be "Mods". You can disable their checkbox, and
+the next time you login, they'll not be loaded.
+
+
diff --git a/monsters.xml b/monsters.xml
index 445b2fe..69fde3a 100644
--- a/monsters.xml
+++ b/monsters.xml
@@ -3,6 +3,7 @@
     <!--
     Each mod folder should append here if they edit monsters. For example:
     <include name="mods/leds/monsters.xml">
-    If you're using a local copy, you can also edit this file directly?
+    If you're using an outdated local copy, you can uncomment the following line:
+    <include name="monsters/_include.xml">
     -->
 </monsters>