Package com.planet_ink.coffee_mud.Libraries.interfaces

Interface AchievementLibrary

All Superinterfaces:

java.lang.Cloneable, CMLibrary, CMObject, java.lang.Comparable<CMObject>

All Known Implementing Classes:

Achievements

public interface AchievementLibrary
extends CMLibrary

The achievement library forms the basis of the achievement system, which accepts player events as input, as well as the file based achievement definition files, and tracks player and account completion of achievements through trackers.

See Also:

AchievementLibrary.Event, AchievementLibrary.Tracker, AchievementLibrary.Achievement

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	AchievementLibrary.AbilityAward	The AbilityAward interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.Achievement	The achievement interface provides basic information about the specific achievement, as defined in the achievements.ini definition file.
static class	AchievementLibrary.AchievementFlag	Legal values for the FLAGS field in an achievement.
static class	AchievementLibrary.AchievementLoadFlag	Flags to denote how awards are given when achievements are granted, especially on character creation and/or remort.
static interface	AchievementLibrary.AmountAward	The award interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.Award	The award interface provides pre-parsed award information for those who complete the achievement.
static class	AchievementLibrary.AwardType	The award type is an enumeration of the different types of awards that can be granted for completing an achievement.
static interface	AchievementLibrary.CurrencyAward	The award interface provides pre-parsed award information for those who complete the achievement.
static class	AchievementLibrary.Event	Events define the type of achievement, describing specific arguments that the achievement of each event type needs.
static interface	AchievementLibrary.ExpertiseAward	The ExpertiseAward interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.StatAward	The award interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.TattooAward	The TattooAward interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.TitleAward	The award interface provides pre-parsed award information for those who complete the achievement.
static interface	AchievementLibrary.Tracker	A tracker object assigned to a particular player or account for a particular achievement, allowing the achievement to track progress if it needs to, or just providing a way to quickly query completion otherwise.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String[]	BASE_ACHIEVEMENT_PARAMETERS	The list of arguments/parameters common to all achievement event types -- remember to also modify fillAchievementParmTree

Fields inherited from interface com.planet_ink.coffee_mud.core.interfaces.CMObject

idConverter

Method Summary

Modifier and Type	Method	Description
java.util.Enumeration<AchievementLibrary.Achievement>	achievements(AccountStats.Agent agent)	Allows iterating through all the achievements of the given agent group.
boolean	addModifyAchievement(MOB mob, AccountStats.Agent agent, java.lang.String tattoo, AchievementLibrary.Achievement A)	Allows a new achievement to be added or removed, with a user interface editor presented for the given mob.
void	bumpAchievement(MOB mob, AchievementLibrary.Achievement A, int bumpNum, java.lang.Object... parms)	Always causes a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well.
AchievementLibrary.Achievement	deleteAchievement(java.lang.String tattoo)	Finds and deleted the achievement with teh given tattoo key.
boolean	evaluateAccountAchievements(MOB mob)	Iterates through all the player account achievements to see if the given mob has completed any new ones, granting them and the awards if they have.
java.lang.String	evaluateAchievement(AccountStats.Agent agent, java.lang.String row, boolean addIfPossible)	This method is how an achievement definition row is evaluated and added to the permanent list of achievements.
boolean	evaluateClanAchievements()	Iterates through all the clan achievements to see if any clans have completed any new ones, granting them and the awards if they have.
boolean	evaluatePlayerAchievements(MOB mob)	Iterates through all the player achievements to see if the given mob has completed any new ones, granting them and the awards if they have.
java.util.List<AchievementLibrary.Achievement>	fakeBumpAchievement(MOB mob, AchievementLibrary.Event E, int bumpNum, java.lang.Object... parms)	When an event occurs that might possible cause a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well.
java.lang.String	findAchievementID(java.lang.String ID, boolean exact)	Searches for an Achievement of the given tattoo name or display name, and returns the tattoo or display name that applies.
java.lang.String	fixAwardDescription(AchievementLibrary.Achievement A, AchievementLibrary.Award award, MOB forM, Tattooable forT)	Returns a friendly description of the award, adjusting for the recipient, and who the award was actually awarded to.
AchievementLibrary.Achievement	getAchievement(java.lang.String tattoo)	Returns the achievement with the given tattoo key.
java.lang.String	getAchievementsHelp(java.lang.String ID)	Searches for an Achievement of the given tattoo name or display name, and returns a help entry for the achievement.
java.lang.String	getAchievementsHelpFromMap(java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>> helpMap, AchievementLibrary.Event E, java.lang.String parmName)	Given the comments/help entried from the achievement definition file, and an event, and the name of the parameter inside the event, this returns the help entry for that parameter
java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>>	getAchievementsHelpMap()	Returns all the comment/help entries from the achievement definition file The map is of the form event ID, then parameter->help map.
java.lang.String	getAwardString(AchievementLibrary.Award[] awards)	Converts a parsed awards list back into an unparsed parameter/value string.
void	grantAbilitiesAndExpertises(MOB mob)	Typically called when a mob gains a level, to allow the achievements on the mob to assign any new skills or expertises.
void	loadAccountAchievements(MOB mob, AchievementLibrary.AchievementLoadFlag flag)	When a new player is created, this method inspects their account tattoos for any that need to be passed down to this new player.
void	loadClanAchievements(MOB mob, AchievementLibrary.AchievementLoadFlag flag)	When a new player added to a clan, this method inspects their clan tattoos for any that need to be passed down to this new member.
void	loadPlayerSkillAwards(Tattooable mob, PlayerStats stats)	When a player is loaded, this method inspects their tattoos for any past achievements and, if found, loads the playerstats with trackable skill and expertises mappings, allowing them to receive those awards when the time is right.
void	possiblyBumpAchievement(MOB mob, AchievementLibrary.Event E, int bumpNum, java.lang.Object... parms)	When an event occurs that might possible cause a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well.
void	reloadAchievements()	Forces all achievements to be reloaded from the definition file.
void	reloadPlayerAwards(MOB mob, AchievementLibrary.AchievementLoadFlag flag)	When a player remorts, they keep their player achievements, but the rewards are removed.
java.lang.String	removeClanAchievementAwards(MOB mob, Clan clan)	When a clan member is removed from his clan for any reason, this method is called to remove any inhereted benefits, such as titles, or abilities or expertises, etc.
void	resaveAchievements(java.lang.String modifyTattoo)	Forces any changed or deleted achievements to re-saved to the definition file.

Methods inherited from interface com.planet_ink.coffee_mud.Libraries.interfaces.CMLibrary

activate, getServiceClient, L, propertiesLoaded, shutdown

Methods inherited from interface com.planet_ink.coffee_mud.core.interfaces.CMObject

copyOf, ID, initializeClass, name, newInstance

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

BASE_ACHIEVEMENT_PARAMETERS

static final java.lang.String[] BASE_ACHIEVEMENT_PARAMETERS

The list of arguments/parameters common to all achievement event types -- remember to also modify fillAchievementParmTree

Method Detail

evaluateAchievement

java.lang.String evaluateAchievement(AccountStats.Agent agent,
                                     java.lang.String row,
                                     boolean addIfPossible)

This method is how an achievement definition row is evaluated and added to the permanent list of achievements. It accepts the coded row with key=value pairs for all the achievement arguments. If all is well, "" is returned, otherwise an error message is returned.

Parameters:

agent - whether this is a player or account

row - the coded key=value pairs row.

addIfPossible - true if, on success, the new achievement is added, false otherwise

Returns:

the error message, or "" for success

reloadAchievements

void reloadAchievements()

Forces all achievements to be reloaded from the definition file.

evaluatePlayerAchievements

boolean evaluatePlayerAchievements(MOB mob)

Iterates through all the player achievements to see if the given mob has completed any new ones, granting them and the awards if they have.

Parameters:

mob - the player to evaluate

Returns:

true if any achievements were newly completed, false otherwise

evaluateAccountAchievements

boolean evaluateAccountAchievements(MOB mob)

Iterates through all the player account achievements to see if the given mob has completed any new ones, granting them and the awards if they have.

Parameters:

mob - the player whose account to evaluate

Returns:

true if any achievements were newly completed, false otherwise

evaluateClanAchievements

boolean evaluateClanAchievements()

Iterates through all the clan achievements to see if any clans have completed any new ones, granting them and the awards if they have.

Returns:

true if any achievements were newly completed, false otherwise

achievements

java.util.Enumeration<AchievementLibrary.Achievement> achievements(AccountStats.Agent agent)

Allows iterating through all the achievements of the given agent group. If the agent is null, then ALL achievements from all groups are iterated through.

Parameters:

agent - the player, or account, or null for all

Returns:

the enumeration of all achievements that apply

getAchievement

AchievementLibrary.Achievement getAchievement(java.lang.String tattoo)

Returns the achievement with the given tattoo key.

Parameters:

tattoo - the tattoo key to find the achievement for

Returns:

the achievement object

deleteAchievement

AchievementLibrary.Achievement deleteAchievement(java.lang.String tattoo)

Finds and deleted the achievement with teh given tattoo key.

Parameters:

tattoo - the tattoo key to find the achievement for

Returns:

the achievement object deleted, or null if not found

resaveAchievements

void resaveAchievements(java.lang.String modifyTattoo)

Forces any changed or deleted achievements to re-saved to the definition file.

Parameters:

modifyTattoo - the tattoo modified or deleted

addModifyAchievement

boolean addModifyAchievement(MOB mob,
                             AccountStats.Agent agent,
                             java.lang.String tattoo,
                             AchievementLibrary.Achievement A)

Allows a new achievement to be added or removed, with a user interface editor presented for the given mob.

Parameters:

mob - the mob adding or editing the achievement

agent - whether player or account achievement

tattoo - the tattoo of the new or old achievement

A - the achievement to modify, or null for new

Returns:

true if the achievement was added or modified, false otherwise

possiblyBumpAchievement

void possiblyBumpAchievement(MOB mob,
                             AchievementLibrary.Event E,
                             int bumpNum,
                             java.lang.Object... parms)

When an event occurs that might possible cause a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well.

Parameters:

mob - the player whose achievement needs to be checked

E - the event that occurred

bumpNum - the amount to bump the achievement by

parms - any event-specific argument that help determine whether a bump is warranted.

bumpAchievement

void bumpAchievement(MOB mob,
                     AchievementLibrary.Achievement A,
                     int bumpNum,
                     java.lang.Object... parms)

Always causes a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well.

Parameters:

mob - the mob who is bumping the achievement

A - the achievement

bumpNum - the amount to bump, plus or minus

parms - any event-specific argument that help determine whether a bump is warranted.

fakeBumpAchievement

java.util.List<AchievementLibrary.Achievement> fakeBumpAchievement(MOB mob,
                                                                   AchievementLibrary.Event E,
                                                                   int bumpNum,
                                                                   java.lang.Object... parms)

When an event occurs that might possible cause a player to have one of their achievements bumped, this method is called with event specific parameters which might possibly cause the achievement to be bumped in the tracker, which might cause it to be completed as well. This method does not actually affect the players trackers, but only pretends to, and then returns the list of Achievements that would be gained by the effort.

Parameters:

mob - the player whose achievement needs to be checked

E - the event that occurred

bumpNum - the amount to bump the achievement by

parms - any event-specific argument that help determine whether a bump is warranted.

Returns:

the list of achievements that would be earned by the bump, if any. Empty list otherwise.

getAchievementsHelpMap

java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>> getAchievementsHelpMap()

Returns all the comment/help entries from the achievement definition file The map is of the form event ID, then parameter->help map.

Returns:

all the comment/help entries from the achievement definition file

getAchievementsHelpFromMap

java.lang.String getAchievementsHelpFromMap(java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>> helpMap,
                                            AchievementLibrary.Event E,
                                            java.lang.String parmName)

Given the comments/help entried from the achievement definition file, and an event, and the name of the parameter inside the event, this returns the help entry for that parameter

Parameters:

helpMap - the help map

E - the event to get help for

parmName - the parameter of that event to get help for

Returns:

the help text.

getAwardString

java.lang.String getAwardString(AchievementLibrary.Award[] awards)

Converts a parsed awards list back into an unparsed parameter/value string.

Parameters:

awards - a parsed awards list

Returns:

an unparsed parameter/value string

grantAbilitiesAndExpertises

void grantAbilitiesAndExpertises(MOB mob)

Typically called when a mob gains a level, to allow the achievements on the mob to assign any new skills or expertises. Can also be called just to populate a mob with achievement skills, so it should also confirm any lower level skills also.

Parameters:

mob - the mob to give abilities to.

See Also:

AbilityContainer.addAbility(Ability)

loadPlayerSkillAwards

void loadPlayerSkillAwards(Tattooable mob,
                           PlayerStats stats)

When a player is loaded, this method inspects their tattoos for any past achievements and, if found, loads the playerstats with trackable skill and expertises mappings, allowing them to receive those awards when the time is right.

Parameters:

mob - the tattooable mob to check tattoos on

stats - the playerstats to load with prizes

See Also:

grantAbilitiesAndExpertises(MOB)

loadAccountAchievements

void loadAccountAchievements(MOB mob,
                             AchievementLibrary.AchievementLoadFlag flag)

When a new player is created, this method inspects their account tattoos for any that need to be passed down to this new player. If any are passed down, then the awards are granted, including skill awards if any.

Parameters:

mob - the new character to load up.

flag - the circumstances under which achievements are being loaded

See Also:

loadPlayerSkillAwards(Tattooable, PlayerStats)

loadClanAchievements

void loadClanAchievements(MOB mob,
                          AchievementLibrary.AchievementLoadFlag flag)

When a new player added to a clan, this method inspects their clan tattoos for any that need to be passed down to this new member. If any are passed down, then the awards are granted, including skill awards if any.

Parameters:

mob - the new character to load up.

flag - the circumstances under which achievements are being loaded

See Also:

loadPlayerSkillAwards(Tattooable, PlayerStats)

reloadPlayerAwards

void reloadPlayerAwards(MOB mob,
                        AchievementLibrary.AchievementLoadFlag flag)

When a player remorts, they keep their player achievements, but the rewards are removed. This method is called to re-reward all player achievement rewards.

Parameters:

mob - the mob to award

flag - this is happening before or after stat selection

getAchievementsHelp

java.lang.String getAchievementsHelp(java.lang.String ID)

Searches for an Achievement of the given tattoo name or display name, and returns a help entry for the achievement.

Parameters:

ID - the tattoo name or display name

Returns:

the help entry, or ""

findAchievementID

java.lang.String findAchievementID(java.lang.String ID,
                                   boolean exact)

Searches for an Achievement of the given tattoo name or display name, and returns the tattoo or display name that applies.

Parameters:

ID - the tattoo name or display name

exact - true for exact match only, false otherwise

Returns:

the final tattoo name or display name

fixAwardDescription

java.lang.String fixAwardDescription(AchievementLibrary.Achievement A,
                                     AchievementLibrary.Award award,
                                     MOB forM,
                                     Tattooable forT)

Returns a friendly description of the award, adjusting for the recipient, and who the award was actually awarded to.

Parameters:

A - the achievement the award came from

award - the award

forM - the recipient of the award

forT - the earner of the award (mob, clan, etc...)

Returns:

the friendliest award description possible

removeClanAchievementAwards

java.lang.String removeClanAchievementAwards(MOB mob,
                                             Clan clan)

When a clan member is removed from his clan for any reason, this method is called to remove any inhereted benefits, such as titles, or abilities or expertises, etc.

Parameters:

mob - the evicted mob

clan - the clan evicted from

Returns:

the message about what is removed