ChatBlade SDK Documentation

Class   CBNicknameList
Header   CBNicknameList.h

Data    Member Summary    Member Details


CBNicknameList is a class designed to support the innovative /Nickname feature.  
Nicknames allow Players to create short, local, Nicknames for other Characters.  
Players can then use these Nicknames instead of the full Character Name to send /tells to the other Player.  
A Nickname is typically a shortened version of a hard to type, long, or familiar Character Name.  
Players can create Nicknames locally on their client by using the /nickname Slash Command (if the Game utilizes the Slash Commands contained in the sample SlashCommands.XML file).  
For Example:  
    /Nickname Zeb, Zebnoculous Androclese        would created a Nickname named "Zeb" that would expand to "Zebnoculous Androclese" when using the /Tell Slash Command.  
    So a user could then type "/tell Zeb, Howdy" which would send the Chat Message to Zebnoculous Androclese.  
Players can remove a Nickname by using the /nickname command with the previously defined Nickname as its parameter or by using the /unnickname Slash Command like so:  /nickname Zeb or /unnickname Zeb    would remove Zeb as a Nickname if it already was one.  
Players can display the current Nicknames they have defined for other players by using the "/nicknamelist" or "/nickname List" commands.  
Nicknames are quite useful when trying to communicate with Characters with difficult to type names such as:  
    /nickname Ill, Illipirilimininilirn
Nicknames can also facilitate /tells to Real Life friends that are playing the Game:  
    /nickname Mike, RockHeart OrcSmasher
Typically in MMOGs most Character names are truncated to 3 or 4 letters in common Group Chat usage.  If a Player is named Scandia then Players often refer to them as Scan.  A Player named Vanadia is usually called Van, etc.  Nicknames allow this normal practice to be codified and used in-game.  
Nicknames are supported only when using /Tell type commands.  They are not currently supported for various other commands such as /who or /follow.  
If a Nickname happens to be the actual name of another Character the other Character may be unreachable via /tells until the conflicting Nickname is removed.  
Here are some Example Nickname commands:  
    /nickname Pal, Palladia Delfin             Creates a Nickname of Pal which expands to Palladia Delfin in /tells
    /nickname Tom, Valeria StarChaser    Creates a Nickname of Tom which expands to Valeria StarChaser
    /nickname List    Displays all the current Nicknames
    /nicknamelist      Displays all the current Nicknames
    /nickname Pal           Removes Pal as a Nickname
    /unnickname Tom    Removes Tom as a Nickname
    /nickname Rom, Romornimirnilli Rediculousirn  Creates a Nickname of Rom which expands to Romornimirnilli Rediculousirn
    /tell Rom, Your Name is too hard to spell    Would send a tell to Romornimirnilli Rediculousirn.  
Nicknames are used Client side and are defined by a Player for other Characters.  
Players cannot define a Nickname for themselves which others can use.  
Each Player likely shall have their own unique list of Nicknames that they have defined.  
Nicknames themselves are limited to 1 word in length.  The real Character name they map to may contain spaces and be more than 1 word long, if the game supports First and Last names.  
Nicknames cannot be created for other Nicknames, only for true Character Names.  
ChatBlade has implemented the Nickname functionality.  Game Developers should not need much additional implementation beyond the Loading and Saving of the Nickname List.  
An instance of CBNicknameList is contained in CBChatHandler and may be referenced via CBData::pChatHandler->m_NicknameList.  

Game Developer Implementation:  

An instance of this class does not need to be created.  ChatBlade already creates an instance as a member of CBChatHandler.  This instance may be referenced via CBData::pChatHandler->m_NicknameList.  
Upon Game startup the Nickname list should be filled with whatever Nicknames a Player had previously defined.  
A Players Nickname list should be persisted so that it may be loaded again the next time a Player enters the Game.  

Source File Comments:  

// Represents a map of user defined Nicknames and their actual Character name equivalents
// Used to support the /nickname Command which lets users define their own Nicknames to use instead of full Character names
// Users may create Nicknames for other Players Character names
// /Nickname name without a Character name clears that Nickname
// /Nickname list displays all the Nicknames one has set up
// For Example:
//   /Nickname Zeb, Zebnoculous Androcles
//   Would allow the user to now type in /tell Zeb, Howdy
//   This class is designed to store the relation between "Zeb" and "Zebnoculous Androcles"
// Other Examples:
//   /Nickname Mike, Avrido Orcsmasher
//   /Nickname van, Vanadia
//   /Nickname Mike (clears this Nickname)
//   /Nickname list (lists our Nicknames)
// CBNicknameList is implemented as a map of the user defined Nicknames and their actual Character name equivalents
// Nicknames are converted to UPPERCASE before storage
// ChatBlade shall check each Character name the user enters and see if it is a Nickname when using /Tell and related Commands
// If so, ChatBlade shall replace that Nickname with the full Character name
// A Nickname cannot be used as a Nickname for another user defined Nickname, only a true Character name
// If the user makes a Nickname that is the Character name of another Player already
// that Player may not be accessible to /tells from this user, until the conflicting Nickname is cleared


std::map<CBSTRING, CBSTRING> m_NicknameMap
        A map of Nicknames and the actual Character names they represent.  Keyed via the UPPERCASE Nickname.  

Member Function Summary:  

        Empty Constructor.  
int  ClearList()
        Empties out all members in the NicknameList.  
int  AddNickname(CBSTRING sNickname, CBSTRING sCharacterName)
        Adds a Nickname to the NicknameList.  
int  RemoveNickname(CBSTRING sNickname)
        Removes a Nickname from the NicknameList.  
int  IsNickname(CBSTRING sNickname)
        Returns CB_TRUE if the parameter is a Nickname.  
int  ExpandNickname(CBSTRING & sNickname /*IN OUT*/)
        Replaces the Nickname with its real Character name.  

Member Function Detail:  

Empty Constructor.  
int  CBNicknameList::ClearList()
Removes all Nicknames from the Nickname List.  
int  CBNicknameList::AddNickname( CBSTRING sNickname,
  CBSTRING sCharacterName)
Adds a Nickname to the Nickname List.  
Creates a local Nickname that the Player can use for /Tells.  
sNickname is the short 1 word Nickname and sCharacterName is the full real Character Name which may be more than 1 word in length (for Games supporting multi-word Names).  
No check is made to ensure that sCharacterName is an actual Name of a Character.  
Nicknames should not be created for other Nicknames, only for real Character Names.  There is no recursion.  
The Nickname is converted to all UPPERCASE before storage, but the Character Name it maps to retains its Case.  
AddNickname() removes a Nickname if it had been previously added.  
Called by CBSlashCommands::OnCommandNickname().  
    A short 1 word Nickname that the Player can use to reference a full Character Name when using /tells.  
    The full Character Name that the Nickname shall expand to.  Can be empty if this function is invoked to remove a Nickname.  
CB_ERROR_EMPTY_STRING if sNickname is empty.  
CB_ERROR_DOES_NOT_EXIST if sCharacterName is empty and sNickname is not a Nickname that can be removed.  
CB_SUCCESS if the Nickname was added or removed.  
int CBNicknameList::RemoveNickname( CBSTRING sNickname)
Removes a previously defined Nickname from the Nickname List.  
Called by CBSlashCommands::OnCommandUnNickname() and CBNicknameList::AddNickname() (when using it to remove a Nickname).  
    A previously defined Nickname we want to clear out and remove from the Nickname List.  It is not Case Sensitive.  
CB_ERROR_EMPTY_STRING if sNickname is empty.  
CB_ERROR_DOES_NOT_EXIST if sNickname is not a previously defined Nickname.  
CB_SUCCESS if the Nickname was removed.  
int  CBNicknameList::IsNickname( CBSTRING sNickname)
Checks to see if the parameter is a previously defined Nickname.  
Returns CB_TRUE if sNickname is found in the Nickname List.  
Returns CB_FALSE if it is not found.  
sNickname is not Case Sensitive.  It is converted to UPPERCASE before comparison.  
Called by CBSlashCommands::OnCommandTell(), CBNicknameList::ExpandNickname(), and CBNicknameList::RemoveNickname().  
    A Name we want to check to verify if it is a Nickname or not.  
CB_FALSE if sNickname is empty or not a previously defined Nickname.  
CB_TRUE if sNickname is a defined Nickname.  
int  CBNicknameList::ExpandNickname( CBSTRING & sNickname /*IN OUT*/)
Replaces the Nickname with its real Character name.  
Takes an incoming Nickname and changes it in-place to its full Character name.  
For Example:  
    If Zeb is a Nickname for Zebnoculous and this function is called with the parameter Zeb, upon return sNickname shall be altered to be Zebnoculous.  
Called by CBSlashCommands::OnCommandTell().  
    A reference to a previously defined Nickname.  Upon function return this parameter shall be converted to the full real Character Name that the Nickname represented.  
CB_FALSE if sNickname is not a Nickname.  
CB_TRUE if sNickname was expanded to a full Character Name.  
Upon return sNickname shall be modified to be a full Character Name.  




ChatBlade Copyright Flex Dolphynn