From The Mana World

How to develop for dummies


This tutorial assumes you are using Linux. If you are using windows, you need to set up a virtual machine.

Initial Setup

This tutorial assumes you are using the Bash shell. If you are using any other shell bugs may happen.

Installing the dependencies

Debian derivates (including Ubuntu)

  • Open a terminal.
sudo apt-get install g++ python2.7 make realpath git

Fedora derivates

  • Open a terminal.
sudo yum install gcc-c++ make git

Creating a github account

Setting up the global git environment

  • Go to https://github.com/settings/tokens and click the button "Generate new token"
  • Choose any name you want for the token.
  • Check those permissions: repo public_repo user:email write:repo_hook repo:status read:public_key user repo_deployment
  • Copy the personal token. It will look something like this: 46cc23de2f02e4t08536803ve705d8241e62e527
  • open a terminal
git config --global credential.helper "cache --timeout=3600"
git config --global user.name "Your Name"
git config --global user.email "<username>@users.noreply.github.com"
touch ~/.netrc
chmod 600 ~/.netrc
  • open the file ~/.netrc in your favorite text editor and put this inside
machine github.com login <username> password <token>
  • save the file and close the text editor

Forking and cloning

echo "export PATH=$PATH:~/bin" >> ~/.bashrc
source ~/.bashrc
mkdir ~/tmwAthena
cd ~/tmwAthena
git clone --recursive https://github.com/<username>/tmwa.git
git clone --recursive https://github.com/<username>/tmwa-server-data.git

Setting up the remotes

  • open a terminal
cd ~/tmwAthena/tmwa
git remote add upstream https://github.com/themanaworld/tmwa.git
git fetch --tags --all
cd ../tmwa-server-data
git remote add upstream https://github.com/themanaworld/tmwa-server-data.git
git fetch --tags --all
cd tools
git remote add upstream https://github.com/themanaworld/tmw-tools.git
git fetch --tags --all
cd ../client-data
git remote add upstream https://github.com/themanaworld/tmwa-client-data.git
git remote set-url origin https://github.com/<username>/tmwa-client-data.git
git branch --set-upstream-to=origin master
git fetch --tags --all

Copying the local config files

  • open a terminal
make conf

Making an admin account

  • open a terminal (and leave it open)
cd ~/tmwAthena/tmwa-server-data
./run-all
  • wait until it says "Map-server 0 loading complete.". If after 2 minutes you do not see this message, ask for support on IRC.
  • while keeping the other terminal open, open a new one
cd ~/tmwAthena/tmwa-server-data/login
tmwa-admin
add <username> M <password>
gm <username> 99
exit
  • close this terminal but keep the one in which you typed run-all

Making a custom manaplus launcher

  • open your favorite text editor and paste this inside:
#!/bin/bash
manaplus --server localhost --port 6901 -u -d ~/tmwAthena/tmwa-server-data/client-data
  • save the file in ~/bin and name it "m+"
  • open a terminal
chmod +x ~/bin/m+

Testing the server

  • While your terminal in which you typed run-all is still open, open a new terminal
m+
  • You will see the login screen. Type the username and password that you have set at the step "Making an admin account"
  • You should now be able to create a character and use the server. If it does not work, seek help on IRC.

Making new content

Branching

A branch is a version of the code each branch is a different version. By default, when using git, you are on the master branch which is the main version. However, when using forks, your master branch should always stay a perfect copy, a mirror of the master branch of the original repository (upstream). When you want to make a modification you should always create a new branch. Never work on the master branch.

Let's say you want to make a modification to client data:

  • go to https://github.com/<username>/tmwa-client-data
  • If it says "This branch is even with themanaworld:master" you can proceed. If it says the branch is behind themanaworld:master, follow the steps of "Updating from upstream". If it says the branch is ahead of themanaworld:master please seek help on IRC.
  • Click on this button (on github, not on this wiki page) : Branch master.png
  • Type the name of your new branch. The name can be anything. If, for example, I wanted to work on the npc "Eurni" I could put something like "eurni-update" as branch name.
  • open a terminal
cd ~/tmwAthena/tmwa-server-data/client-data
git fetch origin
git checkout <branch>

Adding changes

  • Make sure you are not working on the master branch. You can check your current branch with this command:
git rev-parse --abbrev-ref HEAD
  • Modify the files you want to change.
  • Test it by running the server (with ./run-all in tmwa-server-data) and launching m+
  • Mark your changes:
git add path/to/file
  • Review your modifications:
git status
  • Commit and add a summary of your modifications
git commit -m "put a short summary here"
  • When you are ready, push your modifications to github:
git push origin <branch>

Making a pull request

  • After you have pushed to your branch (NOT master), go to the address of your repository. For example: https://github.com/<username>/tmwa-client-data
  • You should see a new button: Compare and pull.png click it (on github, not on this wiki page). If you do not see this button, you probably did something wrong so seek help on IRC.
  • Put a title, a summary and click on "Create pull request"

After you make your pull request, you need to wait. A developer will either tell you what is wrong with your code and how to fix it or, if everything looks fine, add the "test" label. The test label means your modifications can be tested on the test server.

Updating from upstream

to-do: explain how to pull from the tmw repo and force-push to the fork