Advanced C Interface 使用手册

1. 什么是 ACI

ACI 是百宝箱系列软件提供的 C 语言编程接口， 可以让用户在百宝箱系列软件平台的基础上进行二次开发，随心所欲的制作自己想要的功能。

2. 什么人才能使用 ACI

首先你应该懂得 C 语言或者对计算机语言有着天生的感觉。 如果你
不具备这样的能力，可以到百宝箱论坛上寻找其他人编写的合适自己
使用的代码。

3. ACI 的特点

3.1 ACI 和 C 有什么不同

ACI 采用的是类 C 语法，除了以下部分，基本包容了常规 C 所具有
的功能。

a. 取消了指针

指针是引起程序不稳定的重要因素，因为 ACI 取消了指针这个类型。
ACI 采用新增的数组(array)类型和传址方式来替代指针发挥的作用。

b. 取消了结构

结构虽然高效，但是使用过于僵化，不利于快速的编写合适的代码，
因此 ACI 取消了结构，采用了更灵活的映射(mapping)类型来替代结
构。

3.2 ACI 和脚本有什么区别

ACI 和脚本并非一样，脚本类似于批处理，只能按照顺序执行命令和
实现一些简单的逻辑，ACI 支持的 C 语言拥有强大的逻辑处理能力，
并且可以利用宏和函数来实现非常复杂的操作。

4. ACI 使用说明

4.1 编写第一段 ACI 程序：Hello word!

打开百宝箱，登陆进入游戏，切换到 ACI 页面。 点击刷新按钮可以
查阅该角色的 ACI 代码。你看到的是空白？那就对了， 因为一开始
你并没有编写任何代码。上面的窗口是代码窗口，供你输入，编写代
码，相应的下面的窗口是调试窗口，输出运行时各种调试信息。好，
现在在代码窗口输入以下代码：

printf("Hello world!\n");

注意，C 里面是分辨大小写的，所以不要自作主张把 printf 修改为
Printf 或者 PRINTF，最好是将这段代码通过复制粘贴的手段输入到
百宝箱的窗口中。

代码就绪以后，点击加载。这时候你将在下面的窗口看到：

Hello world!

此时恭喜你，你已经成功地写好了第一个 ACI 程序。

4.2 编写一个具有简单逻辑的 ACI 程序：连续密语

首先你准备一个小号，注意，不要搔扰别人。

输入以下代码：

for (i = 0; i < 10; i++)
    tell("小号的名字", "Test " + i);

注意，"小号的名字"请替换成为自己准备的小号的游戏人物名字，而
不要真的输入"小号的名字"。

然后再选择加载（上一次加载的程序会自动地卸载，所以你无需抄心
卸载的问题）。此时你在窗口上可能看不到任何反应，但是你可以切
换到小号上观察，应该有类似的文字：

测试号的名字=> Test 0
测试号的名字=> Test 1
测试号的名字=> Test 2
测试号的名字=> Test 3
测试号的名字=> Test 4
测试号的名字=> Test 5
测试号的名字=> Test 6
测试号的名字=> Test 7

在恭喜你成功编写了第二个 ACI 程序时， 还要提醒你注意：不要利
用这个刷屏搔扰他人，否则游戏运营商可能会限制密语，从而给大家
带来诸多不便。另外一点需要注意的是，如果循环次数太多，那么输
出的信息太多可能会（确切的说是肯定会）导致你断线，如何能够大
量输入并且不会断线， 在你充分掌握了 ACI 提供的函数以后你就会
有解决方案了。

4.3 编写第一个实用的 ACI 程序

到这里你可能会觉得相当的困惑， 因为你还不能发现 ACI 给你带来
任何帮助。实际上，前面两段程序仅仅是一个示范。确切来说，你需
要编写一些指定的 ACI 函数来处理百宝箱发送过来的消息， 这些函
数是实现约定好的，比如我们接下来要接触到的一个函数：处理接收
到的消息并恰当的返回一些信息，代码如下：

mixed on_receive_message(string org, string msg)
{
    string peer_name;

    if (org == MSG_LISTEN)
    {
        sscanf(msg, "%s=> %*s", &peer_name);
        if (peer_name == "小号的名字")
        {
            tell(peer_name, "ACI is working");
            return 1;
        }
    }
}

如果你看不懂其中的逻辑关系，不要提问，你应该首先去尝试学习好
C 语言。

如果你看得懂但是觉得和 C 有一些差别，请看接下来的说明：

mixed 表示一个“任何”类型，也就是 on_receive_message 这个函
数返回什么类型都可以。

string 表示字符串类型，ACI 支持字符串这个数据类型。

MSG_LISTEN 是一个系统预定义的宏，它是什么内容呢？ 这个问题就
交给你了。

&peer_name，ACI 不支持指针，但是为什么会有 "&"  这种和指针关
系非常暧昧的符号？这是因为，peer_name 是一个变参，它需要接受
sscanf 这个函数的返回值，所以需要在他前面赠加一个 "&" 表示它
是变参，这是语法的强制要求。&peer_name 并不像 C 里面那样是一
个指针。

return 1 表示返回 1，这点毋庸置疑。但是返回 1 意味着什么呢？
他意味让百宝箱不要再处理这条消息了。 如果返回 0 或者直接什么
都不返回，百宝箱还会按照预定的流程处理这条消息。比如，你的小
号密你任何信息，你都会反密：“ACI is working”，即使你的小号
密你诸如 "at" 的密语命令你都是如此应答。如果这里的 return 1
替换为 return 0，那么你在反密以后，百宝箱还会继续处理， 返回
原本密语命令需要返回的信息。

最后这个函数没有任何返回就结束了，似乎不太符合 C 的语法。 是
的，的确不符合，但是它符合 ACI 的要求， 什么都没有返回意味着
返回一个 (void)。因为这个函数要求的返回类型是 mixed， 也就是
什么类型都可以，包括 (void)。

4.4 第二个实用范例

输入以下代码：

mixed on_char_appear(mapping ob)
{
    if (ob["type"] == OBJECT_TYPE_MONSTER)
        printf("Monster %s is appeared, at %d, %d.\n", ob["name"],
               ob["x"], ob["y"]);
    else
    if (ob["type"] == OBJECT_TYPE_CHAR)
        printf("Player %s is appeared, at %d, %d.\n", ob["name"],
               ob["x"], ob["y"]);
}

mixed on_item_appear(mapping ob)
{
    printf("Item %s is appeared at %d, %d\n", ob["name"], ob["x"], ob["y"]);
}

加载以后在游戏中走动一会儿，注意一下调试窗口出现的信息


Appendix A. ACI 使用的一些全局变量

all_objects     - mapping，保存可视范围内所有的人物，怪物，NPC，id 为关键字。
brief_index     - int，    该场景的逻辑图，零表示没有逻辑图
zone            - string， 该场景的地图名字

Appendix B. 关于一般对象和“我”的数据组织

// “我”，等效于 all_objects[my_id()]
mapping me()

// 我的 id，等效于 me()["id"]
int     my_id()

普通对象和 me() 这个对象包含以下数据：

"name"     - 名字
"id"       - 代号
"type"     - 类型，包括：OBJECT_TYPE_MONSTER/OBJECT_TYPE_CHAR/
           -             OBJECT_TYPE_NPC/OBJECT_TYPE_ITEM
"x"        - 横坐标
"y"        - 纵坐标

me() 这个对象还包括以下数据
"equip"    - mapping，包括了身上所有的装备，关键字为装备的序号
"carry"    - array，包括了身上所有的物品，序号从 0 - n
"life"     - 当前血值
"max_life" - 最大血值
"mana"     - 当前蓝值
"max_mana" - 最大蓝值

Appendix C. ACI 提供的游戏常用函数

// 转向，direction 表明了方向，0 - 360 度，0 表示北，45 表示东北，
// 90 表示东，以此类推
int face(int direction)

// 走路到某坐标，返回 1 表示成功抵达，0 表示被中断
int walk_to(int x, int y)

// 走路到某坐标附近，返回 1 表示成功抵达，0 表示被中断
int walk_close_to(int x, int y, int distance)

// 跑步到某坐标，返回 1 表示成功抵达，0 表示被中断
int run_to(int x, int y)

// 跑步到某坐标附近，返回 1 表示成功抵达，0 表示被中断
int run_close_to(int x, int y, int distance)

// 使用异形换位到每个坐标处，返回 1 表示成功抵达，0 表示失败
int fly_to(int x, int y)

// 上马
void ride()

// 下马
void unride()

// 使用魔法，object_id 可以是对象 ID，或对象，或对象名字，magic 是
// 魔法名字，返回 1 表示成功，0 表示失败
int cast(mixed object_id, mixed magic);

// 使用魔法并自动选择所需要的符具药粉，参数参见 cast
int casti(mixed object_id, mixed magic);

// 物理攻击某个对象，object_id 参见 cast，注意，必须和对象相邻使用
// 该命令才可能有效果，返回 1 表示成功，0 表示失败
int hit(mixed object_id)

// 使用物品，如药品等，item 可以使物品对象 id，或物品对象，如果 item
// 为零或负数，那么表示是物品在包裹中的序号
int apply(mixed item)

// 丢弃物品，参数 item 参见 apply
int drop(mixed item)

// 拾取物品，注意，人必须站在物品上面，x, y 即自己的坐标
void get_at(int x, int y)

// 和 npc 开始对话，npc 可以是名字或者是 NPC 对象
// 返回 1 表示成功，返回 0 表示失败
int talk_to(mixed npc)

// 和 npc 对话，选择 msg 的条目，msg 可以是动作如"@buy"，也可以
// 是部分文字，比如"购买"
int talk_to(mixed npc, string msg)

// 和 npc 对话，选择 msg 的条目，并输入额外信息，如密码，npc 要求的
// 其他信息等
int talk_to(mixed npc, string msg, string extra)

// 刷新 npc 所出售的物品，item_name 是物品的名字，如果为 0 或负数表示
// 是 npc 所出售物品的序号，page 表示刷新第几页，要刷新第一页则是 0
int show_inv(mixed item_name, int page)

// 购买 npc 所出售的物品，必须刷新所出售的物品以后方可使用
// item 是物品对象 id，或者物品的名字，如果 item 为负数则表示刷新页面
// 中的物品的序号
// amount 是购买的数量，如果是不可合并的物品则应该为 1
// from_npc 是 npc 的名字或对象 id，或对象
// 返回 1 表示成功，返回 0 表示失败，失败可能是超重或金钱不足
int buy(mixed item, mixed amount, mixed from_npc)

// 售出包裹中的物品
// item 参见 apply，amount 表示数量，to_npc 参见 buy
// 返回 1 表示成功，返回 0 表示失败
int sell(mixed item, mixed amount, mixed to_npc)

// 修理包裹中的物品
// 参数说明参见 sell
// 返回 1 表示成功，返回 0 表示失败
int repair(mixed item, mixed by_npc)

// 保存包裹中的物品
// 参数说明参见 sell
// 返回 1 表示成功，返回 0 表示失败
int store(mixed item, mixed amount, mixed to_npc)

// 取出仓库的物品
// item 表示物品对象 id，或物品对象，如果 item 为零或负数，则表示物品
// 在仓库中的序号
// amount 表示物品的数量，如果是不可合并的物品，amount 为 1
// from_npc 表示仓库保管员，可以是 npc 的对象 id，或 npc 对象，或 npc
// 的名字
int take(mixed item, mixed amount, mixed from_npc)

// 装备物品
// item 参见 apply，to_pos 表示装备到身上那个位置，如果没有第二个参数
// 表示让系统自动判断合时的位置
int equip(mixed item, mixed to_pos)

// 卸下物品
// item 表示身上物品对象 id，或物品对象，或物品的名字，如果是零或负数
// 表示物品的序号
int unequip(mixed item)

// 说话
void say(string msg)

// 呐喊
void shout(string msg)

// 密语
// to_who 是密语对象的名字
void tell(string to_who, string msg)

// 段落密语
// to_who 是密语对象的名字
// msgs 是一段文字，用 "\n" 分开，系统会自动逐条告知对方
void tell_msgs(string to_who, string msgs)

// 小组聊天
void league(string msg)

// 行会聊天
void party(string msg)

// 更换攻击方式
// mode 表示攻击方式，即游戏中的文字，如 "[和平攻击方式]"
void change_attack_mode(string mode)

// 更换宝宝的工作方式
// 只有两种工作方式可以选择，PET_PEACE_MODE，PET_ATTACK_MODE
void change_pet_mode(string mode)

Appendix D. ACI 提供的其他控制函数

// 返回城市，停止练功
void back()

// 靠近某个 NPC
// type 取值: "storer"  - 仓库
//            "weapon"  - 武器
//            "armor"   - 防具
//            "jewelry" - 首饰
//            "potion"  - 药水
//            "item"    - 物品
//            "book"    - 书籍
//            "boot"    - 鞋具
// 如果成功到达 NPC 附近，返回 1，同时 the_npc 被设置为该 NPC
int close_to_npc(mixed type, mixed &the_npc)

// 取物品对象
// name_id 可以是身上（包括装备）任何一个物品的 id 或名字
// 返回 0 表示无此物品
mixed get_item_of_me(mixed name_id);

// 取包裹中的物品对象
// name_id 可以是包裹中的物品名字，对象 id，如果 name_id 是零或负数
// 表示包裹中物品的序号
mixed get_item(mixed name_id)

// 取包裹中的物品对象的 id
// name_id 参见 get_item
int get_item_id(mixed name_id)

// 取包裹中的物品对象在包裹中的序号
// name_id 参见 get_item
// 返回值是零或正数表示序号，返回 -1 表示没有找到该物品
int get_item_index(mixed name_id)

// 取包裹中的物品对象的数量
// name_id 参见 get_item
// 返回值是正数表示数量，返回 0 表示并无该物品
int get_item_amount(mixed name_id)

// 统计包裹中不可合并物品（如符具）的总数量
// name_id 是物品的名字
// 返回值是 0 或正数
int count_item_amount(string name)

// 取仓库中物品的序号
// name_id 可以是仓库物品的物品名字，对象 id
// 返回 0 或正数表示仓库中物品的序号，返回 -1 表示并无该物品
// 注意，必须首先和 npc 对话，打开仓库才能使用这个函数
int get_store_item_index(mixed name_id)

// 取仓库中物品的数量
// name_id 参见 get_store_item_index，如果 name_id 为零或负数表示
// 仓库中的物品序号
// 返回值是正数表示数量，返回 0 表示并无该物品
// 注意，必须首先和 npc 对话，打开仓库才能使用这个函数
int get_store_item_amount(mixed name_id)

// 前往某地，如果 x, y 为零表示到达指定城市即可
int goto_city(string to_city, int x, int y)

// 练功中，包括练级，挖矿，摆摊
int is_doing_quest()

// 边跑边打中
int is_in_job()

// 边跑边打至某地，如果 x, y 为零表示到达指定城市即可
void run_with_fight(string to_city, int x, int y)

// 开始练功，包括练级，挖矿，摆摊
// 如果输入了非零参数，则表示从头检测状态并开始练功，如果没
// 有参数或者输入零参数，表示从上次停止时继续
void start_quest(mixed reset)

// 停止边跑边打
void stop_job()

// 停止练功，包括练级，挖矿，摆摊
void stop_quest()

Appendix E. ACI 支持的消息接口函数

// 获得战斗经验/武器经验
void on_acquire_exp(int got_exp, int weapon_exp)
{
}

// 成功使用了和一个物品
void on_applied_item(mapping item)
{
}

// 被攻击
void on_attack_by(mapping attacker, int damaged)
{
}

// 他人攻击信息
void on_attack_info(mapping attacker, mapping victim, int damaged)
{
}

// 当踩到了一个物品时，判断该物品是否需要拾取，返回 -1 表示不需要拾
// 取，返回 0 表示采用原先的判断流程
int on_auto_get(mapping ob)
{
    return 0;
}

// 包裹里的物品数量刷新了
void on_carried_updated(mapping item, int amount)
{
}

// 人物出现
void on_char_appear(mapping ob)
{
}

// 人物死亡
void on_char_died(mapping ob)
{
}

// 人物消失（离开视野）
void on_char_disappeared(mapping ob)
{
}

// 你进入了游戏
void on_enter_world()
{
}

// 你进入了某个区域
void on_enter_zone()
{
}

// 前往练功地点
// 如果定义了这个函数，则系统自动采用这个函数前往练功地点
// 返回 0 表示采用预定的流程前往练功地点，返回 -1 表示无法前
// 往练功地点，返回 1 表示成功到达了练功地点
int on_go_to_pz(string rzone, int x, int y)
{
    return 0;
}

// 物品出现
void on_item_appear(mapping item)
{
}

// 物品消失（离开视野）
void on_item_disappeared(mapping item)
{
}

// 加入了小组，返回非零表示不理会，返回 0 表示采用原先的处理流程
int on_join_team(string member_leader, mapping members)
{
    return 0;
}

// 你离开了游戏
void on_leave_world()
{
}

// 怪物消失了（离开视野）
void on_monster_disappeared(mapping ob)
{
}

// 获得了新物品
void on_new_carried(mapping item)
{
}

// 开始准备，返回 1 表示准备成功，返回 -1 表示准备失败，返回 0 表示
// 使用系统原来的准备流程。
int on_prepare_for_quest()
{
    return 0;
}

// 巡航下一地图，返回 0 表示采用系统预定的流程，返回 1 表示设置了下
// 一练功地图的信息
// 关于设置练功地图参见 on_update_pz
int on_next_pz()
{
    return 0;
}

// 接收到用户消息，返回非零表示消息已被处理，返回 0 表示采用系统原先
// 的处理流程
int on_receive_message(string org, string msg)
{
    return 0;
}

// 物品出现时判断是否需要拾取该物品，返回 -1 表示不打算拾取，返回 0
// 表示采用系统原先的判定流程
int on_to_pickup(mapping item)
{
    return 0;
}

// 选择练功地点，expected 表示期望的练功地点，如果为零表示随机选择，
// 返回 1 表示成功选择了地点，返回 0 表示采用预定的流程
// 函数返回 1 时需要设置变量：
// rz - 练功地点名称
// rx, ry - 练功目的地
// is_cruise - 如果为 1 表示巡航，如果为 0，表示不巡航
// rr - 数组，包括一组坐标，只有 is_cruise 为 1 时有效
int on_update_pz(mixed expected)
{
    return 0;
}

谢谢

还是不太会用，我一般只会找到现成的改一下，还不太会创造!

本人罐水  欢迎加入

好东西  容易入门

增加权限，谢谢合作！！！！！

呵呵~~不就是百宝箱自带的说明吗！

还差141点积分，加油！

学习中.........

为了权限!!!顶!

ＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤＤ

谢谢...............