Discuz!道具系统道具开发文档.doc

Discuz!道具系统采用独立的php文件的道具结构，每个道具拥有一个单独的php文件，做为这个道具运行文件，用户可以自行编写道具文件制作属于自己论坛的道具。下面具体介绍一下相关机制和开发方法
1、  道具的组成
每个道具由两部分组成，php文件和图片文件。
php文件存放在论坛include/magic目录下，命名规范为magic_inc_道具名称.php文件。图片文件存放在images/magics目录下，命名规范为道具唯一标识（小写）.gif

注：其中道具名称由任意英文字母组成，道具唯一标识是在添加的时候确定的，此标识唯一，最长为3个大写英文字母
道具图片不用多说就是gif文件，下面我具体说说php文件编写规范

2、  道具php文件编写详解
我们以一个道具php文件（magic_inc_close.php）为例
1. <?php
2.
3. // 这段代码的作用防止文件直接调用，每个道具文件都必须在开头加入
4. if(!defined('IN_DISCUZ')) {
5.        exit('Access Denied');
6. }
7.
8. // 用户点击使用后，执行的代码
9. if(submitcheck('usesubmit')) {
10.    
11.     // 验证资料是否填写完全，这里验证$tid（帖子id）是否填写
12.        if(empty($tid)) {
13.               showmessage('magics_info_nonexistence');
14.        }
15.    
16.     // 取得帖子的相关资料
17.        $thread = getpostinfo($tid, 'tid', array('fid'));
18.     // 验证帖子所在的版块是否有使用道具的权限
19.        checkmagicperm($magicperm['forum'], $thread['fid']);
20.    
21.     // 道具的执行代码
22.        $db->query("UPDATE {$tablepre}threads SET closed='1', moderated='1' WHERE tid='$tid'");
23.        $expiration = $times*****p + 86400;
24.
25.     // 使用道具代码
26.        usemagic($magicid, $magic['num']);
27.     // 记录道具使用日志
28.        updatemagiclog($magicid, '2', '1', '0', $tid);
29.     // 记录道具使用对象（这里指主题）日志
30.        updatemagicthreadlog($tid, $magicid, $magic['identifier'], $expiration);
31.     // 显示道具使用信息
32.        showmessage('magics_operation_succeed', 'magic.php?action=user');
33.
34. }
35.
36. // 生成道具界面显示代码
37. function showmagic() {
38.        global $tid, $lang;
39.        magicshowtype($lang['option'], 'top');
40.        magicshowsetting($lang['target_tid'], 'tid', $tid, 'text');
41.        magicshowtype('', 'bottom');
42. }
43.
44. ?>

以上就是一个简单道具的编写格式，其中红色注释部分是一个道具必须有的，当然里面的一些代码可以根据道具类型的不同做一些改动，比如取得帖子资料的语句，如果是对用户的操作，可以改为取用户资料。相关这些操作我们已经内置了一些自定义函数，通过这些自定义函数你就可以轻松调用你想调用的资料了，下面我们就来说说这些自定义函数。

3、  道具系统自带函数
所有的自定函数都在include/magic.func.php文件里面，下面我对这些函数一一做解释

// 道具权限验证函数
$perms有权限的groupid或者fid的序列，中间用\t隔开
$id要验证fid或者groupid
checkmagicperm($perms, $id)

// 获得道具函数
$magicid道具id，
$magicnum道具获得数量
$weight 道具重量
$totalweight 用户拥有道具总重量
$uid 获得道具用户的uid
$maxmagicsweight 该用户所拥有的道具最大重量
getmagic($magicid, $magicnum, $weight, $totalweight, $uid, $maxmagicsweight)

// 查询用户拥有道具最大重量函数
$uid 查询用户uid
$magicarray 道具数据数组
getmagicweight($uid, $magicarray)

// 查询帖子信息函数
$id 帖子或者主题的pid或者tid
$type 查询的类型 tid代表主题 pid代表帖子
$colsarray 要查询的字段 数据类型数组
getpostinfo($id, $type, $colsarray = '')

// 查询用户信息函数
$username 查询用户名
$colsarray 要查询的字段 数据类型数组
getuserinfo($username, $colsarray = '')

// 赠送道具函数
$username 要赠送对象的用户名
$magicid 赠送道具道具id
$magicnum 赠送道具的单个数量
$totalnum 赠送道具的总数量
$totalprice 赠送道具的总价格
givemagic($username, $magicid, $magicnum, $totalnum, $totalprice)

// 道具随机函数
$odds 成功的几率，例如10成功的几率就是10%
magicrand($odds)

// 道具市场道具操作函数
$magicid 道具id
$marketnum 道具市场道具数量
$magicnum 道具数量
marketmagicnum($magicid, $marketnum, $magicnum)

// 道具操作验证函数（用户验证道具使用对象是否被版主操作过）
$tid 帖子id
magicthreadmod($tid)

// 道具界面生成函数
magicshowsetting($setname, $varname, $value, $type = 'radio', $width = '20%')
magicshowtips($tips, $title)
magicshowtype($name, $type = '')

// 道具使用函数
$magicid 道具id
$totalnum 被使用道具的用户拥有总数量
$num 使用数量
usemagic($magicid, $totalnum, $num = 1)

// 道具使用对象日志（主要用于使用对象主题时）
$tid 主题tid
$magicid 道具id
$action 动作标识
$expiration 道具有效期
$extra 是否记录用户名 1为不记录，0为记录
updatemagicthreadlog($tid, $magicid, $action, $expiration, $extra = 0)

// 道具使用日志
$magicid 道具id
$action 动作标识 1为购买 2为使用 3为赠送 4为道具市场出售 5为道具市场购买
$amount 道具操作数量
$price道具操作价格
$targettid 道具使用对象tid
$targetpid 道具使用对象pid
$targetuid 道具使用对象uid
updatemagiclog($magicid, $action, $amount, $price, $targettid = 0, $targetpid = 0, $targetuid = 0)