Posted October 18, 2016
high rated
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).
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: 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.
How to create a dictionary
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.
Basic steps
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 (cell A13). This can be a language, or just your own name for the dictionary (e.g. Italian, Pirates, MyAwesomeDictionary)
- Each column represents a different category 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 "export" button in column A. The dictionary file will be created next to the excel file. Its name will be "dictionaries_[name used in second step].json".
- You can create several copies of the base worksheet to have several new dictionaries in one big excel file.
Further details, tips & tricks
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.
That many 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 colored background to structure the document or to disable a word.
We will cover how to use/submit the dictionary in the last section.
How to add a keyboard layout
Adding the keyboard related dictionary
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 the 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 colored background are ignored, and a column will "end" in the first empty cell.
Setting up the controls
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: 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 currently 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.
How to translate the game or alter the story
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".
How to package and test
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. 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.
file list: "controls_(modname).json" - "dictionaries_keyboard_(modname).json" - "dictionaries_(modname).json" - "story_sentences_(modname).xml"
Once you have all the files ready, it's time to package them in a way that makes sense to the game. Go to the game's folder and add/access the "Mods" folder. Create a subfolder. Place your modded files inside that subfolder.
| Epistory
|-Epistory_Data
|-Mods
|--MyOtherMod
|--MyMod
|---controls_MyMod.json
|---dictionaries_keyboard_MyMod.json
|---dictionaries_MyMod.json
|---story_sentences_MyMod.xml
|-Epistory.Exe
Once you have the modded files in the correct folder, 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!
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).
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: 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.
How to create a dictionary
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.
Basic steps
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 (cell A13). This can be a language, or just your own name for the dictionary (e.g. Italian, Pirates, MyAwesomeDictionary)
- Each column represents a different category 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 "export" button in column A. The dictionary file will be created next to the excel file. Its name will be "dictionaries_[name used in second step].json".
- You can create several copies of the base worksheet to have several new dictionaries in one big excel file.
Further details, tips & tricks
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.
That many 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 colored background to structure the document or to disable a word.
We will cover how to use/submit the dictionary in the last section.
How to add a keyboard layout
Adding the keyboard related dictionary
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 the 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 colored background are ignored, and a column will "end" in the first empty cell.
Setting up the controls
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: 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 currently 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.
How to translate the game or alter the story
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".
How to package and test
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. 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.
file list: "controls_(modname).json" - "dictionaries_keyboard_(modname).json" - "dictionaries_(modname).json" - "story_sentences_(modname).xml"
Once you have all the files ready, it's time to package them in a way that makes sense to the game. Go to the game's folder and add/access the "Mods" folder. Create a subfolder. Place your modded files inside that subfolder.
| Epistory
|-Epistory_Data
|-Mods
|--MyOtherMod
|--MyMod
|---controls_MyMod.json
|---dictionaries_keyboard_MyMod.json
|---dictionaries_MyMod.json
|---story_sentences_MyMod.xml
|-Epistory.Exe
Once you have the modded files in the correct folder, 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!
Post edited October 18, 2016 by TheThibz
