Merge branch 'dev'

COMMANDS.en.md

@@ -0,0 +1,169 @@
+Commands are are given in "FULL_VERSION/ABBR_VERSION", while examples are always using full version.
+
+Globals:
+
+ HH current hour(24-hour format)
+ MM current minute
+ BC left BC
+ BC% left BC as percent, like 0.22
+ AP left AP
+ AP% left AP as percent, like 0.12
+ SUPER super value
+ GOLD gold value
+ FP friendship point value
+ FAIRY_ALIVE whether player's fairy is alive
+ GUILD_ALIVE whether guild fairy is alive
+
+###Login
+
+login/l
+
+ login
+ login username
+ login username password
+
+
+###Set carddeck
+
+set_card/sc
+
+ set_card card_deck_key
+ set_card auto_set(CONDITION)
+
+Special deck names are:do not change the carddeck `no_change`, let the fairy escape `letitgo`, abort beating fairy `abort`
+
+`card_deck_key` should appears in section `card_deck`; when `card_deck_key` is **auto_set**, this is equal to `auto_set CONDITION notest`
+
+
+###Autoset carddeck
+
+auto_set/as
+
+ #All args are optional
+ #aim max_dmg:max damage(default)，max_cp:max cp(cp = atk * hp / cost)，defeat:to defeat current fairy(not accurate)
+ #line deck lines, select from 1(默认) to 4; it's recommanded to select 1 if aim is "defeat"
+ #fairy if aim is "defeat", then this arg is needed
+ # fairy:15,300000 fairy of level 15 and hp 300000
+ # fairy:15,300000,WAKE fairy of level 15, hp 300000 and wake
+ #delta fairy hp delta range(1 by default, AKA no range)
+ #bc max: max BC, cur:current BC, or enter a value
+ #notest do not save to server after auto_set(ON by default)
+ #>carddeck save carddeck to config file with deck name `carddeck`
+ #incl include some cards(none by default) (not working)
+ auto_set #select carddeck with 1 line, max damage under current BC
+ auto_set line:2 bc:max notest #select carddeck with 2 line, max damage under max BC, and save to server
+ auto_set aim:defeat line:1 bc:cur fairy:30,263215 notest #select carddeck with 1 line and defeat a fairy of lv 30 and hp 263215, and save
+ auto_set aim:max_dmg line:1 bc:cur incl:124 #select carddeck with 1 line and max damage, including Second - Bisclavret, don't save to server
+ auto_set aim:max_cp line:1 bc:40 incl:124 > forty
+ #select carddeck with 1 line, max CP under cost 40, including Second - Bisclavret, and save to deck name 'forty', don't save to server
+
+###Factor battle
+
+factor_battle/fcb
+
+ factor_battle #select factor randomly
+ factor_battle lake:7 #select lake id = 7
+ factor_battle lake:7 50 #select lake id = 7, and stop when BC < 50
+
+After enabling plugin `map_factor_lakes`, you can use `mf` command to show connections between lake id and knight card.
+
+###Explore
+
+explore/e
+
+ explore #explore as is configured in 'condition' section
+ explore area.name=='學校教室'
+
+Add expression here to override what's configured in config file.
+
+
+###Fairy list refresh
+
+fairy_battle/fyb
+
+ fairy_battle #refresh fairy list as is configured in 'system' section
+ fairy_battle 50 #refresh 50 times
+
+###Use red potion
+
+red_tea/rt
+
+ red_tea
+ red_tea / #use the 1/2 red potion
+
+###Use green potion
+
+green_tea/gt
+
+same as red potion
+
+###Sell card
+
+sell_card/slc
+
+###Set server
+
+set_server/ss
+
+ set_server cn
+ set_server cn2
+ set_server tw
+
+###Friends stuffs
+
+friend/f
+
+Interactive menu
+
+###Gacha
+
+gacha/g
+
+ gacha 1 #friendship gacha
+ gacha 2 #gacha ticket gacha
+ gacha 4 #11 gacha
+
+###Point setting
+
+point/p
+
+Interactive menu
+
+###Get reward box
+
+reward_box/rb
+
+ reward_box #get all rewards
+ reward_box 12345 #get all rewards
+ reward_box 1 #get all cards
+ reward_box 12 #get all cards and items
+ reward_box 3 #only get gold
+ reward_box 4 #only get friendship point
+ reward_box 5 #only get gacha ticket
+ reward_box 5> #only get gacha ticket, and only show total count
+ reward_box 5< #attempt to get gacha ticket, but not for real
+ reward_box PATTERN #get reward with name matching the PATTERN
+
+Regular expressions are supported
+
+###Manualy select fairy to beat
+
+fairy_select/fs
+
+ fairy_select fairy.lv<60
+ fairy_select fairy.lv<60 deck:min #select fairy with lv < 60, use override carddeck 'min'
+
+Add expression here to override what's configured in config file.
+
+Use `deck:xxx` to force use xxx carddeck, or will follow **fairy_select_carddeck** in **condition** section. You can also use auto set:`deck:auto_set(CONDITION)`
+
+###Re-login
+
+relogin/rl
+
+###Greet
+
+like/greet/gr
+
+ like #use default greeting words, if configured in section 'tactic', use that
+ like Hi! #say Hi!

COMMANDS.md

@@ -1,4 +1,6 @@
-命令均以 “完整命令/缩写命令” 的形式给出，范例仅给出完整命令写法
+[For English Users](COMMANDS.en.md)
+
+命令均以 “完整命令/缩写命令” 的形式给出，范例仅给出完整命令写法
 
 全局可用的量：
 
@@ -39,21 +41,21 @@ card_deck_key为card_deck中已定义的项；当卡组名为auto_set时，此
 
 auto_set/as
 
- #所有参数均为可选参数
- #aim 目标，可选 max_dmg最大攻击输出(默认)，max_cp最大CP，defeatT打败指定妖精
- #line 卡组排数，可选1(默认),2,3,4；若目标为DEFEAT，建议排数为1，时间复杂度太高了
- #fairy 如果目标是DEFEAT，则必须输入妖精信息，(默认为空)
- # fairy:15,300000 15级的剩余血量30w的妖精
- # fairy:15,300000,WAKE 15级的剩余血量30w的醒妖
- #delta 妖精血量误差(默认为1，即无误差)
- #bc 可选max 玩家最大BC，cur 当前剩余bc(默认)，或输入一个数值
- #notest 选出卡组后保存(无此参数时默认不保存)
+ #所有参数均为可选参数
+ #aim 目标，可选 max_dmg最大攻击输出(默认)，max_cp最大CP，defeat打败指定妖精
+ #line 卡组排数，可选1(默认),2,3,4；若目标为DEFEAT，建议排数为1，时间复杂度太高了
+ #fairy 如果目标是DEFEAT，则必须输入妖精信息，(默认为空)
+ # fairy:15,300000 15级的剩余血量30w的妖精
+ # fairy:15,300000,WAKE 15级的剩余血量30w的醒妖
+ #delta 妖精血量误差(默认为1，即无误差)
+ #bc 可选max 玩家最大BC，cur 当前剩余bc(默认)，或输入一个数值
+ #notest 选出卡组后保存(无此参数时默认不保存)
  #>carddeck 配卡并保存到配置卡组的carddeck中
- #incl 包含某些卡片(默认为无) (现在还不能用)
- auto_set #选出一排当前剩余BC下最大攻击的卡组
- auto_set line:2 bc:max notest #选出两排不限BC的最大攻击卡组，并保存
- auto_set aim:defeat line:1 bc:cur fairy:30,263215 notest #选出一排能打死Lv30剩余hp263215的普妖的卡组，并保存
- auto_set aim:max_dmg line:1 bc:cur incl:124 #选出当前BC下一排最大攻击输出卡组，包括小狼女，不保存
+ #incl 包含某些卡片(默认为无) (现在还不能用)
+ auto_set #选出一排当前剩余BC下最大攻击的卡组
+ auto_set line:2 bc:max notest #选出两排不限BC的最大攻击卡组，并保存
+ auto_set aim:defeat line:1 bc:cur fairy:30,263215 notest #选出一排能打死Lv30剩余hp263215的普妖的卡组，并保存
+ auto_set aim:max_dmg line:1 bc:cur incl:124 #选出当前BC下一排最大攻击输出卡组，包括小狼女，不保存
  auto_set aim:max_cp line:1 bc:40 incl:124 > forty
  #选出cost40下一排最大CP卡组，包括小狼女，不保存，写入配置文件的forty卡组
 
@@ -153,7 +155,7 @@ fairy_select/fs
 
 筛选条件语法与condition中的fairy_select相同
 
-最后可跟deck:xxx表示强制使用该卡组战斗；可以使用自动配卡，即deck:auto_set(CONDITION)
+最后可跟`deck:xxx`表示强制使用该卡组战斗；可以使用自动配卡，即`deck:auto_set(CONDITION)``
 
 ###重新登录
 

PLUGIN_DOCUMENT.en.md

@@ -0,0 +1,169 @@
+MAClient Plugin Document
+================
+
+* [Overview](#overview)
+* [Hook Plugin](#hook-plugin)
+ * [Examples](#examples)
+ * [Structure](#structure)
+ * [Event Name](#event-name)
+ * [Demo](#demo)
+* [extra_cmd plugin](#extra_cmd-plugin)
+ * [Examples](#examples-1)
+ * [Structure](#structure-1)
+ * [Usable variables](#usable-variables)
+ * [Demo](#demo-1)
+
+##Overview
+
+MAClient has plugin support since version 1.50. plugin system is enabled when `enable_plugins` is set to 1. You can also enable/disable single plugin using the `disabled` config; to disable multiple plugins, use `|` to seperate their names.
+
+Plugins are some Python scripts or native extensions under the plugins folder. All plugins are dynamically imported when maclient_plugin initialize. Plugins with name starts with `_` or under sub folders are NOT going to be imported. When having the same name, plugins have the priority following pyd>py>pyc=pyo.
+
+There're two types of plugins. One appends actions before and after specified events(AKA [hook plugin](#hook-plugin)); the other one adds extra commands to the CLI ui(AKA [extra_cmd plugin](#extra_cmd-plugin)). __The two types exist inside single file.__
+
+##Hook Plugin
+
+###Examples
+
+[example_hook](plugins/_example_hook.py) [bgm](plugins/bgm.py)
+
+###Structure
+
+Let's start with example_hook plugin as an example. In this example, we set up three hooks: before attacking fairy, after attacking fairy, before exploring; when these events occur, we print some stuff on the screen.
+
+
+You should always import `plugin_prototype` super class from _prototype module. At the first of your plugin(we call it metadata), name your plugin, your name, the version. Any meta besides `__plugin_name__` is only optional:
+
+```Python
+from _prototype import plugin_prototype
+__plugin_name__ = 'sample plugin'
+__author = 'fffonion'
+__version__ = 0.1
+require_version = 1.71 #require MAClient version no less then given version number
+require_feature_nologin = True #commands that can be excuted before a player logined (used in extra_cmd plugin)
+```
+
+Set up event hook. It's `ENTER`/`EXIT`+`_`+`EVENT_NAME`:
+```Python
+hooks = {'ENTER__fairy_battle':1,'EXIT__fairy_battle':1,'ENTER_explore':1}
+```
+
+###Event Name
+
+* tasker task scheduler
+* auto_check check if card pack and friendship point is full
+* check_strict_bc check if strict bc is triggered
+* set_card
+* red_tea use red potion
+* green_tea use green potion
+* _use_item use item(including potion) >=v1.68
+* explore explore: select area
+* _explore_floor explore: explore in a floor
+* gacha
+* select_card_sell
+* fairy_battle_loop
+* fairy_select
+* _fairy_battle
+* like greet
+* friends friend menu
+* reward_box get reward box
+* point_setting
+* factor_battle
+* invoke_autoset auto set card deck
+* _exit MAClient exit >= v1.67
+> * ~~sleeper sleeping scheduler >=v1.68~~
+
+The decimal after event name means the priority when hook is invoked. Bigger number means higher priority. When several plugins have a same priority, they are invoked in a random order.
+
+In the example, all hooks are set to priority 1 (lowest).
+
+*Make this empty if not using extra_cmd mode*
+```Python
+extra_cmd = {}
+```
+
+The plugin class
+```Python
+class plugin(plugin_prototype):
+ def __init__(self):
+ self.__name__=__plugin_name__
+
+ def ENTER_explore(self,*args, kwargs):
+ print 'explore!'
+ print args
+ return args,kwargs
+
+ def EXIT__fairy_battle(self,*args, kwargs):
+ print 'fairy_battle done!'
+
+ def ENTER__fairy_battle(self,*args, kwargs):
+ print 'fairy_battle!'
+ return args,kwargs
+```
+Class name must be plugin and inherit from plugin_prototype super class.
+
+For every hook, there must be a method with the name same with hooked event. `*args` and `kwargs` are arguments being tranfered to the event. Return `args` and `kwargs` in a before hook will modify the arguments really transfered to the hooked event.
+
+You can use `self.tuple_assign` (inherited from super class) to modify items in a tuple.
+
+*If there's no return statement of a return without value, then the arguments will not be modified.*
+
+*plugin class will be instantiated so you can save some state infomation*
+
+You can refer to __[maclient.py](maclient.py)__ for dig out each event has what arguments.
+
+###Demo
+
+[bgm](plugins/bgm.py)
+
+
+##extra_cmd plugin
+
+###Examples
+
+[web_helper](plugins/web_helper.py) [query_tool](plugins/query_tool.py)
+
+###Structure
+
+metadata is same as that in hook plugin, the difference is now you should fill the `extra_cmd` dict
+
+key means the command name, value is function name to be called
+```Python
+extra_cmd={'web':'start_webproxy','w':'start_webproxy'}
+```
+
+Use functional structure. Inner function is not necessary to be named as __do__.
+```Python
+def start_webproxy(plugin_vals):
+ def do(*args):
+ .....
+ return do
+```
+
+`plugin_vals` are some class variables of maclient. In fact it's `self.__dict__`
+
+###Usable variables
+
+ plugin_vals['poster'] poster instance of `maclient_network`, can be used to communicate with server, returns decrypted data
+ plugin_vals['player'] player instance
+ ├─.cards card data
+ │ └ .db card databse {1:['First - Lancelot','5','19'],……}
+ │ └ .cards player's cards, elements are object_dict types
+ │ └ .sid(xxx) find card by serial id
+ │ └ .mid(xxx) find card by master id, returns a list
+ ├─.item item data
+ │ └ .name item database {'1':'AP Potion', ...}
+ │ └ .count item count {'1':123, ...}
+ ├─.ap / bc
+ │ └ ['cur'] current value
+ │ └ ['max'] max value
+ ├─.friendship_point / gold
+ plugin_vals['loc'] server name
+ plugin_vals['cookie'] session cookie
+ plugin_vals['logger'] the logger instance
+
+All variables can be found in __[maclient.py](maclient.py)__ with `self.` as prefix
+
+###Demo
+
+[web_helper](plugins/web_helper.py)