Character Download Facility Specification

Table of Contents

1. Introduction

1.1. Purpose of this Document

This document describes the requirements and working of OpenMortal's Character Download Facility (OMCDF) from the developers' point of view.

1.2. Intended Audience

Developers wishing to contribute to, or customize the OMCDF.

1.3. Revision History

Initial version. Describes the OMCDF as we would like for version 0.4
Added client-side internal interface documentation.

1.4. Overview

The OMCDF is a service that allows the users to gain acces to chacarcters that were created or updated after the release of OpenMortal. Characters are versioned: for example if the downloaded version of a character is less then the version on OMCDF, that character can be updated. This allows enhancements to characters after a release.

Also, if a new character is created by a third party, it can be added to the game seamlessly by syndicating it on the OMCDF.

2. The Working of the Character Download Facility

This chapter describes the use cases of the OMCDF. The goal is to make the user's experience as simple as possible. The user should not have to manually download files from the internet, unzip them and test them. The game should make this all possible from inside the game menu.

2.1. Setting up the Connection

User goal: Setting the appropriate parameters to connect to the world wide web.

Background: This step is not necessary if the user has a direct connection to the internet, or has a transparent proxy which allows HTTP connections. However, many computers are behind firewalls and can only access the world wide web if an appropriate proxy configuration is set.

Event flow:
  1. User: Chooses the "Setup Internet Connection" (working name) menu item from the in-game menu.
  2. Client: Displays the current connection parameters.
  3. User: Manipulates the parameters, changing settings. Chooses OK after, or cancels the operation (STOP).
  4. Client: Tries the new settings by attempting to connect to the openmortal server, and downloading a test page.
  5. Client: If the settings are not correct, notifies the user, and returns to step 3.
  6. Client: Once the settings are correct, they are saved into the usual OpenMortal config file.
The configuration should be similar to a web browser's "proxy settings" dialog:
Either allow a manual connection to the internet.
Or allow connection via an HTTP proxy (specify hostname, port, and username/password if necessary)

2.2. Getting the List of Characters

User goal: Connecting to the server and getting the list of characters.

Event flow:
  1. User: Chooses the "List Available Characters" (working name) menu item from the in-game menu.
  2. Client: Connects to the server. Downloads the list of available characters and their "versions" from the OMCDF server.
    If the connection cannot be established, notifies the user that the web setup is not correct, or the connection is down.
  3. Client: Displays the list, marking each character as:
  4. User: Browses the list.

2.3. Downloading a New Character

User goal: Downloading an unavailable character from the OMCDF server.

Event flow:
  1. User: Chooses an unavailable character from the list of characters.
  2. Client: Connects to the server, and downloads the files of the given character. A progress bar is displayed.
  3. User: Either wait for the operation to finish, or cancel it (STOP).
  4. Client: Uncompresses the downloaded files, and places them in the "downloaded characters" folder.
  5. Client: Tries to load the character as a test.
  6. Client: Notifies the user of the success or failure of the operation. If the operation succeeded, then the character will be available from now on.

2.4. Updating and Existing Character

User goal: Updating an existing character from the OMCDF server.

The event flow is the same as with downloading. The client does not overwrite the previous version of the character before it makes sure that the new version works.

3. Server Components

The server-side components of OMCDF consists of nothing but a set of web files. These files can be viewed with an ordinary browser, and characters can be downloaded without the aid of the game. This is for advanced users who know their way around their computer without help.

There is one page, cgi-bin/characters.cgi, which lists the name and author of every character. It also mentions the version of the character and the date of the latest modification. Every character has a numeric ID: 1-99 are reserved for "official" characters, numbers above 100 are for 3rd party characters.

For every character, there is a character description page, cgi-bin/characters.cgi?fighter=idnumber, which contains the characters' long description, stats, and a link to the a downloadable zipped file which is always the latest version of the given character.

These files shall be hosted on

4. Client Components

A character consists of the following files (replace "character" with the actual codename, e.g. "Macy"):

In version 0.3, the DAT and txt files reside in the characters directory, and the perl file resides in the script directory. This is wrong: from version 0.4, the perl file should also go to the charactersdirectory.

The repository of available fighters is in "". To add a new character, or update an old one, the client should call:
g_oBackend.PerlEvalF( "LoadCharacter(%s)", sPerlFilename );
LoadCharacter shall be defined in as well.

The client will use libwww for access of the server files.

The downloaded characters should be placed in:
$HOMEDIR/openmortal_<version>/download (for Linux)
<openmortal_root>/download (for Windows)

4.1. Client-side interfaces

The download facility exposes the following interfaces to the rest of the game:

 class IDownloadFacility
void SetEventSink( IDownloadEventSink* a_poEventSink ) = 0;

void StartCharacterList() = 0;
void CancelCharacterList() = 0;

void GetCharacterCount() = 0;
SCharacterInfo GetCharacterInfo( int a_iIndex ) = 0;

void StartCharacterDownload() = 0;
void CancelCharacterDownoload() = 0;

struct SCharacterInfo
int m_iID; ///< The unique ID of the character.
std::string m_sName; ///< The user-readable name of the character.
std::string m_sTeam; ///< "Good" or "Evil"
std::string m_sStyle;
std::string m_sAge;
std::string m_sWeight, m_sHeight, m_sShoe, m_sStory, m_sKeys;

int m_iGender; ///< 1 for male, 2 for female.
int m_iDataVersion; ///< Characters are versioned, from 1 up
double m_dGameVersion; ///< The version of OpenMortal required
int m_iVotes; ///< # of votes that the character got
double m_dZippedSize; ///< Size of the download
The event sink implemented by the game will be:
 class IDownloadEventSink
void OnCharacterListProgress( double a_dProgress ) = 0;
void OnCharacterListDone() = 0;
void OnCharacterListError( std::string a_sErrorDescription ) = 0;
void OnCharacterDownloadProgress( double a_dProgress ) = 0;
void OnCharacterDownloadDone() = 0;
void OnCharacterDownloadError( std::string a_sErrorDescription ) = 0;

StartCharacterDownload and StartCharacterList should call the *Progress and *Done methods of the event sink during and after their completion. If there is an error or the process was canceled, the *Error method must be called, and the process aborted. The rest of the methods should return immediately.

[... more details required?...]

[... What about localized versions??? E.g. Spanish, English, etc, they only differ in maybe should contain every language.]