ChatBlade API Help

CBLanguageTable is a class designed to support in-game artificial Languages such as Elvish, Orcish, or Klingon.

This class is used by ChatBlade to replace Chat Text with artificial words from the Fantasy/Sci-Fi Language when a Player receives Chat in a Language their Character does not fully comprehend.

Each in-game Fantasy/Sci-Fi Language is represented by a single instance of a CBLanguageTable.

A Map of all the instances for the Languages used in a game is stored in CBChatHandler::m_LanguageTableMap.

This Map is keyed via the LanguageID of a Language. Each in-game Language should have a separate LanguageID.

Developers should create an instance of CBLanguageTable and fill it full of artificial words of the target Language via the AddWord() member Function.

This should be done in the CBClientImplementation::LoadLanguageTables() function which ChatBlade invokes in response to CBChatHandler::InitializeChat().

A sample of creating an loading a CBLanguageTable instance is shown in CBSampleImplementation::LoadLanguageTables().

CBSampleImplementation::LoadLanguageTables() shows the creation of a CBLanguageTable instance then the loading of that instance of numerous Elvish sounding words which are read in from Elvish.XML.

The instance is then placed into the ChatBlade map of CBLanguageTable instances by calling the static function CBLanguageTable::AddLanguageTable() which puts the instance into CBData::pChatHandler->m_LanguageTableMap[CB_LANGUAGE_ELVISH].

Game Developers should load their Language Table instances with words which emulate imagined words from the target Language.

Words of varying lengths should be added.

ChatBlade divides the added words into 3 groups; those 3 letters or shorter, those 7 letters or longer, and words of medium length.

CBLanguageTable is designed to support European based character sets.

This class endeavors to always use the same Fantasy word when replacing typed real words.

So the word Happy should always map up to the same artificial word.

ChatBlade endeavors to ignore any punctuation in a word (Happy, Happy. and Happ!@$y all should map to the same word).

Language word Conversion is done on a word by word basis and does not work on phrases.

When a Player receives a Chat Message that is in a Language his Character does not fully comprehend, ChatBlade shall replace typed words in that Chat Message with Fantasy words stored in this class (the instance with the matching LanguageID to that of the Chat Message).

ChatBlade allows for partial knowledge of a Language. In such cases ChatBlade shall only convert a proportional amount of words into the Fantasy Language.

ChatBlade calls CBClientImplementation::GetLanguageKnowledgeLevel() to determine how much a Character understands a target Language. This function should return a value of 0 - 100 with 100 representing full fluency.

If a Character is fully fluent in a Language, no Language conversion shall occur.

ChatBlade shall do no Language Conversion on any HyperLinks found in a Chat Message.

Game Developers should create one instance of this Class for each in-game Fantasy/Sci-Fi artificial Language that the game supports.

They should load up fake words of varying lengths into the instances. These words should be representative of how one would expect that Language to sound.

Once loaded up the Developer should then add the CBLanguageTable instance to ChatBlade by calling CBLanguageTable::AddLanguageTable() (or CBData::pChatHandler->m_LanguageTableMap[nLanguageID] = cbLangaugeTableInstance).

All this should be implemented in the CBClientImplementation::LoadLanguageTables() function

An example of adding Elvish to a game is supplied in CBSampleImplementation::LoadLanguageTables().

See How to Add an In-Game Language and Elvish.XML.

In addition Developers should implement CBClientImplementation::GetLanguageKnowledgeLevel() so that ChatBlade can determine how radically to Language Convert a Chat Message that is in an in-game Language.

// Represents a single in game artificial Language such as Elvish, Orcish, or Vulcan
// Used to support games which allow users to communicate through in game Languages
// This class contains a list of made up Fantasy language words
// These words are used to replace text when a Player overhears communication in a Language his Character does not know

// CBLanguageTable is implemented as 3 vectors of short, medium, and long length words

// For chat messages which are sent in an in game Language, ChatBlade shall replace typed in text with words from this class
// Support is included for Players who know some of the Language, and as such may be able to understand some words

// One instance of this class should be instantiated for each in game Language
// A map of all the instances of this class is stored in CBChatHandler::m_LanguageTableMap

// This class is not designed to support real-world Languages such as Korean, Mandarin, or Swedish

// TODO: Game Developers should create an instance of this class and populate it for each in Game Language
// In Addition they should implement CBClientImplementation::GetLanguageKnowledgeLevel()

CBLanguageTable::CBLanguageTable()

Comments:

Constructor which sets the LanguageID to CB_LANGUAGE_NONE.

Parameters:

None

Returns:

None

CBLanguageTable::CBLanguageTable(

int nLanguageID)

Comments:

Constructor which sets the LanguageID to that of the supplied parameter.

Parameters:

nLanguageID

The LanguageID of the Language this instance represents.

Returns:

None

int

CBLanguageTable::SetLanguageID(

int nLanguageID)

Comments:

Sets the Language ID for an instance of this class.

Parameters:

nLanguageID

The LanguageID of the Language this instance represents.

Returns:

CB_SUCCESS

int

CBLanguageTable::Clear()

Comments:

Empties out all words in the Language vectors.

Does not set the stored LanguageID to CB_LANGUAGE_NONE.

Parameters:

None

Returns:

CB_SUCCESS

int

CBLanguageTable::AddWord(

CBSTRING sString)

Comments:

Adds a word to the lists of words in this Language.

Each artificial word added should sound like what is expected of the Fantasy/Sci-Fi Language.

Call this function multiple times, once for each word of the artificial Language.

Multi-Word phrases (strings with spaces) may be added.

Added words are placed into one of the 3 vector arrays of this class.

Parameters:

sString

An artificial word of the target in-game Fantasy Language, such as "Felden" or "Korpulgh".

Returns:

CB_SUCCESS

int	CBLanguageTable::LanguageConvertString(	CBSTRING & sString /IN OUT/,
		int nLanguageKnowledgePercentage = CB_LANGUAGE_LOOKUP_FLAG /IN/)

Comments:

Converts a string of words into its artificial in-game Language.

Uses Player knowledge levels (from 0 - 100) to determine if each word is understood.

Words not understood are replaced with fake words stored in this class.

Real words use an internal Hash so that they may always result in the same artificial word.

An attempt is made to ignore any punctuation that may be included in the incoming string.

Any HyperLinks included in the string are not Converted and shall remain the same.

This function attempts to maintain the approximate length of the words when converting them. Short words shall be replaced with short artificial words, while Long real words shall result in longer artificial words.

nLanguageKnowledgePercentage defaults to CB_LANGUAGE_LOOKUP_FLAG. This flag tells this function to call CBData::pChatHandler->m_ClientImplementation.GetLanguageKnowledgeLevel(m_nLanguageID) in order to determine how well the current Character understands the target Language.

If nLanguageKnowledgePercentage > 99 then the Character is fully fluent in the Language and no conversion shall take place.

If nLanguageKnowledgePercentage = 50 then approximately half the real words in the string shall be converted to artificial words of the Fantasy/ Sci-Fi Language.

Any real words in the string which contain numerals shall not be converted.

Called by CBChatMessage::GetChatStringWithHyperlinks() and CBChatMessage::GetChatString().

Parameters:

sString

A reference to a line of text from a Chat Message this was sent in an In-Game Language. Upon entry this string is full of the real-word text of the Chat Message. Upon exit portions of this string are converted to artificial in-game words stored in this Class.

nLanguageKnowledgePercentage

A value between 0 - 100 that represents how well the current Character understands the target Language. 100 = Full Fluent. Defaults to CB_LANGUAGE_LOOKUP_FLAG which tells this function to find out the Characters Fluency.

Returns:

CB_SUCCESS

Upon return sString may be altered and have individual real words replaced with artificial in-game Language words.

static int

CBLanguageTable::AddLanguageTable(

CBLanguageTable cbLanguageTable)

Comments:

Static function which adds a CBLanguageTable instance to ChatBlade.

After a CBLanguageTable instance is filled with words and its LanguageID set, this function should be called to add the Language Table to ChatBlade.

Stores the instance in CBData::pChatHandler->m_LanguageTableMap using the LanguageID as the Map key.

The Language Table can be accessed by CBData::pChatHandler->m_LanguageTableMap[nLanguageID].

Should be called from CBClientImplementation::LoadLanguageTables() once for each Language.

Parameters:

cbLanguageTable

A CBLanguageTable instance that has already been filled with words and had its LanguageID set.

Returns:

CB_ERROR_NULL_POINTER if CBData::pChatHandler is NULL (Language Tables loaded too early).

CB_SUCCESS

Class	CBLanguageTable
Header	CBLanguageTable.h