Andor's Trail

Contributing to Andor's Trail - Contribution Guide

Contributing to Andor's Trail - Contribution Guide

Posted: Sun Jan 26, 2014 11:01 pm

by Zukero

Hello fellow adventurers,

It's been a long time since I wanted to write this post, but time was missing, and I had to organize my ideas constructively to make it useful.
The intent of this post is to show you the way to start creating all types of content for AT. This will not necessarily be an in-depth guide to everything, but you should know that it has the words "DON'T PANIC" in large, friendly letters on the cover.

I have to thank our forum overlord sdevaney and long-time contributor and highly skilled writer ctnbeh13 who worked on a "How to contribute? What to do?" FAQ which I discovered after starting this one, and from which I borrowed full chunks of text and ideas. After all, reading ctnbeh13's words, I knew that my non-native English just couldn't compete...

Introduction

As an introduction, I should say that Andor's Trail is not your typical, content-craving, open-source project. The original author of the game, Oskar Wiksten, has a clear vision, not only for the gameplay and storylines, but also on the development process. For those who don't know him, he's very open-minded and thankful to the community, and doesn't have a fixed roadmap, but he's still our BDFL (benevolent dictator for life), so in the end, he decides what gets included or not.
The two following documents are a must-read to fully grasp how he sees Andor's Trail: his interview with Hookshot Inc. from March 2012 and the rationale of Andor's Trail on the wiki.
Further reading, still on the wiki: the world of Andor's Trail, and the already rejected ideas

Globally, the whole developer section of the Andor's Trail wiki is full enough of information for you to get started. Actually, that's what got me started. I just wanted to synthesize it all, and gather the useful links in one place. Moreover, some of it could use some update (ongoing), and some of it I just do differently. It is very possible that I will just end up copy-pasting some content from this post to the wiki in a further point in time.

Remember that Andor's Trail is open-source, and we are really open to all kind of contributions. After all, the more you contribute, the biggest the next update
Don't be afraid, we really appreciate all kind of suggestions. We will never ever send you back home or throw away what you did. If we think that something could be changed, or that some more work is needed, we will explain constructively why and how, and more generally help you out.

Moreover, you don't have to take on a task alone. You can team up with other members with whom you share an opinion on a feature to get it done.

ctnbeh13 wrote:There are an abundance of great ideas and suggestions, to which we welcome, appreciate, and encourage you to continue to offer up. One of the main factors that determines if and when these might see the light of day in-game is who has the time to commit to their development. This often applies to content that some might assume should just be added to the current workload of those who are writing the game code. Should you read of a fellow forum member's idea or suggestion that you may strongly agree with and support, taking the time to send that individual a P.M. to inquire about working together to make it happen, or work towards completion to the best of your ability, is another great way to contribute.

What can you contribute ?

There are many ways you can contribute to AT, in (more or less) increasing difficulty:

Spread the word to the world!

Visit the forum often, learn about the game, help the newbies, submit your ideas and discuss the others'.

Test the game and report bugs here. We consider each & every one of them seriously.

Become a moderator.

Translate the game! You are fluent in English, but natively speaking something else ? Help us bring AT to your non-English-speaking grand-parents !

Create content : maps, quests, items... whatever.

Get to code !

For the first one, I'm sure that if you enjoyed AT as much as to read this post, you already do.

ctnbeh13 wrote: Simply recommending giving Andor's Trail a try, to someone you know, is perhaps the easiest and most effective way to contribute to the game and its continued development and success. A pleasant number of current contributors came to learn about Andor's Trail by word of mouth, and are helping not only to shape the direction and development of it, but are also helping to increase overall productivity.

For the second one, if you read this, you are already well-equipped to do so, and I have nothing to add, unless you haven't registered yet. I have no doubt that after reading a few of the posts, the "register" link will start looking very attractive.

For the third one (testing, bugs...), I'm serious. If during your play-time, something seems strange to you, or your device displays things wrong, anything, do not hesitate one second, and create a topic describing your issues in the Bugs section of the forums.
Make sure to include as many useful info as possible, most notably your device brand and model, your android version, and the circumstances in which you encountered the issue.

ctnbeh13 wrote:Whether playing an alpha, beta, or a current release version, paying attention and keeping a record of the details at any time you might encounter anything you might find to be unusual, unexpected, inconsistent, or undesirable behavior, is extremely helpful in making the game play experience better for all in a following release. Some things that you may discover may not truly be a bug or another type of error, but if it is undesirable behavior, it probably will deserve the same attention as a true bug.

Becoming a forum moderator is not as hard as it sounds. Hey! I managed to become one! It is however a demanding activity, and while this may not be the largest forum on the interwebs, there's some work to do. Read sdevaney's job position description and see for yourself if you think you have what it takes!

ctnbeh13 wrote: Being a forum moderator serves a genuine necessity in keeping a successfully running forum, running successfully. This position definitely has its perks, such as, maximizing your community involvement, building relationships, recognizing valuable insights, feedback, new ideas, solutions, and general ways to improve the overall forum and game play experience for all, and then passing that information on to those who can best implement them. Most often, this information is carried over to the meeting agenda for us to review and discuss during our development team meetings. This position also allows for fairly efficiently addressing the needs and questions that all forum members have from time to time. While this position can be very rewarding, it does require a good measure of patience, restraint, and self-discipline when dealing with the occasional challenges, all while allowing opportunities for personal growth. No need to worry, because aside from the policing of spam and mediating between forum members who may have taken a debate to a new level that may not be appropriate, you always have a lead moderator and a forum administrator to rely on and guide you.

Translating the game is also a very important way towards world domination world fame for AT!

ctnbeh13 wrote:Fluent in more than one language? There's probably opportunities here for you to help make Andor's Trail available to a countless number of new players within some of the countries that the game has not yet been translated for.

With Andor's Trail currently being available in so many languages, it's almost inevitable that spelling and grammatical errors will occur on occasion. However, with that being said, please keep in mind that some dialogue will "intentionally" have spelling and grammatical errors to better represent a NPC's dialect, level of education, physical and/or emotional state, biological and/or mental age, etc.

About content creation, I cannot guarantee that your hard work will be introduced in the game, but if it's polished, fits into the game, and is well received by the community here, the chances are very high. The next section of this guide ("Content Creation") will give you the info you need to get started.

The code. It seems that every non-programmer in the world is afraid by simply seeing this arcane, obscure word. Just so you want to read further, I have to say that Andor's Trail is developed in Java, like (almost) all Android applications, and this is one of the easiest, most forgiving, and best documented programming language there is. Really, you can find Java tutorials suited for everyone, from the über-coder with 25 years of experience in Perl, Lisp & C++, to the 10 year old kid in Africa with access to a computer and the web 2 hours per week, passing by the 40-ish man that never touched a computer.
Furthermore, starting a program from scratch is not easy, but reading an existing one and adding little modifications to it is one of the most rewarding things to do when beginning.
If you know that already, and just want the short version, skip to the "Development" section of this guide.

If you are ready to publish content for Andor's Trail, there is a fine way to avoid the spoiling all your shiny new quest: the "Development Corner". It is a restricted area of the forum where contributors share their secrets.
To request access to this section, follow these instructions :

ctnbeh13 wrote:To be considered for access to the Development Corner, simply make sure that you are logged in to the forum, touch or click on "User Control Panel" at the top right hand corner of your screen, then at the top left corner area you will see "Options".
Below this, touch or click on "Usergroups" to display "Groups" and "Group details" in the main window.
It's under the "Group details" heading that you will find "Developers" under "Memberships".
To the right of this, in the "Select" column, touch or click on the gray circle to place a black dot in it, and then directly below is the "Submit" button.
Please verify that the scroll down box to the left of the "Submit" button displays "Join selected".
Touch or click on the "Submit" button at this point to request to join the developers group and have access to the "Development Corner".

Content creation

Who played AT without ever thinking "It would be awesome if I could find an item that does X"?
If this is you, and you want to go further, you are reading the right stuff.

The recommended workflow is the following :

Think about it for a while, take notes, and reach the point where it is more than just an idea that popped up, but something that you are confident about, that you could answer any question about it, that it has a story, and that it fits in Andor's Trail.

Post about it in the Ideas and Future development forum section. Discuss it with the community, get feedback, enhance your idea, explain it. If it sounds universally rejected by the community, don't waste your time. Either move on to a new idea, either rework it before submitting it again.

If you can, debug it and test it yourself (see the "Development" and "Content Integration" sections of this guide).

At this point, you may want to avoid spoilers (depending on what you created. When creating maps and quests generally), and thus you should request access to the "Development Corner". A private section of the forums where content creators submit their works away from the eyes of the mere mortals (See at the end of the introduction for instructions).

Submit your works on the forums.

If you can, submit a patch to me on github with your fully integrated work (see the "Development" section of this guide).

Pray your favorite divinity until your submission is accepted and included in the official development branch of the game. If your favorite divinity is made of paper with presidents faces on, I warn you now : bribing the dev team IS NOT the way to go.

Ok, you should now start to get how we work. Now, it's all about how YOU work.
There are mainly three type of content you can create for Andor's Trail :

Graphics

Maps

Game objects (items, NPCs, quests, dialogues...)

Graphics

Posted: Sun Jan 26, 2014 11:03 pm

by Zukero

Graphics

So you're an artist, you love pixel art and you can draw?
Great! We really need new and/or improved tilesets, NPCs and item icons. That's what help other content creator make AT's world rich, surprising and worth exploring.
For the creation part, I can't really help you. You have your favorite tools. Even MS Paint can be a valid option.
What we need, technically, is PNG files, with a transparent background (RGBA colorspace), generally 32x32 pixels big.
Some rare bosses are 64x64, but don't make a merchant that big, right?
If you create several pictures, sort them by category, and make spritesheets.
What's a spritesheet you ask? It is a single image file with several 32x32 images side by side. Here is an example.

Maps

Posted: Sun Jan 26, 2014 11:04 pm

by Zukero

Maps

What would AT be without maps... map making is one of the easiest activities technically, yet is difficult to do right. No wonder the video game industry have employees known as "Level Designers" whose sole job is to create maps. Sure, AT is not your typical "Medal of Duty 14: Modern Field" with 3D levels that explodes everywhere, and lightning that make a fashion photographer's studio look like a single candle, but, it's still difficult to get it right on the first shot.

However, our master map maker, Ian (that's his name on the forum, you can PM him for any map making question you have. He's very nice and helpful) created two awesome tutorials about map making on the wiki.
There is the mapmaking tutorial and there is the advanced map making tutorial.
They are both quite up to date to this day, and I won't elaborate more on creating maps, because I couldn't do any better.

Making maps is nice, but our hero must be able to walk on them. So you will need a spot on the world map. Preferably, take a known dead-end on the world map, and start working from here. Our world cartographer is forum user Ian. He will help you find your place, and give you advice on how to make your maps fit in that region (don't put snow in the middle of a desert...). PM him.

Instructions on how to test your maps can be found in the "Content Integration" section, after the "Development" one. This is not absolutely mandatory, but improve your chances (and reduce the delay) to get your maps included in the game.

Game objects

Posted: Sun Jan 26, 2014 11:04 pm

by Zukero

Game objects

All the game objects (except maps) in AT are defined using JSON data files.
Here is the link to all the JSON files on my github repository
If you opened any of these, you could see that while it's plain text, it's also a plain pain to edit manually.
Fear not! Our awesome team created the Andor's Trail content editor.
This is a browser-based customized tool, but it is not a cloud-like tool. What I mean is that everything you create with it only exists in your browser's memory until you export it to a JSON file. It's not magically saved on andorstrail.com servers or anything. If your browser crashes while you were editing the last line of your long long quest... too bad. You lost it all.
So, just like in AT, save early, save often!

How to use this wonderful tool you ask? Well the wiki has a tutorial for that!
Read this carefully, as it contains loads of helpful info, including a step by step example of a full quest creation that covers NPCs, items, dialogues and quest log!
It is slightly outdated, as new features have been added since the tutorial was written, but the content editor is straightforward enough for you to understand them at first sight.

If something confuses you with the editor, don't hesitate to ask for help on the forums.

In addition to the web-based content editor, I have also developed a desktop solution: ATCS. You can find out more about it there http://andorstrail.com/viewtopic.php?f=6&t=4806
It has more features than the web-based editor, but is also slightly more complicated to set up.

Instructions on how to test your JSON files can be found in the "Content Integration" section, after the "Development" one. This is not absolutely mandatory, but improve your chances (and reduce the delay) to get your content included in the game.

Weblate data is synchronized with my Github repo (https://github.com/Zukero/andors-trail/), so as soon as I publish changes in the development source code, it should be available for translation (after a little while, time for weblate to crunch it on its own).

You will be shown the two sub-projects: "User Interface" (for buttons, tabs, etc.) and "Game content" (for quests, dialogues, items, etc.).
After selecting one of these, you will be prompted to choose your language in the list, or to add a new one.

Click on the desired language to be directed to the translation tool.

You can then select "Untranslated strings", "Strings with failing checks" or another category in the "Strings to check" box, in order to see only the strings that have not been translated yet, or can have errors.

Make your translations, and finally hit the "Save" button below to post them, or "Suggest" to propose your translation for review by other translators.

To see the original text structure, at least for dialogues, you should head to the content editor, or ATCS (recommended).
These are the tools we use to create almost all game content (except maps).

These instructions are for the web-based content editor. Instruction on how to use ATCS are in its dedicated thread.

From there, click on the "Import" button at the top right, then, select the "Import content from existing files" radio button, and use the drop-down list above to select first "Dialogues", then which file to import in the one below.
Weblate references the file including the asset you're translating, so you should be able to identify the desired file quite quick. It's on the right of the screen, in the "Source information" box, as "Source string location". The format is <filename>:<string_id>:0
Finally, click on the "Import" button below (the blue one).

Now, you can open the "Dialogue" category on the left, and select any sentence by its codename. I suggest you to try to find the beginning one, usually named npcname_start or npcname_start_select. Click on it, and then, you will see a "Show as tree" button.
Click on it to see the whole dialogue tree for that NPC, including answers.
If it is too big, you can zoom out (e.g. with Ctrl+Mouse wheel).
You can also click on a given sentence (prefer the NPC's sentences) to be sent to this sentence's editor, the click again on the "Show as tree" button to view the dialogue tree starting from this sentence.

For the location of the NPC, refer to Richard Faila's Andor's Trail Directory.
For the quest info, you can check the dialogue's sentences individually to see if they include a reward of "Quest progress" type. The number indicate the quest step reached. To see all steps from a quest (numbers, and associated quest log entry), you need to import the quests in the editor too (like you did for the dialogue), and check them out in the "Quest" category.

Create a new project in the IDE using the integrated GIT client to check out your own fork of my repository.

Download the Intel x86 system image in the android SDK manager (faster than the horribly slow ARM emulator), connect a device, or setup an Android VM, or any combination of these.

Configure eclipse/Android Studio to use your emulator/device/VM.

Done.

The steps should be same whether you are using Windows, Linux, MacOS X, FreeBSD, Solaris, whatever. This is Java after all.
However, this guide is intended for the widest audience, and will be based on windows. The Linux/Unix folks certainly know how to translate this anyway, and for the Mac OS users, well I've almost never used it, so they'd better refer to Google, or ask in the forums if they have issues.

The first part of this section is not reserved to developers, but to anyone wanting to debug Andor's Trail, build a custom version, or integrate their content. It will help you setup your computer with an Andor's Trail build environment.

Setup the build environment

Posted: Sun Jan 26, 2014 11:09 pm

by Zukero

Setup the build environment

The wiki has a tutorial for that too (it is right here), but I tried to follow it step by step at first, and found some steps to be missing, and it is based on the new Android Studio by google, based on IntelliJ Idea.
I found Android Studio to be not mature enough yet, and I have over 10 years of experience with eclipse, so I prefer using the eclipse ADT bundle. This guide will be based on this tool.

Let's start with the inventory. You will need:

A working computer. You don't need an hardcore gamer rig, just not too old one. I would recommend at least an "Intel Core 2" or similar CPU, with at least 2 GB of RAM. If you plan to use the emulator (not a real Android device connected to your computer), make that a Core i5 with 3 GB of RAM

An internet connection. It is "possible" to do without it (I did on one machine once) if you can download the binaries somewhere, and transfer them to your computer afterwards.

If on Windows, MobaXTerm. It's a neatly packaged way of getting most unix tools on windows.

A GitHub account. You could do without, and I will generally give instructions for both with and without

If you plan to contribute code and/or integrated content, the GitHub account becomes mandatory. Once registered, go to my repository on GitHub and click the "Fork" button, to create your own repository for Andor's Trail.

Now, we will set up your computer.

If you don't have one already, install the Oracle Java Development Kit.

Unzip the eclipse ADT bundle in a directory of your choice. This should create a folder named adt-bundle-<OS Name>-<CPU Architecture, i.e. x86>-<build date in the format YYYYMMDD>. For example, mine is adt-bundle-windows-x86-20130729.
Remember this location, as I will refer to it as your "ADT bundle install dir" or "ADT root".

Create an empty folder to be used as your "workspace". Create it wherever you want, depending on your setup. I generally create it under the "My Documents" folder, or under my "home" folder on Unix-type of systems. Give it a meaningful name, I use "adtworkspace", but you can use "android_projects" for example...
Also remember this location, as I will refer to it as your "workspace".

Now, open the ADT root folder (see, I told you I would refer to it !).
You should have two folders and one file inside it. The "eclipse" folder contains the code editor and the "sdk" folder contains the stand-alone, android-specific tools. The "SDK Manager.exe" file is a tool allowing to download new versions of the android SDK, new images for the emulator, and various other things that won't be used for Andor's Trail.

Open the "eclipse" folder, and start "eclipse.exe". After a short loading, Eclipse should prompt you to select your workspace. This is where you select your newly created workspace folder... pretty trivial huh?

Once eclipse finished loading, close the "Send statistics" window and the "Welcome !" tab. You should be presented with a window full of tools, buttons, panels.... pretty scary if you've never seen an IDE (Integrated Development Environment). Fear not, you will quickly see what really matters.
On the left of the window, you should see the package explorer, this is more or less like a file browser, but smarter.
The biggest part in the middle is the editor view. When you'll open files for editing, that's where they'll show up.
The bottom part is some kind of feedback area. The different tabs will show you information from different tools : errors in your code, console output of the game... we'll get to it later.

Right-click somewhere in the package explorer (on the left of the window. Click anywhere in the middle of it), and select "Import...".
Then, in the window that popped up, under the "Git" folder, select "Projects from Git" and click "Next".
Select "URI" and click "Next".
In the "URI" field, enter one of the following:
- https://github.com/<your github username>/andors-trail.git (If you forked my repository)
- https://github.com/Zukero/andors-trail.git (If you didn't fork my repository)
In the "host" field, enter accordingly to the URI you used (should be filled automatically anyway):
- github.com
In the "Repository path" field, enter what's after the ".com" in the URI, that is, respectively (should be filled automatically anyway):
- /<your github username>/andors-trail.git
- /Zukero/andors-trail.git
In the "protocol" field, select "https".
Then, fill the "Authentication"'s section "User" and "Password" with your GitHub credentials, or leave it blank if you're using the Google Code URI.
Click "Next".

You will be presented with a list of branches to select. Make sure that you have at least "master" selected, and click "Next".
Finally, for the "Local Destination" configuration, select a local directory (I use <workspace>/andors-trail), "master" as initial branch, and "origin" as "Remote name". Click next, and wait while eclipse retrieves the files from Git. Now, make sure that "Import existing projects" is selected, and click "Next". Finally, untick both "AndorsTrailEdit" and "ProjectPage" and click "Finish".

You should now see in your package explorer the "AndorsTrail" folder containing the very latest source code for Andor's Trail! Congratulations!

Unless you are very lucky, you should see in the "Console" tab at the bottom (remember, the "feedback area") a message in red like the following:

This means that you do not have the android SDK that matches the one currently used by Andor's Trail.
Note what target the message references. In my example, it is "android-19", meaning I need version 19 of the SDK.
If you are lucky, and do not see this message, you can be sure it will appear someday when we upgrade the project to a newer one. So read the next steps anyway.

Open the ADT root folder, and launch "SDK Manager.exe".
It will connect to the internet, to google servers, and fetch the information about what releases are available, what plugins are available.
If you want to know more, I suggest that you read the SDK Manager documentation, and more generally find information about "SDK Platforms" and "System Images".
If the download is successful, you should see a folder named "Android 4.4 (API 19)". That's the one we need (android-19, API 19, do you see the connection?). Expand this folder, and under it, and select the "SDK Platform" (tick its checkbox).

If you plan to use the emulator, follow the next steps:
Find the latest SDK version that has a line with "Intel x86 Atom System Image", and select both this line, and the corresponding "SDK Platform".
Then, if you have an Intel CPU with virtualization extensions (Intel VT-x) and are running Windows or Mac OS X, at the bottom, under extras, select "Intel Hardware Accelerated Execution Manager".
Click the "Install packages..." button to download and install the items selected.
Finally, run <ADT root folder>/sdk/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe and follow the instructions.
Back to eclipse, click the "Android Virtual Device Manager" button (looks like a smartphone with an android face on screen).
In the "Android Virtual Device Manager" window, make sure that the "Android Virtual Devices" tab is selected, press "New...", and fill the fields this way :

Now press OK.
Check that it works by selecting your new AVD in the list, and pressing the "Start..." button. It could take a while for it to completely start.

If you plan NOT to use the emulator
Make sure that your device enables remote debugging. On mine, it's in Settings->Developer Options->USB Debugging. If you can't find it,look for some help specific to your device on google.
Make sure you have your device's drivers installed on your computer.
Connect your device to your computer with an USB cable.
Open a command line (shortcut Windows+R, type "cmd", press enter), and type the following (adapt the folder names and drive letters):

Note: the emulator is way slower than a real device, even an old cheap one. A good alternative is an Android x86 VM, in VirtualBox, VMWare Workstation, or whatever. It's pretty easy to set up and gives great results. Google for help if you need.

Note 2: you can do both, and select at runtime whether to run Andor's Trail on your device, the emulator, a VM, or several!

Warning: running Andor's Trail this way on your device will overwrite the Google Play version, and can mess up your saved games. Make sure to do a backup of your saves, and remember to reinstall Andor's Trail from Google Play once you're done. I even had to delete the debug app from Google Play to reinstall it.

Alright, you should have everything you need to start Andor's Trail.
Press the "Run" button in eclipse (looks like a Green "Play" arrow), it should prompt you to select a physical device and/or AVD. After a few seconds (or minutes), Andor's Trail should start automatically. If not, try to launch it manually (it sometimes happens on my x86 emulator image).
If you are using the emulator, do not try to start a new game. Andor's Trail loads all the content at startup, and in v0.7.0, this content is huge, and several hours could not suffice... you would be looking at a never ending "Loading..." screen.

Anyway, at this point, your environment is set up basically. You have all the basic stuff to run/debug/edit the game and the contents to your liking.
There are a few other things you could do to make your life easier, but I will not describe them step by step. Consider this an exercise for the reader!

Configure Eclipse to open the .tmx files with Tiled.

Customize the view in eclipse by opening/closing/moving/resizing the "views" (hint : Window->Show View).

Get familiar with Git

Posted: Sun Jan 26, 2014 11:09 pm

by Zukero

Get familiar with Git

You don't need to become an expert, but some basics are mandatory.
I don't know which is worst before learning Git: having never heard of version control systems, or having used another one than Git.
I strongly suggest that you read the following articles, in the following order:

Note that the Git book uses exclusively commands in a terminal, but that we use eclipse. Try to identify how to do these things in eclipse. Hint: all the Git functions can be found using right-click on a file/folder/project, then opening the "Team" sub-menu.