Introduction to Content Development

Did you ever stumble over an obvious mistake in the game like a spelling error? Did you consider posting on Mantis but felt it was just not worth it? Would you just have corrected it if given the means? If so, keep reading, this tutorial is for you.

This tutorial lists an easy way to contribute to Illarion development by fixing mistakes such as spelling errors yourself. It gives a basic introduction into our development process and policies, i.e. what you need to know to contribute to Illarion development.

Illarion uses a free revision control system called Git. Git was initially designed for Linux kernel development. With Git, various developers can work on one project simultanously without causing conflicts between commits of different developers. One can also define development branches. The running game is not affected by the development. Using Git is quite challenging for beginners. Once you get used to it, it is really simple, promise!

Setup

Prerequisites

Remarks

  • Note that GitHub is not affiliated with Illarion in any way.
  • You can use other editors, but if you do it is on you, since they might not meet my definition of modern and good.
  • For each step with Git, also the console commands are given.
  • Illarions team language is English. Thus, it is reasonable to use the English versions of the tools. This way, you don't have to ask for translations if a problem occurs.

Preparations

  • Open this page with your internet browser: https://github.com/Illarion-eV/Illarion-Content
  • Click on "Fork" to copy the game content repository to your GitHub account.
  • Your Illarion-Content fork URL will look like this: https://github.com/<your_account_name>/Illarion-Content

Windows/Mac

  • Start SourceTree and follow its instructions.
  • Open the "Options" from the "Tools" menu and select the "Default text encoding" iso-8859-1, click OK.
  • Hit "Clone / New".
  • Insert the "HTTPS clone URL" from your github fork as "Source Path / URL".
  • Insert the destination path where another copy of the content repository will be stored, this time on your hard disk.
  • Hit the "Clone" button. (You have now copied the entire game content twice already!)
  • In the "Repository" menu click "Add Remote..." and "Add" a remote with the name "upstream" and URL https://github.com/Illarion-eV/Illarion-Content

Linux/Console

  • git clone [your github fork url]
  • git remote add upstream https://github.com/Illarion-eV/Illarion-Content

General workflow

Find and correct the error

  • Write down the exact phrase containing the error, keep it as short as possible, since you might encounter multiple occurrences of the error.
  • In Notepad++ select "Find in Files..." from the "Search" menu.
  • Enter your phrase under "Find what" and select your copy of Illarion-Content under "Directory".
  • Hit "Find All" to list all occurrences of the error.
  • Review these and either use "Replace with" and "Replace All" to fix everything, or open each file by double-clicking the mentioned lines, replace manually and save.

Share your work using Windows/Mac

  • In SourceTree, right-click the "upstream"-remote in the left hand side list, select "Pull from upstream" and choose "master" as "Remote branch to pull" to update your local copy with the version currently in the game.
  • You need to click "Refresh" first if "master" is not listed.
  • Click the "Commit" icon in the top bar to prepare a set of changes to send.
  • View your changes by selecting each file, then add them to the commit by using the single arrow up or add all of them by using the double arrow up.
  • Enter a meaningful commit message in imperative (like I did here). It should be something like, "Fix spelling error in NPC John Doe". If you need more than one line, use a short descriptive title and leave the second line blank.
  • Finally hit the "Commit" button to store your changeset locally.
  • Hit the "Push" button in the upper bar and confirm with "OK" to send your changeset(s) to your Github account. You will need to enter your GitHub login the first time at least.

Share your work using Linux/Console

  • git pull upstream master
  • git add [files to commit]
  • git commit
  • git push

In both cases

  • In your Illarion-Content fork in your GitHub account you will now see your latest commit message title (after refreshing).
  • Click "Pull Request" right above that message and for the last time review your changes before confirming with the "Click to create a pull request for this comparison" link.
  • If the automatic title is not descriptive enough, add a comment.
  • Finally hit the "Send pull request" button. You will be notified via e-mail when your changes are pulled. Soon after they will appear in the game.
  • Well done! Thank you very much for improving Illarion!

Further steps and options

  • Write your own NPCs with easyNPC.
  • Shape the map with the map editor.
  • Create quests or help developing the fighting and magic system.
  • Illarion uses Lua 5.2, a book covering Lua 5.0 (very similar) is available online.
  • See the Illarion extension to Lua.
  • Get your own local Illarion server to play around with.
  • Learn more about Git, the fast and distributed version control system.
  • Talk to our content developers in the IRC chat (#illarion on QuakeNet).