Welcome to the modding guide for Epistory!

First things first: modding is enabled for all non-programmed elements - meaning anyone with Excel can join the fun! Modding should also work with OpenOffice Calc (but this hasn't been tested). Note that modding does not support not roman/latin alphabets.

Everything in the zip file below this contains major spoilers. It's like reading the script before seeing the movie. You have been warned.

You should start by getting the latest version of the dictionaries and script here: http://www.epistorygame.com/epistory_mod_files.zip

The zip contains three files:

• EPISTORY - Dictionaries-vba.xlsm is a dictionary file. Dictionaries contain all the words the player types.
  
• EPISTORY_script.xlsm is a script file, containing all the all the sentences and words that the player doesn't type. These range from story text to menu items.
  
• controls_qwerty.json contains key bindings for the game.

The goal here is to add, change or translate the words the player has to type. When you open "EPISTORY - Dictionaries-vba.xlsm" you will see 3 worksheets. The Instructions sheet contains basic instructions (the same which our translators used) to help navigate the document.

The other two tabs are where the magic happens. Let's do this step by step:

• Duplicate the "Dict - ENGLISH" worksheet. Name the copy whatever you like.
  
  
• In your copy, change the value of the language used . This can be a language, or just your own name for the dictionary (eg Italian, Pirates, MyAwesomeDictionary)
  
  
• Each column represents a different catagory of words, which will be displayed by the game at the appropriate time. For example, the ChestShort, ChestMedium and ChestLong columns contain words which appear on treasure chests. You can start editing the words in each column. Note that you cannot add, rename or remove the column headers.
  
  
• Some words have a || separator in them, like "animal||lamina". Some interactive elements require two, three or more words at once. For example, the twin statues.
  
  
• Once you are done, press the button in column A. The dictionary file will be created next to the excel file. Its name will be "dictionaries_[name use in second step].json".
  
  
• You can create several copies of the base worksheet to have several new dictionaries in one big excel file.

The magic names in the cells A16-A19 are irrelevant. If you want/need to change the words the player has to type for switching magic, you will have to create a new translation (see the "How to translate the game or alter the story" section)

The last tab is only for keyboard layouts and will be covered in the next section.

Spaces are allowed, you can write a whole sentence. Be careful that the player may not have time to write a lot of words.

The quantity of words can seem daunting but if you so desire, you can have only 1 word per column.

Note that there are two special rules for each column. Firstly, the column is considered "done" when it reaches the first blank cell. Any further words will not appear in-game.


Secondly, any "non-white" cells are treated as comments - they don't appear in-game either. You can use a coloured background to structure the document or to disable a word.

It this example, the game will stop reading words at remit||timer and ignore "gi".


We will cover how to use/submit the dictionary in the last section.

To add or change a keyboard layout, you first need to configure the dictionary for special character sequences - like the home row. To do this:

• Open "EPISTORY - Dictionaries-vba.xlsm" and duplicate the "keyb - QWERTY" tab.
  
  
• Set the name of the keyboard layout in cell A13. Be careful how you name it - you will have to use the same name later.
  
  
• The "words" here are patterns on the keyboard. Lines, 4 letters next to each other and mirrored letters (draw a line between "F" and "J" on a qwerty keyboard and use it as a mirror).
  
  
• Don't forget to add the || separator between repeated letters when creating patterns. Each will appear as a different word in game, but is treated as a single word by the system.
  
  
• Press the export button (in column A) when you are done. The file will be created next to the excel document. Its name will be "dictionaries_keyboard_[name used in step 2].json".

Like regular dictionary words, there are two special rules on cells (you might want to check the previous section for more information about this). Briefly, any cells with a coloured background are ignored, and a column will "end" on the first empty cell.

Once you have updated the dictionary, it's time to modify the controls. Duplicate the "controls_querty.json" and start modifying it. The name used for the keys are the same names as defined by the Unity documentation here: http://docs.unity3d.com/ScriptReference/KeyCode.html

The syntax for each key binding is as follows:

"HideMessage":"Tab" --> The game action "HideMessage" is bound to the key "Tab"
"PauseMenu":["Tab", "Escape"] --> The game action "PauseMenu" is bound to they keys "Tab" and "Escape".

The following actions are available:

• HideMessage: Removes the tutorial text
  
• PauseMenu: Displays the menu
  
• CancelWord: Cancel the current typed word
  
• ToggleWrite: Toggles writing mode
  
• ToggleSprint: Toggles sprint
  
• LeftUp, RightDown, RightUp, RightDown: The recommended movement keys. In diagonals.
  
• AltUp, AltDown, AltLeft, AltRight: The alternative movement keys. In straight lines.

Name your file "controls_[name used for the dictionary].json".

As for the dictionary, packaging and usage will be in the last section.

The first step to translate the game would be to translate the dictionaries and add a keyboard layout (if your language requires a non-supported keyboard). When we say translate... well, you have access to the whole story. You won't be able to change the placement of sentences, but with some creativity you could rewrite the whole story.

To translate or modify sentences, open "EPISTORY_script-v2.4-vba-trimmed", which contains the game's script (and translations for different languages). As for the dictionaries there is an "instruction" tab which will help you navigate the document.

There are two important details to know here. The name of the language as it will appear in the menus can be found in the "Menu & HUD" worksheet, row 92. The words the player has to type to switch to another magic are in the same worksheet, rows 113 to 116.

You can ignore most background colors - except the red ones after the last relevant item. This is a "stopper" for the game's script parser and it should stay right where it is. Note that this means you cannot use a red background, or else you risk stopping the parser too early.



For each worksheet, fill in the empty "other" columns. You can rename them and add more if you want to create more than one translation at once.

Once you're done, you can press the "export" button in the "Instructions" page. The exported file(s) will be created next to the excel file. The "English" column will be exported as well. You can ignore the file if you didn't modify that column. The naming pattern is "story_sentences_[column name as written in the "Menu & HUD" tab].xml".

Let's review the files. If you did all of the steps above, you should have 4 files. You can have as few as 1 file if you only changed one dictionary. Ideally, they should all end with a common name ("my_mod" in this example). You also have to avoid conflicting names with existing hard coded languages/keyboards. Conflicting with other mod names is not officially supported, but should work in most cases.


Once you have all the files ready, it's time to package them in a way that makes sense to the game. There's two way to do that.

You can go to the game's folder and add/access the "Mods" folder. Create a subfolder. Place your modded files inside that subfolder.

• Create a folder (wherever you want). Inside place an image to act as a preview. It can be either png or jpg, it should be square. 200*200 pixels is largely enough.
  
• Create a sub folder and place your modded files inside it. I tend to name it "content" but any name is fine.

The next steps require the game to be launched.

• In the main menu, press/type the "Options" button and then the "Workshop" button.
  
• The item ID is used to update an existing mod. If your mod is new, please input 0.
  
• By default, the mod you upload will be set as "hidden". You will be able to review the title and the description before setting the item to public visibility. As well as adding more details such as preview screenshots.
  
• The "content folder path" is the full path of the folder where your modded files are (eg "C:\Users\ ... \my_mod\content"). The game supports copy & pasting.
  
• The "preview image path" is the direct link to your png/jpg (eg "C:\Users\ ... \my_mod\preview.png").
  
• The change note allows you to keep track of your different versions.
  
• When uploading a new mod, the item ID will be set with your assigned ID.

Once you have either the modded files in the correct folder or you have the files from the steam workshop, you can go to the options menu and change the language/keyboard there. Modded items should appear in the list of available languages and keyboard.

Have fun!