We're using Git as version control system for our source files and content. Have a look at our Tutorial about how to use Git.

Set Up

This is a how to help content development for official server (tmwAthena) using Ubuntu and the Mana+ client. Other OS and clients may differ. Following this guide, you should be able to get development testing versions of the client data (tmwa-client-data), server-data (tmwa-server-data) and participate in development by using a localhost server. After getting these, you can both test current development and begin development in the direction you find most fitting.

Install Dependencies

In addition to the basic build tools (GCC, Make, headers, ...), Bison, and Flex are needed.

Debian derivates (including Ubuntu)

• Open a terminal.

sudo apt-get install g++ flex bison python make realpath git

Fedora derivates

• Open a terminal.

sudo yum install gcc-c++ flex bison make git

Note that you must have gcc 4.6 or later. Any modern distro will have this version, but "stable" distros with very long release cycles, such as Red Hat Enterprise Linux, might not.

Set Up Own Server

Here are the steps to use when creating a new local testing server.

• Open a terminal.

 mkdir ~/tmwAthena
 cd ~/tmwAthena/
 git clone --recursive https://github.com/themanaworld/tmwa.git
 git clone --recursive https://github.com/themanaworld/tmwa-server-data.git
 cd tmwa/
 ./configure --user # (Assuming ~/bin is in your PATH if not use ./configure)
 make
 make install
 git config --global url.git@github.com:.pushInsteadOf https://github.com [1] [2]
 cd ../tmwa-server-data

• Preferably, add the update hooks.

 ln -s ../../git/hooks/post-merge .git/hooks/
 ln -s ../../../../git/hooks/post-merge .git/modules/client-data/hooks/ # (git 1.7.8 or newer)
 ln -s ../../../git/hooks/post-merge client-data/.git/hooks/ # (git 1.7.7 or older)
 make conf
 cd client-data
 git checkout master
 cd music
 git checkout master

Hosting Updates

TMW makes it easy to generate delta zips out of a repository, once it is initially set up.

It will put them in ~/www/updates/, which may be a symlink to wherever your web server is really serving. Setting up a webserver is not covered here.

Once everything is set up, just run 'make updates' from the server-data dir every time client-data changes. It will do nothing if appropriate, generate complete zips the first time, and incremental zips afterwards.

Some notes:

• You must put news.txt and skeleton resources.xml file (and maybe an empty resources2.txt) in ~/www/updates/ first.
• Music updates are never added; they should be in the skeleton and updated manually if needed.
• You definitely want to run one of the analyzer scripts frequently, and remove the old updates.

Running and Administrating the Server

The TMWAthena is in fact 3 servers:

• tmwa-login which manages accounts and connection to char server.
• tmwa-char which manages characters and connects them to the map server.
• tmwa-map which manages game content (maps, monsters, items, scripts...) and their interaction with characters

• Start the servers: Open a terminal and run all the local servers. To stop them, either close the terminal or type control-C.

 cd ~/tmwAthena/tmwa-server-data/
 ./run-all

• In a new terminal, Launch tmwa-admin the administration tool, add yourself as an user and make yourself a GM:

cd ~/tmwAthena/tmwa-server-data/login
tmwa-admin
add <username> M <password> 
gm <username> 99

Note : Be sure that you are running tmwa-admin from within the "login/" directory. Check that the config files are correct: the connection port should be 6901 for tmwa's configuration, not 6900, which is the hard-coded default.

See also: GM Commands

Connecting

1. Open a command line terminal and run your client pointing to your client data and your local server :

 manaplus --server localhost --port 6901 -u -d ~/tmwAthena/tmwa-server-data/client-data

If all went well, you are now ready to test new content and participate with development.

develop new content

You are now free to do some changes, first close the client and your servers.

Notes for client data changes: 1) commit and push them in the client-data repo 2) commit and push "client-data" when it shows "(new commits)" in your server-data 3) commit and push other server data changes.

• Make your modifications (e.g. Change a map) and save them.
• Open a terminal.

 cd ~/tmwAthena/tmwa-server-data/client-data
 git status
 git add [modified files]
 git commit

git push

Note: push

 cd ..
 make maps (if you changed a map)
 git status
 git add [modified files]
 git add client-data (if git status shows (new commits). Don't do this if you don't have push access to client-data!)
 git commit

git push

Note: push

• Close the terminal.

Note: push

 : a step for those with commit access to the remote repositories. For others, you don't need to reconfigure your clone and please make a patch on steps where git push is suggested.

Note: once

 : you only need to do this once, no matter how many times you independently clone the repositories.

 git format-patch -M -C origin/master

• pastebin the patch(es) and post for review at irc.libera.chat channel: #themanaworld-dev or on our development forums. Extensive patches must be posted on the forum as a series of well-formed patches with descriptive commit messages. In particular, later patches should not fix errors introduced in earlier patches, and each patch should form a logically independent part.

Note : This is kind of outdated; with github it's often easier to do patches on branches there. see: Working With Git page

You can also pull the data which has been modified.

• Open a terminal.

cd ~/tmwAthena/tmwa-server-data
git pull

• If you haven't installed the hook,

git submodule update --merge  at toplevel (for client-data) and in client-data (for music)

• Close the terminal.

See Also: README.mv.txt - Documentation on using git submodules, like client-data and tmw-music.

Git guide

Git guide

This page is currently just some kind of experiment to update/merge Git and Dev:Working With Git in both content and design. What is Git? Git is a distributed revision control and source code management system. GitHub is a web-based hosting service for projects that use the Git revision control system. Together, these two tools allow developers working on The Mana World to easily collaborate and merge changes into the game. Working with Git Installing Git To install Git, select the appropriate Operating System at Git Downloads and follow the instructions. (For Windows users, accept all the default settings for the installer.) Please note that although the download for Windows includes a GUI tool, we will focus on the Git Bash command line tool in order to maintain consistency across platforms. After installation, please follow the basic setup instructions at GitHub under the Set Up Git heading. You will likely also want to set up SSH authentication for GitHub. This can be done by following their SSH Guide. Creating a Fork Once you have installed Git, your first task should be to create a personal copy (also known as a fork) of the server data on your GitHub account. This will allow you to make changes and save them to a place where the content leaders can retrieve copies to include in the main server. It's also easier to work with. To create a fork, login to your GitHub account and go to the TMW Repository. You will see a button on the page that says Fork. Click it. You should now see a page that has some details and history for the fork you just created. At the top will be a series of buttons including one that says SSH. Clicking the SSH button will create a link for you to copy which will be needed in the next step. It will look like git@github.com:yournamehere/tmwa-server-data.git. Copy that link or keep the page open; we'll need it later. If you will be working with client-data or music, you will need to create separate forks for those repositories as well. client-data music Creating a Clone You now need to create a copy of the data on your computer to work with (also known as a clone). We will create a clone from the main repository and set up Git to allow you to push changes to your personal fork. If you are using Windows, open the Git Bash tool which you installed earlier. If you are using Linux, open a terminal window. Navigate to the folder where you want to create your clone. Now issue the command to have Git create a copy: git clone --recursive https://github.com/themanaworld/tmwa-server-data.git TMW The --recursive command tells Git to copy all of the data from the included submodules (client-data and music). If you don't plan on working with these, it can be omitted. The TMW at the end of the command is the name of the folder you want the data in. In the example, git clone --recursive https://github.com/themanaworld/tmwa-server-data.git TMW will create a new folder called TMW and put the files inside that folder. You can use any folder name that makes sense to you. Note that copying the data may take some time. After the data is finished cloning to your computer, you need to tell it how to keep track of changes. Creating Remotes When a repo (short for repository) is cloned, it has a default remote called origin that points to the repo it was cloned from. To allow you to make changes on your personal fork, you need to add another remote which we will name fork. Change to the directory you created when you cloned your repo: cd TMW Using the link we found at the end of the Creating a Fork section, issue the command git remote add fork git@github.com:yournamehere/tmwa-server-data.git We'll also need to add remote pointers and select the correct branch for the submodules, if you cloned them. cd client-data git remote add client-data git@github.com:yournamehere/tmwa-client-data.git git checkout master cd music git remote add music git@github.com:yournamehere/tmw-music.git git checkout master Git includes the ability to work with branches, or multiple versions of files. This can provide a way to work on separate projects without having to create a new clone for each one. We won't be going too deeply into this option, but the option is there once you are more comfortable. By default, you will be working on the master branch. The command above, git checkout master, tells the submodule which branch you want to use. At this point you now have a personal fork, a local clone, and remote pointers for your fork. You're ready to start making changes! You are free to use whatever tools work for you to make your changes, but please ensure that the final results are in harmony with The Mana World's formatting guidelines. TmwAthena Scripting Standards Retrieving Changes Because many developers are working on the project at the same time, you will want to make sure you have all the latest changes before making a commit. This will ensure that your changes do not conflict with changes another developer has made. If you have not made any changes yet and want to make sure your clone is up-to-date before starting to work, you can simply pull from the repo. git pull If you have made local changes and want to get the latest updates before continuing, you will need to tell Git to get the updates and then apply your changes on top of them. git pull --rebase Making Commits After making changes to any of the source files (maps, graphics, scripts) you will want to save those changes so other developers can see and review them. You need to commit those changes to Git. When committing files to Git, you will need to have a terminal or Git Bash open in the directory containing the changes. For example, if you are changing music files, you will need to be in the TMW/client-data/music folder. Your first step toward making a commit is to verify that Git recognizes there have been changes. git status You will receive a result that tells you what branch you are working on, what files (if any) have been modified, and what files (if any) are untracked. At this point, we want to add our changed or untracked files to Git. Issue the command git add <file> replacing <file> with the path and filename of the file to be added. Be careful: the commands ARE case sensitive! Repeat as needed until your changed files are all added. Issue the command git commit -m 'your message here' Using the -m switch in the command allows you to specify a brief commit message which will tell others what the changes are. For example, git commit -m 'Spelling corrections for Beer quest' will tell others that we made corrections that might apply to multiple files, without giving an overload of detail. If you aren't sure how much detail to include in a commit message, you can check with the development team on IRC for suggestions. Pushing to a Fork Once you have committed your changes to your local clone, you now have to put them where they can be seen: your fork. To ensure that your fork will match what you have in your local clone, we will tell Git to force the changes to the repo. git push -f fork master Please note that using the -f option to force your changes causes Git to overwrite commit history on the repo. This option should only ever be used on personal forks to bring them into the same state as the main repo. If you have been working on and committing changes to music or client-data, you will need to push those to their respective forks. git push -f client-data master git push -f music master

Making Content

Making Map Content

See Mapping Tutorial.

Python Converter Tool

After editing maps for the client, you need to generate the walkmaps and imports for the server. yhis can be done either by the Tiled application or by running the python script tmx_converter.py which is located in the tools folder of the Server Data folder. (see Mapping Tutorial#Creating the WLK files) After that, commit and push the files that the converter edited. Note that, if you do not have push access to the main repository, you should let someone else update the submodule itself.

Getting Art Content Into The Game

• Post [CPT] or [WIP] art on the graphics development forum.
• Work with the Art Director and collaborators on getting the art consistent.
• When finished, edit topic as [FND].
• Art Director approves [FND] art and marks it [RC]. Should the art need animation or special effect, the Art Director requests xml for it. If not, the Art Director commits it and marks as [GIT].
• XML Team reviews or drafts xml related to the art, then commits the .png and .xml. Topic can be marked as [GIT].

• Art content affected: client-data/graphics/sprites then related directory for .png and .xml animation addition.

• Project developer requests database entry reservations from a General Content Team developer.

• Map entry server data affected: resnametable.txt and .wlk files in the data directory, map content files in the npc directory.
• Map entry client data affected: .tmx files in the maps directory.
• Map entry requires the running of the .tmx converter (aka java converter) before commits can be made.
• Art content server data affected: entry made in the item_db.txt, mob_db.txt or mob_skills_db.txt in the db directory.
• Art content client data affected: entry added in items.xml, monsters.xml or other identification file.

Handling General Content Team [REQ]s

• General Content Team member adds a [REQ] topic to the graphics development forum.
• General Content Team member adds the [REQ] topic as a hyperlink under "Required Art" on the Art in Development page.
• Art Director attempts to network with other artists to assign the art to an artist.

Bit Masking

Bit Masking helps us reduce our variable count while offering a dynamic method of script writing that is versatile and flexible to both linear and non-linear script writing.

Bit Masking Test Script

Generating client updates

• Shutdown all your servers.

• First we are going to check the config files to be sure the paths are correct.

cd ~/tmwAthena/tmwa-server-data/client-data/tools/
ls

Output:
add-git-attributes  edit-all-to-export-tilesets.sh  formatXML.sh  list-tileset-order  map-db.py       minimap-render.py
adler32             edit-map-tileset-names.sh       indent.xsl    make-updates        map-diff.py
End of output 

• The easiest solution is to create a symbolic link to that directory

ln -s /var/www/tmwupdates ~/www/updates (your public www folder is /tmwupdates)

• You can Edit the make-updates file with gedit or nano or vi.

Search for the folowing lines: output=~/www/updates And change them to: output=/var/www/tmwupdates (your public www folder is /tmwupdates)

• Save the file and get back in the terminal.

cd ~/tmwAthena/tmwa-server-data/login/conf
ls

Output:
ladmin_athena.conf         lan_support.conf   login_local.conf.example 
ladmin_local.conf          login_athena.conf 
ladmin_local.conf.example  login_local.conf 
End of output

• Edit the login_local.conf with an editor and look for the following line:

update_host: http://updates.themanaworld.org/

• Change that line to:

update_host: http://127.0.0.1/tmwupdates/ (or use your external ip)

• Save the file and get back in the terminal.

• Open a terminal.

First we compile the adler32 tool to generate a hash.

cd ~/tmwAthena/tmwa-server-data/client-data/tools/adler32/ 
make

Output must be: 
gcc -lz -o adler32 adler32.c

make install

• Now that we compiled the adler tool we can make us a update.

cd ~/tmwAthena/tmwa-server-data/
make updates

• Each time you want to make new updates

make sure you have a new commit then
cd ~/tmwAthena/tmwa-server-data/
make updates