Documentation

###Table of Contents

• License
• Standards
  • Naming
  • Usage
  • Internal Documentation
  • Structure
• Utilities
  • Mine Information
  • Player Information
    • wearingMiningGear
    • canAdventure
    • canMine
  • Mine Parsing
  • Actions
    • pwhash
    • mineAtSpot

 

License

This software falls under the Creative-Commons Attribution Share-Alike 4.0 International License (cc-by-sa). Share it, edit, use it, credit.

Standards and Conventions

Standards are adapted from CS61B-style

The file MUST end with a newline.

Naming

Since there is no package schema in ASH scripts, all names of elements of this library should start with the prefix utils_mining_. All suffix names follow the programming lowerCamelCase naming convention. Parameter names, function names, and field names must be descriptive. (Please, no cultural references).

Usage

This library is not intended to be directly usable from the graphical CLI.

Internal Documentation

Major sections should be marked with /** two-asterisk **/ level comments and minor sections should be marked with /** three-asterisk ***/ level comments.

All functions and fields should be fully described with //doubleslash commentary. If expensive, runtime and space bounds should be provided.

Structure

Helper functions should appear before their children. They should have their own utility and be fully documented.

Fields and functions should appear in the file as closely as possible to the order they appear here.

Appropriate indentation with a buffer size of four spaces should be applied. All separate elements should be separated with blank lines.

 

Utilities

Features available within the KoLMinerUtils library in utils_mining.ash.

Mine Information

These functions are passive information about the mine and do not require the mine to be loaded. They do not perform any actions.

 

Player Information

These functions are concerned with the player state and do not require the mine to be loaded. They do not perform any actions.

wearingMiningGear

• boolean utils_mining_wearingMiningGear()

Checks whether or not the player is equipped to mine generic mines. This includes the Knob shaft, Itznotyerzitz_Mine, and the Gummi Mine (retired).

It returns true if and only if the player is wearing the outfit Mining Gear or Dwarvish War Uniform, or if they are on the challenge path Way of the Surprising Fist, have the Earthen Fist effect active.

#####Example

The following code checks if the player is properly equipped to mine, and if they are not, attempts to equip the outfit Mining Gear, or reports and halts if it is absent.

if (! utils_mining_wearingMiningGear()) {
    if (have_outfit("Mining Gear")) {
        outfit("Mining Gear);
    } else {
        print("Need outfit: Mining Gear", "red");
        return;
    }
}

 

canAdventure

• int utils_mining_canAdventure()

Returns the status of the player with regards to adventuring in general as a int code.

Note that this shares its codes with canMine.

Return codes:

• 0 - Fit to mine.
• 1 - Has no adventures left.
• 2 - Beaten up/Unsafe hp or mp.
• 3 - Drunk.

Example

The following code checks if a player is ready to adventure at any mining spot. If not, it prints information to the CLI.

switch (utils_mining_canAdventure()) {
    case 0: break;
    case 1: print("can't go there.", "red"); break;
    case 2: print("No adventures left.", "red"); break;
    case 3: print("need to heal/restore mp", "black"); break;
}

canMine

• int utils_mining_canMine(int mineCode)
• int utils_mining_canMine(string mine)

Returns the status of the player with regards to mining as a int code.

Return codes:

• 0 - Fit to mine.
• 1 - Has no adventures left.
• 2 - Beaten up/Unsafe hp or mp.
• 3 - Drunk.
• 4 - No access to the mine.
• 5 - Improperly equipped.

Example

The following code checks if a player is ready to mine at Mine 6 (the Gold mine). If it is, it attempts to mine the square (2,4). If not, it prints information to the CLI.

switch (utils_mining_canMine(6)) {
    case 0:
        mineAt(6, 2, 4);
        break;
    case 1: print("can't go there.", "red"); break;
    case 2: print("No adventures left.", "red"); break;
    case 3: print("need to heal/restore mp", "black"); break;
    case 4: print("You're drunk, bub.", "red"); break;
    case 5: print("Put on more clothes.", "black"); break;
}

 

Mine Parsing

These functions are concerned with the loading and processing of the mine's data. They do not perform any actions.

 

Actions

These functions execute actions that may have irreversible changes. Use with caution.

pwhash

string utils_mining_pwhash;

Field whose value is "&pwd=" + my_hash(), to be used for HTTP POST requests to the server.

This field is present for performance but not recommended for external use.

Example

Mines at square (1, 1) Mine 6 (the Gold mine) and writes it to the buffer page. (Not recommended; use mineAtSpot instead)

buffer page = visit_url("mining.php?mine=6&which=9" + utils_mining_pwhash, true);

 

mineAtSpot

• buffer utils_mining_mineAtSpot(int mineCode, int square)
• buffer utils_mining_mineAtSpot(int mineCode, int col, int row)
• buffer utils_mining_mineAtSpot(string mine, int square)
• buffer utils_mining_mineAtSpot(string mine, int col, int row)

Visits the mine at mineCode or the mine called mine and attempts to mine at the square given by the number square or the coordinates (col, row). Returns the resultant page as a buffer.

Example

Mines at square (4, 2) in Mine 6 (the Gold mine) and writes it to the buffer page.

buffer page = utils_mining_mineAtSpot(6, 4, 2);

 

---

Want to contribute to this project?

Fork, add documented changes on a new branch, test, merge, and create a pull request.