Download Facility Specification
Table of Contents
1.1. Purpose of this
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
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
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.
The configuration should be similar to a web browser's "proxy settings"
- User: Chooses the "Setup Internet Connection" (working
name) menu item from the in-game menu.
- Client: Displays the current connection parameters.
- User: Manipulates the parameters, changing settings.
Chooses OK after, or cancels the operation (STOP).
- Client: Tries the new settings by attempting to connect to
the openmortal server, and downloading a test page.
- Client: If the settings are not correct, notifies the
user, and returns to step 3.
- Client: Once the settings are correct, they are saved into
the usual OpenMortal config file.
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
User goal: Connecting to the server and getting the list of
- User: Chooses the "List Available Characters" (working
name) menu item from the in-game menu.
- 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.
- Client: Displays the list, marking each character as:
User: Browses the list.
- Available: The character is downloaded, and can be
played. It has the same local version as the server's version.
- Upgraded: The character is downloaded, but the server's
version is newer. It can be downloaded to upgrade the local version.
- Unavailable: The characters it not downloaded and is
currently not playable. It can be downloaded from the server and added
to the playable characters.
2.3. Downloading a
User goal: Downloading an unavailable character from the OMCDF
- User: Chooses an unavailable character from the list of
- Client: Connects to the server, and downloads the files of
the given character. A progress bar is displayed.
- User: Either wait for the operation to finish, or cancel
- Client: Uncompresses the downloaded files, and places them
in the "downloaded characters" folder.
- Client: Tries to load the character as a test.
- 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
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
These files shall be hosted on http://openmortal.sourceforge.net
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 "FighterStats.pl".
To add a new character, or update an old one, the client should call:
LoadCharacter shall be defined in FighterStats.pl as
The client will use libwww for
access of the server files.
The downloaded characters should be placed in:
<openmortal_root>/download (for Windows)
The download facility exposes the following interfaces to the rest
of the game:
The event sink implemented by the game will be:
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;
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_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
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 Character.pl... maybe Character.pl should contain every