README

Laravel package for retrieving and updating data from a Perfect World game server.

Compatibility

PHP: 8.1+
Laravel: 10.x, 11.x, 12.x

Install

composer require bahastriker/pw-api

Configuration

Publish the config file:

php artisan vendor:publish --tag=pw-api-config

Edit config/pw-api.php:

return [
    'local'          => '127.0.0.1',   // Server IP address
    'server_ip'      => '127.0.0.1',   // Alias for local
    'ports' => [
        'gamedbd'    => 29400,
        'gdeliveryd' => 29100,
        'gacd'       => 29300,
        'client'     => 29000,
    ],
    'game_version'    => '156',         // Protocol version
    'server_version'  => '156',         // Alias for game_version
    'maxbuffer'       => 65536,
    's_block'         => false,
    's_readtype'      => 3,
];

Supported Protocol Versions

07, 63, 69, 70, 80, 85, 88, 101, 145, 156, 352

Version 352 is built from the PW v174 C++ source (build 352) and includes extended storage, glyph, ranking, and admin operations not available in older protocols.

Settings Resolution

This package supports two runtime configuration sources:

The setting() helper (if your app provides it, for example via akaunting/setting)
Fallback to config values from pw-api.php

When setting() is not available, these config keys are used:

pw-api.game_version (fallback for server_version)
pw-api.local (fallback for server_ip)

Usage

use Striker\PerfectWorldAPI\API;

$api = new API();

All methods communicate with the game server over raw TCP sockets. The server must be running and the configured ports must be reachable.

API Reference

Server Status

`serverOnline()`

Check if the game server client port is accepting connections.

$isOnline = $api->serverOnline(); // true or false

`ports()`

Check the status of all configured service ports.

$ports = $api->ports();
// [
//     'gamedbd'    => ['port' => 29400, 'open' => true],
//     'gdeliveryd' => ['port' => 29100, 'open' => true],
//     'gacd'       => ['port' => 29300, 'open' => true],
//     'client'     => ['port' => 29000, 'open' => true],
// ]

`checkRoleOnline($role)`

Check if a specific role is currently online. Fetches the full online list and searches for the role ID.

Parameter	Type	Description
`$role`	int	Role ID

$isOnline = $api->checkRoleOnline(128);

`getOnlineList()`

Get an array of all currently online players.

$online = $api->getOnlineList();
// [
//     ['userid' => 32, 'roleid' => 128, 'linkid' => 1, 'localsid' => 5, 'gsid' => 1, 'status' => 0, 'name' => 'PlayerOne'],
//     ...
// ]

Account & User Data

`getUser($id)`

Get full account data for a user ID. Returns cash balances, exchange logs, forbid status, login IP, and login time.

Parameter	Type	Description
`$id`	int	User ID

$user = $api->getUser(32);
// $user['logicuid']     - Logic UID
// $user['cash']         - Current cash balance
// $user['money']        - In-game money
// $user['status']       - Account status byte
// $user['login_ip']     - Last login IP (parsed)
// $user['login_time']   - Last login timestamp (parsed)
// $user['forbid']       - Array of active bans [{type, time, createtime, reason}]

`getRoles($user)`

Get a list of all characters (roles) belonging to a user account.

Parameter	Type	Description
`$user`	int	User ID

$roles = $api->getRoles(32);
// ['count' => 2, 'roles' => [['id' => 128, 'name' => 'MyChar'], ...]]

`getUserCash($userid)`

Get the cash balance and VIP info for a user account.

Parameter	Type	Description
`$userid`	int	User ID

$cash = $api->getUserCash(32);
// ['cash_total' => 10000, 'cash_vip_score_add' => 0, 'cash_vip_level' => 0]

Role Data — Read

`getRole($role)`

Get complete character data in a single call. Returns all sections: base, status, pocket, equipment, storehouse, and task.

Parameter	Type	Description
`$role`	int	Role ID

$role = $api->getRole(128);
// $role['base']       - Character base info (name, race, class, gender, etc.)
// $role['status']     - Level, exp, HP/MP, position, reputation, skills, etc.
// $role['pocket']     - Inventory items
// $role['equipment']  - Equipped items
// $role['storehouse'] - Bank/storehouse items
// $role['task']       - Quest data and task inventory

`getRoleBase($role)`

Get only the base section of a character (name, race, class, creation time, marriage, bans).

Parameter	Type	Description
`$role`	int	Role ID

$base = $api->getRoleBase(128);
// $base['name']           - Character name
// $base['race']           - Race ID
// $base['cls']            - Class ID
// $base['gender']         - Gender (0 = male, 1 = female)
// $base['status']         - 0 = active, 1 = deleted
// $base['delete_time']    - Deletion timestamp (0 if active)
// $base['create_time']    - Creation timestamp
// $base['lastlogin_time'] - Last login timestamp
// $base['spouse']         - Spouse role ID (0 if unmarried)
// $base['userid']         - Owning user ID
// $base['custom_data']    - Character appearance data (hex octets)
// $base['forbid']         - Array of role-level bans

`getRoleStatus($role)`

Get character status: level, experience, position, stats, skill data, and various octet fields.

Parameter	Type	Description
`$role`	int	Role ID

$status = $api->getRoleStatus(128);
// $status['level']            - Current level
// $status['level2']           - Reincarnation level
// $status['exp']              - Experience points
// $status['sp']               - Spirit points
// $status['hp'], ['mp']       - Current HP/MP
// $status['posx/y/z']         - World position (float)
// $status['worldtag']         - Current world/map ID
// $status['reputation']       - Reputation value
// $status['invader_state']    - PK mode state
// $status['skills']           - Skill data (hex octets)
// $status['property']         - Extended properties (hex octets)
// $status['var_data']         - PK/PvP variables (hex octets)
// $status['force_data']       - Force/faction reputation (hex octets)
// $status['meridian_data']    - Meridian data (hex octets)
// $status['reincarnation_data'] - Reincarnation data (hex octets)

`getRoleInventory($role)`

Get inventory (pocket) contents.

Parameter	Type	Description
`$role`	int	Role ID

$inv = $api->getRoleInventory(128);
// $inv['icapacity']    - Inventory capacity
// $inv['money']        - Coin in inventory
// $inv['inv']          - Array of items [{id, pos, count, max_count, data, proctype, expire_date, guid1, guid2, mask}]
// $inv['silver_money'] - Silver coin (v174+)

`getRoleEquipment($role)`

Get currently equipped items.

Parameter	Type	Description
`$role`	int	Role ID

$eqp = $api->getRoleEquipment(128);
// $eqp['eqp'] - Array of equipped items [{id, pos, count, max_count, data, ...}]

`getRoleStorehouse($role)`

Get bank/storehouse contents including dress and material tabs.

Parameter	Type	Description
`$role`	int	Role ID

$store = $api->getRoleStorehouse(128);
// $store['capacity'] - Storage capacity
// $store['money']    - Stored coins
// $store['store']    - Main storage items
// $store['dress']    - Fashion tab items
// $store['material'] - Material tab items
// $store['generalcard'] - General card tab items

`getRoleTask($role)`

Get quest/task data and task inventory items.

Parameter	Type	Description
`$role`	int	Role ID

$task = $api->getRoleTask(128);
// $task['task_data']      - Active task data (hex octets)
// $task['task_complete']  - Completed tasks (hex octets)
// $task['task_finishtime'] - Task finish times (hex octets)
// $task['task_inventory'] - Task inventory items

`getRolePetBadge($role)`

Get pet badge inventory.

Parameter	Type	Description
`$role`	int	Role ID

$badges = $api->getRolePetBadge(128);

`getRoleFriends($role)`

Get friend list and friend groups for a character.

Parameter	Type	Description
`$role`	int	Role ID

$friends = $api->getRoleFriends(128);
// $friends['groupinfo']  - Friend groups [{gid, name}]
// $friends['friendinfo'] - Friends [{rid, cls, gid, name}]

Role Data — Write

`putRole($role, $params)`

Save complete character data. The $params array must contain the same section structure as returned by getRole().

Parameter	Type	Description
`$role`	int	Role ID
`$params`	array	Full role data with sections: `base`, `status`, `pocket`, `equipment`, `storehouse`, `task`

$role = $api->getRole(128);
$role['status']['level'] = 150;
$role['status']['hp'] = 50000;
$api->putRole(128, $role);

Items arrays are auto-wrapped: if you pass a single item (flat array with id key) instead of an array of items, it will be normalized.

Octet Parsing

`parseOctet($octet, $name)`

Parse a hex-encoded octet string into a structured array using a named octet definition from the protocol file.

Parameter	Type	Description
`$octet`	string	Hex-encoded octet data
`$name`	string	Octet type name: `var_data`, `property`, `force_data`, `faction_contrib`, `title_data`

$status = $api->getRoleStatus(128);

// Parse PK/PvP data
$varData = $api->parseOctet($status['var_data'], 'var_data');
// $varData['pk_count']         - PK kill count
// $varData['pvp_flag']         - PvP flag
// $varData['dead_flag']        - Death flag
// $varData['trashbox_size']    - Trash box size

// Parse combat properties
$props = $api->parseOctet($status['property'], 'property');
// $props['hp'], ['mp']         - Max HP/MP
// $props['attack']             - Physical attack
// $props['defense']            - Physical defense
// $props['damage_low/high']    - Damage range
// $props['resistance']         - Elemental resistances [1-5]

// Parse force reputation
$force = $api->parseOctet($status['force_data'], 'force_data');
// $force['cur_force_id']  - Active force ID
// $force['force']         - Array of [{force_id, reputation, contribution}]

// Parse faction contribution
$contrib = $api->parseOctet($status['faction_contrib'], 'faction_contrib');
// $contrib['consume_contrib']   - Consumed contribution
// $contrib['exp_contrib']       - Experience contribution
// $contrib['cumulate_contrib']  - Total accumulated contribution

`getRolePvp($var_data)`

Convenience method to extract PK count and death flag from a var_data hex octet string.

Parameter	Type	Description
`$var_data`	string	Hex-encoded var_data octet (from `getRoleStatus()['var_data']`)

$status = $api->getRoleStatus(128);
$pvp = $api->getRolePvp($status['var_data']);
// ['pk_count' => 5, 'dead_flag' => 0]

ID Lookups

`getRoleid($rolename)`

Look up a role ID by character name.

Parameter	Type	Description
`$rolename`	string	Character name

$id = $api->getRoleid('PlayerOne'); // 128

`roleIdToUserId($roleid)` ^v174+

Convert a role ID to its owning user (account) ID.

Parameter	Type	Description
`$roleid`	int	Role ID

$userId = $api->roleIdToUserId(128); // 32

`userIdToLogicUid($userid)` ^v174+

Convert a user ID to its logic UID.

Parameter	Type	Description
`$userid`	int	User ID

$logicUid = $api->userIdToLogicUid(32);

Character Management

`renameRole($role, $oldname, $newname)`

Rename a character. The old name must match the current name.

Parameter	Type	Description
`$role`	int	Role ID
`$oldname`	string	Current character name
`$newname`	string	New character name

$api->renameRole(128, 'OldName', 'NewName');

`undoDeleteRole($role)` ^v174+

Restore a deleted character.

Parameter	Type	Description
`$role`	int	Role ID

$api->undoDeleteRole(128);

`copyRole($srcroleid, $dstroleid)` ^v174+

Copy all data from one character to another. The destination role must already exist.

Parameter	Type	Description
`$srcroleid`	int	Source role ID
`$dstroleid`	int	Destination role ID

$api->copyRole(128, 256);

`positionReset($role, $worldtag, $x, $y, $z)` ^v174+

Teleport an offline character to a specific position. The character must be logged out.

Parameter	Type	Description
`$role`	int	Role ID
`$worldtag`	int	World/map tag (e.g., `1` for main world)
`$x`	float	X coordinate
`$y`	float	Y coordinate
`$z`	float	Z coordinate

$api->positionReset(128, 1, 4200.0, 700.0, 3800.0);

`modifyRoleData($role, $mask, $params)` ^v174+

Directly modify character attributes. Only fields enabled by the bitmask are applied.

Parameter	Type	Description
`$role`	int	Role ID
`$mask`	int	Bitmask of fields to modify
`$params`	array	Values for enabled fields

Mask bits:

Bit	Field	Key
0x01	Level	`level`
0x02	Experience	`exp`
0x04	Inventory money	`pocket_money`
0x08	Storehouse money	`store_money`
0x10	PK value	`pkvalue`
0x20	Reputation	`reputation`
0x40	Potential (spirit)	`potential`
0x80	Occupation (class)	`occupation`

// Set level to 105 and reset PK value to 0
$api->modifyRoleData(128, 0x01 | 0x10, [
    'level' => 105,
    'pkvalue' => 0,
]);

// Set experience to a large value (int64)
$api->modifyRoleData(128, 0x02, [
    'exp' => 2000000000,
]);

`clearStorehousePasswd($role, $rolename)` ^v174+

Clear the storehouse and cash password for a character.

Parameter	Type	Description
`$role`	int	Role ID
`$rolename`	string	Character name

$api->clearStorehousePasswd(128, 'PlayerOne');

Faction Operations

`getUserFaction($id)`

Get a character's faction membership info.

Parameter	Type	Description
`$id`	int	Role ID

$faction = $api->getUserFaction(128);
// $faction['rid']       - Role ID
// $faction['name']      - Character name
// $faction['fid']       - Faction ID (0 if none)
// $faction['cls']       - Class
// $faction['role']      - Faction role (0=member, 1=officer, etc.)
// $faction['nickname']  - Faction nickname

`getFactionInfo($id)`

Get basic faction info including the member list (role IDs and roles only).

Parameter	Type	Description
`$id`	int	Faction ID

$info = $api->getFactionInfo(1);
// $info['fid']      - Faction ID
// $info['name']     - Faction name
// $info['level']    - Faction level
// $info['master']   - Leader: ['roleid' => ..., 'role' => ...]
// $info['member']   - Members: [['roleid' => ..., 'role' => ...], ...]
// $info['announce'] - Announcement text
// $info['sysinfo']  - System info (hex octets)

`getFactionDetail($id)`

Get detailed faction info with full member data, alliances, and hostiles.

Parameter	Type	Description
`$id`	int	Faction ID

$detail = $api->getFactionDetail(1);
// $detail['fid']          - Faction ID
// $detail['name']         - Faction name
// $detail['level']        - Faction level
// $detail['master']       - Leader role ID (int)
// $detail['announce']     - Announcement text
// $detail['member']       - Full member info:
//     [['roleid', 'level', 'occupation', 'froleid', 'login_day', 'online_status',
//       'name', 'nickname', 'contrib_old', 'delayexpel', 'expeltime',
//       'reputation', 'reincarn_times', 'gender', 'contrib', 'guild_money'], ...]
// $detail['alliance']     - Allied factions [{fid, end_time}]
// $detail['hostile']      - Hostile factions [{fid, end_time}]
// $detail['apply']        - Pending relation applications [{type, fid, end_time}]
// $detail['last_op_time'] - Last operation timestamp
// $detail['unifid']       - Unified faction ID (int64)

`addFaction($roleid, $name, $fid)`

Create a new faction.

Parameter	Type	Description
`$roleid`	int	Leader role ID
`$name`	string	Faction name
`$fid`	int	Faction ID to assign

$api->addFaction(128, 'MyGuild', 1);

`delFaction($fid)`

Delete a faction.

Parameter	Type	Description
`$fid`	int	Faction ID

$api->delFaction(1);

`upgradeFaction($roleid, $fid, $level)`

Set a faction's level.

Parameter	Type	Description
`$roleid`	int	Role ID performing the upgrade
`$fid`	int	Faction ID
`$level`	int	New level

$api->upgradeFaction(128, 1, 3);

Territory War

`getTerritories()`

Get the full list of territory war zones with ownership, timing, and challenge data.

$territories = $api->getTerritories();
// $territories['Territory'] - Array of territories:
//     [['id', 'level', 'owner', 'occupy_time', 'challenger', 'deposit',
//       'cutoff_time', 'battle_time', 'bonus_time', 'color', 'status',
//       'timeout', 'challenge_time', 'challengerdetails',
//       'reserved1', 'reserved2', 'reserved3'], ...]

Mail

`sendMail($receiver, $title, $context, $item, $money)`

Send an in-game mail to a character. Optionally attach one item and/or money.

Parameter	Type	Description
`$receiver`	int	Recipient role ID
`$title`	string	Mail subject
`$context`	string	Mail body text
`$item`	array	Item attachment (optional, default: empty)
`$money`	int	Coin attachment (optional, default: `0`)

// Text-only mail
$api->sendMail(128, 'Welcome', 'Welcome to the server!');

// Mail with item attachment
$api->sendMail(128, 'Gift', 'Here is your item.', [
    'id'          => 21652,   // Item template ID
    'pos'         => 0,
    'count'       => 1,
    'max_count'   => 1,
    'data'        => '',      // Item octet data (hex)
    'proctype'    => 0,
    'expire_date' => 0,
    'guid1'       => 0,
    'guid2'       => 0,
    'mask'        => 0,
], 1000000);

`getMailList($role)` ^v174+

Get a list of mail headers for a character.

Parameter	Type	Description
`$role`	int	Role ID

$mails = $api->getMailList(128);
// [
//     ['id' => 0, 'sender' => 256, 'sndr_type' => 0, 'receiver' => 128,
//      'title' => 'Hello', 'send_time' => 1700000000, 'attribute' => 0, 'sender_name' => 'Admin'],
//     ...
// ]

`deleteMail($role, $mailid)` ^v174+

Delete a specific mail by its ID.

Parameter	Type	Description
`$role`	int	Role ID
`$mailid`	int	Mail ID (from `getMailList()`)

$api->deleteMail(128, 0);

Chat & Announcements

`WorldChat($role, $msg, $channel)`

Send a message to the game chat on a specific channel.

Parameter	Type	Description
`$role`	int	Sender role ID
`$msg`	string	Message text
`$channel`	int	Channel number (0 = normal, 1 = world, 7 = trade, 9 = system, etc.)

$api->WorldChat(128, 'Server restarting in 5 minutes!', 9);

`announce($role, $msg)` ^v174+

Send a GM announcement broadcast to the entire server. Uses the system channel.

Parameter	Type	Description
`$role`	int	GM role ID
`$msg`	string	Announcement text

$api->announce(128, 'Maintenance in 30 minutes.');

Bans & Mutes

`forbidAcc($role, $time, $reason)`

Ban an account. All characters on the account will be unable to log in.

Parameter	Type	Description
`$role`	int	User ID
`$time`	int	Ban duration in seconds (`-1` for permanent)
`$reason`	string	Ban reason

$api->forbidAcc(32, 86400, 'Violation of rules');   // 24-hour ban
$api->forbidAcc(32, -1, 'Permanent ban');            // Permanent
$api->forbidAcc(32, 0, '');                          // Unban

`forbidRole($role, $time, $reason)`

Ban a specific character.

Parameter	Type	Description
`$role`	int	Role ID
`$time`	int	Ban duration in seconds
`$reason`	string	Ban reason

$api->forbidRole(128, 3600, 'Temporary suspension');

`muteAcc($role, $time, $reason)`

Mute an account (prevent all characters from chatting).

Parameter	Type	Description
`$role`	int	User ID
`$time`	int	Mute duration in seconds
`$reason`	string	Mute reason

$api->muteAcc(32, 600, 'Spam');

`muteRole($role, $time, $reason)`

Mute a specific character.

Parameter	Type	Description
`$role`	int	Role ID
`$time`	int	Mute duration in seconds
`$reason`	string	Mute reason

$api->muteRole(128, 600, 'Spam');

Extended Role Data ^v174+

These methods require protocol version 352 or later.

`getNewRoleDetail($role)`

Get extended character data including PvP statistics, kill/death counts, silver money, and various octets for glyph, codex, celestial systems, etc.

Parameter	Type	Description
`$role`	int	Role ID

$detail = $api->getNewRoleDetail(128);
// $detail['roleid']                  - Role ID
// $detail['pk_time']                 - Last PK timestamp
// $detail['pk_status']               - PK status
// $detail['money_silver']            - Silver coin balance
// $detail['pvp_rank']                - PvP rank
// $detail['pvp_rank_exp']            - PvP rank experience
// $detail['player_kill']             - Total player kills
// $detail['monster_kill']            - Total monster kills
// $detail['player_death']            - Total player deaths
// $detail['monster_death']           - Total monster deaths
// $detail['has_astrolabe_lock']      - Astrolabe lock flag
// $detail['enabled_fashion_weapon']  - Fashion weapon toggle
// $detail['double_factor_exp/sp/realm'] - Double rate flags
// $detail['glyph']                   - Glyph data (hex octets)
// $detail['codex']                   - Codex data (hex octets)
// $detail['celestial']               - Celestial data (hex octets)
// $detail['pet_skin']                - Pet skin data (hex octets)
// ... (see protocol file for full field list)

`setNewRoleDetail($role, $params)`

Save extended character data. Pass the full array (e.g., from getNewRoleDetail() with modifications).

Parameter	Type	Description
`$role`	int	Role ID
`$params`	array	Full new role detail data

$detail = $api->getNewRoleDetail(128);
$detail['money_silver'] = 50000;
$detail['pvp_rank'] = 5;
$api->setNewRoleDetail(128, $detail);

Extended Storage ^v174+

`getNewTrashBox($role)`

Get extra storage box tabs (boxes 4-7) for a character.

Parameter	Type	Description
`$role`	int	Role ID

$trash = $api->getNewTrashBox(128);
// $trash['roleid']  - Role ID
// $trash['size4']   - Box 4 capacity
// $trash['box4']    - Box 4 items [{id, pos, count, max_count, data, ...}]
// $trash['size5']   - Box 5 capacity
// $trash['box5']    - Box 5 items
// $trash['size6']   - Box 6 capacity
// $trash['box6']    - Box 6 items
// $trash['size7']   - Box 7 capacity
// $trash['box7']    - Box 7 items

`setNewTrashBox($role, $params)`

Save extra storage box data.

Parameter	Type	Description
`$role`	int	Role ID
`$params`	array	Trash box data

$trash = $api->getNewTrashBox(128);
$trash['size4'] = 16;
$api->setNewTrashBox(128, $trash);

`getGlyphBox($role)`

Get glyph box inventory.

Parameter	Type	Description
`$role`	int	Role ID

$glyph = $api->getGlyphBox(128);
// $glyph['roleid']    - Role ID
// $glyph['size']      - Glyph box capacity
// $glyph['glyph_box'] - Glyph items [{id, pos, count, max_count, data, ...}]

`setGlyphBox($role, $params)`

Save glyph box inventory.

Parameter	Type	Description
`$role`	int	Role ID
`$params`	array	Glyph box data

$glyph = $api->getGlyphBox(128);
$glyph['size'] = 32;
$api->setGlyphBox(128, $glyph);

`getRoleStorage($role, $type)`

Get a specific storage type by name. This is a unified interface for multiple storage systems.

Parameter	Type	Description
`$role`	int	Role ID
`$type`	string	Storage type name

Available types:

Type	Description	Fields
`lotteryItems`	Lottery item entries	`roleid`, `treasure_items` (octets)
`lotteryData`	Lottery progress	`roleid`, `level`, `score`, `lottery_data` (octets)
`treasureData`	Treasure box data	`roleid`, `score`, `treasure_data` (octets)
`libItems`	Library items	`roleid`, `lib_items` (octets)
`glyphData`	Glyph system data	`roleid`, `glyph_data` (octets)
`celestialData`	Celestial system data	`roleid`, `celestial` (octets)
`repositoryData`	Repository data	`roleid`, `repository_data` (octets)
`activityData`	Activity/event data	`roleid`, `activity` (octets)
`petSkin`	Pet skin data	`roleid`, `pet_skin` (octets)

$lottery = $api->getRoleStorage(128, 'lotteryData');
// ['roleid' => 128, 'level' => 3, 'score' => 1500, 'lottery_data' => '...']

$celestial = $api->getRoleStorage(128, 'celestialData');
// ['roleid' => 128, 'celestial' => '...']

`setRoleStorage($role, $type, $params)`

Save a specific storage type by name.

Parameter	Type	Description
`$role`	int	Role ID
`$type`	string	Storage type name (same as `getRoleStorage`)
`$params`	array	Storage data

$lottery = $api->getRoleStorage(128, 'lotteryData');
$lottery['score'] = 5000;
$api->setRoleStorage(128, 'lotteryData', $lottery);

Lua Storage ^v174+

`getLuaStorage($key, $data_mask)`

Read a Lua storage entry by key. Used for server-side Lua script data.

Parameter	Type	Default	Description
`$key`	int	—	Storage key
`$data_mask`	int	`1`	Data mask

$data = $api->getLuaStorage(100);
// ['key' => 100, 'data' => '...']  (hex octets)

`setLuaStorage($key, $value, $data_mask)`

Write a Lua storage entry.

Parameter	Type	Default	Description
`$key`	int	—	Storage key
`$value`	string	—	Hex-encoded octet data
`$data_mask`	int	`1`	Data mask

$api->setLuaStorage(100, 'deadbeef');

Player Ranking ^v174+

`getPlayerRanking($role)`

Get ranking data for a character.

Parameter	Type	Description
`$role`	int	Role ID

$rank = $api->getPlayerRanking(128);
// $rank['role_id']         - Role ID
// $rank['user_id']         - User ID
// $rank['cls']             - Class
// $rank['score_pve']       - PvE score
// $rank['score_pvp']       - PvP score
// $rank['kill_monsters']   - Total monster kills
// $rank['die_monsters']    - Total monster deaths
// $rank['kill_players']    - Total player kills
// $rank['die_players']     - Total player deaths
// $rank['score_pve_level'] - PvE level score
// $rank['score_pvp_level'] - PvP level score
// $rank['fama_score']      - Fame score
// $rank['level']           - Current level
// $rank['level2']          - Reincarnation level
// $rank['name']            - Character name

Server Data & Global Control ^v174+

`getServerData($world_tag, $data_mask)`

Get server-wide data (wedding, DPS rankings, etc.).

Parameter	Type	Default	Description
`$world_tag`	int	`0`	World/map tag
`$data_mask`	int	`1`	Data mask

$data = $api->getServerData();
// $data['world_tag']     - World tag
// $data['wedding_data']  - Wedding system data (hex octets)
// $data['dpsrank_data']  - DPS ranking data (hex octets)

`loadGlobalControl()`

Load the current global control settings (cash exchange, feature toggles, forbidden items/skills/tasks).

$ctrl = $api->loadGlobalControl();
// $ctrl['cash_money_exchange_open'] - Gold exchange enabled (0/1)
// $ctrl['cash_money_exchange_rate'] - Exchange rate
// $ctrl['forbid_ctrl_list']         - Disabled control IDs [{item => id}]
// $ctrl['forbid_item_list']         - Forbidden item IDs
// $ctrl['forbid_service_list']      - Forbidden service IDs
// $ctrl['forbid_task_list']         - Forbidden task IDs
// $ctrl['forbid_skill_list']        - Forbidden skill IDs
// $ctrl['trigger_ctrl_list']        - Trigger control IDs
// $ctrl['forbid_shopitem_list']     - Forbidden shop item IDs
// $ctrl['forbid_recipe_list']       - Forbidden recipe IDs

`putGlobalControl($params)`

Save global control settings. Pass the full structure (e.g., from loadGlobalControl() with modifications).

Parameter	Type	Description
`$params`	array	Global control data

$ctrl = $api->loadGlobalControl();
$ctrl['cash_money_exchange_open'] = 1;
$ctrl['cash_money_exchange_rate'] = 200;
$api->putGlobalControl($ctrl);

Raw Database Access

`getRaw($table, $handler, $key)`

Perform a raw database table read from gamedbd.

Parameter	Type	Default	Description
`$table`	string	—	Table name
`$handler`	string	`''`	Handler (hex octets)
`$key`	string	`''`	Key (hex octets)

$raw = $api->getRaw('base');
// $raw['handle'] - Handle data (hex octets)
// $raw['Raw']    - Array of key-value pairs [['key' => '...', 'value' => '...'], ...]

Skill Generation

`generateSkill($params)`

Append a skill to existing skill octet data. Returns the modified skill hex string.

Parameter	Type	Description
`$params`	array	Keys: `skills` (existing skill hex), `id` (skill ID), `level`, `progress`

$status = $api->getRoleStatus(128);
$newSkills = $api->generateSkill([
    'skills'   => $status['skills'],
    'id'       => 100,
    'level'    => 10,
    'progress' => 0,
]);

bahastriker / pw-api

Maintainers

Package info

Statistics

Security

README

Compatibility

Install

Configuration

Supported Protocol Versions

Settings Resolution

Usage

API Reference

Server Status

serverOnline()

ports()

checkRoleOnline($role)

getOnlineList()

Account & User Data

getUser($id)

getRoles($user)

getUserCash($userid)

Role Data — Read

getRole($role)

getRoleBase($role)

getRoleStatus($role)

getRoleInventory($role)

getRoleEquipment($role)

getRoleStorehouse($role)

getRoleTask($role)

getRolePetBadge($role)

getRoleFriends($role)

Role Data — Write

putRole($role, $params)

Octet Parsing

parseOctet($octet, $name)

getRolePvp($var_data)

ID Lookups

getRoleid($rolename)

roleIdToUserId($roleid) v174+

userIdToLogicUid($userid) v174+

Character Management

renameRole($role, $oldname, $newname)

undoDeleteRole($role) v174+

copyRole($srcroleid, $dstroleid) v174+

positionReset($role, $worldtag, $x, $y, $z) v174+

modifyRoleData($role, $mask, $params) v174+

clearStorehousePasswd($role, $rolename) v174+