Suppose you have a map league, where bots host your map and keep track of stats. But the map has modes and you want to force a particular mode in league games (eg. random pick or hard difficulty) without having a separate league version of the map. There is no good way to do this, so you use HCL to pass a short mode in.
This library allows the bot to communicate with your map by encoding characters into players' handicaps (idea by Varlock). Warcraft 3 normally only allows 6 possible handicaps, but bots can specify 256 different values. By encoding the original handicap inside the larger handicap, and only performing the encoding just before the map starts, players don't even realize their handicap was temporarily mutilated.
There is a limit of 1 character per player (empty slots don't count, but computers do), and the characters are limited to the set "abcdefghijklmnopqrstuvwxyz0123456789 -=,.". So don't expect someone to be entering long strings this way. Make the automated modes as short as they need to be. To read the mode entered by the bot, just call HCL_GetCommandString(). If it returns the empty string, there was no mode entered.
It's probably a good idea to include this in popular maps, even if they don't use it. If a bot tries to enter modes on a map without this library, the player handicaps will be absolutely ruined.
History
JASS:
library HCL initializer init
globals
private string command = ""
endglobals
public function GetCommandString takes nothing returns string
return command
endfunction
private function init takes nothing returns nothing
local integer i
local integer j
local integer h
local integer v
local string chars = "abcdefghijklmnopqrstuvwxyz0123456789 -=,."
local integer array map
local boolean array blocked
set blocked[0] = true
set blocked[50] = true
set blocked[60] = true
set blocked[70] = true
set blocked[80] = true
set blocked[90] = true
set blocked[100] = true
set i = 0
set j = 0
loop
if blocked[j] then
set j = j + 1
endif
exitwhen j >= 256
set map[j] = i
set i = i + 1
set j = j + 1
endloop
set i = 0
loop
exitwhen i >= 12
set h = R2I(100*GetPlayerHandicap(Player(i)) + 0.5)
if not blocked[h] then
set h = map[h]
set v = h/6
set h = h-v*6
call SetPlayerHandicap(Player(i), 0.5 + h/10.0)
set command = command + SubString(chars, v, v+1)
endif
set i = i + 1
endloop
endfunction
endlibrary
