Atlantis Programmer's Guide

The main reason for making modifications is to create your own rule-set for Atlantis, or customize an existing rule-set. This document details customizing Atlantis game rules extensively; I'll also try to touch on other changes you might wish to make.

Be sure to check the source code licensing terms before making changes. Not that I don't want you to make changes, but any commercial use of the Atlantis source code is not allowed without my explicit permission. For more information, check the license terms that come with the source code, and the licensing documents on this web site.

Coding Style

My coding style has changed over the years, and you will find that the source code often doesn't follow the rules I list below. However, any future changes I make will follow this style, and I'd appreciate you following these conventions, especially in any code you'd like me to incorporate into the "official" version of the source code. I think the conventions are not very restrictive, and shouldn't be too hard to follow.

• No tabs should be in source code files.
• Indentation is done in 4 space increments.
• Closing braces should be at the same indentation level as the line containing the opening brace, and everything in between should be indented by 4 spaces (1 level).
• Function names should look like: ThisIsAFunctionName, and variable names should look like: thisIsAVariableName. Names should be pretty verbose; names like i and temp are discouraged, unless it's really obvious what they're for.
• Pointer variables should be preceded by p (pVariable), and member variables should be preceded by m_ (m_memberVariable).
• Globals variables are strongly discouraged; put them in a class somewhere.
• Passing arguments by reference (&) is discouraged unless it is a const reference (const &). Use a pointer instead.
• Lines should be kept to 80 characters or less.

Here's an example:

void MyFunction( int inputVariable, int *pOutputVariable )
{
    if( inputVariable )
    {
        *pOutputVariable = 0;
    } else {
        *pOutputVariable = 1;
    }
}

Notes on the Code

The Atlantis source code is quite a mess, having been assembled over many years. At one point I set out to rewrite the whole thing, but ended up giving up after wasting many hours. Since it is a hobby for me, it is hard to find the time to make broad sweeping changes, some of which would improve the code. This document describes the code as it is; elsewhere on this site I describe many of the changes I would like to make to the code.

Version Information

Both the Atlantis engine, and the rule-set in use, have a version number. The format of this version is Major.Minor.Patch; each section of the version is limited to a value of 256, though I don't expect versions to get close to that. (Example: 4.0.2). The meaning of each part of the version:

• Major - The major version indicates the overall architecture of the engine or rule-set. Changes to this version indicate some sort of grand change.
• Minor - The minor version indicates smaller but important changes of the engine or rule-set. A change in the minor version number means that the saved-game format changes (or at least may have changed). Thus, version 4.1.0 will not load a saved-game that used version 4.0.2. Also, if the minor version is even, the engine or rule-set is considered to be beta software, and may not be fully tested. Odd-numbered versions indicate release-quality software, which should be more fully tested and more robust. This is just the opinion of the author; there is no "formal" difference between beta and release versions of Atlantis.
• Patch - The patch version should increase every time there is any change to the engine or rule-set. It is expected that if the patch version changes, the new version will still be able to load saved-games that differ only based on patch version. Note that only backward compatibility is guaranteed; version 4.0.2 of Atlantis can load a saved-game with version 4.0.1, but not a saved-game with version 4.0.3.

Both the Atlantis version and the rule-set version should be printed in each report, for the players' information.

Basic Organization

Compiling a game of Atlantis involves including the Atlantis Engine source code, and the source code for the particular rule-set. The Atlantis Engine source code is in the main directory, and includes all of the standard game-running code. The rule-set source code lives in a sub-directory (conq10 for the sample Atlantis rule-set, Atlantis Conquest). Eventually, it would be nice if the game-specific code could be compiled separately into a program, and the rule-set specific source code compiled into a dynamic library that could be loaded depending on what game you want to run. However, for now, that doesn't work, and you need to compile a separate program for each Atlantis rule-set.

Eventually I'll update this document to include more information about the Atlantis Engine source code here.

Customizing an Atlantis Rule-Set

The following are the main modifications you'll want to make to a rule-set.

GameDefs structure

The GameDefs structure is defined in gamedefs.h, and created in rules.cpp. This structure defines some of the basic rules and behaviors of the Atlantis engine. If you are creating a new rule-set, the first thing you'll want to do is define the RULESET_NAME variable, and initialize the RULESET_VERSION field to version 1.0.0. If you are modifying a rule-set, you'll want to update the version, based on the version specifications above.

The rest of the structure is a combination of important game constants, and flags that define the behavior of the Atlantis engine. For instance, if you set the TOWNS_EXIST variable to 0, there will be no cities or towns in the world. Note that some of the variables may not have any meaning, depending on how you set the other variables. For example, if you set TOWNS_EXIST to 0, then the CITY_POP variable is ignored. Unfortunately, for now, this doc doesn't describe the dependencies, and you'll have to hunt through the engine code if you are in doubt.

Basic Game Definitions

The files rules.h and rules.cpp define the basic items, terrains, and other "things" that exist in an Atlantis rule-set. You can modify these files to change the properties of things, or add new things to the game. Note that rules.h has a number of enums that must be kept in sync with the structures in rules.cpp, or things won't work correctly. Hopefully the comments and example rules.cpp file in the Atlantis Conquest rule-set will help you if you wish to make changes to these files.

World Creation

The file world.cpp contains the various functions required to create an initialize the Atlantis world (this only occurs when a new game is started, of course).

The first thing you may want to customize is the way names are given to regions and towns in the world. Eventually, I'll try to make a more flexible way that names are generated, but for now, you can just fill in the regionnames array with the possible names that a region or town can have, and they will be assigned randomly.

Next, you'll want to modify the Game::CreateWorld function; this is the main function that controls world creation. There are 3 steps you must call in this function:

1. You need to call regions.CreateLevels() with the number of levels that are to be created. The sample rule-set, Atlantis Conquest, creates just one level, because there is just the surface of Atlantis in this rule-set. If you wanted to have an underworld, or other worlds, you might want to create more levels.
2. You need to call SetupNames(), or any other name-initialization you might want to do.
3. You need to create each level. The sample rule-set does this with a regions.CreateIslandLevel() call. Eventually, there will be a number of handy level creation calls in ARegionList, but for now you'll probably want to write your own and add it to the engine.

Any other world initialization code that you need for your rule-set should get called from CreateWorld as well.

There are some other functions in world.cpp that you'll probably want to modify, depending on the rule-set.

• Game::CreateNPCFactions() - Use this call to create and NPC factions for your rule-set.
• Game::CreateCityMon() - This call is used to create monsters that exist in each town (City Guardsmen, for instance).
• ARegionList::GetRegType() - This call is used to generate the type for each region.
• ARegionList::CheckRegionExit() - This is called for each pair of adjacent regions, to determine whether movement is permitted between the regions.
• ARegion::CanBeStartingCity() and ARegion::MakeStartingCity() - These are used in the creation of any starting cities.

Extra Functions

The file extra.cpp contains some other functions, including a couple of important ones. Game::SetupFaction() is called when a new faction is added to the game. It should set-up the faction, or return 0 if the faction can't be added to the game at this point. Game::CheckVictory() is called after each turn, if the rule-set is not for open-ended games. This function check to see if someone has won the game.

Skill Descriptions

The file skillshows.cpp contains an array of descriptions for skills in the rule-set. Update this array to add a new skill description, or modify a skill description.

Special Attacks and Magic

The file specials.cpp contains functions that will have to be filled in if the rule-set allows magical shields, magical attacks, or healing.

The files spells.h and spells.cpp contain functions that should be filled in if the rule-set has spells of any sort.

Other Atlantis Modifications

More info is needed here on how to make other modifications to Atlantis.

Last Modified: December 19, 2002

This page maintained by Geoff Dunbar (gdunbar@prankster.com).