GettingStartedAsADeveloper
So you want to help us develop Argentum Age? Maybe you want to add cards, develop scenarios and campaign maps, add some artwork and special effects, or any or all of the above? You've come to the right place to learn how.
We assume you know the basics of editing text files, and how to use github. If you don't please ask for help.
You should have downloaded Argentum Age:
- Windows: http://theargentlark.com/david/ArgentumAge-setup.exe
- OSX: http://theargentlark.com/david/ArgentumAge-OSX.zip
- Linux: installation guide
You should have run the game at least once and started it up. Then quit the game.
Now, you want to locate the directory that the Argentum Age game rules are synced to.
- On Windows this will be something like
User\(your username)\AppData\Roaming\citadel\dlc\citadel. - On macOS this will be something like
~/Library/Application Support/citadel/dlc/citadel/. - On GNU/Linux this will be something like
/PATH/TO/ARGENTUM_AGE/aa/, but was previously something like~/.citadel/dlc/citadel/so your mileage may vary depending on how old is your original install of Argentum Age.
Delete this directory (or rename it to something else) and in its place sync the citadel github from https://github.com/davewx7/Citadel
You want to make sure the auto update process doesn't overwrite what you have
from github though. To do this you want to go to the folder you installed
Argentum Age into and find the master-config.cfg file. Find the argument
reading "--update-module=true" and change it to "--update-module=false".
Or, if there it exists an argument reading "--auto-update-module", remove it
or move it from the original arguments JSON list to another JSON list keyed
like disabled_arguments or any other thing the application most probably
will safely ignore.
Now when you run Argentum Age it will use what you synced from github. It might still do some automatic updates to update the Anura engine, but will leave you to sync your game data from github. You're ready to develop.
If you're adding new cards you probably want to have your own private 'universe' to test your creations. Doing this is easy. Just edit the master-config.cfg file and in the arguments, add the following:
"--internal-tbs-matchmaking-server", "--server=localhost:23456", "--db-json-file=db.json"
This will make it so when you run Argentum Age, you will run your own local server which you will connect to instead of connecting to the online server. To be clear, this will make it so Argentum Age makes no network connections for gameplay outside of your machine. So if you add a card to the game, the server will recognize it.
This means that you will start over with a brand new user account that is played on your local server.
The server will save its database in db.json ... you can edit this file with a text editor and change the details of your account. You can use this to 'cheat' and give yourself new cards quickly so you can test them.
While in the game, you can press ctrl+d to bring up the debug console (press ctrl+d again to close it when you're done). You can type commands into the debug console to do a variety of debugging.
One useful thing you can do is type, for instance,
debug_card('Blink Mage')
To award yourself the 'Blink Mage' card. When testing a new card you have created you can use this to give yourself the card easily. You can also give yourself mana:
debug_mana(10)
There are also some special debug cards:
debug_card('Debug Victory')
This will give you a special card called 'Debug Victory' which will make you win the game immediately when cast. This is useful when debugging to move quickly through scenarios.
Sync anura from https://github.com/anura-engine/anura . Sync citadel from https://github.com/davewx7/Citadel and put it under [anura location]/modules/citadel
Build anura by using 'make'. You may need to install some dependencies. More info here: https://github.com/anura-engine/anura/blob/trunk/INSTALL
Note that the makefile uses the headers which are included in the repository, not the ones on your system (may have changed since time of writing this). If your build is broken this may be the cause.
The licensed font for Argentum Age is "Core Mellow". It is not licensed such that it can be placed in the git repo. To install it, download this zip file and extract it to "/data/fonts" inside the Citadel module. If you don't you will get the fallback font instead. http://theargentlark.com/david/core-mellow.zip
Run the game with ./anura --module=citadel
To adjust the resolution / enable full screen from the start, use e.g.
./anura --module=Citadel --fullscreen --width=1366 --height=768
At time of writing I recommend not using fullscreen, because of some issues with alt-tabbing out of it which you often want to do when developing.
Generally this is the only thing you should need if you want to create content for argentum age -- you will be able to modify the local game files and have them appear in game for you. If you want to develop more than that e.g. make modifications to the client-server protocol, you will probably want to be able to run a local matchmaking server with modifications and connect several clients to it for testing. I use a pair of scripts like this:
$ cat local_citadel.sh
#!/bin/bash
if [[ $# -ge 1 ]]; then
gdb -q -batch -ex "run" -ex "bt" --args ./anura --module=Citadel --user="$1" --pass="$2" --width=1366 --height=718 --server=localhost:23456
else
gdb -q -batch -ex "run" -ex "bt" --args ./anura --module=Citadel --width=1366 --height=718 --server=localhost:23456
fi
$ cat launch.sh
#!/bin/bash
tab="--tab"
cmd0="bash -c './anura --db-json-file=db.json --module=Citadel --utility=tbs_matchmaking_server';bash"
cmd1="bash -c './local_citadel.exe user1 password';bash"
cmd2="bash -c './local_citadel.exe user2 password';bash"
cmd3="bash -c './local_citadel.exe user3 password';bash"
foo=""
foo+=($tab -e "$cmd0")
foo+=($tab -e "$cmd1")
foo+=($tab -e "$cmd2")
foo+=($tab -e "$cmd3")
gnome-terminal "${foo[@]}"
exit 0
When you start Argentum Age, it connects to the Argentum Age matchmaking servers. These servers are responsible for keeping track of your account progress, letting you chat, and arranging for multiplayer games to take place.
If you start a multiplayer game of Argentum Age, a game server is started and the clients connect to it. It arbitrates moves.
However, if you start a campaign game vs the AI, an game server on your local machine is started and you play on that. This means that if you edit most data files and game rules locally they will show up in local games against the AI without any problems. This makes it very convenient to develop without having to run your own matchmaking server or game server manually.
If you e.g. change the rules of a card (say by editing cards-blood.cfg the file containing all Entropia cards) it will show up in your local games though not if you play an online game against someone.
Likewise you can edit campaign scenarios, and make most other modifications without worrying about the matchmaking or game servers at all.
Here are some important files under the Citadel module (argentum-age/aa/modules/citadel):
-
data/cards-food.cfg, cards-blood.cfg, etc. These contain all the card definitions for the different schools.
-
data/campaign-map.cfg: This contains the configuration of the 'world map' with all the map locations on it.
-
data/campaign-*.cfg: Each one of these files contains a single 'campaign'. That is the set of scenarios at a location
-
data/classes/*.cfg: This contains most of the rules logic of Argentum Age. All the game rules are implemented in here. In particular, game.cfg, card.cfg, player.cfg, and creature.cfg contain all the game rules.
-
data/objects/*.cfg: This contains most of the presentation logic of Argentum Age. It uses information from the classes to present the UI to the user.
-
images/portraits/*.png: This contains all the card art.
The *.cfg files use JSON-like format for declarative description of lists of objects and their properties. Any code required for game rules or card's special effects is stored as string value of a dictionary where keys are events which trigger the code.
The game uses the Frogatto Formula Language (FFL), and here are some brief introductions to the FFL:
The code is purely functional (immutable architecture) with syntax slightly similar to Python, uses classes and functions and usually responds to an event by returning a list of commands which are first evaluated and then executed by the game engine. Conditions in the code ("if") are realised using ternary operator returning a value, repetitions ("for") are replaced by list comprehensions, map() function or find() function with boolean criteria etc. For example Dark Priest has triggered ability activated by on_summoned event which finds creatures in the same lane owned by different player and returns list of two commands if none are found: inflict 3 damage to the opponent and add animation hint for player damage.