Character Download Facility Specification

Table of Contents

• 1. Introduction
  • 1.1. Purpose of this Document
  • 1.2. Intended Audience
  • 1.3. Revision History
  • 1.4. Overview
• 2. The Working of the Character Download Facility
  • 2.1. Setting up the Connection
  • 2.2. Getting the List of Characters
  • 2.3. Downloading a New Character
  • 2.4. Updating and Existing Character
• 3. Server Components
• 4. Client Components
  • 4.1. Client-side interfaces

1. Introduction

1.1. Purpose of this Document

1.2. Intended Audience

1.3. Revision History

1.4. Overview

2. The Working of the Character Download Facility

2.1. Setting up the Connection

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.
   

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

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:
• 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.
4. User: Browses the list.
   

2.3. Downloading a New Character

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

3. Server Components

4. Client Components

CHARACTERDATA.DAT
CHARACTERDATA.DAT.txt
Character.pl

g_oBackend.PerlEvalF( "LoadCharacter(%s)", sPerlFilename );

$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
 {
 public:
 	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
 };

 class IDownloadEventSink
 {
 public:
 	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.