The Achievements Script v1.0 Documentation - March 12th, 201

The Achievements Script v1.0 by DES|Bukz - README - Last Update: March 12th, 2011
---------------------------------------------------------------------------------
A valid (IMHO) attempt to add an achievements system to AssaultCube via strictly CubeScript.
Features 16 unlockable achievements with 3 variable degrees of difficulty, and a "level-up"
type system that only allows you to unlock higher level achievements if you have unlocked
all of the current level's achievements first.

Thanks to DES|GeneralDisarray, V-Man, and V-Wifey for their hard work on the 12 awesome
new sounds used in the script. Thanks to all the folks at {BoB} clan for all their help
advertising, testing, giving suggestions, etc. Thanks to everyone else who I may have
forgotten to add up here, I'm happy that this can now be considered a community project.

This script requires tools.cfg! http://forum.cubers.net/thread-1776.html

This script is licensed under the attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0) license:

http://creativecommons.org/licenses/by-nc-sa/3.0/

CREDITS
-------

Bukz            - Creator/Rage Scripting
GeneralDisarray - Advice/Audio/trimf (a.k.a. format_precision)/'The Lead Wind Blows' achievement's 'scoring' system
V-Wifey         - Vocals
V-Man           - Advice/Testing/Vocals
Billybob        - Advertising/Hosting
gRamps          - Advertising/Advice/Ideas/Testing
slackie         - Advertising
R4zor           - Promotional GFX Work
Gibstick        - Advice/Ideas/Testing
vern            - Advice/Ideas/Motivation/Testing
Splatz          - Ideas
Lantry          - Ideas
Frogulis        - Ideas
noOne           - Ideas

CHANGELOG
---------

v1.0 stable - March 11th, 2011:
-------------------------------

* Formatting heavily modified for less overall script length (in lines). *** Upon request, I'll make a modder friendly version available that has proper formatting, or versions that work offline with bots, etc.
* The listlen command was *almost* entirely avoided in favor of more efficient, predefined loops.
* New achievement "The Lead Wind Blows" that is based off the total number of bullets fired over time.
* Achievement "Akimbo Madman" now has lower difficulties.
* Achievement "Knife Specialist" is now an "over time" achievement".
* All "over time" achievements now have higher difficulties.
* New optional sound system.
* 12 awesome new sounds thanks to DES|GeneralDisarray, V-Man and V-Wifey. :)
* The "Killstreak Settings" menu is now the "Achievements Script Settings" menu.
* Bunch of new sliders in the settings menu.
* New optional stats at the top of the menu that keep track of stuff like total: bullets fired, enemies killed, and rounds played (since progress start).
* New command "achievement_stats_top" for enabling or disabling the extra stats at the top of the "My Achievements" menu.
* New commands "add_achievements_main" and "add_achievements_ingame" for adding the "My Achievements" menu (item) to existing default AssaultCube menus.
* New command "achievement_progress_style" for choosing between default (progress/goal) or new "percentages" view on the "My Achievements" menu.
* New command "achievement_percentage_style" for choosing between default (rounded whole numbers) or (floating point) percentages on the "My Achievements" menu.
* New command "achperlen" for setting the number of decimal places for the floating point percentages on the "My Achievements" menu.
* New commands "sound_on_achievement" and "sound_on_levelup" for enabling or disabling the new sounds sytem.
* New "extra" messages on the killstreaks if you're in the 2-10 killstreak range.
* The "My Achievements" menu keybind requirement was removed from the actual script and put into the settings menu so users can set the key of their choice there, hopefully making installation less confusing in the future.
* Script packaged as a zip archive now due to the new custom media (audio) requirement.
* EOL style changed from WIN to UNIX on all .cfg files for less saved.cfg spam.
* More stuff that can't be listed or I have forgotten... :P


v1.0 beta - February 10th, 2011:
--------------------------------

* First public release! :)

INSTALLATION
------------

NOTE: This script requires "tools.cfg", a collection of useful scripts (tools) for cubescripters to be installed in order to function.
      This script also requires it's custom sounds to be registered FIRST, before any other scripts you are using registers theirs. If you do not have any custom sounds (more than the default 98 in AssaultCube) you can safely ignore this warning.

Step 1: Extract "The_Achievements_Script_v1.0.zip" to your AssaultCube installation folder. (On windows, this is commonly C:\Program Files\AssaultCube_v1.1.0.4)
Step 2: Open the "config" folder in your AssaultCube installation folder.
Step 3: Open the "autoexec.cfg" file with any text editor. (Notepad will work.)
Step 4: Add the following lines below where you execute tools.cfg:
  run achievements; run achievements_docs
Step 5: Save and exit. (The script is now installed and you're almost done ! ;)
Step 6: Launch AssaultCube and enter the following command to the in-game console:
  /showmenu "My Achievements"
Step 7: Enter the Settings menu by checking the option at the bottom of the Achievements menu.
Step 8: Setup your "My Achievements" menu keybind and other script settings and you're good to go! :D

AUTOEXEC
--------

Here is what your autoexec should look like after having installed the achievements script properly:

exec config\tools.cfg
run achievements; run achievements_docs

OR...

run tools
run achievements; run achievements_docs

Take special note how you are executing the tools.cfg file before executing the Achievements script! This is absolutely necessary for the proper functioning of the script.

Optionally, instead of adding "run achievements; run achievements_docs" and moving the "achievements.cfg" and "achievements_docs.cfg" files to your config folder, you can drop them in your automatically executed scripts folder by following the instructions from this thread:

http://forum.cubers.net/thread-2356.html

NOTE: You still must ensure that the achievements script registers it's sounds FIRST, and is executed AFTER tools.cfg!

COMMANDS
--------

/achievement_stats_top        - Enables or disables extra over time stats at the top of the "My Achievements" menu.
/add_achievements_main        - Enables or disables adding the "My Achievements" menu (item) to the default "main" menu.
/add_achievements_ingame      - Enables or disables adding the "My Achievements" menu (item) to the default "In-game" menu.
/achievement_progress_style   - Enables or disables the new percentages view for the "My Achievements" menu.
/achievement_percentage_style - Enables or disables floating point percentages on the "My Achievements" menu.
/achperlen                    - Sets the exact number of decimal places on floating point percentages on the "My Achievements" menu.
/sound_on_achievement         - Enables or disables the various achievement unlock sounds.
/sound_on_levelup             - Enables or disables the on level up sounds.
/reset_achievements           - Resets your achievement progress.
/reset_all_achievements       - Resets EVERYTHING achievements script related, progress, completions counter, etc.
/show_killstreak_switch       - Enables or disables the showing of extra killstreak messages on the console.

NOTES
-----

"The Lead Wind Blows" achievement uses a "balancing system" to make the achievement fair for non-automatic weapons users. In theory it will take
longer for the automatic weapon user to earn this achievement because of the much higher rate of fire on their weapons, however, because of the way
that the system scores every bullet, the achievement will take approximately the same amount of time regardless of what your primary weapon of choice is.

You must ensure that the achievements script is registering it's custom sounds before any others because the script assumes default sounds only and uses
sounds 99-110 after installation to play the proper sound file upon achievement unlock/level completion. If for some reason other custom sounds are registered
first, the script will most likely play the wrong sound file!

The /reset_achievements command resets everything you need to play the script again after having beaten it. The /reset_all_achievements resets everything and
should only be used when you want the script completions counter, secret achievement progress, and other over time stats counters to reset as well.

The script relies heavily on saved.cfg being readable/writable by AssaultCube to store and gather/display information, progress and statistics used by the script. If
for some reason your saved.cfg gets deleted, you will lose all of your progress and you will also lose any saved progress you had when using the save/load state script
for the achievements script. This is an unfortunate but inevitable drawback of the cubescript system. Take careful note that executing commands like "/resetcfg" WILL
ALSO delete your saved.cfg and cause this to happen.

A lot of data was added to this update because of the large amount of new features and settings, but because this script still does not modify and read a massive amount
of data (aliases) simultaneously, the chances of suffering from the "large FPS drop of the MPL Script" is unlikely. If you do suffer from this or any other achievements
script related problems PLEASE report them ASAP so they can be fixed in future versions! :)

Although this script is licensed under the attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0) license, the sounds (created by DES|GeneralDisarray) are licensed under a completely different, custom license.
Read the "README.txt" in /packages/audio/sounds/achievements/gd/ for more information about this. Do not assume you are free to anything without his prior written permission.