v0.8.9 (Bugfixes + translations) released to Google Play!

Useful links
Source code of the game - Contribution guide - ATCS Editor - Translate the game on Weblate - Example walkthrough - Andor's Trail Directory - Join the Discord
Get the game (v0.8.9) from Google, F-Droid, our server, or itch.io

ATCS User Manual

Discussions of the development process of the game.
Locked
User avatar
Zukero
Lead Developer
Posts: 2028
Joined: Thu Jul 21, 2011 9:56 am
android_version: 8.0
Location: Eclipse

ATCS User Manual

Post by Zukero »

ATCS User Manual

This guide will help you install and configure Andor's Trail Content Studio (aka ATCS) on your computer, and create some content.

Downloads

You will need a bunch of files from the internet:
  • A Java Runtime Environment version 7 at least.
  • An ATCS release from here.
  • The source code of the game.
Additionally, you may find these tools useful (or even necessary) while dealing with ATCS: For Java, you may already have one installed. Check it by opening a command prompt (Win+R to open the "execute" dialog, type "cmd.exe ", and press enter) and running

Code: Select all

java.exe -version
If you get a reply saying that you have a Java version superior to 7, you're good to go.
Otherwise, head to http://java.oracle.com, and download the latest Java Runtime Environment Standard Edition :!: for your system.
They tend to change slightly the wording, or what gets acronymized, so you may need to look for the following:
- Java SE Runtime Environment
- JRE Standard Edition
- J2RE SE
- Java SE JRE
What you need is the most downloaded item, so it shouldn't be hard to locate.
Once downloaded, install it.

For ATCS, make sure to grab the latest release from the dedicated topic. There are two versions:
- If you are using your own windows computer, use this link:
Image
- In all other cases (windows without admin rights, MacOS, Linux, Unix, BSD...), use this one:
Image
For the source code of the game, don't be afraid, you won't even have to look at it.
Note that you can use several different copies of the source code, depending on what you want to build your content from, but we'll cover this later.
You have three options to retrieve a copy of the source code: After this is done, you should have the following files:
Image

Installation

The first thing is to create an empty folder to serve as ATCS' workspace.
The workspace is the folder where ATCS will store all working data. Every project you create, every setting you change, is saved in the workspace.
I suggest creating an empty folder named "atcs_workspace".

Then, if you didn't go the Git way to get the game sources, extract the contents of the zip file you downloaded. If you are using 7-zip on windows, I recommend using the "Extract to andors-trail-master/" option, as it will create a folder named after the zip file to contain all the contents of the zip.

You should end up with a folder like this:
Image

Now, if you downloaded the Windows installer release of ATCS, start the ATCS installer (ATCS_vX.Y.Z_setup.exe).
Image

Install it as you would for any software (Next, next, next... eventually change the installation folder...).
Image

If you downloaded the "zip file" release of ATCS, just unzip it in an ATCS folder, and, depending on your OS, you may also need to mark some files as executables (the ATCS.sh file at least, but maybe the whole folder).


First launch & configuration

:!: Important. For the first launch on windows, I strongly suggest running ATCS as Administrator. You may need a similar action on other systems depending on where you installed ATCS. The startup script will attempt to create ATCS.env.bat (on windows) or ATCS.env.sh (everywhere else) in the installation folder. This file is not necessary, but can help you customize the startup of ATCS in a way that is preserved upon upgrading ATCS.
You can close ATCS as soon as it started, and relaunch it as a standard user if you wish.

You can launch ATCS from the start menu:
Image

Alternatively, you can run the ATCS.cmd (Windows) or ATCS.sh (Linux, MacOS, BSD, Unix...) located at the root of the installation folder of ATCS.

When run, ATCS will ask you for the workspace to use:
Image

Use the "Browse..." button to select the empty folder you created earlier:
Image

Click "Ok" to start ATCS. The window will first appear like this:
Image

This is ugly. Drag the bars within the window to resize the different areas to your liking. ATCS normally remembers every change you make to its UI dimensions, and will restore the window dimensions at the next launch.
Image

To ease further explanations, here are the different areas of the ATCS UI:
Image
The notification area at the bottom is of little interest generally. I've been a bit too lazy in the code to make as useful as it should.
The menu bar at the top gives you access to all actions in the tool.
The project tree at the left is where you'll browse your projects and the game source. The right-click menu in the project tree gives you access to most actions you can find in the menu bar, showing only items relevant to your current selection in the project tree.
The editor area on the right is where you'll view and edit all game data. The tabs at the top let you switch between opened editors, and close the ones you don't need. The tabs at the bottom give you access to the different views offered by a single editor.

Let's configure ATCS to your liking by using the menu bar to reach the "File->Edit workspace settings..." menu item.
Image

You'll be presented with the following dialog:
Image
This will let you modify the way ATCS can launch an external tool to edit TMX maps (you'll most certainly want Tiled there) and an image viewer/editor.
The second part lets you prevent ATCS from connecting to the internet, or enable the translator mode (weblate integration) and version checking at startup.

Create a project

Let's try to do something useful now. Create your first project by using the "File->Create project..." menu item:
Image

You need to enter the following information:
Image

For the project name, make it meaningful, but please use only lowercase characters and underscores. For example, "dark_shadow_castle". I generally create one called "source_explore" only to browse the game content, and not create anything.

For the "AT Source" entry, use the "Browse..." button to reach the "AndorsTrail" subfolder of the downloaded game source:
Image

The project creation wizard will confirm that everything looks good:Image

Press OK to create the project. It will load the game source data, which may take a while. You can now use the project tree to browse through the existing content.
Image

Translator mode

In the workspace settings, if you allowed internet access and chose a language for translator mode, ATCS will help you review and edit translations on weblate.
Every translatable content text will be complemented by a translation bar below:
Image

You can see, left to right, a link to weblate, a status indicator (red, orange, green, or blue) and the current translation on weblate for this text.
The weblate link will take you directly to the desired page:
Image

The status indicator will also display a tool tip when you hover your mouse over it. It will give you additional information on the status of the translation. Mostly useful when the status is orange or blue.
Lvl: 78, XP: 8622632, Gold: 271542, RoLS: 1, ElyR: -, RoL: -, ChaR: 1, GoLF: 1, ShaF: 1, SRoV: 1, VSH: 1, WMC: 1, GoW: 1
HP: 71, AC: 301%, AD: 38-47, AP: 3, ECC: 50%, CM: 3.75, BC: 101%, DR: 2
User avatar
Zukero
Lead Developer
Posts: 2028
Joined: Thu Jul 21, 2011 9:56 am
android_version: 8.0
Location: Eclipse

Re: ATCS User Manual

Post by Zukero »

This topic is locked, for at least as long as the manual is incomplete. Please post comments and questions in the dedicated ATCS thread: viewtopic.php?f=6&t=4806
Lvl: 78, XP: 8622632, Gold: 271542, RoLS: 1, ElyR: -, RoL: -, ChaR: 1, GoLF: 1, ShaF: 1, SRoV: 1, VSH: 1, WMC: 1, GoW: 1
HP: 71, AC: 301%, AD: 38-47, AP: 3, ECC: 50%, CM: 3.75, BC: 101%, DR: 2
Locked