Official Epistory Guide to Modding

The official guide to modifying Epistory's dictionaries, translating or changing the script, and adding new keyboard layouts.

Introduction

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.

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 . 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.

Further detials, 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.

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.

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 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.

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: 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.

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, test and submit

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.

Testing without steam

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

Uploading to steam

• 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.

Testing in game

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!

[MasterZoen]

@AvatarShinobi It was a good story, but I found it obvious and didn't feel that there were any surprises.

[AvatarShinobi]

One of the berst games that I played! Pay attention at the story over the game and have a very good surprise at the end! That was shocking amazing!

[rin_jugatla]

@MrJacques Someone may be able to help you if you ask on the official Discord server.

[MrJacques]

I'm having an issue with a custom dictionary. When I use it, I get no_word for the magic abilities. I've tried different combinations of file names for the mod file and language in the file as well as adding a language file and editing that. Any help would be appreciated, thanks.

[RexVonTerror]

Someone please help me, I'm struggling to change the keyboard keys from WASD to ESDF
I had installed a mod through the workshop but it isn't working in-game... This is so annoying as it is the thing that made me rage quit the game two times already.. I have only played 3 times... 2/3 rage quit over the movement keys.... doesn't look too good if you ask me. I have tried in the Input Options when you start the game and that too doesn't work... This is so frustrating and now I cannot get my money back....

[LeLobster]

The modding/workshop is broken on Linux and Mac. No matter what you try, the game won't recognize that files are present in the Mods folder. And subscribed workshop mods show up in the options but just refuse to activate ingame.

[此事断不可声张女士]

I would like to know the scoring mechanism of Epistory. When I played in the arena, my combo score was not included in my total score after my death. I played three or four times like this:(

[bronze.sparrow]

Is Hebrew supported by the modding system, by any chance? I tried following the instructions above, with no success.

[alburdet619]

Is it possible to use modifier keys? I'm a developer and recently got an Advantage2 keyboard with all the keys like command, option, etc on thumb triggers and the arrow keys are in an odd place. It's it possible to use these and other special characters {} [] ; ?

[rin_jugatla]

I made a Japanese-English dictionary (ex. 狐/Kitune -> 狐/Fox). I put this in the MOD folder and played it. However, only "Fox", "Apple", etc. are displayed and Japanese is not displayed. How can I make a Japanese-English dictionary?
In writing on 2/8 heheooo seems the same thing happens in Chinese.