This API example has been made for C++ but you can use the API with any programming language that supports TCP sockets and JSON. This example basicaly provides a function to find all the running bot ports and a class that holds the socket that will be connected to a specific port and receive all the data from the bot.
Important: Messages are terminated with '\1' character or 0x01 byte. This examples already manages that so you should not worrie about it, however if you plan to use the API with other language you need to handle that correctly.
The messages received from the bot and sent to the bot are in JSON format and they match the following syntax:
{
"type": 0, // The type of the message
// [...]
// Further parameters of the message, depends on the type
}The type is just a numerical value and it must be a valid type. In the C++ example it is represented by an enum for easier access:
enum class Type
{
packet_send, // 0
packet_recv, // 1
attack, // 2
player_skill, // 3
player_walk, // 4
pet_skill, // 5
partner_skill, // 6
pets_walk, // 7
pick_up, // 8
collect, // 9
start_bot, // 10
stop_bot, // 11
continue_bot, // 12
load_settings, // 13
start_minigame_bot, // 14
stop_minigame_bot, // 15
query_player_info, // 16
query_inventory, // 17
query_skills_info, // 18
query_map_entities // 19
}The bot will constantly send you messages of type 0 and 1 which are send and recv packets. These 2 types of messages also have the field packet with the full packet.
Examples:
-
Send packet
{ "type": 0, "packet": "u_s 0 3 2432" }
-
Recv packet
{ "type": 1, "packet": "mv 3 2389 70 11 5" }
You can also query the player infomation, inventory, skills and all map entities information using the messages with type 16, 17, 18 and 19.
Examples:
-
Player information
{ "type": 16, "player_info": { "name": "Hatz", "id": 123123, "x": 5, "y": 8, "level": 99, "champion_level": 80, "hp_percent": 100, "mp_percent": 100, "map_id": 1, "is_resting": false } } -
Inventory
{ "type": 17, "inventory": { "equip": [ { "quantity": 1, "name": "Beast King's Crossbow", "position": 0, "vnum": 4465 }, { "quantity": 1, "name": "Great Leader's Crossbow", "position": 1, "vnum": 4007 } ], "main": [ { "quantity": 70, "name": "Gillion Stone", "position": 0, "vnum": 1013 }, { "quantity": 311, "name": "Seed of Power", "position": 1, "vnum": 1012 } ], "etc": [ { "quantity": 999, "name": "Pearl of Darkness", "position": 0, "vnum": 2094 }, { "quantity": 112, "name": "Small Bean", "position": 5, "vnum": 2016 } ], "gold": 1000000 } } -
Skills information
{ "type": 18, "skills": [ { "name": "Shuriken Attack", "vnum": 880, "id": 0, "range": 3, "area": 0, "mana_cost": 0, "is_ready": true }, { "name": "Summon Kamapakun", "vnum": 886, "id": 6, "area": 3, "mana_cost": 0, "is_ready": true } ] } -
Map entities
{ "type": 19, "players": [ { "name": "Hatz", "id": 123123, "x": 10, "y": 20, "family": "PhoenixEnjoyers", "hp_percent": 100, "mp_percent": 100, "level": 99, "champion_level": 80 } ], "npcs": [ { "name": "Malcolm Mix", "id": 123, "x": 5, "y": 50, "vnum": 321, "hp_percent": 100, "mp_percent": 100 } ], "monsters": [ { "name": "Dander", "id": 2400, "x": 43, "y": 65, "vnum": 1, "hp_percent": 100, "mp_percent": 100 } ], "items": [ { "name": "Gillion Stone", "vnum": 123, "x": 69, "y": 69, "quantity": 999, "owner_id": 56789, "id": 45645 } ] }
You can send multiple messages to the bot to send or receive a packet and also do some actions like attacking, walking, picking up an item, etc. All this actions are performed by calling game functions in the main game thread to guarantee thread safety.
Examples:
-
Description: Send a packet to the game server. -
packet: The packet to send to the game server, in this case it uses an item from the inventory{ "type": 0, "packet": "u_i 1 1234 2 15 0 0" }
-
Description: Simulates a received packet from the game server. -
packet: The packet to get received, in this case it simulates client side getting 1kkk of gold.{ "type": 1, "packet": "gold 1000000000 0" }
-
Description: Attack a monster by using the top ready skill that you've set in the bot for the player, pet and partner. -
monster_id: ID of the monster you want to attack.{ "type": 2, "monster_id": 2307 }
-
Description: Attack a monster with the given skill. -
monster_id: ID of the monster you want to attack -
skill_id: ID of the skill you want to use.{ "type": 3, "monster_id": 2307, "skill_id": 0 }
-
Description: Character walks to coordiantes (x, y).{ "type": 4, "x": 34, "y": 68, }
-
Description: Attack a monster with the given pet skill. -
monster_id: ID of the monster you want to attack -
skill_id: ID of the pet skill you want to use.{ "type": 5, "monster_id": 2307, "skill_id": 0 }
-
Description: Attack a monster with the given partner skill. -
monster_id: ID of the monster you want to attack -
skill_id: ID of the partner skill you want to use.{ "type": 6, "monster_id": 2307, "skill_id": 1 }
-
Description: Pet and partner walks to coordinates (x, y).{ "type": 7, "x": 120, "y": 46 }
-
Description: Walk and pick up the given item. -
item_id: ID of the item you want to pick up.{ "type": 8, "item_id": 1234 }
-
Description: Walk and collect a npc (ice flowers and that kind of stuff). -
npc_id: ID of the npc you want to collect.{ "type": 9, "npc_id": 4321 }
-
Description: Start the farming bot{ "type": 10 }
-
Description: Stop the farming bot{ "type": 11 }
-
Description: Continue the farming bot{ "type": 12 }
-
Description: Load existing bot settings/profile -
path: Full path of the .ini file{ "type": 13, "path": "C:/Program Files (x86)/Nostale/mysettings.ini" }
-
Description: Starts the minigame bot{ "type": 14 }
-
Description: Stops the minigame bot{ "type": 15 }
-
Description: Query information from the player, see response example above{ "type": 16 }
-
Description: Query the inventory information from the player, see response example above{ "type": 17 }
-
Description: Query the skill information from the player, see response example above{ "type": 18 }
-
Description: Query information about all the map entities, see response example above{ "type": 19 }
-
Description: Target an entity in the game client -
entity_id: The id of the entity to target -
entity_type: The type of entity (1 - player, 2 - npc, 3 - monster){ "type": 20, "entity_type": 3, "entity_id": 2664 }
To use this API you just need to add the following files into your project and #include "Api.h" where you want to use it:
-
Api.h -
Api.cpp -
Port_finder.h -
Port_finder.cpp -
Safe_queue.h -
Safe_queue.cpp
This example was made using Microsoft Visual Studio Community 2019 and C++14.
Since C++ doesn't support JSON natively you'll need to use a third party library to use it. In this example I've used nlohmann json. To handle the dependencies I've used vcpkg.
In the file main.cpp you have an example of a packetlogger that will connect to the first port found and print to the standard output every send/recv packet that comes from the bot.