Raised This Month: $12 Target: $400
 3% 

Achievements API


Post New Thread Reply   
 
Thread Tools Display Modes
Plugin Info:     Modification:   ALL        Category:   Technical/Development        Approver:   Arkshine (91)
Xellath
Veteran Member
Join Date: Dec 2007
Location: Sweden
Old 08-30-2011 , 14:36   Achievements API
Reply With Quote #1

Achievements API
Version: 0.0.4


Content

Description
Achievements API allows you to create, remove and customize your own set of achievements. Achievements are seperated into seperate plugins and registered to a core plugin, to allow complete customization. The API is not just extensive, it allows you to save data either using SQLVault or NFVault.


Installation
Follow these instructions:
  1. Download and extract the achievement_api.zip attached below into your amxmodx folder.
  2. When extracted; compile it locally. (How to compile)
  3. Install plugin (move it from compiled to plugins) and write achievement_api.amxx in your plugins.ini file.

    NOTE: achievement_api.amxx MUST be placed on top of the other achievement_*.amxx plugins.

    Code:
    achievement_api.amxx
    achievement_addict.amxx
    achievement_1337.amxx
    achievement_motd.amxx ;(if you want to be able to check your achievements in a MOTD)

Customization

Follow the steps below to customize the API to your needs.

Default saving is with NFVault.

As said before, this API allows saving by either SQL or Vault, so to enable SQL and disable Vault for example;
You need to open the plugin in an editor (notepad for example) and remove the comment from line 3:
Code:
//#define UseSQL // comment to use nfvault (local saving)
To:
Code:
#define UseSQL // comment to use nfvault (local saving)

To remove ChatColor; (To use chatcolor requires the chatcolor plugin and include file that is attached)
You need to open the plugin in an editor (notepad for example) and comment line 11:
Code:
#define UseChatColor // comment to use regular chat text, without colors)
To:
Code:
//#define UseChatColor // comment to use regular chat text, without colors

To add CZTutor messages;
You need to open the plugin in an editor (notepad for example) and uncomment line 16:
Code:
//#define UseCZTutor // comment to use tutor messages (only works on CZ)
To:
Code:
#define UseCZTutor // comment to use tutor messages (only works on CZ)

NOTE: CZTutor messages ONLY work on Condition Zero.

Save and recompile, and you're good to go!


Commands

There's only one command available (and only if achievement_motd.amxx is installed):
  • /achievements - Shows your current achievement progress in a MOTD window


Creating Custom Achievements (API)


API Guide:
HOW TO: Create a custom achievement (plus a webstats snippet!)

The API is very easy easily handled. Lets go through some natives and the forward that is available. There is a total of nine natives and one forward.

Natives
  • Code:
    /*  * Registers an achievement  *  * @param      Name - Achievement name  * @param      Description - Description of objective to complete achievement  * @param      SaveName - Save key that is used to set data  * @param      MaxValue - Max value to complete achievement  *  * @return   Pointer to achievement  */ native RegisterAchievement( const Name[ ], const Description[ ], const SaveName[ ], const MaxValue );
  • Code:
    /*  * Sets the current achievement status  *  * @param      Client - Index of player  * @param      AchievementPointer - Pointer from the registration of the achievement  * @param      Announce - Whether to announce achievement earned or not (default: true)  *  * @noreturn  */ native ClientAchievementCompleted( const Client, AchievementPointer, bool:Announce = true );
  • Code:
    /*  * Gets the current achievement status  *  * @param      AchievementPointer - Pointer from the registration of the achievement  * @param      Objective - Client value to check whether its over max value or not  *  * @return    Returns the current Status of achievement  *  * @note        enum Status  *        {  *          _In_Progress = 0,  *          _Unlocked  *        };  */ native Status:GetClientAchievementStatus( AchievementPointer, Objective );
  • Code:
    /*  * Returns the name of the achievement  *  * @param      AchievementPointer - Pointer from the registration of the achievement  * @param      Description - Name passed by reference  *  * @return    Returns the name by reference (2nd param)  */ native GetAchievementName( AchievementPointer, Name[ ] );
  • Code:
    /*  * Returns the description of the achievement  *  * @param      AchievementPointer - Pointer from the registration of the achievement  * @param      Description - Description passed by reference  *  * @return    Returns the description by reference (2nd param)  */ native GetAchievementDesc( AchievementPointer, Description[ ] );
  • Code:
    /*  * Returns the save key that is required to complete achievement  *  * @param      AchievementPointer - Pointer from the registration of the achievement  * @param      SaveKey - Key passed by reference  *  * @return    Returns the save key by reference (2nd param)  */ native GetAchievementSaveKey( AchievementPointer, SaveKey[ ] );
  • Code:
    /*  * Returns the max value that is required to complete achievement  *  * @param      AchievementPointer - Pointer from the registration of the achievement  *  * @return    Returns the max value that is required to complete achievement  */ native GetAchievementMaxValue( AchievementPointer );
  • Code:
    /*  * Returns the total number of achievements client has completed  *  * @param      Client - Index of player  *  * @return    Returns the total number of achievements client has completed  */ native GetClientAchievementsCompleted( const Client );
  • Code:
    /*  * Returns the total number of achievements  *  * @noparams  *  * @return    Returns the total number of achievements  */ native GetMaxAchievements( );
  • Code:
    /*  * Assign an integer value to Key in database/vault  *  * @param      Key - Key to where to set data (mainly used as steamid)  * @param      SaveName - Save name used in the init of an achievement (RegisterAchievement() param 4)  * @param      Data - Integer value assigned to Key  *  * @noreturn  */ native SetAchievementData( const Key[ ], const SaveName[ ], Data );
  • Code:
    /*  * Gets an integer value from database/vault  *  * @param      Key - Key to where to look for data (mainly used as steamid)  * @param      SaveName - Save name used in the init of an achievement (RegisterAchievement() param 4)  *  * @return    Returns the value on success, 0 on failure to get data (and if there is no progress)  */ native GetAchievementData( const Key[ ], const SaveName[ ] );

Forwards
  • Code:
    /*  * Called when a player has recently earned an achievement  *  * @param      AchiPointer - Pointer to achievement  * @param      Client - Index of player  *  * @noreturn  *  */ forward Forward_ClientEarnedAchievement( const AchiPointer, const Client );

All natives and forwards are explained in the example plugin and the two attached WORKING achievements (addict and 1337). Documentation in the achievement_api.inc.
The forward is mainly used to award additional things (such as perhaps a model or xp from your xp mod - no limits; everything is possible!), it's not necessary to include in your code at all.


Thanks
  • Empī for his NFVault include file.
  • Exolent for his SQLVault include file and his way of showing Dynamic Items.
  • ConnorMcLeod for his ColorChat include file.
  • Hunter-Digital for this thread layout. (Sorry bout that! Too lazy to format my own...)
  • The people that was requesting this and nagging enough to make me complete it.


Changelog

Code:
v0.0.4:
	* Changed plugins: achievement_api.sma
	achievement_api.sma:
	~ Fixed MySQL saving. SQLite still works if needed.
	- Removed api_sql_* cvars (API now uses the amx_sql_* cvars by default)

v0.0.3:
	* Changed plugins: achievement_api.sma, achievement_api.inc
	* New plugins: achievement_motd.sma
	achievement_api.sma:
	~ Fixed invalid cellvector issue.
	+ Added two new natives: GetAchievementName(), GetAchievementDesc()
	achievement_api.inc:
	+ Natives

v0.0.2:
	* Changed plugins: achievement_api.sma, achievement_addict.sma
	* New plugins: colorchat.sma and include file chatcolor.inc (both required for chatcolor; can be disabled if wanted)
	achievement_api.sma:
	- Removed CZTutor availability for CS 1.6, now only works for CZ.
	- Resources removed.
	+ Added colorchat to compensate for CZTutor removal.
	achievement_addict.sma:
	~ Fixed a small bug involving times connected.
	
v0.0.1:
	- Initial Release.

Notes

Please report to me if there are any problems regarding this system that I have presented. Any bugs, suggestions or feedback is wholeheartedly welcome.

For moderators; I do not know if this qualifies as a plugin submission, if it does not, it may be suited more for Code Snippets/Tutorials.

For plugin developers; to see a comprehensive example I would refer you to look at one of the achievement_*.sma files and achievement_example.sma explains how to register several achievements in the same plugin.

Servers using this plugin

Thank you for your time.

Previous version views: roughly 790
Attached Files
File Type: sma Get Plugin or Get Source (achievement_motd.sma - 2609 views - 2.8 KB)
File Type: sma Get Plugin or Get Source (achievement_example.sma - 2410 views - 6.7 KB)
File Type: sma Get Plugin or Get Source (achievement_api.sma - 2773 views - 10.5 KB)
File Type: inc achievement_api.inc (4.0 KB, 1011 views)
File Type: zip achievement_api.zip (30.0 KB, 1745 views)

Last edited by Xellath; 11-28-2011 at 11:23. Reason: Updated to v0.0.4 (check changelog)
Xellath is offline
FaktuM
Junior Member
Join Date: Oct 2009
Location: Sweden
Old 08-30-2011 , 14:42   Re: Achievements API
Reply With Quote #2

Perfection at it's finest, excellent work!
FaktuM is offline
Gam3ronE
SourceMod Donor
Join Date: Aug 2010
Old 08-30-2011 , 15:03   Re: Achievements API
Reply With Quote #3

Very good job thank you for sharing.
Gam3ronE is offline
Xellath
Veteran Member
Join Date: Dec 2007
Location: Sweden
Old 08-30-2011 , 15:19   Re: Achievements API
Reply With Quote #4

Thanks.

Reuploaded the attachments; forgot to comment out debug-mode.
Xellath is offline
nikhilgupta345
Veteran Member
Join Date: Aug 2009
Location: Virginia
Old 08-30-2011 , 15:23   Re: Achievements API
Reply With Quote #5

You could put the enum _:AchievementDataStructure directly into the .inc file so that people don't have to put that in every single achievements plugin if they decide to use your way for registering achievements.

Good job though.
__________________
Quote:
Originally Posted by DarkGod View Post
nikhilgupta generates his plugins using sheer awesome.
If you like my work, please
nikhilgupta345 is offline
Send a message via ICQ to nikhilgupta345 Send a message via Yahoo to nikhilgupta345
drekes
Veteran Member
Join Date: Jul 2009
Location: Vault 11
Old 08-30-2011 , 17:47   Re: Achievements API
Reply With Quote #6

Nice work.
__________________

Quote:
Originally Posted by nikhilgupta345 View Post
You're retarded.
drekes is offline
Send a message via MSN to drekes
DarkGod
SourceMod DarkCrab
Join Date: Jul 2007
Location: Sweden
Old 08-31-2011 , 03:34   Re: Achievements API
Reply With Quote #7

I'm pretty sure the CZTutor message is only allowed if you actually own CZ, so you should remove the resources and say that it's only allowed on CZ servers (they'll have them anyways so it shouldn't be necessary to attach). I'm quite sure it was deleted from some plugins using it in the past.

Nice work, though. I'm glad to see something from you as I haven't seen you for a while :]
__________________
DarkGod is offline
Send a message via AIM to DarkGod Send a message via MSN to DarkGod
abdul-rehman
Veteran Member
Join Date: Jan 2010
Location: Khi, Pakistan
Old 08-31-2011 , 04:17   Re: Achievements API
Reply With Quote #8

Nice work. !
__________________

My Plugins For ZP

Inactive due to College and Studies
abdul-rehman is offline
Send a message via Yahoo to abdul-rehman Send a message via Skype™ to abdul-rehman
Xellath
Veteran Member
Join Date: Dec 2007
Location: Sweden
Old 08-31-2011 , 11:29   Re: Achievements API
Reply With Quote #9

Update v0.0.2:
Code:
v0.0.2:
	* Changed plugins: achievement_api.sma, achievement_addict.sma
	* New plugins: colorchat.sma and include file chatcolor.inc (both required for chatcolor; can be disabled if wanted)
	achievement_api.sma:
	- Removed CZTutor availability for CS 1.6, now only works for CZ.
	- Resources removed.
	+ Added colorchat to compensate for CZTutor removal.
	achievement_addict.sma:
	~ Fixed a small bug involving times connected.
Reuploaded all resources and removed the tutor-related ones.

Also planning to write a tutorial of how to create achievements, so stay tuned.

nikhilgupta345:
Thank you!

Chose not to place the struct in the include file because users should not feel forced to use an enum for their registration. However, I thank you for your suggestion.

DarkGod:
Thanks for clarifying that it's against copyright to make it enabled on non-CZ-servers. Made it available only on CZ servers and removed the resources.

And yeah, I was on hiatus from CS for quite some time, just didn't seem like any fun to me at the time. Anyhow, I always liked to do some sideproject-programming so I ended up here again. Glad to see you and thanks!

drekes and abdul-rehman:
Thank you!

Last edited by Xellath; 08-31-2011 at 11:32.
Xellath is offline
nikhilgupta345
Veteran Member
Join Date: Aug 2009
Location: Virginia
Old 08-31-2011 , 13:17   Re: Achievements API
Reply With Quote #10

Quote:
Originally Posted by Xellath View Post
nikhilgupta345:
Thank you!

Chose not to place the struct in the include file because users should not feel forced to use an enum for their registration. However, I thank you for your suggestion.
Just because it's in the include file does not mean that players must use the enum to register the achievements. I'm saying that I think a lot of people would prefer your way, so instead of making them copy + paste the enum or write it out every time, they could use the one provided in the include file.
__________________
Quote:
Originally Posted by DarkGod View Post
nikhilgupta generates his plugins using sheer awesome.
If you like my work, please
nikhilgupta345 is offline
Send a message via ICQ to nikhilgupta345 Send a message via Yahoo to nikhilgupta345
Reply


Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are GMT -4. The time now is 13:28.


Powered by vBulletin®
Copyright ©2000 - 2024, vBulletin Solutions, Inc.
Theme made by Freecode