Development:How to Develop

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

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 git://github.com/themanaworld/tmwa.git
 git clone --recursive git://github.com/themanaworld/tmwa-server-data.git
 cd tmwa/
 ./configure # (you can use ./configure --prefix=/path to install somewhere other than /usr/local, or ./configure --user to install in your home directory. On most systems ~/bin is in your PATH if it exists)
 make
 sudo make install
 git config --global url.git@github.com:.pushInsteadOf git://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

or

 mana --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.freenode.net 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.

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 change the config files to be sure the paths are correct.

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

Ouptut:
client-updates-gen      client-updates-push 
adler32.c                    client-updates-inspect  makefile 
client-updates.conf.example  client-updates-news
End of output 

• Copy the example file and make a conf file of it.

cp client-updates.conf.example client-updates.conf
ls

Output:
client-updates.conf.example  client-updates-news 
adler32.c            client-updates-gen           client-updates-push 
client-updates.conf  client-updates-inspect       makefile 

(as you can see now there is a client-updates.conf file made)

End of output

• Edit the client-updates.conf file with gedit or nano or vi.

Search for the folowing lines:

CLIENT_DATA_DIR="$HOME/tmwa-client-data"
UPDATES_DIR="$HOME/client-updates" 
UPDATES_PUBLISH_DIR="$HOME/www/tmwupdate"

And change them to:

CLIENT_DATA_DIR="~/tmwAthena/tmwa-server-data/client-data"
UPDATES_DIR="~/tmwAthena/tmwa-server-data/client-data/tools/client-updates" 
UPDATES_PUBLISH_DIR="/var/www/tmwupdates" (your public www folder /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.

For this part you realy need to change something inside of the client-data folder. If you do not change a file, the updates are generated but nothing will be updated. You are now free to do some changes, first close the client and your servers. Make your modifications (e.g. Change a map) and save them.

• Open a terminal.

First we compile the adler32 tool to generate a hash.

cd ~/tmwAthena/tmwa-server-data/client-data/tools/client-updates/src 
make

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

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

cd ~/tmwAthena/tmwa-server-data/client-data
make maps (if you changed a map. the output will be converting all the maps by tmx_converter.py tool.)

• Then we check the latest commitment on git.

git log --oneline | tail -n 1

The output of this will be: 
840c732 *** empty log message ***
End of output

We only so this once, after we made an update with client-updates-gen 840c732 the client-updates-gen can exec without the commit value.

git status

Output example:
On branch master 
Changed but not updated: 
(use "git add <file>..." to update what will be committed) 
(use "git checkout -- <file>..." to discard changes in working directory)  
modified:   maps/001-1.tmx 
no changes added to commit (use "git add" and/or "git commit -a")
End of output 

• Now we add the modified files with git add.

git add [modified files] (example git add maps/001-1.tmx)
git add client-data (or add the file that changed see example above).
git commit

If we do git commit it will open up vi or nano and you must fill in something to commit something. If you just save the file without filling in something its not working, so if you dont know what to fill in just put … in it and save. Above, we changed the 001-1.tmx map so i will fill in the commit file like this: changed map 001-1. Then save the file.

./tools/client-updates/src/client-updates-gen 840c732

This will make a zip file that has to be pushed to your webserver so that the manaplus or tmw client can download the updates and install them. If we dont do “client-updates-push” there will be no data on the webserver and the client keeps saying us that the update is not complete. Or the client will crash.

./tools/client-updates/src/client-updates-push

You will see that the files are copied to the location you specified in the config file (/var/www/tmwupdates) earlier

• Now you can start your servers and start the client to see if the updates are working.

All content can now be displayed without starting a client with the -u -d arguments.

If you make another change at the maps or data and want to make more updates, just repeat the last steps:

Repeat steps:

cd ~/tmwAthena/tmwa-server-data/client-data
make maps (if you changed a map)
git status
git add [modified files] (example git add maps/001-1.tmx)
git add client-data (or add the file that changed see example above).
git commit
./tools/client-updates/src/client-updates-gen

The first time we did this command with client-updates-gen 840c732. We dont do that anymore. Just client-updates-gen is ok to do the job.

./tools/client-updates/src/client-updates-push